@skmtc/core 0.0.785 → 0.0.787

package/esm/dsl/Identifier.js

@@ -1,18 +1,88 @@
 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 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,
@@ -23,6 +93,37 @@ export 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({
@@ -36,12 +137,63 @@ export class Identifier {
             entityType: new 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('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;
     }

package/esm/dsl/Import.d.ts

@@ -1,21 +1,242 @@
+/**
+ * Constructor arguments for {@link Import}.
+ */
 type ConstructorArgs = {
+    /** The module path to import from */
     module: string;
+    /** Array of import names (can be strings or alias objects) */
     importNames: ImportNameArg[];
 };
+/**
+ * Represents a TypeScript import statement in the SKMTC DSL system.
+ *
+ * The `Import` class generates properly formatted import statements for TypeScript
+ * files, handling named imports with optional aliases. It's used throughout the
+ * code generation pipeline to manage module dependencies.
+ *
+ * This class supports both simple string imports and aliased imports, making it
+ * easy to avoid naming conflicts and provide cleaner import statements.
+ *
+ * @example Basic named imports
+ * ```typescript
+ * import { Import } from '@skmtc/core';
+ *
+ * const basicImport = new Import({
+ *   module: './types',
+ *   importNames: ['User', 'Product', 'Order']
+ * });
+ *
+ * console.log(basicImport.toString());
+ * // import { User, Product, Order } from './types'
+ * ```
+ *
+ * @example Imports with aliases
+ * ```typescript
+ * const aliasedImport = new Import({
+ *   module: 'react',
+ *   importNames: [
+ *     'useState',
+ *     'useEffect',
+ *     { 'default': 'React' } // Import default as React
+ *   ]
+ * });
+ *
+ * console.log(aliasedImport.toString());
+ * // import { useState, useEffect, default as React } from 'react'
+ * ```
+ *
+ * @example Mixed imports
+ * ```typescript
+ * const mixedImport = new Import({
+ *   module: './api/client',
+ *   importNames: [
+ *     'ApiClient',
+ *     { 'RequestOptions': 'Options' }, // Alias to avoid conflicts
+ *     'ResponseType'
+ *   ]
+ * });
+ *
+ * console.log(mixedImport.toString());
+ * // import { ApiClient, RequestOptions as Options, ResponseType } from './api/client'
+ * ```
+ *
+ * @example Using in File generation
+ * ```typescript
+ * import { File, Import } from '@skmtc/core';
+ *
+ * const file = new File({ path: './generated.ts', settings: undefined });
+ *
+ * // Add import to file
+ * file.imports.set('./types', new Set(['User', 'Product']));
+ *
+ * // Or create Import directly for more control
+ * const customImport = new Import({
+ *   module: './helpers',
+ *   importNames: [{ 'validateEmail': 'emailValidator' }]
+ * });
+ * ```
+ */
 export declare class Import {
+    /** The module path to import from */
     module: string;
+    /** Array of parsed import names with potential aliases */
     importNames: ImportName[];
+    /**
+     * Creates a new Import instance.
+     *
+     * @param args - Import configuration
+     * @param args.module - The module path to import from (e.g., './types', 'react')
+     * @param args.importNames - Array of import names, can be strings or alias objects
+     *
+     * @example
+     * ```typescript
+     * const importStatement = new Import({
+     *   module: './models/User',
+     *   importNames: [
+     *     'User',                           // Simple import
+     *     { 'UserType': 'IUser' },         // Aliased import
+     *     'createUser'                     // Another simple import
+     *   ]
+     * });
+     * ```
+     */
     constructor({ module, importNames }: ConstructorArgs);
+    /**
+     * Converts the import to a record format.
+     *
+     * This method creates a record representation where the module path is the key
+     * and the import names are the value. Useful for serialization or when working
+     * with import maps.
+     *
+     * @returns A record with module as key and import names as value
+     *
+     * @example
+     * ```typescript
+     * const importStatement = new Import({
+     *   module: './types',
+     *   importNames: ['User', { 'Product': 'IProduct' }]
+     * });
+     *
+     * const record = importStatement.toRecord();
+     * console.log(record);
+     * // {
+     * //   './types': ['User', { 'Product': 'IProduct' }]
+     * // }
+     * ```
+     */
     toRecord(): Record<string, ImportNameArg[]>;
+    /**
+     * Generates the TypeScript import statement string.
+     *
+     * This method produces a properly formatted ES6 import statement that can be
+     * written directly to a TypeScript file. It handles both simple and aliased
+     * imports correctly.
+     *
+     * @returns The formatted import statement string
+     *
+     * @example
+     * ```typescript
+     * const basicImport = new Import({
+     *   module: './utils',
+     *   importNames: ['formatDate', 'parseJson']
+     * });
+     *
+     * console.log(basicImport.toString());
+     * // import { formatDate, parseJson } from './utils'
+     *
+     * const aliasedImport = new Import({
+     *   module: 'lodash',
+     *   importNames: [{ 'isEqual': 'deepEqual' }, 'cloneDeep']
+     * });
+     *
+     * console.log(aliasedImport.toString());
+     * // import { isEqual as deepEqual, cloneDeep } from 'lodash'
+     * ```
+     *
+     * @todo Move syntax to typescript package to enable language-agnostic use
+     */
     toString(): string;
 }
+/**
+ * Argument type for import names - can be a simple string or an alias object.
+ *
+ * @example String import
+ * ```typescript
+ * const simpleImport: ImportNameArg = 'User';
+ * ```
+ *
+ * @example Aliased import
+ * ```typescript
+ * const aliasedImport: ImportNameArg = { 'User': 'IUser' };
+ * // This creates: User as IUser
+ * ```
+ */
 export type ImportNameArg = string | {
     [name: string]: string;
 };
+/**
+ * Represents a single import name with optional aliasing.
+ *
+ * This class handles the parsing and formatting of individual import specifiers,
+ * supporting both simple imports and aliased imports. It's used internally by
+ * the {@link Import} class to manage import statement components.
+ *
+ * @example Simple import name
+ * ```typescript
+ * const simple = new ImportName('useState');
+ * console.log(simple.toString()); // 'useState'
+ * ```
+ *
+ * @example Aliased import name
+ * ```typescript
+ * const aliased = new ImportName({ 'React': 'ReactLib' });
+ * console.log(aliased.toString()); // 'React as ReactLib'
+ * ```
+ */
 export declare class ImportName {
+    /** The original name being imported */
     name: string;
+    /** The alias to use (if any) */
     alias?: string;
+    /**
+     * Creates a new ImportName instance.
+     *
+     * @param name - Either a string for simple imports or an object for aliased imports
+     *
+     * @example Simple import
+     * ```typescript
+     * const importName = new ImportName('User');
+     * // Results in: User
+     * ```
+     *
+     * @example Aliased import
+     * ```typescript
+     * const importName = new ImportName({ 'UserInterface': 'IUser' });
+     * // Results in: UserInterface as IUser
+     * ```
+     */
     constructor(name: ImportNameArg);
+    /**
+     * Generates the string representation of the import name.
+     *
+     * This method creates the appropriate import specifier syntax,
+     * either a simple name or an aliased import using TypeScript's
+     * 'as' keyword.
+     *
+     * @returns The formatted import specifier string
+     *
+     * @example Simple import
+     * ```typescript
+     * const simple = new ImportName('useState');
+     * console.log(simple.toString()); // 'useState'
+     * ```
+     *
+     * @example Aliased import
+     * ```typescript
+     * const aliased = new ImportName({ 'Component': 'ReactComponent' });
+     * console.log(aliased.toString()); // 'Component as ReactComponent'
+     * ```
+     */
     toString(): string;
 }
 export {};

package/esm/dsl/Import.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Import.d.ts","sourceRoot":"","sources":["../../src/dsl/Import.ts"],"names":[],"mappings":"AAAA,KAAK,eAAe,GAAG;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,aAAa,EAAE,CAAA;CAC7B,CAAA;AAED,qBAAa,MAAM;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,UAAU,EAAE,CAAA;gBAEb,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,eAAe;IAKpD,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC;IAQ3C,QAAQ,IAAI,MAAM;CAKnB;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG;IAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAA;AAE/D,qBAAa,UAAU;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;gBAEF,IAAI,EAAE,aAAa;IAW/B,QAAQ,IAAI,MAAM;CAGnB"}
+{"version":3,"file":"Import.d.ts","sourceRoot":"","sources":["../../src/dsl/Import.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,KAAK,eAAe,GAAG;IACrB,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAA;IACd,8DAA8D;IAC9D,WAAW,EAAE,aAAa,EAAE,CAAA;CAC7B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,qBAAa,MAAM;IACjB,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAA;IAEd,0DAA0D;IAC1D,WAAW,EAAE,UAAU,EAAE,CAAA;IAEzB;;;;;;;;;;;;;;;;;;OAkBG;gBACS,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,eAAe;IAKpD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC;IAQ3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,QAAQ,IAAI,MAAM;CAKnB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG;IAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAA;AAE/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,UAAU;IACrB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAA;IAEZ,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;;;;;;;;;;;;;;OAgBG;gBACS,IAAI,EAAE,aAAa;IAW/B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,IAAI,MAAM;CAGnB"}

package/esm/dsl/Import.js

@@ -1,11 +1,101 @@
+/**
+ * Represents a TypeScript import statement in the SKMTC DSL system.
+ *
+ * The `Import` class generates properly formatted import statements for TypeScript
+ * files, handling named imports with optional aliases. It's used throughout the
+ * code generation pipeline to manage module dependencies.
+ *
+ * This class supports both simple string imports and aliased imports, making it
+ * easy to avoid naming conflicts and provide cleaner import statements.
+ *
+ * @example Basic named imports
+ * ```typescript
+ * import { Import } from '@skmtc/core';
+ *
+ * const basicImport = new Import({
+ *   module: './types',
+ *   importNames: ['User', 'Product', 'Order']
+ * });
+ *
+ * console.log(basicImport.toString());
+ * // import { User, Product, Order } from './types'
+ * ```
+ *
+ * @example Imports with aliases
+ * ```typescript
+ * const aliasedImport = new Import({
+ *   module: 'react',
+ *   importNames: [
+ *     'useState',
+ *     'useEffect',
+ *     { 'default': 'React' } // Import default as React
+ *   ]
+ * });
+ *
+ * console.log(aliasedImport.toString());
+ * // import { useState, useEffect, default as React } from 'react'
+ * ```
+ *
+ * @example Mixed imports
+ * ```typescript
+ * const mixedImport = new Import({
+ *   module: './api/client',
+ *   importNames: [
+ *     'ApiClient',
+ *     { 'RequestOptions': 'Options' }, // Alias to avoid conflicts
+ *     'ResponseType'
+ *   ]
+ * });
+ *
+ * console.log(mixedImport.toString());
+ * // import { ApiClient, RequestOptions as Options, ResponseType } from './api/client'
+ * ```
+ *
+ * @example Using in File generation
+ * ```typescript
+ * import { File, Import } from '@skmtc/core';
+ *
+ * const file = new File({ path: './generated.ts', settings: undefined });
+ *
+ * // Add import to file
+ * file.imports.set('./types', new Set(['User', 'Product']));
+ *
+ * // Or create Import directly for more control
+ * const customImport = new Import({
+ *   module: './helpers',
+ *   importNames: [{ 'validateEmail': 'emailValidator' }]
+ * });
+ * ```
+ */
 export class Import {
+    /**
+     * Creates a new Import instance.
+     *
+     * @param args - Import configuration
+     * @param args.module - The module path to import from (e.g., './types', 'react')
+     * @param args.importNames - Array of import names, can be strings or alias objects
+     *
+     * @example
+     * ```typescript
+     * const importStatement = new Import({
+     *   module: './models/User',
+     *   importNames: [
+     *     'User',                           // Simple import
+     *     { 'UserType': 'IUser' },         // Aliased import
+     *     'createUser'                     // Another simple import
+     *   ]
+     * });
+     * ```
+     */
     constructor({ module, importNames }) {
+        /** The module path to import from */
         Object.defineProperty(this, "module", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Array of parsed import names with potential aliases */
         Object.defineProperty(this, "importNames", {
             enumerable: true,
             configurable: true,
@@ -15,25 +105,116 @@ export class Import {
         this.module = module;
         this.importNames = importNames.map(importName => new ImportName(importName));
     }
+    /**
+     * Converts the import to a record format.
+     *
+     * This method creates a record representation where the module path is the key
+     * and the import names are the value. Useful for serialization or when working
+     * with import maps.
+     *
+     * @returns A record with module as key and import names as value
+     *
+     * @example
+     * ```typescript
+     * const importStatement = new Import({
+     *   module: './types',
+     *   importNames: ['User', { 'Product': 'IProduct' }]
+     * });
+     *
+     * const record = importStatement.toRecord();
+     * console.log(record);
+     * // {
+     * //   './types': ['User', { 'Product': 'IProduct' }]
+     * // }
+     * ```
+     */
     toRecord() {
         return {
             [this.module]: this.importNames.map(({ name, alias }) => alias ? { [name]: alias } : name)
         };
     }
+    /**
+     * Generates the TypeScript import statement string.
+     *
+     * This method produces a properly formatted ES6 import statement that can be
+     * written directly to a TypeScript file. It handles both simple and aliased
+     * imports correctly.
+     *
+     * @returns The formatted import statement string
+     *
+     * @example
+     * ```typescript
+     * const basicImport = new Import({
+     *   module: './utils',
+     *   importNames: ['formatDate', 'parseJson']
+     * });
+     *
+     * console.log(basicImport.toString());
+     * // import { formatDate, parseJson } from './utils'
+     *
+     * const aliasedImport = new Import({
+     *   module: 'lodash',
+     *   importNames: [{ 'isEqual': 'deepEqual' }, 'cloneDeep']
+     * });
+     *
+     * console.log(aliasedImport.toString());
+     * // import { isEqual as deepEqual, cloneDeep } from 'lodash'
+     * ```
+     *
+     * @todo Move syntax to typescript package to enable language-agnostic use
+     */
     toString() {
         // @TODO move syntax to typescript package to enable
         // language agnostic use
         return `import { ${this.importNames.join(', ')} } from '${this.module}'`;
     }
 }
+/**
+ * Represents a single import name with optional aliasing.
+ *
+ * This class handles the parsing and formatting of individual import specifiers,
+ * supporting both simple imports and aliased imports. It's used internally by
+ * the {@link Import} class to manage import statement components.
+ *
+ * @example Simple import name
+ * ```typescript
+ * const simple = new ImportName('useState');
+ * console.log(simple.toString()); // 'useState'
+ * ```
+ *
+ * @example Aliased import name
+ * ```typescript
+ * const aliased = new ImportName({ 'React': 'ReactLib' });
+ * console.log(aliased.toString()); // 'React as ReactLib'
+ * ```
+ */
 export class ImportName {
+    /**
+     * Creates a new ImportName instance.
+     *
+     * @param name - Either a string for simple imports or an object for aliased imports
+     *
+     * @example Simple import
+     * ```typescript
+     * const importName = new ImportName('User');
+     * // Results in: User
+     * ```
+     *
+     * @example Aliased import
+     * ```typescript
+     * const importName = new ImportName({ 'UserInterface': 'IUser' });
+     * // Results in: UserInterface as IUser
+     * ```
+     */
     constructor(name) {
+        /** The original name being imported */
         Object.defineProperty(this, "name", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The alias to use (if any) */
         Object.defineProperty(this, "alias", {
             enumerable: true,
             configurable: true,
@@ -49,6 +230,27 @@ export class ImportName {
             this.alias = alias;
         }
     }
+    /**
+     * Generates the string representation of the import name.
+     *
+     * This method creates the appropriate import specifier syntax,
+     * either a simple name or an aliased import using TypeScript's
+     * 'as' keyword.
+     *
+     * @returns The formatted import specifier string
+     *
+     * @example Simple import
+     * ```typescript
+     * const simple = new ImportName('useState');
+     * console.log(simple.toString()); // 'useState'
+     * ```
+     *
+     * @example Aliased import
+     * ```typescript
+     * const aliased = new ImportName({ 'Component': 'ReactComponent' });
+     * console.log(aliased.toString()); // 'Component as ReactComponent'
+     * ```
+     */
     toString() {
         return this.alias ? `${this.name} as ${this.alias}` : this.name;
     }