@traqula/core 1.1.0 → 1.1.1

package/dist/esm/lib/indirection-builder/IndirBuilder.d.ts

@@ -1,14 +1,37 @@
 import type { ParseNamesFromList } from '../parser-builder/builderTypes.js';
 import type { CheckOverlap } from '../utils.js';
 import type { IndirDef, IndirectionMap, IndirectObjFromIndirDefs, ParseIndirsToObject } from './helpers.js';
+/**
+ * Builder for composing modular transformation pipelines using indirection definitions.
+ * Functions registered through this builder call each other via SUBRULE, enabling the same
+ * modularity and extensibility as the parser and generator builders.
+ *
+ * Builders mutate internal state and return `this`.
+ * Always start by copying an existing builder with `IndirBuilder.create(existingBuilder)`.
+ */
 export declare class IndirBuilder<Context, Names extends string, RuleDefs extends IndirectionMap<Names>> {
+    /**
+     * Create an IndirBuilder from initial indirection definitions or an existing builder.
+     * If a builder is provided, a new copy will be created.
+     */
     static create<Context, Names extends string, RuleDefs extends IndirectionMap<Names>>(args: IndirBuilder<Context, Names, RuleDefs>): IndirBuilder<Context, Names, RuleDefs>;
     static create<Rules extends readonly IndirDef[] = readonly IndirDef[], Context = Rules[0] extends IndirDef<infer context> ? context : never, Names extends string = ParseNamesFromList<Rules>, RuleDefs extends IndirectionMap<Names> = ParseIndirsToObject<Rules>>(rules: Rules): IndirBuilder<Context, Names, RuleDefs>;
     private rules;
     private constructor();
+    /**
+     * Narrow the builder's context type parameter to a more specific subtype.
+     * This is a zero-cost type-level operation — the builder instance is returned as-is
+     * but with updated type parameters.
+     */
     widenContext<NewContext extends Context>(): IndirBuilder<NewContext, Names, {
         [Key in keyof RuleDefs]: Key extends Names ? (RuleDefs[Key] extends IndirDef<any, any, infer RT, infer PT> ? IndirDef<NewContext, Key, RT, PT> : never) : never;
     }>;
+    /**
+     * Update the type signatures (return types and/or parameter types) of existing indirections
+     * without changing their implementations. Use this when a patched indirection changes the types
+     * flowing through downstream indirections that don't need new implementations.
+     * This is a zero-cost type-level operation.
+     */
     typePatch<Patch extends {
         [Key in Names]?: [any] | [any, any[]];
     }>(): IndirBuilder<Context, Names, {
@@ -32,6 +55,12 @@ export declare class IndirBuilder<Context, Names extends string, RuleDefs extend
     addRule<U extends string, RET, ARGS extends any[]>(rule: CheckOverlap<U, Names, IndirDef<Context, U, RET, ARGS>>): IndirBuilder<Context, Names | U, {
         [K in Names | U]: K extends U ? IndirDef<Context, K, RET, ARGS> : (K extends Names ? (RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never) : never);
     }>;
+    /**
+     * Add multiple indirection definitions at once using rest parameters.
+     * Provides better TypeScript type inference than calling {@link addRule} in a loop,
+     * but avoid passing too many at once as this can cause TypeScript compilation slowdowns.
+     * TypeScript errors if any name conflicts with an existing one.
+     */
     addMany<U extends readonly IndirDef<Context>[]>(...rules: CheckOverlap<ParseNamesFromList<U>, Names, U>): IndirBuilder<Context, Names | ParseNamesFromList<U>, {
         [K in Names | ParseNamesFromList<U>]: K extends keyof ParseIndirsToObject<typeof rules> ? (ParseIndirsToObject<typeof rules>[K] extends IndirDef<Context, K> ? ParseIndirsToObject<typeof rules>[K] : never) : (K extends Names ? (RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never) : never);
     }>;
@@ -41,9 +70,33 @@ export declare class IndirBuilder<Context, Names extends string, RuleDefs extend
     deleteRule<U extends Names>(ruleName: U): IndirBuilder<Context, Exclude<Names, U>, {
         [K in Exclude<Names, U>]: RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never;
     }>;
+    /**
+     * Delete multiple indirection definitions by name in a single call.
+     * @param ruleNames - Names of the indirections to delete.
+     */
     deleteMany<U extends Names>(...ruleNames: U[]): IndirBuilder<Context, Exclude<Names, U>, {
         [K in Exclude<Names, U>]: RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never;
     }>;
+    /**
+     * Retrieve an indirection definition by its name.
+     * Useful for inspecting or wrapping existing definitions when extending a pipeline.
+     * @param ruleName - The name of the indirection, type-checked against the builder's known names.
+     */
     getRule<U extends Names>(ruleName: U): RuleDefs[U] extends IndirDef<any, U, infer RT, infer PT> ? IndirDef<Context, U, RT, PT> : never;
+    /**
+     * Merge this indirection builder with another.
+     * If the two builders both have a definition with the same name,
+     * no error will be thrown in case they map to the same object (by reference).
+     * If they map to a different object, an error will be thrown.
+     * To fix this problem, the overridingRules array should contain a definition with the same conflicting name,
+     * whose implementation will be used.
+     */
+    merge<OtherNames extends string, OtherRules extends IndirectionMap<OtherNames>, OW extends readonly IndirDef<Context>[]>(builder: IndirBuilder<Context, OtherNames, OtherRules>, overridingRules: OW): IndirBuilder<Context, Names | OtherNames | ParseNamesFromList<OW>, {
+        [K in Names | OtherNames | ParseNamesFromList<OW>]: K extends keyof ParseIndirsToObject<OW> ? (ParseIndirsToObject<OW>[K] extends IndirDef<Context, K> ? ParseIndirsToObject<OW>[K] : never) : (K extends Names ? (RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never) : K extends OtherNames ? (OtherRules[K] extends IndirDef<Context, K> ? OtherRules[K] : never) : never);
+    }>;
+    /**
+     * Construct an indirection object from the registered definitions.
+     * @returns An object with a method for each registered indirection name.
+     */
     build(): IndirectObjFromIndirDefs<Context, Names, RuleDefs>;
 }

package/dist/esm/lib/indirection-builder/IndirBuilder.js

@@ -1,5 +1,13 @@
 import { DynamicIndirect } from './dynamicIndirected.js';
 import { listToIndirectionMap } from './helpers.js';
+/**
+ * Builder for composing modular transformation pipelines using indirection definitions.
+ * Functions registered through this builder call each other via SUBRULE, enabling the same
+ * modularity and extensibility as the parser and generator builders.
+ *
+ * Builders mutate internal state and return `this`.
+ * Always start by copying an existing builder with `IndirBuilder.create(existingBuilder)`.
+ */
 export class IndirBuilder {
     static create(start) {
         if (Array.isArray(start)) {
@@ -11,9 +19,20 @@ export class IndirBuilder {
     constructor(startRules) {
         this.rules = startRules;
     }
+    /**
+     * Narrow the builder's context type parameter to a more specific subtype.
+     * This is a zero-cost type-level operation — the builder instance is returned as-is
+     * but with updated type parameters.
+     */
     widenContext() {
         return this;
     }
+    /**
+     * Update the type signatures (return types and/or parameter types) of existing indirections
+     * without changing their implementations. Use this when a patched indirection changes the types
+     * flowing through downstream indirections that don't need new implementations.
+     * This is a zero-cost type-level operation.
+     */
     typePatch() {
         return this;
     }
@@ -43,6 +62,12 @@ export class IndirBuilder {
     addRule(rule) {
         return this.addRuleRedundant(rule);
     }
+    /**
+     * Add multiple indirection definitions at once using rest parameters.
+     * Provides better TypeScript type inference than calling {@link addRule} in a loop,
+     * but avoid passing too many at once as this can cause TypeScript compilation slowdowns.
+     * TypeScript errors if any name conflicts with an existing one.
+     */
     addMany(...rules) {
         this.rules = { ...this.rules, ...listToIndirectionMap(rules) };
         return this;
@@ -54,15 +79,62 @@ export class IndirBuilder {
         delete this.rules[ruleName];
         return this;
     }
+    /**
+     * Delete multiple indirection definitions by name in a single call.
+     * @param ruleNames - Names of the indirections to delete.
+     */
     deleteMany(...ruleNames) {
         for (const name of ruleNames) {
             delete this.rules[name];
         }
         return this;
     }
+    /**
+     * Retrieve an indirection definition by its name.
+     * Useful for inspecting or wrapping existing definitions when extending a pipeline.
+     * @param ruleName - The name of the indirection, type-checked against the builder's known names.
+     */
     getRule(ruleName) {
         return this.rules[ruleName];
     }
+    /**
+     * Merge this indirection builder with another.
+     * If the two builders both have a definition with the same name,
+     * no error will be thrown in case they map to the same object (by reference).
+     * If they map to a different object, an error will be thrown.
+     * To fix this problem, the overridingRules array should contain a definition with the same conflicting name,
+     * whose implementation will be used.
+     */
+    merge(builder, overridingRules) {
+        // Assume the other set is bigger than yours. So start from that one and add this one
+        const otherRules = { ...builder.rules };
+        const myRules = this.rules;
+        for (const rule of Object.values(myRules)) {
+            if (otherRules[rule.name] === undefined) {
+                otherRules[rule.name] = rule;
+            }
+            else {
+                const existingRule = otherRules[rule.name];
+                // If same rule, no issue, move on. Else
+                if (existingRule !== rule) {
+                    const override = overridingRules.find(x => x.name === rule.name);
+                    // If override specified, take override, else, inform user that there is a conflict
+                    if (override) {
+                        otherRules[rule.name] = override;
+                    }
+                    else {
+                        throw new Error(`Function with name "${rule.name}" already exists in the builder, specify an override to resolve conflict`);
+                    }
+                }
+            }
+        }
+        this.rules = otherRules;
+        return this;
+    }
+    /**
+     * Construct an indirection object from the registered definitions.
+     * @returns An object with a method for each registered indirection name.
+     */
     build() {
         return new DynamicIndirect(this.rules);
     }

package/dist/esm/lib/indirection-builder/IndirBuilder.js.map

@@ -1 +1 @@
-{"version":3,"file":"IndirBuilder.js","sourceRoot":"","sources":["../../../../lib/indirection-builder/IndirBuilder.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEpD,MAAM,OAAO,YAAY;IAUhB,MAAM,CAAC,MAAM,CAMlB,KAAqD;QAErD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,OAA0D,IAAI,YAAY,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1G,CAAC;QACD,OAAO,IAAI,YAAY,CAAC,EAAE,GAAiC,KAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IAC7E,CAAC;IAEO,KAAK,CAAW;IAExB,YAAoB,UAAoB;QACtC,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC;IAC1B,CAAC;IAEM,YAAY;QAOjB,OAAa,IAAI,CAAC;IACpB,CAAC;IAEM,SAAS;QASd,OAAa,IAAI,CAAC;IACpB,CAAC;IAED;;OAEG;IACI,SAAS,CAA2C,KAAsC;QAK/F,MAAM,IAAI,GAEE,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAS,KAAK,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACI,gBAAgB,CAA4C,IAAqC;QAKtG,MAAM,IAAI,GAGE,IAAI,CAAC;QACjB,MAAM,KAAK,GAAuC,IAAI,CAAC,KAAK,CAAC;QAC7D,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YAChE,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,CAAC,IAAI,gCAAgC,CAAC,CAAC;QACzE,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACI,OAAO,CACZ,IAA6D;QAI7D,OAAO,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAEM,OAAO,CACZ,GAAG,KAAoD;QAYvD,IAAI,CAAC,KAAK,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,GAAG,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/D,OAAuB,IAAI,CAAC;IAC9B,CAAC;IAED;;OAEG;IACI,UAAU,CAAkB,QAAW;QAG5C,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC5B,OAEY,IAAI,CAAC;IACnB,CAAC;IAEM,UAAU,CAAkB,GAAG,SAAc;QAGlD,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD,OAEY,IAAI,CAAC;IACnB,CAAC;IAEM,OAAO,CAAkB,QAAW;QAEzC,OAAa,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAEM,KAAK;QACV,OAA4D,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9F,CAAC;CACF","sourcesContent":["import type { ParseNamesFromList } from '../parser-builder/builderTypes.js';\nimport type { CheckOverlap } from '../utils.js';\nimport { DynamicIndirect } from './dynamicIndirected.js';\nimport type { IndirDef, IndirectionMap, IndirectObjFromIndirDefs, ParseIndirsToObject } from './helpers.js';\nimport { listToIndirectionMap } from './helpers.js';\n\nexport class IndirBuilder<Context, Names extends string, RuleDefs extends IndirectionMap<Names>> {\n  public static create<Context, Names extends string, RuleDefs extends IndirectionMap<Names>>(\n    args: IndirBuilder<Context, Names, RuleDefs>\n  ): IndirBuilder<Context, Names, RuleDefs>;\n  public static create<\n    Rules extends readonly IndirDef[] = readonly IndirDef[],\n    Context = Rules[0] extends IndirDef<infer context> ? context : never,\n    Names extends string = ParseNamesFromList<Rules>,\n    RuleDefs extends IndirectionMap<Names> = ParseIndirsToObject<Rules>,\n  >(rules: Rules): IndirBuilder<Context, Names, RuleDefs>;\n  public static create<\n    Rules extends readonly IndirDef[] = readonly IndirDef[],\n    Context = Rules[0] extends IndirDef<infer context> ? context : never,\n    Names extends string = ParseNamesFromList<Rules>,\n    RuleDefs extends IndirectionMap<Names> = ParseIndirsToObject<Rules>,\n  >(\n    start: Rules | IndirBuilder<Context, Names, RuleDefs>,\n  ): IndirBuilder<Context, Names, RuleDefs> {\n    if (Array.isArray(start)) {\n      return <IndirBuilder<Context, Names, RuleDefs>> <unknown> new IndirBuilder(listToIndirectionMap(start));\n    }\n    return new IndirBuilder({ ...(<IndirBuilder<any, any, any>>start).rules });\n  }\n\n  private rules: RuleDefs;\n\n  private constructor(startRules: RuleDefs) {\n    this.rules = startRules;\n  }\n\n  public widenContext<NewContext extends Context>(): IndirBuilder<\n    NewContext,\n    Names,\n    {[Key in keyof RuleDefs]: Key extends Names ?\n        (RuleDefs[Key] extends IndirDef<any, any, infer RT, infer PT> ? IndirDef<NewContext, Key, RT, PT> : never)\n      : never }\n  > {\n    return <any> this;\n  }\n\n  public typePatch<Patch extends {[Key in Names]?: [any] | [any, any[]]}>():\n  IndirBuilder<Context, Names, {[Key in Names]: Key extends keyof Patch ? (\n    Patch[Key] extends [any, any[]] ? IndirDef<Context, Key, Patch[Key][0], Patch[Key][1]> : (\n      // Only  one - infer arg yourself\n      Patch[Key] extends [ any ] ? (\n        RuleDefs[Key] extends IndirDef<any, any, any, infer Par> ? IndirDef<Context, Key, Patch[Key][0], Par> : never\n      ) : never\n    )\n  ) : (RuleDefs[Key] extends IndirDef<Context, Key> ? RuleDefs[Key] : never) }> {\n    return <any> this;\n  }\n\n  /**\n   * Change the implementation of an existing indirection.\n   */\n  public patchRule<U extends Names, RET, ARGS extends any[]>(patch: IndirDef<Context, U, RET, ARGS>):\n  IndirBuilder<Context, Names, {[Key in Names]: Key extends U ?\n    IndirDef<Context, Key, RET, ARGS> :\n      (RuleDefs[Key] extends IndirDef<Context, Key> ? RuleDefs[Key] : never)\n  } > {\n    const self = <IndirBuilder<Context, Names, {[Key in Names]: Key extends U ?\n      IndirDef<Context, Key, RET, ARGS> : (RuleDefs[Key] extends IndirDef<Context, Key> ? RuleDefs[Key] : never) }>>\n      <unknown> this;\n    self.rules[patch.name] = <any> patch;\n    return self;\n  }\n\n  /**\n   * Add an indirection function. If the rule already exists, but the implementation differs, an error will be thrown.\n   */\n  public addRuleRedundant<U extends string, RET, ARGS extends any[]>(rule: IndirDef<Context, U, RET, ARGS>):\n  IndirBuilder<Context, Names | U, {[K in Names | U]: K extends U ?\n    IndirDef<Context, K, RET, ARGS> :\n      (K extends Names ? (RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never) : never)\n  }> {\n    const self = <IndirBuilder<Context, Names | U, {[K in Names | U]: K extends U ?\n      IndirDef<Context, K, RET, ARGS> :\n        (K extends Names ? (RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never) : never) }>>\n      <unknown> this;\n    const rules = <Record<string, IndirDef<Context>>> self.rules;\n    if (rules[rule.name] !== undefined && rules[rule.name] !== rule) {\n      throw new Error(`Function ${rule.name} already exists in the builder`);\n    }\n    rules[rule.name] = rule;\n    return self;\n  }\n\n  /**\n   * Add a rule to the grammar. Will raise a typescript error if the rule already exists in the grammar.\n   */\n  public addRule<U extends string, RET, ARGS extends any[]>(\n    rule: CheckOverlap<U, Names, IndirDef<Context, U, RET, ARGS>>,\n  ): IndirBuilder<Context, Names | U, {[K in Names | U]: K extends U ?\n    IndirDef<Context, K, RET, ARGS> :\n      (K extends Names ? (RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never) : never) }> {\n    return this.addRuleRedundant(rule);\n  }\n\n  public addMany<U extends readonly IndirDef<Context>[]>(\n    ...rules: CheckOverlap<ParseNamesFromList<U>, Names, U>\n  ): IndirBuilder<\n    Context,\n    Names | ParseNamesFromList<U>,\n    {[K in Names | ParseNamesFromList<U>]:\n      K extends keyof ParseIndirsToObject<typeof rules> ? (\n        ParseIndirsToObject<typeof rules>[K] extends IndirDef<Context, K> ? ParseIndirsToObject<typeof rules>[K] : never\n      ) : (\n        K extends Names ? (RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never) : never\n      )\n    }\n  > {\n    this.rules = { ...this.rules, ...listToIndirectionMap(rules) };\n    return <any> <unknown> this;\n  }\n\n  /**\n   * Delete a grammar rule by its name.\n   */\n  public deleteRule<U extends Names>(ruleName: U):\n  IndirBuilder<Context, Exclude<Names, U>, {[K in Exclude<Names, U>]:\n    RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never }> {\n    delete this.rules[ruleName];\n    return <IndirBuilder<Context, Exclude<Names, U>, {[K in Exclude<Names, U>]:\n      RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never }>>\n      <unknown> this;\n  }\n\n  public deleteMany<U extends Names>(...ruleNames: U[]):\n  IndirBuilder<Context, Exclude<Names, U>, {[K in Exclude<Names, U>]:\n    RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never }> {\n    for (const name of ruleNames) {\n      delete this.rules[name];\n    }\n    return <IndirBuilder<Context, Exclude<Names, U>, {[K in Exclude<Names, U>]:\n      RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never }>>\n      <unknown> this;\n  }\n\n  public getRule<U extends Names>(ruleName: U): RuleDefs[U] extends IndirDef<any, U, infer RT, infer PT> ?\n    IndirDef<Context, U, RT, PT> : never {\n    return <any> this.rules[ruleName];\n  }\n\n  public build(): IndirectObjFromIndirDefs<Context, Names, RuleDefs> {\n    return <IndirectObjFromIndirDefs<Context, Names, RuleDefs>> new DynamicIndirect(this.rules);\n  }\n}\n"]}
+{"version":3,"file":"IndirBuilder.js","sourceRoot":"","sources":["../../../../lib/indirection-builder/IndirBuilder.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ParseNamesFromList } from '../parser-builder/builderTypes.js';\nimport type { CheckOverlap } from '../utils.js';\nimport { DynamicIndirect } from './dynamicIndirected.js';\nimport type { IndirDef, IndirectionMap, IndirectObjFromIndirDefs, ParseIndirsToObject } from './helpers.js';\nimport { listToIndirectionMap } from './helpers.js';\n\n/**\n * Builder for composing modular transformation pipelines using indirection definitions.\n * Functions registered through this builder call each other via SUBRULE, enabling the same\n * modularity and extensibility as the parser and generator builders.\n *\n * Builders mutate internal state and return `this`.\n * Always start by copying an existing builder with `IndirBuilder.create(existingBuilder)`.\n */\nexport class IndirBuilder<Context, Names extends string, RuleDefs extends IndirectionMap<Names>> {\n  /**\n   * Create an IndirBuilder from initial indirection definitions or an existing builder.\n   * If a builder is provided, a new copy will be created.\n   */\n  public static create<Context, Names extends string, RuleDefs extends IndirectionMap<Names>>(\n    args: IndirBuilder<Context, Names, RuleDefs>\n  ): IndirBuilder<Context, Names, RuleDefs>;\n  public static create<\n    Rules extends readonly IndirDef[] = readonly IndirDef[],\n    Context = Rules[0] extends IndirDef<infer context> ? context : never,\n    Names extends string = ParseNamesFromList<Rules>,\n    RuleDefs extends IndirectionMap<Names> = ParseIndirsToObject<Rules>,\n  >(rules: Rules): IndirBuilder<Context, Names, RuleDefs>;\n  public static create<\n    Rules extends readonly IndirDef[] = readonly IndirDef[],\n    Context = Rules[0] extends IndirDef<infer context> ? context : never,\n    Names extends string = ParseNamesFromList<Rules>,\n    RuleDefs extends IndirectionMap<Names> = ParseIndirsToObject<Rules>,\n  >(\n    start: Rules | IndirBuilder<Context, Names, RuleDefs>,\n  ): IndirBuilder<Context, Names, RuleDefs> {\n    if (Array.isArray(start)) {\n      return <IndirBuilder<Context, Names, RuleDefs>> <unknown> new IndirBuilder(listToIndirectionMap(start));\n    }\n    return new IndirBuilder({ ...(<IndirBuilder<any, any, any>>start).rules });\n  }\n\n  private rules: RuleDefs;\n\n  private constructor(startRules: RuleDefs) {\n    this.rules = startRules;\n  }\n\n  /**\n   * Narrow the builder's context type parameter to a more specific subtype.\n   * This is a zero-cost type-level operation — the builder instance is returned as-is\n   * but with updated type parameters.\n   */\n  public widenContext<NewContext extends Context>(): IndirBuilder<\n    NewContext,\n    Names,\n    {[Key in keyof RuleDefs]: Key extends Names ?\n        (RuleDefs[Key] extends IndirDef<any, any, infer RT, infer PT> ? IndirDef<NewContext, Key, RT, PT> : never)\n      : never }\n  > {\n    return <any> this;\n  }\n\n  /**\n   * Update the type signatures (return types and/or parameter types) of existing indirections\n   * without changing their implementations. Use this when a patched indirection changes the types\n   * flowing through downstream indirections that don't need new implementations.\n   * This is a zero-cost type-level operation.\n   */\n  public typePatch<Patch extends {[Key in Names]?: [any] | [any, any[]]}>():\n  IndirBuilder<Context, Names, {[Key in Names]: Key extends keyof Patch ? (\n    Patch[Key] extends [any, any[]] ? IndirDef<Context, Key, Patch[Key][0], Patch[Key][1]> : (\n      // Only  one - infer arg yourself\n      Patch[Key] extends [ any ] ? (\n        RuleDefs[Key] extends IndirDef<any, any, any, infer Par> ? IndirDef<Context, Key, Patch[Key][0], Par> : never\n      ) : never\n    )\n  ) : (RuleDefs[Key] extends IndirDef<Context, Key> ? RuleDefs[Key] : never) }> {\n    return <any> this;\n  }\n\n  /**\n   * Change the implementation of an existing indirection.\n   */\n  public patchRule<U extends Names, RET, ARGS extends any[]>(patch: IndirDef<Context, U, RET, ARGS>):\n  IndirBuilder<Context, Names, {[Key in Names]: Key extends U ?\n    IndirDef<Context, Key, RET, ARGS> :\n      (RuleDefs[Key] extends IndirDef<Context, Key> ? RuleDefs[Key] : never)\n  } > {\n    const self = <IndirBuilder<Context, Names, {[Key in Names]: Key extends U ?\n      IndirDef<Context, Key, RET, ARGS> : (RuleDefs[Key] extends IndirDef<Context, Key> ? RuleDefs[Key] : never) }>>\n      <unknown> this;\n    self.rules[patch.name] = <any> patch;\n    return self;\n  }\n\n  /**\n   * Add an indirection function. If the rule already exists, but the implementation differs, an error will be thrown.\n   */\n  public addRuleRedundant<U extends string, RET, ARGS extends any[]>(rule: IndirDef<Context, U, RET, ARGS>):\n  IndirBuilder<Context, Names | U, {[K in Names | U]: K extends U ?\n    IndirDef<Context, K, RET, ARGS> :\n      (K extends Names ? (RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never) : never)\n  }> {\n    const self = <IndirBuilder<Context, Names | U, {[K in Names | U]: K extends U ?\n      IndirDef<Context, K, RET, ARGS> :\n        (K extends Names ? (RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never) : never) }>>\n      <unknown> this;\n    const rules = <Record<string, IndirDef<Context>>> self.rules;\n    if (rules[rule.name] !== undefined && rules[rule.name] !== rule) {\n      throw new Error(`Function ${rule.name} already exists in the builder`);\n    }\n    rules[rule.name] = rule;\n    return self;\n  }\n\n  /**\n   * Add a rule to the grammar. Will raise a typescript error if the rule already exists in the grammar.\n   */\n  public addRule<U extends string, RET, ARGS extends any[]>(\n    rule: CheckOverlap<U, Names, IndirDef<Context, U, RET, ARGS>>,\n  ): IndirBuilder<Context, Names | U, {[K in Names | U]: K extends U ?\n    IndirDef<Context, K, RET, ARGS> :\n      (K extends Names ? (RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never) : never) }> {\n    return this.addRuleRedundant(rule);\n  }\n\n  /**\n   * Add multiple indirection definitions at once using rest parameters.\n   * Provides better TypeScript type inference than calling {@link addRule} in a loop,\n   * but avoid passing too many at once as this can cause TypeScript compilation slowdowns.\n   * TypeScript errors if any name conflicts with an existing one.\n   */\n  public addMany<U extends readonly IndirDef<Context>[]>(\n    ...rules: CheckOverlap<ParseNamesFromList<U>, Names, U>\n  ): IndirBuilder<\n    Context,\n    Names | ParseNamesFromList<U>,\n    {[K in Names | ParseNamesFromList<U>]:\n      K extends keyof ParseIndirsToObject<typeof rules> ? (\n        ParseIndirsToObject<typeof rules>[K] extends IndirDef<Context, K> ? ParseIndirsToObject<typeof rules>[K] : never\n      ) : (\n        K extends Names ? (RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never) : never\n      )\n    }\n  > {\n    this.rules = { ...this.rules, ...listToIndirectionMap(rules) };\n    return <any> <unknown> this;\n  }\n\n  /**\n   * Delete a grammar rule by its name.\n   */\n  public deleteRule<U extends Names>(ruleName: U):\n  IndirBuilder<Context, Exclude<Names, U>, {[K in Exclude<Names, U>]:\n    RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never }> {\n    delete this.rules[ruleName];\n    return <IndirBuilder<Context, Exclude<Names, U>, {[K in Exclude<Names, U>]:\n      RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never }>>\n      <unknown> this;\n  }\n\n  /**\n   * Delete multiple indirection definitions by name in a single call.\n   * @param ruleNames - Names of the indirections to delete.\n   */\n  public deleteMany<U extends Names>(...ruleNames: U[]):\n  IndirBuilder<Context, Exclude<Names, U>, {[K in Exclude<Names, U>]:\n    RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never }> {\n    for (const name of ruleNames) {\n      delete this.rules[name];\n    }\n    return <IndirBuilder<Context, Exclude<Names, U>, {[K in Exclude<Names, U>]:\n      RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never }>>\n      <unknown> this;\n  }\n\n  /**\n   * Retrieve an indirection definition by its name.\n   * Useful for inspecting or wrapping existing definitions when extending a pipeline.\n   * @param ruleName - The name of the indirection, type-checked against the builder's known names.\n   */\n  public getRule<U extends Names>(ruleName: U): RuleDefs[U] extends IndirDef<any, U, infer RT, infer PT> ?\n    IndirDef<Context, U, RT, PT> : never {\n    return <any> this.rules[ruleName];\n  }\n\n  /**\n   * Merge this indirection builder with another.\n   * If the two builders both have a definition with the same name,\n   * no error will be thrown in case they map to the same object (by reference).\n   * If they map to a different object, an error will be thrown.\n   * To fix this problem, the overridingRules array should contain a definition with the same conflicting name,\n   * whose implementation will be used.\n   */\n  public merge<\n    OtherNames extends string,\n    OtherRules extends IndirectionMap<OtherNames>,\n    OW extends readonly IndirDef<Context>[],\n  >(\n    builder: IndirBuilder<Context, OtherNames, OtherRules>,\n    overridingRules: OW,\n  ):\n    IndirBuilder<\n      Context,\n      Names | OtherNames | ParseNamesFromList<OW>,\n      {[K in Names | OtherNames | ParseNamesFromList<OW>]:\n        K extends keyof ParseIndirsToObject<OW> ? (\n          ParseIndirsToObject<OW>[K] extends IndirDef<Context, K> ? ParseIndirsToObject<OW>[K] : never\n        )\n          : (\n              K extends Names ? (RuleDefs[K] extends IndirDef<Context, K> ? RuleDefs[K] : never)\n                : K extends OtherNames ? (OtherRules[K] extends IndirDef<Context, K> ? OtherRules[K] : never) : never\n            ) }\n    > {\n    // Assume the other set is bigger than yours. So start from that one and add this one\n    const otherRules: Record<string, IndirDef<Context>> = { ...builder.rules };\n    const myRules: Record<string, IndirDef<Context>> = this.rules;\n\n    for (const rule of Object.values(myRules)) {\n      if (otherRules[rule.name] === undefined) {\n        otherRules[rule.name] = rule;\n      } else {\n        const existingRule = otherRules[rule.name];\n        // If same rule, no issue, move on. Else\n        if (existingRule !== rule) {\n          const override = overridingRules.find(x => x.name === rule.name);\n          // If override specified, take override, else, inform user that there is a conflict\n          if (override) {\n            otherRules[rule.name] = override;\n          } else {\n            throw new Error(`Function with name \"${rule.name}\" already exists in the builder, specify an override to resolve conflict`);\n          }\n        }\n      }\n    }\n\n    this.rules = <any> <unknown> otherRules;\n    return <any> <unknown> this;\n  }\n\n  /**\n   * Construct an indirection object from the registered definitions.\n   * @returns An object with a method for each registered indirection name.\n   */\n  public build(): IndirectObjFromIndirDefs<Context, Names, RuleDefs> {\n    return <IndirectObjFromIndirDefs<Context, Names, RuleDefs>> new DynamicIndirect(this.rules);\n  }\n}\n"]}

package/dist/esm/lib/indirection-builder/helpers.d.ts

@@ -1,8 +1,25 @@
 import type { ParseNamesFromList } from '../parser-builder/builderTypes.js';
+/**
+ * Definition of an indirection function, analogous to {@link ParserRule} for parsers
+ * and {@link GeneratorRule} for generators.
+ *
+ * An indirection definition has a `name` and a `fun` function.
+ * The `fun` function receives helper utilities (currently just `SUBRULE`) and returns
+ * the actual implementation function that receives a context and optional parameters.
+ *
+ * @typeParam Context - Context object available in the function implementation.
+ * @typeParam NameType - Name of the function, should be a string literal type (e.g., `'myFunction'`).
+ * @typeParam ReturnType - Type returned by the function.
+ * @typeParam ParamType - Tuple of additional parameter types beyond the context.
+ */
 export type IndirDef<Context = any, NameType extends string = string, ReturnType = unknown, ParamType extends any[] = any[]> = {
     name: NameType;
     fun: (def: IndirDefArg) => (c: Context, ...params: ParamType) => ReturnType;
 };
+/**
+ * Helper utilities provided to {@link IndirDef.fun} implementations.
+ * Currently exposes only `SUBRULE` for calling other indirection definitions.
+ */
 export type IndirDefArg = {
     /**
      * Calls another rule using the provided arguments.
@@ -12,6 +29,9 @@ export type IndirDefArg = {
      */
     SUBRULE: <T, U extends any[]>(rule: IndirDef<any, any, T, U>, ...arg: U) => T;
 };
+/**
+ * Record type mapping rule names to their corresponding {@link IndirDef} definitions.
+ */
 export type IndirectionMap<RuleNames extends string> = {
     [Key in RuleNames]: IndirDef<any, Key>;
 };
@@ -25,6 +45,10 @@ export declare function listToIndirectionMap<T extends readonly IndirDef[]>(rule
 export type ParseIndirsToObject<T extends readonly IndirDef[], Names extends string = ParseNamesFromList<T>, Agg extends Record<string, IndirDef> = Record<never, never>> = T extends readonly [infer First, ...infer Rest] ? (First extends IndirDef ? (Rest extends readonly IndirDef[] ? (ParseIndirsToObject<Rest, Names, {
     [K in keyof Agg | First['name']]: K extends First['name'] ? First : Agg[K];
 }>) : never) : never) : IndirectionMap<Names> & Agg;
+/**
+ * The callable object type produced by {@link IndirBuilder.build}.
+ * Maps each rule name to a function with the appropriate context and parameter types.
+ */
 export type IndirectObjFromIndirDefs<Context, Names extends string, RuleDefs extends IndirectionMap<Names>> = {
     [K in Names]: RuleDefs[K] extends IndirDef<Context, K, infer RET, infer ARGS> ? (context: Context, ...args: ARGS) => RET : never;
 };

package/dist/esm/lib/indirection-builder/helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../../lib/indirection-builder/helpers.ts"],"names":[],"mappings":"AAwBA;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAgC,KAAQ;IAC1E,MAAM,QAAQ,GAA6B,EAAE,CAAC;IAC9C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7B,CAAC;IACD,OAA+B,QAAQ,CAAC;AAC1C,CAAC","sourcesContent":["import type { ParseNamesFromList } from '../parser-builder/builderTypes.js';\n\nexport type IndirDef<\n  Context = any,\n  NameType extends string = string,\n  ReturnType = unknown,\n  ParamType extends any[] = any[],\n> = {\n  name: NameType;\n  fun: (def: IndirDefArg) => (c: Context, ...params: ParamType) => ReturnType;\n};\n\nexport type IndirDefArg = {\n  /**\n   * Calls another rule using the provided arguments.\n   * @param rule\n   * @param arg\n   * @constructor\n   */\n  SUBRULE: <T, U extends any[]>(rule: IndirDef<any, any, T, U>, ...arg: U) => T;\n};\n\nexport type IndirectionMap<RuleNames extends string> = {[Key in RuleNames]: IndirDef<any, Key> };\n\n/**\n * Converts a list of ruledefs to a record mapping a name to the corresponding ruledef.\n */\nexport function listToIndirectionMap<T extends readonly IndirDef[]>(rules: T): ParseIndirsToObject<T> {\n  const newRules: Record<string, IndirDef> = {};\n  for (const rule of rules) {\n    newRules[rule.name] = rule;\n  }\n  return <ParseIndirsToObject<T>>newRules;\n}\n\n/**\n * Convert a list of IndirDefs to a Record with the name of the IndirDef as the key, matching the IndirectionMap type.\n */\nexport type ParseIndirsToObject<\n  T extends readonly IndirDef[],\n  Names extends string = ParseNamesFromList<T>,\n  Agg extends Record<string, IndirDef> = Record<never, never>,\n> = T extends readonly [infer First, ...infer Rest] ? (\n  First extends IndirDef ? (\n    Rest extends readonly IndirDef[] ? (\n      ParseIndirsToObject<Rest, Names, {[K in keyof Agg | First['name']]: K extends First['name'] ? First : Agg[K] }>\n    ) : never\n  ) : never\n) : IndirectionMap<Names> & Agg;\n\nexport type IndirectObjFromIndirDefs<Context, Names extends string, RuleDefs extends IndirectionMap<Names>> = {\n  [K in Names]: RuleDefs[K] extends IndirDef<Context, K, infer RET, infer ARGS> ?\n      (context: Context, ...args: ARGS) => RET : never\n};\n"]}
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../../lib/indirection-builder/helpers.ts"],"names":[],"mappings":"AA4CA;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAgC,KAAQ;IAC1E,MAAM,QAAQ,GAA6B,EAAE,CAAC;IAC9C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7B,CAAC;IACD,OAA+B,QAAQ,CAAC;AAC1C,CAAC","sourcesContent":["import type { ParseNamesFromList } from '../parser-builder/builderTypes.js';\n\n/**\n * Definition of an indirection function, analogous to {@link ParserRule} for parsers\n * and {@link GeneratorRule} for generators.\n *\n * An indirection definition has a `name` and a `fun` function.\n * The `fun` function receives helper utilities (currently just `SUBRULE`) and returns\n * the actual implementation function that receives a context and optional parameters.\n *\n * @typeParam Context - Context object available in the function implementation.\n * @typeParam NameType - Name of the function, should be a string literal type (e.g., `'myFunction'`).\n * @typeParam ReturnType - Type returned by the function.\n * @typeParam ParamType - Tuple of additional parameter types beyond the context.\n */\nexport type IndirDef<\n  Context = any,\n  NameType extends string = string,\n  ReturnType = unknown,\n  ParamType extends any[] = any[],\n> = {\n  name: NameType;\n  fun: (def: IndirDefArg) => (c: Context, ...params: ParamType) => ReturnType;\n};\n\n/**\n * Helper utilities provided to {@link IndirDef.fun} implementations.\n * Currently exposes only `SUBRULE` for calling other indirection definitions.\n */\nexport type IndirDefArg = {\n  /**\n   * Calls another rule using the provided arguments.\n   * @param rule\n   * @param arg\n   * @constructor\n   */\n  SUBRULE: <T, U extends any[]>(rule: IndirDef<any, any, T, U>, ...arg: U) => T;\n};\n\n/**\n * Record type mapping rule names to their corresponding {@link IndirDef} definitions.\n */\nexport type IndirectionMap<RuleNames extends string> = {[Key in RuleNames]: IndirDef<any, Key> };\n\n/**\n * Converts a list of ruledefs to a record mapping a name to the corresponding ruledef.\n */\nexport function listToIndirectionMap<T extends readonly IndirDef[]>(rules: T): ParseIndirsToObject<T> {\n  const newRules: Record<string, IndirDef> = {};\n  for (const rule of rules) {\n    newRules[rule.name] = rule;\n  }\n  return <ParseIndirsToObject<T>>newRules;\n}\n\n/**\n * Convert a list of IndirDefs to a Record with the name of the IndirDef as the key, matching the IndirectionMap type.\n */\nexport type ParseIndirsToObject<\n  T extends readonly IndirDef[],\n  Names extends string = ParseNamesFromList<T>,\n  Agg extends Record<string, IndirDef> = Record<never, never>,\n> = T extends readonly [infer First, ...infer Rest] ? (\n  First extends IndirDef ? (\n    Rest extends readonly IndirDef[] ? (\n      ParseIndirsToObject<Rest, Names, {[K in keyof Agg | First['name']]: K extends First['name'] ? First : Agg[K] }>\n    ) : never\n  ) : never\n) : IndirectionMap<Names> & Agg;\n\n/**\n * The callable object type produced by {@link IndirBuilder.build}.\n * Maps each rule name to a function with the appropriate context and parameter types.\n */\nexport type IndirectObjFromIndirDefs<Context, Names extends string, RuleDefs extends IndirectionMap<Names>> = {\n  [K in Names]: RuleDefs[K] extends IndirDef<Context, K, infer RET, infer ARGS> ?\n      (context: Context, ...args: ARGS) => RET : never\n};\n"]}

package/dist/esm/lib/lexer-builder/LexerBuilder.d.ts

@@ -1,22 +1,76 @@
 import type { ILexerConfig, TokenType } from '@traqula/chevrotain';
 import { Lexer } from '@traqula/chevrotain';
 import type { CheckOverlap, NamedToken } from '../utils.js';
+/**
+ * Builder for constructing Chevrotain lexers with type-safe token management.
+ * Token ordering matters — the lexer matches the first token that fits, so more specific
+ * tokens (e.g., keywords) must be positioned before more general ones (e.g., identifiers).
+ *
+ * Builders mutate internal state and return `this`.
+ * Always start by copying an existing builder with `LexerBuilder.create(existingBuilder)`.
+ */
 export declare class LexerBuilder<NAMES extends string = string> {
     private readonly tokens;
+    /**
+     * Create a new LexerBuilder, optionally copying from an existing one.
+     * @param starter - An existing builder to copy tokens from. If omitted, starts empty.
+     */
     static create<U extends LexerBuilder<T>, T extends string = never>(starter?: U): U;
     private constructor();
+    /**
+     * Merge tokens from another LexerBuilder into this one.
+     * Duplicate tokens (by reference) are skipped. Different tokens with the same name
+     * cause an error unless an override is provided.
+     * @param merge - The other builder whose tokens to merge.
+     * @param overwrite - Tokens that take precedence when names conflict.
+     */
     merge<OtherNames extends string, OW extends string>(merge: LexerBuilder<OtherNames>, overwrite?: NamedToken<OW>[]): LexerBuilder<NAMES | OtherNames>;
+    /**
+     * Append tokens to the end of the builder's token list.
+     * TypeScript errors if a token name already exists.
+     * @param token - One or more tokens to add.
+     */
     add<Name extends string>(...token: CheckOverlap<Name, NAMES, NamedToken<Name>[]>): LexerBuilder<Name | NAMES>;
+    /**
+     * Insert tokens before a specified reference token in the ordering.
+     * @param before - The existing token to insert before.
+     * @param token - One or more tokens to insert.
+     */
     addBefore<Name extends string>(before: NamedToken<NAMES>, ...token: CheckOverlap<Name, NAMES, NamedToken<Name>[]>): LexerBuilder<NAMES | Name>;
     private moveBeforeOrAfter;
     /**
-     * @param before token to move rest before
-     * @param tokens tokens to move before the first token
+     * Move existing tokens so they appear before a specified reference token.
+     * The tokens must already exist in the builder.
+     * @param before - The reference token to move before.
+     * @param tokens - The tokens to reposition.
      */
     moveBefore<Name extends string>(before: NamedToken<NAMES>, ...tokens: CheckOverlap<Name, NAMES, never, NamedToken<Name>[]>): LexerBuilder<NAMES>;
+    /**
+     * Move existing tokens so they appear after a specified reference token.
+     * The tokens must already exist in the builder.
+     * @param after - The reference token to move after.
+     * @param tokens - The tokens to reposition.
+     */
     moveAfter<Name extends string>(after: NamedToken<NAMES>, ...tokens: CheckOverlap<Name, NAMES, never, NamedToken<Name>[]>): LexerBuilder<NAMES>;
+    /**
+     * Insert tokens after a specified reference token in the ordering.
+     * @param after - The existing token to insert after.
+     * @param token - One or more tokens to insert.
+     */
     addAfter<Name extends string>(after: NamedToken<NAMES>, ...token: CheckOverlap<Name, NAMES, NamedToken<Name>[]>): LexerBuilder<NAMES | Name>;
+    /**
+     * Remove tokens from the builder by reference.
+     * @param token - One or more tokens to remove. Throws if a token is not found.
+     */
     delete<Name extends NAMES>(...token: NamedToken<Name>[]): LexerBuilder<Exclude<NAMES, Name>>;
+    /**
+     * Construct a Chevrotain {@link Lexer} from the current token ordering.
+     * @param lexerConfig - Optional Chevrotain lexer configuration overrides.
+     */
     build(lexerConfig?: ILexerConfig): Lexer;
+    /**
+     * Get the current token list (readonly).
+     * Useful for passing to {@link ParserBuilder.build} as the `tokenVocabulary` argument.
+     */
     get tokenVocabulary(): readonly TokenType[];
 }

package/dist/esm/lib/lexer-builder/LexerBuilder.js

@@ -1,12 +1,31 @@
 import { Lexer } from '@traqula/chevrotain';
+/**
+ * Builder for constructing Chevrotain lexers with type-safe token management.
+ * Token ordering matters — the lexer matches the first token that fits, so more specific
+ * tokens (e.g., keywords) must be positioned before more general ones (e.g., identifiers).
+ *
+ * Builders mutate internal state and return `this`.
+ * Always start by copying an existing builder with `LexerBuilder.create(existingBuilder)`.
+ */
 export class LexerBuilder {
     tokens;
+    /**
+     * Create a new LexerBuilder, optionally copying from an existing one.
+     * @param starter - An existing builder to copy tokens from. If omitted, starts empty.
+     */
     static create(starter) {
         return new LexerBuilder(starter);
     }
     constructor(starter) {
         this.tokens = starter?.tokens ? [...starter.tokens] : [];
     }
+    /**
+     * Merge tokens from another LexerBuilder into this one.
+     * Duplicate tokens (by reference) are skipped. Different tokens with the same name
+     * cause an error unless an override is provided.
+     * @param merge - The other builder whose tokens to merge.
+     * @param overwrite - Tokens that take precedence when names conflict.
+     */
     merge(merge, overwrite = []) {
         const extraTokens = merge.tokens.filter((token) => {
             const overwriteToken = overwrite.find(t => t.name === token.name);
@@ -25,10 +44,20 @@ export class LexerBuilder {
         this.tokens.push(...extraTokens);
         return this;
     }
+    /**
+     * Append tokens to the end of the builder's token list.
+     * TypeScript errors if a token name already exists.
+     * @param token - One or more tokens to add.
+     */
     add(...token) {
         this.tokens.push(...token);
         return this;
     }
+    /**
+     * Insert tokens before a specified reference token in the ordering.
+     * @param before - The existing token to insert before.
+     * @param token - One or more tokens to insert.
+     */
     addBefore(before, ...token) {
         const index = this.tokens.indexOf(before);
         if (index === -1) {
@@ -53,15 +82,28 @@ export class LexerBuilder {
         return this;
     }
     /**
-     * @param before token to move rest before
-     * @param tokens tokens to move before the first token
+     * Move existing tokens so they appear before a specified reference token.
+     * The tokens must already exist in the builder.
+     * @param before - The reference token to move before.
+     * @param tokens - The tokens to reposition.
      */
     moveBefore(before, ...tokens) {
         return this.moveBeforeOrAfter('before', before, ...tokens);
     }
+    /**
+     * Move existing tokens so they appear after a specified reference token.
+     * The tokens must already exist in the builder.
+     * @param after - The reference token to move after.
+     * @param tokens - The tokens to reposition.
+     */
     moveAfter(after, ...tokens) {
         return this.moveBeforeOrAfter('after', after, ...tokens);
     }
+    /**
+     * Insert tokens after a specified reference token in the ordering.
+     * @param after - The existing token to insert after.
+     * @param token - One or more tokens to insert.
+     */
     addAfter(after, ...token) {
         const index = this.tokens.indexOf(after);
         if (index === -1) {
@@ -70,6 +112,10 @@ export class LexerBuilder {
         this.tokens.splice(index + 1, 0, ...token);
         return this;
     }
+    /**
+     * Remove tokens from the builder by reference.
+     * @param token - One or more tokens to remove. Throws if a token is not found.
+     */
     delete(...token) {
         for (const t of token) {
             const index = this.tokens.indexOf(t);
@@ -80,6 +126,10 @@ export class LexerBuilder {
         }
         return this;
     }
+    /**
+     * Construct a Chevrotain {@link Lexer} from the current token ordering.
+     * @param lexerConfig - Optional Chevrotain lexer configuration overrides.
+     */
     build(lexerConfig) {
         return new Lexer(this.tokens, {
             positionTracking: 'onlyStart',
@@ -90,6 +140,10 @@ export class LexerBuilder {
             ...lexerConfig,
         });
     }
+    /**
+     * Get the current token list (readonly).
+     * Useful for passing to {@link ParserBuilder.build} as the `tokenVocabulary` argument.
+     */
     get tokenVocabulary() {
         return this.tokens;
     }

package/dist/esm/lib/lexer-builder/LexerBuilder.js.map

@@ -1 +1 @@
-{"version":3,"file":"LexerBuilder.js","sourceRoot":"","sources":["../../../../lib/lexer-builder/LexerBuilder.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ILexerConfig, TokenType } from '@traqula/chevrotain';\nimport { Lexer } from '@traqula/chevrotain';\nimport type { CheckOverlap, NamedToken } from '../utils.js';\n\nexport class LexerBuilder<NAMES extends string = string> {\n  private readonly tokens: TokenType[];\n\n  public static create<U extends LexerBuilder<T>, T extends string = never>(starter?: U): U {\n    return <U> new LexerBuilder(starter);\n  }\n\n  private constructor(starter?: LexerBuilder<NAMES>) {\n    this.tokens = starter?.tokens ? [ ...starter.tokens ] : [];\n  }\n\n  public merge<OtherNames extends string, OW extends string>(\n    merge: LexerBuilder<OtherNames>,\n    overwrite: NamedToken<OW>[] = [],\n  ):\n    LexerBuilder<NAMES | OtherNames> {\n    const extraTokens = merge.tokens.filter((token) => {\n      const overwriteToken = overwrite.find(t => t.name === token.name);\n      if (overwriteToken) {\n        return false;\n      }\n      const match = this.tokens.find(t => t.name === token.name);\n      if (match) {\n        if (match !== token) {\n          throw new Error(`Token with name ${token.name} already exists. Implementation is different and no overwrite was provided.`);\n        }\n        return false;\n      }\n      return true;\n    });\n    this.tokens.push(...extraTokens);\n    return this;\n  }\n\n  public add<Name extends string>(...token: CheckOverlap<Name, NAMES, NamedToken<Name>[]>):\n  LexerBuilder<Name | NAMES> {\n    this.tokens.push(...token);\n    return this;\n  }\n\n  public addBefore<Name extends string>(\n    before: NamedToken<NAMES>,\n    ...token: CheckOverlap<Name, NAMES, NamedToken<Name>[]>\n  ): LexerBuilder<NAMES | Name> {\n    const index = this.tokens.indexOf(before);\n    if (index === -1) {\n      throw new Error('Token not found');\n    }\n    this.tokens.splice(index, 0, ...token);\n    return this;\n  }\n\n  private moveBeforeOrAfter<Name extends string>(\n    beforeOrAfter: 'before' | 'after',\n    before: NamedToken<NAMES>,\n    ...tokens: CheckOverlap<Name, NAMES, never, NamedToken<Name>[]>\n  ): LexerBuilder<NAMES> {\n    const beforeIndex = this.tokens.indexOf(before) + (beforeOrAfter === 'before' ? 0 : 1);\n    if (beforeIndex === -1) {\n      throw new Error('BeforeToken not found');\n    }\n    for (const token of tokens) {\n      const tokenIndex = this.tokens.indexOf(token);\n      if (tokenIndex === -1) {\n        throw new Error('Token not found');\n      }\n      this.tokens.splice(tokenIndex, 1);\n      this.tokens.splice(beforeIndex, 0, token);\n    }\n    return this;\n  }\n\n  /**\n   * @param before token to move rest before\n   * @param tokens tokens to move before the first token\n   */\n  public moveBefore<Name extends string>(\n    before: NamedToken<NAMES>,\n    ...tokens: CheckOverlap<Name, NAMES, never, NamedToken<Name>[]>\n  ): LexerBuilder<NAMES> {\n    return this.moveBeforeOrAfter('before', before, ...tokens);\n  }\n\n  public moveAfter<Name extends string>(\n    after: NamedToken<NAMES>,\n    ...tokens: CheckOverlap<Name, NAMES, never, NamedToken<Name>[]>\n  ): LexerBuilder<NAMES> {\n    return this.moveBeforeOrAfter('after', after, ...tokens);\n  }\n\n  public addAfter<Name extends string>(\n    after: NamedToken<NAMES>,\n    ...token: CheckOverlap<Name, NAMES, NamedToken<Name>[]>\n  ): LexerBuilder<NAMES | Name> {\n    const index = this.tokens.indexOf(after);\n    if (index === -1) {\n      throw new Error('Token not found');\n    }\n    this.tokens.splice(index + 1, 0, ...token);\n    return this;\n  }\n\n  public delete<Name extends NAMES>(...token: NamedToken<Name>[]): LexerBuilder<Exclude<NAMES, Name>> {\n    for (const t of token) {\n      const index = this.tokens.indexOf(t);\n      if (index === -1) {\n        throw new Error('Token not found');\n      }\n      this.tokens.splice(index, 1);\n    }\n    return this;\n  }\n\n  public build(lexerConfig?: ILexerConfig): Lexer {\n    return new Lexer(this.tokens, {\n      positionTracking: 'onlyStart',\n      recoveryEnabled: false,\n      ensureOptimizations: true,\n      // SafeMode: true,\n      // SkipValidations: true,\n      ...lexerConfig,\n    });\n  }\n\n  public get tokenVocabulary(): readonly TokenType[] {\n    return this.tokens;\n  }\n}\n"]}
+{"version":3,"file":"LexerBuilder.js","sourceRoot":"","sources":["../../../../lib/lexer-builder/LexerBuilder.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ILexerConfig, TokenType } from '@traqula/chevrotain';\nimport { Lexer } from '@traqula/chevrotain';\nimport type { CheckOverlap, NamedToken } from '../utils.js';\n\n/**\n * Builder for constructing Chevrotain lexers with type-safe token management.\n * Token ordering matters — the lexer matches the first token that fits, so more specific\n * tokens (e.g., keywords) must be positioned before more general ones (e.g., identifiers).\n *\n * Builders mutate internal state and return `this`.\n * Always start by copying an existing builder with `LexerBuilder.create(existingBuilder)`.\n */\nexport class LexerBuilder<NAMES extends string = string> {\n  private readonly tokens: TokenType[];\n\n  /**\n   * Create a new LexerBuilder, optionally copying from an existing one.\n   * @param starter - An existing builder to copy tokens from. If omitted, starts empty.\n   */\n  public static create<U extends LexerBuilder<T>, T extends string = never>(starter?: U): U {\n    return <U> new LexerBuilder(starter);\n  }\n\n  private constructor(starter?: LexerBuilder<NAMES>) {\n    this.tokens = starter?.tokens ? [ ...starter.tokens ] : [];\n  }\n\n  /**\n   * Merge tokens from another LexerBuilder into this one.\n   * Duplicate tokens (by reference) are skipped. Different tokens with the same name\n   * cause an error unless an override is provided.\n   * @param merge - The other builder whose tokens to merge.\n   * @param overwrite - Tokens that take precedence when names conflict.\n   */\n  public merge<OtherNames extends string, OW extends string>(\n    merge: LexerBuilder<OtherNames>,\n    overwrite: NamedToken<OW>[] = [],\n  ):\n    LexerBuilder<NAMES | OtherNames> {\n    const extraTokens = merge.tokens.filter((token) => {\n      const overwriteToken = overwrite.find(t => t.name === token.name);\n      if (overwriteToken) {\n        return false;\n      }\n      const match = this.tokens.find(t => t.name === token.name);\n      if (match) {\n        if (match !== token) {\n          throw new Error(`Token with name ${token.name} already exists. Implementation is different and no overwrite was provided.`);\n        }\n        return false;\n      }\n      return true;\n    });\n    this.tokens.push(...extraTokens);\n    return this;\n  }\n\n  /**\n   * Append tokens to the end of the builder's token list.\n   * TypeScript errors if a token name already exists.\n   * @param token - One or more tokens to add.\n   */\n  public add<Name extends string>(...token: CheckOverlap<Name, NAMES, NamedToken<Name>[]>):\n  LexerBuilder<Name | NAMES> {\n    this.tokens.push(...token);\n    return this;\n  }\n\n  /**\n   * Insert tokens before a specified reference token in the ordering.\n   * @param before - The existing token to insert before.\n   * @param token - One or more tokens to insert.\n   */\n  public addBefore<Name extends string>(\n    before: NamedToken<NAMES>,\n    ...token: CheckOverlap<Name, NAMES, NamedToken<Name>[]>\n  ): LexerBuilder<NAMES | Name> {\n    const index = this.tokens.indexOf(before);\n    if (index === -1) {\n      throw new Error('Token not found');\n    }\n    this.tokens.splice(index, 0, ...token);\n    return this;\n  }\n\n  private moveBeforeOrAfter<Name extends string>(\n    beforeOrAfter: 'before' | 'after',\n    before: NamedToken<NAMES>,\n    ...tokens: CheckOverlap<Name, NAMES, never, NamedToken<Name>[]>\n  ): LexerBuilder<NAMES> {\n    const beforeIndex = this.tokens.indexOf(before) + (beforeOrAfter === 'before' ? 0 : 1);\n    if (beforeIndex === -1) {\n      throw new Error('BeforeToken not found');\n    }\n    for (const token of tokens) {\n      const tokenIndex = this.tokens.indexOf(token);\n      if (tokenIndex === -1) {\n        throw new Error('Token not found');\n      }\n      this.tokens.splice(tokenIndex, 1);\n      this.tokens.splice(beforeIndex, 0, token);\n    }\n    return this;\n  }\n\n  /**\n   * Move existing tokens so they appear before a specified reference token.\n   * The tokens must already exist in the builder.\n   * @param before - The reference token to move before.\n   * @param tokens - The tokens to reposition.\n   */\n  public moveBefore<Name extends string>(\n    before: NamedToken<NAMES>,\n    ...tokens: CheckOverlap<Name, NAMES, never, NamedToken<Name>[]>\n  ): LexerBuilder<NAMES> {\n    return this.moveBeforeOrAfter('before', before, ...tokens);\n  }\n\n  /**\n   * Move existing tokens so they appear after a specified reference token.\n   * The tokens must already exist in the builder.\n   * @param after - The reference token to move after.\n   * @param tokens - The tokens to reposition.\n   */\n  public moveAfter<Name extends string>(\n    after: NamedToken<NAMES>,\n    ...tokens: CheckOverlap<Name, NAMES, never, NamedToken<Name>[]>\n  ): LexerBuilder<NAMES> {\n    return this.moveBeforeOrAfter('after', after, ...tokens);\n  }\n\n  /**\n   * Insert tokens after a specified reference token in the ordering.\n   * @param after - The existing token to insert after.\n   * @param token - One or more tokens to insert.\n   */\n  public addAfter<Name extends string>(\n    after: NamedToken<NAMES>,\n    ...token: CheckOverlap<Name, NAMES, NamedToken<Name>[]>\n  ): LexerBuilder<NAMES | Name> {\n    const index = this.tokens.indexOf(after);\n    if (index === -1) {\n      throw new Error('Token not found');\n    }\n    this.tokens.splice(index + 1, 0, ...token);\n    return this;\n  }\n\n  /**\n   * Remove tokens from the builder by reference.\n   * @param token - One or more tokens to remove. Throws if a token is not found.\n   */\n  public delete<Name extends NAMES>(...token: NamedToken<Name>[]): LexerBuilder<Exclude<NAMES, Name>> {\n    for (const t of token) {\n      const index = this.tokens.indexOf(t);\n      if (index === -1) {\n        throw new Error('Token not found');\n      }\n      this.tokens.splice(index, 1);\n    }\n    return this;\n  }\n\n  /**\n   * Construct a Chevrotain {@link Lexer} from the current token ordering.\n   * @param lexerConfig - Optional Chevrotain lexer configuration overrides.\n   */\n  public build(lexerConfig?: ILexerConfig): Lexer {\n    return new Lexer(this.tokens, {\n      positionTracking: 'onlyStart',\n      recoveryEnabled: false,\n      ensureOptimizations: true,\n      // SafeMode: true,\n      // SkipValidations: true,\n      ...lexerConfig,\n    });\n  }\n\n  /**\n   * Get the current token list (readonly).\n   * Useful for passing to {@link ParserBuilder.build} as the `tokenVocabulary` argument.\n   */\n  public get tokenVocabulary(): readonly TokenType[] {\n    return this.tokens;\n  }\n}\n"]}