@skmtc/core 0.0.785 → 0.0.787

package/esm/dsl/Definition.js

@@ -1,26 +1,170 @@
 import { ContentBase } from './ContentBase.js';
 import { withDescription } from '../typescript/withDescription.js';
+/**
+ * Represents a complete code definition in the SKMTC DSL system.
+ *
+ * The `Definition` class is the primary output unit of generators, representing
+ * a complete piece of generated code (like an interface, function, or constant).
+ * It combines an identifier, generated content, and optional metadata into a
+ * formatted code definition with proper TypeScript syntax.
+ *
+ * This class automatically handles export statements, type annotations, and
+ * JSDoc comment generation, making it the building block for all generated
+ * code artifacts.
+ *
+ * ## Key Features
+ *
+ * - **Automatic Exports**: Handles export keyword based on configuration
+ * - **Type Safety**: Preserves type information through generic parameters
+ * - **JSDoc Integration**: Automatic comment generation from descriptions
+ * - **Entity Type Support**: Handles different definition types (const, type, etc.)
+ * - **Identifier Management**: Integrates with the Identifier system for naming
+ *
+ * @template V - The type of generated value (preserves generator-specific types)
+ *
+ * @example Basic interface definition
+ * ```typescript
+ * import { Definition, Identifier } from '@skmtc/core';
+ *
+ * const userInterface = new Definition({
+ *   context: generateContext,
+ *   identifier: Identifier.createType('User'),
+ *   description: 'Represents a user in the system',
+ *   value: {
+ *     generatorKey: 'typescript-interfaces',
+ *     content: `{
+ *       id: string;
+ *       name: string;
+ *       email: string;
+ *     }`
+ *   }
+ * });
+ *
+ * console.log(userInterface.toString());
+ * //
+ * // Represents a user in the system
+ * //
+ * // export type User = {
+ * //   id: string;
+ * //   name: string;
+ * //   email: string;
+ * // };
+ * ```
+ *
+ * @example Function definition with parameters
+ * ```typescript
+ * const apiFunction = new Definition({
+ *   context: generateContext,
+ *   identifier: Identifier.createVariable('fetchUser', 'Promise<User>'),
+ *   description: 'Fetches a user by ID from the API',
+ *   value: {
+ *     generatorKey: 'api-client',
+ *     content: `async (id: string) => {
+ *       const response = await fetch(\`/api/users/\${id}\`);
+ *       return response.json();
+ *     }`
+ *   }
+ * });
+ *
+ * console.log(apiFunction.toString());
+ * //
+ * //  Fetches a user by ID from the API
+ * //
+ * // export const fetchUser: Promise<User> = async (id: string) => {
+ * //   const response = await fetch(`/api/users/${id}`);
+ * //   return response.json();
+ * // };
+ * ```
+ *
+ * @example Non-exported definition
+ * ```typescript
+ * const helperFunction = new Definition({
+ *   context: generateContext,
+ *   identifier: Identifier.createVariable('validateEmail'),
+ *   value: {
+ *     generatorKey: 'utilities',
+ *     content: `(email: string): boolean => {
+ *       return /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(email);
+ *     }`
+ *   },
+ *   noExport: true // Internal helper, not exported
+ * });
+ *
+ * console.log(helperFunction.toString());
+ * // const validateEmail = (email: string): boolean => {
+ * //   return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+ * // };
+ * ```
+ *
+ * @example Using in generator classes
+ * ```typescript
+ * import { ModelBase, Definition, Identifier } from '@skmtc/core';
+ *
+ * class TypeScriptInterface extends ModelBase {
+ *   toDefinition(): Definition {
+ *     const schema = this.context.getSchema(this.refName);
+ *
+ *     return new Definition({
+ *       context: this.context,
+ *       identifier: Identifier.createType(this.refName),
+ *       description: schema.description,
+ *       value: {
+ *         generatorKey: this.generatorKey,
+ *         content: this.generateInterfaceBody(schema)
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ */
 export class Definition extends ContentBase {
+    /**
+     * Creates a new Definition instance.
+     *
+     * @param args - Definition configuration
+     * @param args.context - Generation context for pipeline access
+     * @param args.identifier - The identifier (name and type info) for this definition
+     * @param args.value - The generated content value
+     * @param args.description - Optional description for JSDoc comments
+     * @param args.noExport - Whether to omit the export keyword (default: false)
+     *
+     * @example
+     * ```typescript
+     * const constant = new Definition({
+     *   context: generateContext,
+     *   identifier: Identifier.createVariable('API_BASE_URL', 'string'),
+     *   description: 'Base URL for all API requests',
+     *   value: {
+     *     generatorKey: 'constants',
+     *     content: "'https://api.example.com'"
+     *   }
+     * });
+     * ```
+     */
     constructor({ context, identifier, value, description, noExport }) {
         super({ context, generatorKey: value.generatorKey });
+        /** The identifier for this definition */
         Object.defineProperty(this, "identifier", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Optional description for JSDoc comments */
         Object.defineProperty(this, "description", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The generated value content */
         Object.defineProperty(this, "value", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Whether to skip the export keyword */
         Object.defineProperty(this, "noExport", {
             enumerable: true,
             configurable: true,
@@ -32,6 +176,51 @@ export class Definition extends ContentBase {
         this.description = description;
         this.noExport = noExport;
     }
+    /**
+     * Generates the complete TypeScript definition code.
+     *
+     * This method produces a properly formatted TypeScript definition with:
+     * - Optional JSDoc comments from the description
+     * - Export keyword (unless noExport is true)
+     * - Entity type (const, type, function, etc.)
+     * - Identifier with optional type annotation
+     * - Generated value content
+     *
+     * The output follows TypeScript syntax conventions and can be written
+     * directly to a .ts file.
+     *
+     * @returns The complete TypeScript definition as a string
+     *
+     * @example Type definition
+     * ```typescript
+     * const typeDef = new Definition({
+     *   context,
+     *   identifier: Identifier.createType('Status'),
+     *   description: 'Possible status values',
+     *   value: { generatorKey: 'types', content: "'pending' | 'complete' | 'failed'" }
+     * });
+     *
+     * console.log(typeDef.toString());
+     * //
+     * // Possible status values
+     * //
+     * // export type Status = 'pending' | 'complete' | 'failed';
+     * ```
+     *
+     * @example Constant definition
+     * ```typescript
+     * const constDef = new Definition({
+     *   context,
+     *   identifier: Identifier.createVariable('DEFAULT_TIMEOUT', 'number'),
+     *   value: { generatorKey: 'config', content: '5000' }
+     * });
+     *
+     * console.log(constDef.toString());
+     * // export const DEFAULT_TIMEOUT: number = 5000;
+     * ```
+     *
+     * @todo Move syntax to typescript package to enable language-agnostic use
+     */
     toString() {
         const identifier = this.identifier.typeName
             ? `${this.identifier.name}: ${this.identifier.typeName}`

package/esm/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/esm/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/esm/dsl/EntityType.js

@@ -1,6 +1,64 @@
 import { match } from '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'
+ * ```
+ */
 export 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,
@@ -9,6 +67,31 @@ export 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 match(this.type)
             .with('variable', () => 'const')

package/esm/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/esm/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"}