@traqula/core 0.0.24 → 1.0.0

package/dist/esm/lib/transformers/TransformerTyped.d.ts

@@ -1,5 +1,5 @@
 import type { Typed } from '../types.js';
-import type { SelectiveTraversalContext, TransformContext, VisitContext } from './TransformerObject.js';
+import type { TransformContext, VisitContext } from './TransformerObject.js';
 import { TransformerObject } from './TransformerObject.js';
 export type Safeness = 'safe' | 'unsafe';
 export type SafeWrap<Safe extends Safeness, obj extends object> = Safe extends 'safe' ? {
@@ -13,14 +13,17 @@ export declare class TransformerTyped<Nodes extends Typed> extends TransformerOb
     constructor(defaultContext?: TransformContext, defaultNodePreVisitor?: DefaultNodePreVisitor<Nodes>);
     clone(newDefaultContext?: TransformContext, newDefaultNodePreVisitor?: DefaultNodePreVisitor<Nodes>): TransformerTyped<Nodes>;
     /**
-     * Transform a single node.
-     * The transformation calls the preVisitor from starting from the startObject.
-     * The preVisitor can dictate whether transformation should be stopped.
-     * Note that stopping the transformation also prevets further copying.
-     * The transformer itself transforms object starting with the deepest one that can be visited.
-     * The transformer callback is performed on a copy of the original.
-     * @param startObject
-     * @param nodeCallBacks
+     * Transform a single node ({@link Typed}).
+     * @param startObject the object from which we will start the transformation,
+     *   potentially visiting and transforming its descendants along the way.
+     * @param nodeCallBacks a dictionary mapping the various node types to objects optionally
+     *    containing preVisitor and transformer.
+     *    The preVisitor allows you to provide {@link TransformContext} for the current object,
+     *    altering how it will be transformed.
+     *    The transformer allows you to manipulate the copy of the current object,
+     *    and expects you to return the value that should take the current objects place.
+     * @return the result of transforming the requested descendant operations (based on the preVisitor)
+     * using a transformer that works its way back up from the descendant to the startObject.
      */
     transformNode<Safe extends Safeness = 'safe', OutType = unknown>(startObject: object, nodeCallBacks: {
         [T in Nodes['type']]?: {
@@ -29,10 +32,19 @@ export declare class TransformerTyped<Nodes extends Typed> extends TransformerOb
         };
     }): Safe extends 'unsafe' ? OutType : unknown;
     /**
-     * Similar to {@link this.transformNode}, but without copying the startObject.
+     * Visit a selected subTree given a startObject, steering the visits based on {@link Typed} nodes.
+     * Will first call the preVisitor on the project and notice it should not iterate on its descendants.
+     * It then visits the project, and the outermost distinct, printing '21'.
      * The pre-visitor visits starting from the root, going deeper, while the actual visitor goes in reverse.
-     * @param startObject
-     * @param nodeCallBacks
+     * @param startObject the object from which we will start visiting,
+     *   potentially visiting its descendants along the way.
+     * @param nodeCallBacks a dictionary mapping the various operation types to objects optionally
+     *    containing preVisitor and visitor.
+     *    The preVisitor allows you to provide {@link VisitContext} for the current object,
+     *    altering how it will be visited.
+     *    The visitor allows you to visit the object from deepest to the outermost object.
+     *    This is useful if you for example want to manipulate the objects you visit during your visits,
+     *    similar to {@link this.transformNode}.
      */
     visitNode(startObject: object, nodeCallBacks: {
         [T in Nodes['type']]?: {
@@ -40,12 +52,4 @@ export declare class TransformerTyped<Nodes extends Typed> extends TransformerOb
             preVisitor?: (op: Extract<Nodes, Typed<T>>) => VisitContext;
         };
     }): void;
-    /**
-     * Traverses only selected nodes as returned by the function.
-     * @param currentNode
-     * @param traverse
-     */
-    traverseNodes(currentNode: Nodes, traverse: {
-        [T in Nodes['type']]?: (op: Extract<Nodes, Typed<T>>) => SelectiveTraversalContext<Nodes>;
-    }): void;
 }

package/dist/esm/lib/transformers/TransformerTyped.js

