@skmtc/core 0.0.785 → 0.0.787

package/script/dsl/EntityType.d.ts

@@ -1,6 +1,89 @@
+/**
+ * Represents the type of a TypeScript entity for code generation.
+ *
+ * `EntityType` encapsulates the distinction between different kinds of
+ * TypeScript entities, specifically variables (which become `const` declarations)
+ * and types (which become `type` or `interface` declarations).
+ *
+ * This class is used by the {@link Identifier} system to ensure that
+ * generated code uses the correct TypeScript keywords and syntax patterns.
+ *
+ * @example Variable entity type
+ * ```typescript
+ * import { EntityType } from '@skmtc/core';
+ *
+ * const variableEntity = new EntityType('variable');
+ * console.log(variableEntity.toString()); // 'const'
+ *
+ * // Used in code generation:
+ * // const API_URL = 'https://api.example.com';
+ * ```
+ *
+ * @example Type entity type
+ * ```typescript
+ * const typeEntity = new EntityType('type');
+ * console.log(typeEntity.toString()); // 'type'
+ *
+ * // Used in code generation:
+ * // type User = { id: string; name: string; };
+ * ```
+ *
+ * @example Integration with Identifier
+ * ```typescript
+ * import { Identifier, EntityType } from '@skmtc/core';
+ *
+ * // Create a variable identifier (uses 'const' keyword)
+ * const varId = Identifier.createVariable('API_KEY', 'string');
+ * console.log(varId.entityType.toString()); // 'const'
+ *
+ * // Create a type identifier (uses 'type' keyword)
+ * const typeId = Identifier.createType('UserStatus');
+ * console.log(typeId.entityType.toString()); // 'type'
+ * ```
+ */
 export declare class EntityType {
+    /** The entity type discriminator */
     type: 'variable' | 'type';
+    /**
+     * Creates a new EntityType instance.
+     *
+     * @param type - The type of entity ('variable' for const declarations, 'type' for type declarations)
+     *
+     * @example
+     * ```typescript
+     * // For generating const declarations
+     * const constEntity = new EntityType('variable');
+     *
+     * // For generating type declarations
+     * const typeEntity = new EntityType('type');
+     * ```
+     */
     constructor(type: 'variable' | 'type');
+    /**
+     * Returns the appropriate TypeScript keyword for this entity type.
+     *
+     * This method maps the entity type to the correct TypeScript declaration
+     * keyword that should be used in generated code:
+     * - 'variable' entities become 'const' declarations
+     * - 'type' entities become 'type' declarations
+     *
+     * @returns The TypeScript keyword string ('const' or 'type')
+     *
+     * @example
+     * ```typescript
+     * const varEntity = new EntityType('variable');
+     * console.log(varEntity.toString()); // 'const'
+     *
+     * const typeEntity = new EntityType('type');
+     * console.log(typeEntity.toString()); // 'type'
+     *
+     * // Used in code generation:
+     * const keyword = entityType.toString();
+     * const declaration = `${keyword} ${identifier} = ${value};`;
+     * // Results in: "const API_URL = 'https://example.com';" or
+     * // Results in: "type Status = 'active' | 'inactive';"
+     * ```
+     */
     toString(): string;
 }
 //# sourceMappingURL=EntityType.d.ts.map

