Better type information for lib consumers

[Buckwich]

Is your feature request related to a problem? Please describe

Consumers of this lib don't get intellisense including the jsdoc or wrong information

originally I wanted to fix the index.d.ts file for normalizeContextKey

eg it should have been name: string

But then I realized by having the index.d.ts we are stripping everyother type information we could get from the already present jsdoc. See no description of class:

Describe the solution you'd like

I want to see accurate type and explanatory comments as intellisense. like:

This could be achieved by generating the types based on the bundle:

npx tsc ./dist/index.js --declaration  --allowJs --emitDeclarationOnly

example output of index.d.ts

export type ContextValue = VariableContext | any;
export type ContextCache = {
    keys: Set<string>;
    prefixes: Set<string>;
    originalMap: Map<string, string>;
};
export type CacheMap = WeakMap<VariableContext, ContextCache>;
/**
 * A basic key-value store to hold context values.
 */
export class VariableContext {
    /**
     * Wether the given value is atomic. Non-atomic values need to be wrapped in a
     * context Class.
     *
     * @param {any} value
     * @returns {Boolean}
     */
    static isAtomic(value: any): boolean;
    /**
     * Takes any number of Contexts and merges them into a single context.
     *
     * @param { ...VariableContext } contexts
     * @returns { VariableContext }
     */
    static of(...contexts: VariableContext[]): VariableContext;
    /**
     * Returns the raw representation of the given context.
     *
     * @param {VariableContext | any} context
     *
     * @return {any}
     */
    static __unwrap(context: VariableContext | any): any;
    /**
     * Non-destructively merges two contexts (or their values)
     * with each other, returning the result.
     *
     * @param {ContextValue} context
     * @param {ContextValue} other
     *
     * @return {ContextValue} merged context value
     */
    static __merge(context: ContextValue, other: ContextValue): ContextValue;
    /**
     * Creates a new context from a JavaScript object.
     *
     * @param {any} [value]
     */
    constructor(value?: any);
    /**
     * @protected
     */
    protected value: any;
    /**
     * Return all defined keys of the context.
     *
     * @returns {string[] } the keys of the context
     */
    getKeys(): string[];
    /**
     * Returns the value of the given key.
     *
     * If the value represents a context itself, it should be wrapped in a
     * context class.
     *
     * @param {string} key
     * @returns {VariableContext|ValueProducer|null}
     */
    get(key: string): VariableContext | ValueProducer | null;
    /**
     * Creates a new context with the given key added.
     *
     * @param {string} key
     * @param {any} value
     *
     * @returns {VariableContext} new context with the given key added
     */
    set(key: string, value: any): VariableContext;
    /**
     * Non-destructively merge another context into this one,
     * and return the result.
     *
     * @param {ContextValue} other
     *
     * @return {VariableContext}
     */
    merge(other: ContextValue): VariableContext;
}
/**
 * @param { string } name
 *
 * @return { string } normalizedName
 */
export function normalizeContextKey(name: string): string;
export const parser: LRParser;
/**
 * @param { ContextValue } [context]
 * @param { typeof VariableContext } [Context]
 *
 * @return { ContextTracker<Variables> }
 */
export function trackVariables(context?: ContextValue, Context?: typeof VariableContext): ContextTracker<Variables>;
/**
 * A simple producer that retrievs a value from
 * a given context. Used to lazily take things.
 */
declare class ValueProducer {
    /**
     * @param { (variables: Variables) => ContextValue } fn
     *
     * @return { ValueProducer }
     */
    static of(fn: (variables: Variables) => ContextValue): ValueProducer;
    /**
     * @param { Function } fn
     */
    constructor(fn: Function);
    fn: Function;
    get(variables: any): any;
}
import { LRParser } from '@lezer/lr';
import { ContextTracker } from '@lezer/lr';
declare class Variables {
    /**
     * @param { {
     *   name?: string,
     *   tokens?: string[],
     *   children?: Variables[],
     *   parent?: Variables | null
     *   context: VariableContext,
     *   value?: any,
     *   raw?: any,
     *   __cache?: CacheMap
     * } } options
     *
     * @return {Variables}
     */
    static of(options: {
        name?: string;
        tokens?: string[];
        children?: Variables[];
        parent?: Variables | null;
        context: VariableContext;
        value?: any;
        raw?: any;
        __cache?: CacheMap;
    }): Variables;
    /**
     * @param { {
     *   name?: string,
     *   tokens?: string[],
     *   children?: Variables[],
     *   parent: Variables | null
     *   context: VariableContext,
     *   value?: any,
     *   raw?: any,
     *   __cache?: CacheMap
     * } } options
     */
    constructor({ name, tokens, children, parent, context, value, raw, __cache }: {
        name?: string;
        tokens?: string[];
        children?: Variables[];
        parent: Variables | null;
        context: VariableContext;
        value?: any;
        raw?: any;
        __cache?: CacheMap;
    });
    name: string;
    tokens: string[];
    children: Variables[];
    parent: Variables;
    context: VariableContext;
    value: any;
    raw: any;
    __cache: CacheMap;
    /**
     * Get the root Variables instance by traversing up the parent chain.
     *
     * @returns {Variables}
     */
    get root(): Variables;
    /**
     * Get the root Variables instance by traversing up the parent chain.
     *
     * @returns {CacheMap}
     */
    get cache(): CacheMap;
    enterScope(name: any): Variables;
    exitScope(str: any): Variables;
    token(part: any): Variables;
    literal(value: any): Variables;
    /**
     * Return computed scope value
     *
     * @return {any}
     */
    computedValue(): any;
    /**
     * Get or compute the context cache for fast retrival
     * of keys, prefixes and original mappings.
     *
     * @returns {ContextCache}
     */
    contextCache(): ContextCache;
    get path(): any;
    /**
     * Return value of variable.
     *
     * @param { string } variable
     * @return { any } value
     */
    get(variable: string): any;
    resolveName(): Variables;
    pushChild(child: any): Variables;
    pushChildren(children: any): Variables;
    declareName(): Variables;
    define(name: any, value: any): Variables;
    /**
     * @param { Record<string, any> } [options]
     *
     * @return { Variables }
     */
    assign(options?: Record<string, any>): Variables;
    /**
     * @param { Record<string, any> } [options]
     *
     * @return { Variables }
     */
    of(options?: Record<string, any>): Variables;
}
export {};

Describe alternatives you've considered

• keep the index.d.ts manually in sync with comments, types
• maybe https://github.com/nikku/bio-dts could be used

Additional context

• also applies to bpmn fork, but i want them to be as close as possible, if you (@nikku) agree with the proposed solution I can go ahead and prepare PRs for both

[nikku]

This is a limitations of types generated via typescript. Thank you 🪟 😉

[nikku]

Thanks for opening the issue. Will see what I can do to improve the situation.