@@ -10,14 +10,17 @@ export class TransformerTyped extends TransformerObject {
         return new TransformerTyped({ ...this.defaultContext, ...newDefaultContext }, { ...this.defaultNodePreVisitor, ...newDefaultNodePreVisitor });
     }
     /**
-     * Transform a single node.
-     * The transformation calls the preVisitor from starting from the startObject.
-     * The preVisitor can dictate whether transformation should be stopped.
-     * Note that stopping the transformation also prevets further copying.
-     * The transformer itself transforms object starting with the deepest one that can be visited.
-     * The transformer callback is performed on a copy of the original.
-     * @param startObject
-     * @param nodeCallBacks
+     * Transform a single node ({@link Typed}).
+     * @param startObject the object from which we will start the transformation,
+     *   potentially visiting and transforming its descendants along the way.
+     * @param nodeCallBacks a dictionary mapping the various node types to objects optionally
+     *    containing preVisitor and transformer.
+     *    The preVisitor allows you to provide {@link TransformContext} for the current object,
+     *    altering how it will be transformed.
+     *    The transformer allows you to manipulate the copy of the current object,
+     *    and expects you to return the value that should take the current objects place.
+     * @return the result of transforming the requested descendant operations (based on the preVisitor)
+     * using a transformer that works its way back up from the descendant to the startObject.
      */
     transformNode(startObject, nodeCallBacks) {
         const transformWrapper = (copy, orig) => {
@@ -42,10 +45,19 @@ export class TransformerTyped extends TransformerObject {
         return this.transformObject(startObject, transformWrapper, preVisitWrapper);
     }
     /**
-     * Similar to {@link this.transformNode}, but without copying the startObject.
+     * Visit a selected subTree given a startObject, steering the visits based on {@link Typed} nodes.
+     * Will first call the preVisitor on the project and notice it should not iterate on its descendants.
+     * It then visits the project, and the outermost distinct, printing '21'.
      * The pre-visitor visits starting from the root, going deeper, while the actual visitor goes in reverse.
-     * @param startObject
-     * @param nodeCallBacks
+     * @param startObject the object from which we will start visiting,
+     *   potentially visiting its descendants along the way.
+     * @param nodeCallBacks a dictionary mapping the various operation types to objects optionally
+     *    containing preVisitor and visitor.
+     *    The preVisitor allows you to provide {@link VisitContext} for the current object,
+     *    altering how it will be visited.
+     *    The visitor allows you to visit the object from deepest to the outermost object.
+     *    This is useful if you for example want to manipulate the objects you visit during your visits,
+     *    similar to {@link this.transformNode}.
      */
     visitNode(startObject, nodeCallBacks) {
         const visitorWrapper = (curObject) => {
@@ -70,29 +82,5 @@ export class TransformerTyped extends TransformerObject {
         };
         return this.visitObject(startObject, visitorWrapper, preVisitWrapper);
     }
-    /**
-     * Traverses only selected nodes as returned by the function.
-     * @param currentNode
-     * @param traverse
-     */
-    traverseNodes(currentNode, traverse) {
-        let didShortCut = false;
-        const recurse = (curNode) => {
-            const traverser = traverse[curNode.type];
-            if (traverser) {
-                const { next, shortcut } = traverser(curNode);
-                didShortCut = shortcut ?? false;
-                if (!didShortCut) {
-                    for (const node of next ?? []) {
-                        if (didShortCut) {
-                            return;
-                        }
-                        recurse(node);
-                    }
-                }
-            }
-        };
-        recurse(currentNode);
-    }
 }
 //# sourceMappingURL=TransformerTyped.js.map

package/dist/esm/lib/transformers/TransformerTyped.js.map

@@ -1 +1 @@
-{"version":3,"file":"TransformerTyped.js","sourceRoot":"","sources":["../../../../lib/transformers/TransformerTyped.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Typed } from '../types.js';\nimport type { SelectiveTraversalContext, TransformContext, VisitContext } from './TransformerObject.js';\nimport { TransformerObject } from './TransformerObject.js';\n\nexport type Safeness = 'safe' | 'unsafe';\nexport type SafeWrap<Safe extends Safeness, obj extends object> =\n  Safe extends 'safe' ? {[key in keyof obj]: unknown } : obj;\n\nexport type DefaultNodePreVisitor<Nodes extends Typed> = {[T in Nodes['type']]?: TransformContext };\n\nexport class TransformerTyped<Nodes extends Typed> extends TransformerObject {\n  public constructor(\n    defaultContext: TransformContext = {},\n    protected defaultNodePreVisitor: DefaultNodePreVisitor<Nodes> = {},\n  ) {\n    super(defaultContext);\n  };\n\n  public override clone(\n    newDefaultContext: TransformContext = {},\n    newDefaultNodePreVisitor: DefaultNodePreVisitor<Nodes> = {},\n  ): TransformerTyped<Nodes> {\n    return new TransformerTyped(\n      { ...this.defaultContext, ...newDefaultContext },\n      { ...this.defaultNodePreVisitor, ...newDefaultNodePreVisitor },\n    );\n  }\n\n  /**\n   * Transform a single node.\n   * The transformation calls the preVisitor from starting from the startObject.\n   * The preVisitor can dictate whether transformation should be stopped.\n   * Note that stopping the transformation also prevets further copying.\n   * The transformer itself transforms object starting with the deepest one that can be visited.\n   * The transformer callback is performed on a copy of the original.\n   * @param startObject\n   * @param nodeCallBacks\n   */\n  public transformNode<Safe extends Safeness = 'safe', OutType = unknown>(\n    startObject: object,\n    nodeCallBacks: {[T in Nodes['type']]?: {\n      transform?: (copy: SafeWrap<Safe, Extract<Nodes, Typed<T>>>, orig: Extract<Nodes, Typed<T>>) => unknown;\n      preVisitor?: (orig: Extract<Nodes, Typed<T>>) => TransformContext;\n    }},\n  ): Safe extends 'unsafe' ? OutType : unknown {\n    const transformWrapper = (copy: object, orig: object): unknown => {\n      let ogTransform: ((copy: any, orig: any) => unknown) | undefined;\n      const casted = <Typed<Nodes['type']>>copy;\n      if (casted.type) {\n        ogTransform = nodeCallBacks[casted.type]?.transform;\n      }\n      return ogTransform ? ogTransform(casted, orig) : copy;\n    };\n    const nodeDefaults = this.defaultNodePreVisitor;\n    const preVisitWrapper = (curObject: object): VisitContext => {\n      let ogPreVisit: ((node: any) => VisitContext) | undefined;\n      let nodeContext: VisitContext = {};\n      const casted = <Typed<Nodes['type']>>curObject;\n      if (casted.type) {\n        ogPreVisit = nodeCallBacks[casted.type]?.preVisitor;\n        nodeContext = nodeDefaults[casted.type] ?? nodeContext;\n      }\n      return ogPreVisit ? { ...nodeContext, ...ogPreVisit(casted) } : nodeContext;\n    };\n    return <any> this.transformObject(startObject, transformWrapper, preVisitWrapper);\n  }\n\n  /**\n   * Similar to {@link this.transformNode}, but without copying the startObject.\n   * The pre-visitor visits starting from the root, going deeper, while the actual visitor goes in reverse.\n   * @param startObject\n   * @param nodeCallBacks\n   */\n  public visitNode(\n    startObject: object,\n    nodeCallBacks: {[T in Nodes['type']]?: {\n      visitor?: (op: Extract<Nodes, Typed<T>>) => void;\n      preVisitor?: (op: Extract<Nodes, Typed<T>>) => VisitContext;\n    }},\n  ): void {\n    const visitorWrapper = (curObject: object): void => {\n      const casted = <Typed<Nodes['type']>>curObject;\n      if (casted.type) {\n        const ogTransform = nodeCallBacks[casted.type]?.visitor;\n        if (ogTransform) {\n          ogTransform(<any> casted);\n        }\n      }\n    };\n    const nodeDefaults = this.defaultNodePreVisitor;\n    const preVisitWrapper = (curObject: object): VisitContext => {\n      let ogPreVisit: ((node: any) => VisitContext) | undefined;\n      let nodeContext: VisitContext = {};\n      const casted = <Typed<Nodes['type']>>curObject;\n      if (casted.type) {\n        ogPreVisit = nodeCallBacks[casted.type]?.preVisitor;\n        nodeContext = nodeDefaults[casted.type] ?? nodeContext;\n      }\n      return ogPreVisit ? { ...nodeContext, ...ogPreVisit(casted) } : nodeContext;\n    };\n    return this.visitObject(startObject, visitorWrapper, preVisitWrapper);\n  }\n\n  /**\n   * Traverses only selected nodes as returned by the function.\n   * @param currentNode\n   * @param traverse\n   */\n  public traverseNodes(\n    currentNode: Nodes,\n    traverse: {[T in Nodes['type']]?: (op: Extract<Nodes, Typed<T>>) => SelectiveTraversalContext<Nodes> },\n  ): void {\n    let didShortCut = false;\n\n    const recurse = (curNode: Nodes): void => {\n      const traverser = traverse[<Nodes['type']>curNode.type];\n      if (traverser) {\n        const { next, shortcut } = traverser(<any>curNode);\n        didShortCut = shortcut ?? false;\n        if (!didShortCut) {\n          for (const node of next ?? []) {\n            if (didShortCut) {\n              return;\n            }\n            recurse(node);\n          }\n        }\n      }\n    };\n\n    recurse(currentNode);\n  }\n}\n"]}
+{"version":3,"file":"TransformerTyped.js","sourceRoot":"","sources":["../../../../lib/transformers/TransformerTyped.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Typed } from '../types.js';\nimport type { TransformContext, VisitContext } from './TransformerObject.js';\nimport { TransformerObject } from './TransformerObject.js';\n\nexport type Safeness = 'safe' | 'unsafe';\nexport type SafeWrap<Safe extends Safeness, obj extends object> =\n  Safe extends 'safe' ? {[key in keyof obj]: unknown } : obj;\n\nexport type DefaultNodePreVisitor<Nodes extends Typed> = {[T in Nodes['type']]?: TransformContext };\n\nexport class TransformerTyped<Nodes extends Typed> extends TransformerObject {\n  public constructor(\n    defaultContext: TransformContext = {},\n    protected defaultNodePreVisitor: DefaultNodePreVisitor<Nodes> = {},\n  ) {\n    super(defaultContext);\n  };\n\n  public override clone(\n    newDefaultContext: TransformContext = {},\n    newDefaultNodePreVisitor: DefaultNodePreVisitor<Nodes> = {},\n  ): TransformerTyped<Nodes> {\n    return new TransformerTyped(\n      { ...this.defaultContext, ...newDefaultContext },\n      { ...this.defaultNodePreVisitor, ...newDefaultNodePreVisitor },\n    );\n  }\n\n  /**\n   * Transform a single node ({@link Typed}).\n   * @param startObject the object from which we will start the transformation,\n   *   potentially visiting and transforming its descendants along the way.\n   * @param nodeCallBacks a dictionary mapping the various node types to objects optionally\n   *    containing preVisitor and transformer.\n   *    The preVisitor allows you to provide {@link TransformContext} for the current object,\n   *    altering how it will be transformed.\n   *    The transformer allows you to manipulate the copy of the current object,\n   *    and expects you to return the value that should take the current objects place.\n   * @return the result of transforming the requested descendant operations (based on the preVisitor)\n   * using a transformer that works its way back up from the descendant to the startObject.\n   */\n  public transformNode<Safe extends Safeness = 'safe', OutType = unknown>(\n    startObject: object,\n    nodeCallBacks: {[T in Nodes['type']]?: {\n      transform?: (copy: SafeWrap<Safe, Extract<Nodes, Typed<T>>>, orig: Extract<Nodes, Typed<T>>) => unknown;\n      preVisitor?: (orig: Extract<Nodes, Typed<T>>) => TransformContext;\n    }},\n  ): Safe extends 'unsafe' ? OutType : unknown {\n    const transformWrapper = (copy: object, orig: object): unknown => {\n      let ogTransform: ((copy: any, orig: any) => unknown) | undefined;\n      const casted = <Typed<Nodes['type']>>copy;\n      if (casted.type) {\n        ogTransform = nodeCallBacks[casted.type]?.transform;\n      }\n      return ogTransform ? ogTransform(casted, orig) : copy;\n    };\n    const nodeDefaults = this.defaultNodePreVisitor;\n    const preVisitWrapper = (curObject: object): VisitContext => {\n      let ogPreVisit: ((node: any) => VisitContext) | undefined;\n      let nodeContext: VisitContext = {};\n      const casted = <Typed<Nodes['type']>>curObject;\n      if (casted.type) {\n        ogPreVisit = nodeCallBacks[casted.type]?.preVisitor;\n        nodeContext = nodeDefaults[casted.type] ?? nodeContext;\n      }\n      return ogPreVisit ? { ...nodeContext, ...ogPreVisit(casted) } : nodeContext;\n    };\n    return <any> this.transformObject(startObject, transformWrapper, preVisitWrapper);\n  }\n\n  /**\n   * Visit a selected subTree given a startObject, steering the visits based on {@link Typed} nodes.\n   * Will first call the preVisitor on the project and notice it should not iterate on its descendants.\n   * It then visits the project, and the outermost distinct, printing '21'.\n   * The pre-visitor visits starting from the root, going deeper, while the actual visitor goes in reverse.\n   * @param startObject the object from which we will start visiting,\n   *   potentially visiting its descendants along the way.\n   * @param nodeCallBacks a dictionary mapping the various operation types to objects optionally\n   *    containing preVisitor and visitor.\n   *    The preVisitor allows you to provide {@link VisitContext} for the current object,\n   *    altering how it will be visited.\n   *    The visitor allows you to visit the object from deepest to the outermost object.\n   *    This is useful if you for example want to manipulate the objects you visit during your visits,\n   *    similar to {@link this.transformNode}.\n   */\n  public visitNode(\n    startObject: object,\n    nodeCallBacks: {[T in Nodes['type']]?: {\n      visitor?: (op: Extract<Nodes, Typed<T>>) => void;\n      preVisitor?: (op: Extract<Nodes, Typed<T>>) => VisitContext;\n    }},\n  ): void {\n    const visitorWrapper = (curObject: object): void => {\n      const casted = <Typed<Nodes['type']>>curObject;\n      if (casted.type) {\n        const ogTransform = nodeCallBacks[casted.type]?.visitor;\n        if (ogTransform) {\n          ogTransform(<any> casted);\n        }\n      }\n    };\n    const nodeDefaults = this.defaultNodePreVisitor;\n    const preVisitWrapper = (curObject: object): VisitContext => {\n      let ogPreVisit: ((node: any) => VisitContext) | undefined;\n      let nodeContext: VisitContext = {};\n      const casted = <Typed<Nodes['type']>>curObject;\n      if (casted.type) {\n        ogPreVisit = nodeCallBacks[casted.type]?.preVisitor;\n        nodeContext = nodeDefaults[casted.type] ?? nodeContext;\n      }\n      return ogPreVisit ? { ...nodeContext, ...ogPreVisit(casted) } : nodeContext;\n    };\n    return this.visitObject(startObject, visitorWrapper, preVisitWrapper);\n  }\n}\n"]}

package/dist/esm/lib/types.d.ts

@@ -1,22 +1,33 @@
+/**
+ * Type that is used by the Traqula core package to type raw objects/ Data Transfer Objects (DTO).
+ * Enforces the presence of a type string, and that in case the subType key is present, it also be a string.
+ */
 export interface Typed<Type extends string = string> {
     type: Type;
     subType?: string;
 }
+/**
+ * A {@link Typed} object that is sure to have a subType
+ */
 export interface SubTyped<Type extends string = string, SubType extends string = string> extends Typed<Type> {
     subType: SubType;
 }
+/**
+ * Type used by the parser and generator builders of the core Traqula package to annotate
+ * the relation between AST objects and the source string.
+ */
 export interface Localized {
-    /**
-     * Location undefined means the node does have a string representation, but it was not clarified.
-     * This happens when an AST node is patched by a client of the lib.
-     */
     loc: SourceLocation;
 }
+/**
+ * Wrapper type for localization,
+ * can be used to state localization information about any other type (including primitive types)
+ */
 export interface Wrap<T> extends Localized {
     val: T;
 }
 /**
- * A AST node. Nodes are indexable by their types.
+ * An AST node. Nodes are indexable by their types.
  * When generating, the SUBRULES called should be located within the current location range.
  */
 export interface Node extends Localized, Typed {
@@ -24,11 +35,38 @@ export interface Node extends Localized, Typed {
 export interface SourceLocationBase {
     sourceLocationType: string;
 }
+/**
+ * SourceLocation type that annotates that the node represents the AST representation of
+ * the given range in the source string.
+ */
 export interface SourceLocationSource extends SourceLocationBase {
     sourceLocationType: 'source';
     start: number;
     end: number;
 }
+/**
+ * Similar to {@link SourceLocationSource} but also carrying the source it related too.
+ * All sourceLocation nodes that are descends of this one, relate themselves to this source.
+ */
+export interface SourceLocationInlinedSource extends SourceLocationBase, Localized {
+    sourceLocationType: 'inlinedSource';
+    /**
+     * The string that will be used as the source for this node and the descends of this node.
+     * Note that the generator will print the characters from newSource[0] until start. Likewise for the suffix.
+     */
+    newSource: string;
+    /**
+     * Behavior of the current loc, after replacing the source string.
+     */
+    loc: SourceLocation;
+    /**
+     * The range that this node replaces in the context of the original source.
+     */
+    start: number;
+    end: number;
+    startOnNew: number;
+    endOnNew: number;
+}
 /**
  * NoStringManifestation means the node does not have a string representation.
  * For example the literal '5' has an integer type (which is an AST node),
@@ -38,15 +76,39 @@ export interface SourceLocationSource extends SourceLocationBase {
 export interface SourceLocationNoMaterialize extends SourceLocationBase {
     sourceLocationType: 'noMaterialize';
 }
+/**
+ * SourceLocation type that annotates that the node has been replaced
+ *   in relation to the original string by a new string.
+ * It means that this node should be generated, and that the source string from start to end has been changed.
+ */
 export interface SourceLocationStringReplace extends SourceLocationBase {
     sourceLocationType: 'stringReplace';
+    /**
+     * The string that will replace the given range in the original source.
+     */
     newSource: string;
+    /**
+     * The start of the region in the original source string that this node replaces.
+     */
     start: number;
+    /**
+     * The end of the region in the original source string that this node replaces.
+     */
     end: number;
 }
+/**
+ * SourceLocation type that annotates that the node has been replaced in relation to the original string.
+ * It means that this node should be generated, and that the source string from start to end has been changed.
+ */
 export interface SourceLocationNodeReplace extends SourceLocationBase {
     sourceLocationType: 'nodeReplace';
+    /**
+     * The start of the region in the original source string that this node replaces.
+     */
     start: number;
+    /**
+     * The end of the region in the original source string that this node replaces.
+     */
     end: number;
 }
 /**
@@ -55,4 +117,4 @@ export interface SourceLocationNodeReplace extends SourceLocationBase {
 export interface SourceLocationNodeAutoGenerate extends SourceLocationBase {
     sourceLocationType: 'autoGenerate';
 }
-export type SourceLocation = SourceLocationSource | SourceLocationNoMaterialize | SourceLocationStringReplace | SourceLocationNodeReplace | SourceLocationNodeAutoGenerate;
+export type SourceLocation = SourceLocationSource | SourceLocationInlinedSource | SourceLocationNoMaterialize | SourceLocationStringReplace | SourceLocationNodeReplace | SourceLocationNodeAutoGenerate;

package/dist/esm/lib/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../lib/types.ts"],"names":[],"mappings":"","sourcesContent":["export interface Typed<Type extends string = string> {\n  type: Type;\n  subType?: string;\n}\n\nexport interface SubTyped<Type extends string = string, SubType extends string = string> extends Typed<Type> {\n  subType: SubType;\n}\n\nexport interface Localized {\n  /**\n   * Location undefined means the node does have a string representation, but it was not clarified.\n   * This happens when an AST node is patched by a client of the lib.\n   */\n  loc: SourceLocation;\n}\n\nexport interface Wrap<T> extends Localized {\n  val: T;\n}\n\n/**\n * A AST node. Nodes are indexable by their types.\n * When generating, the SUBRULES called should be located within the current location range.\n */\nexport interface Node extends Localized, Typed {}\n\nexport interface SourceLocationBase {\n  sourceLocationType: string;\n}\n\nexport interface SourceLocationSource extends SourceLocationBase {\n  sourceLocationType: 'source';\n  start: number;\n  end: number;\n}\n\n/**\n * NoStringManifestation means the node does not have a string representation.\n * For example the literal '5' has an integer type (which is an AST node),\n * but the type does not have an associated string representation.\n * When set to true, the node will not be printed, start and end are meaningless in this case.\n */\nexport interface SourceLocationNoMaterialize extends SourceLocationBase {\n  sourceLocationType: 'noMaterialize';\n}\n\nexport interface SourceLocationStringReplace extends SourceLocationBase {\n  sourceLocationType: 'stringReplace';\n  newSource: string;\n  start: number;\n  end: number;\n}\n\nexport interface SourceLocationNodeReplace extends SourceLocationBase {\n  sourceLocationType: 'nodeReplace';\n  start: number;\n  end: number;\n}\n/**\n * Must have an ancestor of type {@link SourceLocationNodeReplace}\n */\nexport interface SourceLocationNodeAutoGenerate extends SourceLocationBase {\n  sourceLocationType: 'autoGenerate';\n}\n\nexport type SourceLocation =\n  | SourceLocationSource\n  | SourceLocationNoMaterialize\n  | SourceLocationStringReplace\n  | SourceLocationNodeReplace\n  | SourceLocationNodeAutoGenerate;\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../lib/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Type that is used by the Traqula core package to type raw objects/ Data Transfer Objects (DTO).\n * Enforces the presence of a type string, and that in case the subType key is present, it also be a string.\n */\nexport interface Typed<Type extends string = string> {\n  type: Type;\n  subType?: string;\n}\n\n/**\n * A {@link Typed} object that is sure to have a subType\n */\nexport interface SubTyped<Type extends string = string, SubType extends string = string> extends Typed<Type> {\n  subType: SubType;\n}\n\n/**\n * Type used by the parser and generator builders of the core Traqula package to annotate\n * the relation between AST objects and the source string.\n */\nexport interface Localized {\n  loc: SourceLocation;\n}\n\n/**\n * Wrapper type for localization,\n * can be used to state localization information about any other type (including primitive types)\n */\nexport interface Wrap<T> extends Localized {\n  val: T;\n}\n\n/**\n * An AST node. Nodes are indexable by their types.\n * When generating, the SUBRULES called should be located within the current location range.\n */\nexport interface Node extends Localized, Typed {}\n\nexport interface SourceLocationBase {\n  sourceLocationType: string;\n}\n\n/**\n * SourceLocation type that annotates that the node represents the AST representation of\n * the given range in the source string.\n */\nexport interface SourceLocationSource extends SourceLocationBase {\n  sourceLocationType: 'source';\n  start: number;\n  end: number;\n}\n\n/**\n * Similar to {@link SourceLocationSource} but also carrying the source it related too.\n * All sourceLocation nodes that are descends of this one, relate themselves to this source.\n */\nexport interface SourceLocationInlinedSource extends SourceLocationBase, Localized {\n  sourceLocationType: 'inlinedSource';\n  /**\n   * The string that will be used as the source for this node and the descends of this node.\n   * Note that the generator will print the characters from newSource[0] until start. Likewise for the suffix.\n   */\n  newSource: string;\n  /**\n   * Behavior of the current loc, after replacing the source string.\n   */\n  loc: SourceLocation;\n  /**\n   * The range that this node replaces in the context of the original source.\n   */\n  start: number;\n  end: number;\n  startOnNew: number;\n  endOnNew: number;\n}\n\n/**\n * NoStringManifestation means the node does not have a string representation.\n * For example the literal '5' has an integer type (which is an AST node),\n * but the type does not have an associated string representation.\n * When set to true, the node will not be printed, start and end are meaningless in this case.\n */\nexport interface SourceLocationNoMaterialize extends SourceLocationBase {\n  sourceLocationType: 'noMaterialize';\n}\n\n/**\n * SourceLocation type that annotates that the node has been replaced\n *   in relation to the original string by a new string.\n * It means that this node should be generated, and that the source string from start to end has been changed.\n */\nexport interface SourceLocationStringReplace extends SourceLocationBase {\n  sourceLocationType: 'stringReplace';\n  /**\n   * The string that will replace the given range in the original source.\n   */\n  newSource: string;\n  /**\n   * The start of the region in the original source string that this node replaces.\n   */\n  start: number;\n  /**\n   * The end of the region in the original source string that this node replaces.\n   */\n  end: number;\n}\n\n/**\n * SourceLocation type that annotates that the node has been replaced in relation to the original string.\n * It means that this node should be generated, and that the source string from start to end has been changed.\n */\nexport interface SourceLocationNodeReplace extends SourceLocationBase {\n  sourceLocationType: 'nodeReplace';\n  /**\n   * The start of the region in the original source string that this node replaces.\n   */\n  start: number;\n  /**\n   * The end of the region in the original source string that this node replaces.\n   */\n  end: number;\n}\n/**\n * Must have an ancestor of type {@link SourceLocationNodeReplace}\n */\nexport interface SourceLocationNodeAutoGenerate extends SourceLocationBase {\n  sourceLocationType: 'autoGenerate';\n}\n\nexport type SourceLocation =\n  // Relate yourself to the source\n  | SourceLocationSource\n  // Add a new source\n  | SourceLocationInlinedSource\n  // No not generate anything for the current node and descendants\n  | SourceLocationNoMaterialize\n  // Replace some range by a string\n  | SourceLocationStringReplace\n  // Replace this node by some autogen\n  | SourceLocationNodeReplace\n  // Auto gen current node.\n  | SourceLocationNodeAutoGenerate;\n"]}

package/dist/esm/lib/utils.d.ts

@@ -3,13 +3,23 @@ import type { ITokenConfig, TokenType } from '@traqula/chevrotain';
  * Check whether the first two types overlap, if no, return the 3th argument, else the 4th.
  */
 export type CheckOverlap<T, U, V, W = never> = T & U extends never ? V : W;
+/**
+ * Lowercase the first letter of a given string.
+ * @param str
+ */
 export declare function unCapitalize<T extends string>(str: T): Uncapitalize<T>;
 export type NamedToken<Name extends string = string> = TokenType & {
     name: Name;
 };
+/**
+ * Create a token in a typesafe way necessary by the traqula core builders.
+ */
 export declare function createToken<Name extends string>(config: ITokenConfig & {
     name: Name;
 }): NamedToken<Name>;
+/**
+ * Patch a given type by changing the value-type of a specific key in the given object type.
+ */
 export type Patch<T extends object, Patch extends {
     [Key in keyof T]?: unknown;
 }> = {

package/dist/esm/lib/utils.js

@@ -1,7 +1,14 @@
 import { createToken as chevcT } from '@traqula/chevrotain';
+/**
+ * Lowercase the first letter of a given string.
+ * @param str
+ */
 export function unCapitalize(str) {
     return (str.charAt(0).toLowerCase() + str.slice(1));
 }
+/**
+ * Create a token in a typesafe way necessary by the traqula core builders.
+ */
 export function createToken(config) {
     return chevcT(config);
 }

package/dist/esm/lib/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../lib/utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,IAAI,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAO5D,MAAM,UAAU,YAAY,CAAmB,GAAM;IACnD,OAAyB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACxE,CAAC;AAID,MAAM,UAAU,WAAW,CAAsB,MAAqC;IACpF,OAAoC,MAAM,CAAC,MAAM,CAAC,CAAC;AACrD,CAAC;AAKD;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAC7B,wFAAwF,CAAC","sourcesContent":["import type { ITokenConfig, TokenType } from '@traqula/chevrotain';\nimport { createToken as chevcT } from '@traqula/chevrotain';\n\n/**\n * Check whether the first two types overlap, if no, return the 3th argument, else the 4th.\n */\nexport type CheckOverlap<T, U, V, W = never> = T & U extends never ? V : W;\n\nexport function unCapitalize<T extends string>(str: T): Uncapitalize<T> {\n  return <Uncapitalize<T>> (str.charAt(0).toLowerCase() + str.slice(1));\n}\n\nexport type NamedToken<Name extends string = string> = TokenType & { name: Name };\n\nexport function createToken<Name extends string>(config: ITokenConfig & { name: Name }): NamedToken<Name> {\n  return <TokenType & { name: Name }> chevcT(config);\n}\n\nexport type Patch<T extends object, Patch extends {[Key in keyof T ]?: unknown }> =\n  {[Key in keyof T]: Key extends keyof Patch ? Patch[Key] : T[Key] };\n\n/**\n * Key that allows you to set the space based indentation of your query when generating newlines using the NEW_LINE.\n * A value of -1 disables the generation of newlines from the NEW_LINE function\n */\nexport const traqulaIndentation =\n  'When you use this string, you expect traqula to handle indentation after every newline';\n"]}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../lib/utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,IAAI,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAO5D;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAmB,GAAM;IACnD,OAAyB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACxE,CAAC;AAID;;GAEG;AACH,MAAM,UAAU,WAAW,CAAsB,MAAqC;IACpF,OAAoC,MAAM,CAAC,MAAM,CAAC,CAAC;AACrD,CAAC;AAQD;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAC7B,wFAAwF,CAAC","sourcesContent":["import type { ITokenConfig, TokenType } from '@traqula/chevrotain';\nimport { createToken as chevcT } from '@traqula/chevrotain';\n\n/**\n * Check whether the first two types overlap, if no, return the 3th argument, else the 4th.\n */\nexport type CheckOverlap<T, U, V, W = never> = T & U extends never ? V : W;\n\n/**\n * Lowercase the first letter of a given string.\n * @param str\n */\nexport function unCapitalize<T extends string>(str: T): Uncapitalize<T> {\n  return <Uncapitalize<T>> (str.charAt(0).toLowerCase() + str.slice(1));\n}\n\nexport type NamedToken<Name extends string = string> = TokenType & { name: Name };\n\n/**\n * Create a token in a typesafe way necessary by the traqula core builders.\n */\nexport function createToken<Name extends string>(config: ITokenConfig & { name: Name }): NamedToken<Name> {\n  return <TokenType & { name: Name }> chevcT(config);\n}\n\n/**\n * Patch a given type by changing the value-type of a specific key in the given object type.\n */\nexport type Patch<T extends object, Patch extends {[Key in keyof T ]?: unknown }> =\n  {[Key in keyof T]: Key extends keyof Patch ? Patch[Key] : T[Key] };\n\n/**\n * Key that allows you to set the space based indentation of your query when generating newlines using the NEW_LINE.\n * A value of -1 disables the generation of newlines from the NEW_LINE function\n */\nexport const traqulaIndentation =\n  'When you use this string, you expect traqula to handle indentation after every newline';\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@traqula/core",
   "type": "module",
-  "version": "0.0.24",
+  "version": "1.0.0",
   "description": "Core components of Traqula",
   "lsd:module": true,
   "license": "MIT",
@@ -41,7 +41,7 @@
     "build:cjs": "node \"../../node_modules/typescript/bin/tsc\" -b tsconfig.cjs.json"
   },
   "dependencies": {
-    "@traqula/chevrotain": "^0.0.24"
+    "@traqula/chevrotain": "^1.0.0"
   },
-  "gitHead": "9865fe1fe302819d46e19c6f3250ceef778f434f"
+  "gitHead": "9e648d6d9081a3b4f994599fa22116414914746f"
 }