package/script/dsl/EntityType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EntityType.d.ts","sourceRoot":"","sources":["../../src/dsl/EntityType.ts"],"names":[],"mappings":"AAEA,qBAAa,UAAU;IACrB,IAAI,EAAE,UAAU,GAAG,MAAM,CAAA;gBACb,IAAI,EAAE,UAAU,GAAG,MAAM;IAIrC,QAAQ,IAAI,MAAM;CAMnB"}
+{"version":3,"file":"EntityType.d.ts","sourceRoot":"","sources":["../../src/dsl/EntityType.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,UAAU;IACrB,oCAAoC;IACpC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAA;IAEzB;;;;;;;;;;;;;OAaG;gBACS,IAAI,EAAE,UAAU,GAAG,MAAM;IAIrC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,IAAI,MAAM;CAMnB"}

package/script/dsl/EntityType.js

@@ -2,8 +2,66 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EntityType = void 0;
 const ts_pattern_1 = require("ts-pattern");
+/**
+ * Represents the type of a TypeScript entity for code generation.
+ *
+ * `EntityType` encapsulates the distinction between different kinds of
+ * TypeScript entities, specifically variables (which become `const` declarations)
+ * and types (which become `type` or `interface` declarations).
+ *
+ * This class is used by the {@link Identifier} system to ensure that
+ * generated code uses the correct TypeScript keywords and syntax patterns.
+ *
+ * @example Variable entity type
+ * ```typescript
+ * import { EntityType } from '@skmtc/core';
+ *
+ * const variableEntity = new EntityType('variable');
+ * console.log(variableEntity.toString()); // 'const'
+ *
+ * // Used in code generation:
+ * // const API_URL = 'https://api.example.com';
+ * ```
+ *
+ * @example Type entity type
+ * ```typescript
+ * const typeEntity = new EntityType('type');
+ * console.log(typeEntity.toString()); // 'type'
+ *
+ * // Used in code generation:
+ * // type User = { id: string; name: string; };
+ * ```
+ *
+ * @example Integration with Identifier
+ * ```typescript
+ * import { Identifier, EntityType } from '@skmtc/core';
+ *
+ * // Create a variable identifier (uses 'const' keyword)
+ * const varId = Identifier.createVariable('API_KEY', 'string');
+ * console.log(varId.entityType.toString()); // 'const'
+ *
+ * // Create a type identifier (uses 'type' keyword)
+ * const typeId = Identifier.createType('UserStatus');
+ * console.log(typeId.entityType.toString()); // 'type'
+ * ```
+ */
 class EntityType {
+    /**
+     * Creates a new EntityType instance.
+     *
+     * @param type - The type of entity ('variable' for const declarations, 'type' for type declarations)
+     *
+     * @example
+     * ```typescript
+     * // For generating const declarations
+     * const constEntity = new EntityType('variable');
+     *
+     * // For generating type declarations
+     * const typeEntity = new EntityType('type');
+     * ```
+     */
     constructor(type) {
+        /** The entity type discriminator */
         Object.defineProperty(this, "type", {
             enumerable: true,
             configurable: true,
@@ -12,6 +70,31 @@ class EntityType {
         });
         this.type = type;
     }
+    /**
+     * Returns the appropriate TypeScript keyword for this entity type.
+     *
+     * This method maps the entity type to the correct TypeScript declaration
+     * keyword that should be used in generated code:
+     * - 'variable' entities become 'const' declarations
+     * - 'type' entities become 'type' declarations
+     *
+     * @returns The TypeScript keyword string ('const' or 'type')
+     *
+     * @example
+     * ```typescript
+     * const varEntity = new EntityType('variable');
+     * console.log(varEntity.toString()); // 'const'
+     *
+     * const typeEntity = new EntityType('type');
+     * console.log(typeEntity.toString()); // 'type'
+     *
+     * // Used in code generation:
+     * const keyword = entityType.toString();
+     * const declaration = `${keyword} ${identifier} = ${value};`;
+     * // Results in: "const API_URL = 'https://example.com';" or
+     * // Results in: "type Status = 'active' | 'inactive';"
+     * ```
+     */
     toString() {
         return (0, ts_pattern_1.match)(this.type)
             .with('variable', () => 'const')

package/script/dsl/Identifier.d.ts

@@ -1,11 +1,163 @@
 import { EntityType } from './EntityType.js';
+/**
+ * Represents a TypeScript identifier in the SKMTC DSL system.
+ *
+ * The `Identifier` class encapsulates named entities in generated code,
+ * providing type-safe creation and management of variables, types, and other
+ * identifiers. It distinguishes between different kinds of identifiers and
+ * optionally tracks type information.
+ *
+ * This class uses factory methods instead of direct construction to ensure
+ * proper entity type classification and to provide a cleaner API.
+ *
+ * ## Key Features
+ *
+ * - **Type Safety**: Distinguishes between variables, types, and other entities
+ * - **Factory Methods**: Provides semantic constructors for different identifier types
+ * - **Optional Typing**: Can associate type information with variable identifiers
+ * - **String Conversion**: Clean string representation for code generation
+ *
+ * @example Creating variable identifiers
+ * ```typescript
+ * import { Identifier } from '@skmtc/core';
+ *
+ * // Simple variable without type
+ * const userName = Identifier.createVariable('userName');
+ * console.log(userName.toString()); // 'userName'
+ *
+ * // Typed variable
+ * const userId = Identifier.createVariable('userId', 'string');
+ * console.log(userId.name);     // 'userId'
+ * console.log(userId.typeName); // 'string'
+ * ```
+ *
+ * @example Creating type identifiers
+ * ```typescript
+ * // Type identifier
+ * const userType = Identifier.createType('User');
+ * console.log(userType.toString());        // 'User'
+ * console.log(userType.entityType.value); // 'type'
+ * ```
+ *
+ * @example Using in code generation
+ * ```typescript
+ * import { Definition, Identifier } from '@skmtc/core';
+ *
+ * class ApiGenerator {
+ *   generateFunction(name: string) {
+ *     const funcId = Identifier.createVariable(name);
+ *     const requestType = Identifier.createType('RequestType');
+ *
+ *     return new Definition({
+ *       name: funcId.name,
+ *       content: `function ${funcId}(data: ${requestType}) {
+ *         // Implementation
+ *       }`
+ *     });
+ *   }
+ * }
+ * ```
+ */
 export declare class Identifier {
+    /** The identifier name */
     name: string;
+    /** The entity type (variable, type, etc.) */
     entityType: EntityType;
+    /** Optional type name for typed variables */
     typeName?: string;
+    /**
+     * Creates a new Identifier instance.
+     *
+     * This constructor is private to enforce the use of factory methods
+     * that provide better semantic clarity and type safety.
+     *
+     * @param args - Identifier configuration
+     */
     private constructor();
+    /**
+     * Creates a variable identifier with optional type information.
+     *
+     * This factory method creates an identifier for variables, constants,
+     * function parameters, and other value-based entities. Optionally
+     * associates type information for typed variables.
+     *
+     * @param name - The variable name
+     * @param typeName - Optional type name for the variable
+     * @returns A new variable Identifier instance
+     *
+     * @example Untyped variable
+     * ```typescript
+     * const count = Identifier.createVariable('count');
+     * console.log(count.name); // 'count'
+     * console.log(count.typeName); // undefined
+     * ```
+     *
+     * @example Typed variable
+     * ```typescript
+     * const userId = Identifier.createVariable('userId', 'string');
+     * console.log(userId.name);     // 'userId'
+     * console.log(userId.typeName); // 'string'
+     * ```
+     *
+     * @example In function generation
+     * ```typescript
+     * const param = Identifier.createVariable('data', 'RequestData');
+     * const funcDef = `function processRequest(${param.name}: ${param.typeName}) {}`;
+     * ```
+     */
     static createVariable(name: string, typeName?: string): Identifier;
+    /**
+     * Creates a type identifier for TypeScript types.
+     *
+     * This factory method creates an identifier for type entities like
+     * interfaces, type aliases, classes, and other type-level constructs.
+     * Type identifiers don't have associated type information since they
+     * represent types themselves.
+     *
+     * @param name - The type name
+     * @returns A new type Identifier instance
+     *
+     * @example Interface type
+     * ```typescript
+     * const userInterface = Identifier.createType('User');
+     * console.log(userInterface.name);                // 'User'
+     * console.log(userInterface.entityType.value);   // 'type'
+     * ```
+     *
+     * @example Type alias
+     * ```typescript
+     * const statusType = Identifier.createType('Status');
+     * const typeDef = `type ${statusType} = 'pending' | 'complete'`;
+     * ```
+     *
+     * @example Generic type
+     * ```typescript
+     * const responseType = Identifier.createType('ApiResponse');
+     * const genericDef = `interface ${responseType}<T> { data: T; success: boolean; }`;
+     * ```
+     */
     static createType(name: string): Identifier;
+    /**
+     * Returns the string representation of the identifier.
+     *
+     * This method simply returns the identifier name, which is the most
+     * common usage when generating code. The name can be used directly
+     * in code generation contexts.
+     *
+     * @returns The identifier name as a string
+     *
+     * @example
+     * ```typescript
+     * const variable = Identifier.createVariable('userName');
+     * const typeId = Identifier.createType('User');
+     *
+     * console.log(variable.toString()); // 'userName'
+     * console.log(typeId.toString());   // 'User'
+     *
+     * // Can be used directly in template strings
+     * const code = `const ${variable}: ${typeId} = getUserData();`;
+     * ```
+     */
     toString(): string;
 }
 //# sourceMappingURL=Identifier.d.ts.map

package/script/dsl/Identifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Identifier.d.ts","sourceRoot":"","sources":["../../src/dsl/Identifier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAQ5C,qBAAa,UAAU;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,UAAU,CAAA;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB,OAAO;IAMP,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU;IAelE,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU;IAO3C,QAAQ,IAAI,MAAM;CAGnB"}
+{"version":3,"file":"Identifier.d.ts","sourceRoot":"","sources":["../../src/dsl/Identifier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAc5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,qBAAa,UAAU;IACrB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAA;IAEZ,6CAA6C;IAC7C,UAAU,EAAE,UAAU,CAAA;IAEtB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;;;;;OAOG;IACH,OAAO;IAMP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU;IAelE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU;IAO3C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,IAAI,MAAM;CAGnB"}

package/script/dsl/Identifier.js

@@ -2,20 +2,90 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Identifier = void 0;
 const EntityType_js_1 = require("./EntityType.js");
+/**
+ * Represents a TypeScript identifier in the SKMTC DSL system.
+ *
+ * The `Identifier` class encapsulates named entities in generated code,
+ * providing type-safe creation and management of variables, types, and other
+ * identifiers. It distinguishes between different kinds of identifiers and
+ * optionally tracks type information.
+ *
+ * This class uses factory methods instead of direct construction to ensure
+ * proper entity type classification and to provide a cleaner API.
+ *
+ * ## Key Features
+ *
+ * - **Type Safety**: Distinguishes between variables, types, and other entities
+ * - **Factory Methods**: Provides semantic constructors for different identifier types
+ * - **Optional Typing**: Can associate type information with variable identifiers
+ * - **String Conversion**: Clean string representation for code generation
+ *
+ * @example Creating variable identifiers
+ * ```typescript
+ * import { Identifier } from '@skmtc/core';
+ *
+ * // Simple variable without type
+ * const userName = Identifier.createVariable('userName');
+ * console.log(userName.toString()); // 'userName'
+ *
+ * // Typed variable
+ * const userId = Identifier.createVariable('userId', 'string');
+ * console.log(userId.name);     // 'userId'
+ * console.log(userId.typeName); // 'string'
+ * ```
+ *
+ * @example Creating type identifiers
+ * ```typescript
+ * // Type identifier
+ * const userType = Identifier.createType('User');
+ * console.log(userType.toString());        // 'User'
+ * console.log(userType.entityType.value); // 'type'
+ * ```
+ *
+ * @example Using in code generation
+ * ```typescript
+ * import { Definition, Identifier } from '@skmtc/core';
+ *
+ * class ApiGenerator {
+ *   generateFunction(name: string) {
+ *     const funcId = Identifier.createVariable(name);
+ *     const requestType = Identifier.createType('RequestType');
+ *
+ *     return new Definition({
+ *       name: funcId.name,
+ *       content: `function ${funcId}(data: ${requestType}) {
+ *         // Implementation
+ *       }`
+ *     });
+ *   }
+ * }
+ * ```
+ */
 class Identifier {
+    /**
+     * Creates a new Identifier instance.
+     *
+     * This constructor is private to enforce the use of factory methods
+     * that provide better semantic clarity and type safety.
+     *
+     * @param args - Identifier configuration
+     */
     constructor({ name, typeName, entityType }) {
+        /** The identifier name */
         Object.defineProperty(this, "name", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The entity type (variable, type, etc.) */
         Object.defineProperty(this, "entityType", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Optional type name for typed variables */
         Object.defineProperty(this, "typeName", {
             enumerable: true,
             configurable: true,
@@ -26,6 +96,37 @@ class Identifier {
         this.typeName = typeName;
         this.entityType = entityType;
     }
+    /**
+     * Creates a variable identifier with optional type information.
+     *
+     * This factory method creates an identifier for variables, constants,
+     * function parameters, and other value-based entities. Optionally
+     * associates type information for typed variables.
+     *
+     * @param name - The variable name
+     * @param typeName - Optional type name for the variable
+     * @returns A new variable Identifier instance
+     *
+     * @example Untyped variable
+     * ```typescript
+     * const count = Identifier.createVariable('count');
+     * console.log(count.name); // 'count'
+     * console.log(count.typeName); // undefined
+     * ```
+     *
+     * @example Typed variable
+     * ```typescript
+     * const userId = Identifier.createVariable('userId', 'string');
+     * console.log(userId.name);     // 'userId'
+     * console.log(userId.typeName); // 'string'
+     * ```
+     *
+     * @example In function generation
+     * ```typescript
+     * const param = Identifier.createVariable('data', 'RequestData');
+     * const funcDef = `function processRequest(${param.name}: ${param.typeName}) {}`;
+     * ```
+     */
     static createVariable(name, typeName) {
         if (typeName) {
             return new Identifier({
@@ -39,12 +140,63 @@ class Identifier {
             entityType: new EntityType_js_1.EntityType('variable')
         });
     }
+    /**
+     * Creates a type identifier for TypeScript types.
+     *
+     * This factory method creates an identifier for type entities like
+     * interfaces, type aliases, classes, and other type-level constructs.
+     * Type identifiers don't have associated type information since they
+     * represent types themselves.
+     *
+     * @param name - The type name
+     * @returns A new type Identifier instance
+     *
+     * @example Interface type
+     * ```typescript
+     * const userInterface = Identifier.createType('User');
+     * console.log(userInterface.name);                // 'User'
+     * console.log(userInterface.entityType.value);   // 'type'
+     * ```
+     *
+     * @example Type alias
+     * ```typescript
+     * const statusType = Identifier.createType('Status');
+     * const typeDef = `type ${statusType} = 'pending' | 'complete'`;
+     * ```
+     *
+     * @example Generic type
+     * ```typescript
+     * const responseType = Identifier.createType('ApiResponse');
+     * const genericDef = `interface ${responseType}<T> { data: T; success: boolean; }`;
+     * ```
+     */
     static createType(name) {
         return new Identifier({
             name,
             entityType: new EntityType_js_1.EntityType('type')
         });
     }
+    /**
+     * Returns the string representation of the identifier.
+     *
+     * This method simply returns the identifier name, which is the most
+     * common usage when generating code. The name can be used directly
+     * in code generation contexts.
+     *
+     * @returns The identifier name as a string
+     *
+     * @example
+     * ```typescript
+     * const variable = Identifier.createVariable('userName');
+     * const typeId = Identifier.createType('User');
+     *
+     * console.log(variable.toString()); // 'userName'
+     * console.log(typeId.toString());   // 'User'
+     *
+     * // Can be used directly in template strings
+     * const code = `const ${variable}: ${typeId} = getUserData();`;
+     * ```
+     */
     toString() {
         return this.name;
     }