@skmtc/core 0.0.786 → 0.0.788

package/script/dsl/Definition.js

@@ -3,27 +3,171 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Definition = void 0;
 const ContentBase_js_1 = require("./ContentBase.js");
 const withDescription_js_1 = require("../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)
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ */
 class Definition extends ContentBase_js_1.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,
@@ -35,6 +179,51 @@ class Definition extends ContentBase_js_1.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/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/JsonFile.d.ts

@@ -1,12 +1,174 @@
+/**
+ * Constructor arguments for {@link JsonFile}.
+ */
 type JsonFileArgs = {
+    /** The file path for the generated JSON file */
     path: string;
+    /** The JSON content to write to the file */
     content: Record<string, unknown>;
 };
+/**
+ * Represents a JSON file in the SKMTC DSL system.
+ *
+ * The `JsonFile` class is used to generate JSON files as part of the code generation
+ * process. It provides a simple interface for creating configuration files, manifests,
+ * package.json files, and other JSON-based artifacts with proper formatting.
+ *
+ * ## Key Features
+ *
+ * - **JSON Formatting**: Automatically formats JSON with 2-space indentation
+ * - **Type Safety**: Accepts any valid JSON-serializable content structure
+ * - **Path Management**: Associates content with specific file paths
+ * - **String Conversion**: Easy integration with file writing systems
+ *
+ * @example Basic JSON file creation
+ * ```typescript
+ * import { JsonFile } from '@skmtc/core';
+ *
+ * const packageJson = new JsonFile({
+ *   path: './package.json',
+ *   content: {
+ *     name: 'my-api-client',
+ *     version: '1.0.0',
+ *     type: 'module',
+ *     main: './index.js',
+ *     dependencies: {
+ *       'axios': '^1.0.0'
+ *     }
+ *   }
+ * });
+ *
+ * const jsonContent = packageJson.toString();
+ * console.log(jsonContent);
+ * // {
+ * //   "name": "my-api-client",
+ * //   "version": "1.0.0",
+ * //   "type": "module",
+ * //   "main": "./index.js",
+ * //   "dependencies": {
+ * //     "axios": "^1.0.0"
+ * //   }
+ * // }
+ * ```
+ *
+ * @example Configuration file generation
+ * ```typescript
+ * const configFile = new JsonFile({
+ *   path: './src/config/api.json',
+ *   content: {
+ *     baseUrl: 'https://api.example.com',
+ *     timeout: 5000,
+ *     retryAttempts: 3,
+ *     endpoints: {
+ *       users: '/users',
+ *       products: '/products',
+ *       orders: '/orders'
+ *     }
+ *   }
+ * });
+ *
+ * // Write to file system
+ * await Deno.writeTextFile(configFile.path, configFile.toString());
+ * ```
+ *
+ * @example OpenAPI specification output
+ * ```typescript
+ * const openApiFile = new JsonFile({
+ *   path: './dist/openapi.json',
+ *   content: {
+ *     openapi: '3.0.0',
+ *     info: {
+ *       title: 'My API',
+ *       version: '1.0.0'
+ *     },
+ *     paths: {
+ *       '/users': {
+ *         get: {
+ *           summary: 'List users',
+ *           responses: {
+ *             '200': {
+ *               description: 'Success'
+ *             }
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example Using with generator registration
+ * ```typescript
+ * class MyGenerator extends ContentBase {
+ *   generate() {
+ *     const manifestFile = new JsonFile({
+ *       path: './generated/manifest.json',
+ *       content: {
+ *         generatedAt: new Date().toISOString(),
+ *         version: '1.0.0',
+ *         files: [
+ *           './models/User.ts',
+ *           './models/Product.ts'
+ *         ]
+ *       }
+ *     });
+ *
+ *     // Register with the generation context
+ *     this.register({ jsonFile: manifestFile });
+ *   }
+ * }
+ * ```
+ */
 export declare class JsonFile {
+    /** The file type, always 'json' for JSON files */
     fileType: 'json';
+    /** The file path for this generated JSON file */
     path: string;
+    /** The JSON content to write to the file */
     content: Record<string, unknown>;
+    /**
+     * Creates a new JsonFile instance.
+     *
+     * @param args - JSON file configuration
+     * @param args.path - The output path for this JSON file
+     * @param args.content - The JSON content to write
+     *
+     * @example
+     * ```typescript
+     * const configFile = new JsonFile({
+     *   path: './config/settings.json',
+     *   content: {
+     *     theme: 'dark',
+     *     language: 'en',
+     *     features: ['auth', 'notifications']
+     *   }
+     * });
+     * ```
+     */
     constructor({ path, content }: JsonFileArgs);
+    /**
+     * Converts the JSON content to a formatted string.
+     *
+     * This method serializes the content object to JSON with 2-space indentation
+     * for readable output. The resulting string is suitable for writing directly
+     * to a file or including in the generation pipeline.
+     *
+     * @returns The formatted JSON content as a string
+     *
+     * @example
+     * ```typescript
+     * const file = new JsonFile({
+     *   path: './data.json',
+     *   content: { name: 'test', value: 42 }
+     * });
+     *
+     * console.log(file.toString());
+     * // {
+     * //   "name": "test",
+     * //   "value": 42
+     * // }
+     * ```
+     */
     toString(): string;
 }
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"JsonFile.d.ts","sourceRoot":"","sources":["../../src/dsl/JsonFile.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC,CAAA;AAED,qBAAa,QAAQ;IACnB,QAAQ,EAAE,MAAM,CAAS;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;gBAEpB,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,YAAY;IAK3C,QAAQ,IAAI,MAAM;CAGnB"}
+{"version":3,"file":"JsonFile.d.ts","sourceRoot":"","sources":["../../src/dsl/JsonFile.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,KAAK,YAAY,GAAG;IAClB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAA;IACZ,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+GG;AACH,qBAAa,QAAQ;IACnB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAS;IAEzB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAA;IAEZ,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAEhC;;;;;;;;;;;;;;;;;;OAkBG;gBACS,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,YAAY;IAK3C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,IAAI,MAAM;CAGnB"}