@skmtc/core 0.0.785 → 0.0.787

package/script/dsl/ContentSettings.js

@@ -1,20 +1,136 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContentSettings = void 0;
+/**
+ * Configuration settings for content generators in the SKMTC DSL system.
+ *
+ * `ContentSettings` encapsulates the configuration needed by generators to
+ * produce content, including where to export the generated files, how to
+ * identify the content, and any custom enrichment data for extending
+ * the generation process.
+ *
+ * This class is used by both {@link ModelBase} and {@link OperationBase}
+ * to configure their generation behavior, providing a consistent interface
+ * for generator settings across the system.
+ *
+ * ## Key Features
+ *
+ * - **Export Path Management**: Specifies where generated content should be written
+ * - **Identifier Integration**: Links content to specific identifiers for naming
+ * - **Enrichment Support**: Allows custom data to extend generation capabilities
+ * - **Type Safety**: Generic enrichment typing for compile-time validation
+ *
+ * @template EnrichmentType - The type of enrichment data (default: undefined)
+ *
+ * @example Basic settings without enrichments
+ * ```typescript
+ * import { ContentSettings, Identifier } from '@skmtc/core';
+ *
+ * const settings = ContentSettings.empty({
+ *   exportPath: './src/generated/models.ts',
+ *   identifier: Identifier.createType('UserModels')
+ * });
+ *
+ * console.log(settings.exportPath); // './src/generated/models.ts'
+ * console.log(settings.enrichments); // undefined
+ * ```
+ *
+ * @example Settings with custom enrichments
+ * ```typescript
+ * type ValidationEnrichment = {
+ *   validateRequired: boolean;
+ *   generateComments: boolean;
+ *   customValidators: string[];
+ * };
+ *
+ * const enrichedSettings = new ContentSettings({
+ *   identifier: Identifier.createType('ValidatedModels'),
+ *   exportPath: './src/models/validated.ts',
+ *   enrichments: {
+ *     validateRequired: true,
+ *     generateComments: true,
+ *     customValidators: ['email', 'phone']
+ *   }
+ * });
+ *
+ * // Access enrichment data in generators
+ * if (enrichedSettings.enrichments?.validateRequired) {
+ *   // Generate validation logic
+ * }
+ * ```
+ *
+ * @example Using with ModelBase
+ * ```typescript
+ * class ValidatedModelGenerator extends ModelBase<ValidationEnrichment> {
+ *   constructor(args) {
+ *     super({
+ *       ...args,
+ *       settings: new ContentSettings({
+ *         identifier: Identifier.createType(args.refName),
+ *         exportPath: './src/validated-models.ts',
+ *         enrichments: {
+ *           validateRequired: true,
+ *           generateComments: false,
+ *           customValidators: []
+ *         }
+ *       })
+ *     });
+ *   }
+ *
+ *   toDefinition(): Definition {
+ *     const validation = this.settings.enrichments?.validateRequired
+ *       ? this.generateValidation()
+ *       : '';
+ *
+ *     return new Definition({
+ *       context: this.context,
+ *       identifier: this.settings.identifier,
+ *       value: {
+ *         generatorKey: this.generatorKey,
+ *         content: `${this.generateInterface()}${validation}`
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ */
 class ContentSettings {
+    /**
+     * Creates a new ContentSettings instance with enrichments.
+     *
+     * @param args - Settings configuration
+     * @param args.identifier - The identifier for the content being generated
+     * @param args.exportPath - The path where generated content will be exported
+     * @param args.enrichments - Custom enrichment data for extending generation
+     *
+     * @example
+     * ```typescript
+     * const settings = new ContentSettings({
+     *   identifier: Identifier.createType('ApiModels'),
+     *   exportPath: './src/api/models.ts',
+     *   enrichments: {
+     *     includeValidation: true,
+   *     format: 'detailed'
+     *   }
+     * });
+     * ```
+     */
     constructor({ identifier, exportPath, enrichments }) {
+        /** The identifier for the content being generated */
         Object.defineProperty(this, "identifier", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The path where generated content will be exported */
         Object.defineProperty(this, "exportPath", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Custom enrichment data for extending generation */
         Object.defineProperty(this, "enrichments", {
             enumerable: true,
             configurable: true,
@@ -25,6 +141,41 @@ class ContentSettings {
         this.exportPath = exportPath;
         this.enrichments = enrichments;
     }
+    /**
+     * Factory method to create ContentSettings without enrichments.
+     *
+     * This is a convenience method for creating ContentSettings when no
+     * custom enrichment data is needed. It explicitly sets enrichments
+     * to undefined and returns a properly typed instance.
+     *
+     * @param args - Basic settings arguments
+     * @param args.identifier - The identifier for the content being generated
+     * @param args.exportPath - The path where generated content will be exported
+     * @returns ContentSettings instance with undefined enrichments
+     *
+     * @example
+     * ```typescript
+     * const basicSettings = ContentSettings.empty({
+     *   identifier: Identifier.createType('SimpleModels'),
+     *   exportPath: './src/models.ts'
+     * });
+     *
+     * console.log(basicSettings.enrichments); // undefined
+     *
+     * // Use in generator
+     * class SimpleGenerator extends ModelBase {
+     *   constructor(args) {
+     *     super({
+     *       ...args,
+     *       settings: ContentSettings.empty({
+     *         identifier: Identifier.createType(args.refName),
+     *         exportPath: './src/simple-models.ts'
+     *       })
+     *     });
+     *   }
+     * }
+     * ```
+     */
     static empty({ identifier, exportPath }) {
         return new ContentSettings({
             identifier,

package/script/dsl/Definition.d.ts

@@ -2,19 +2,218 @@ import type { GenerateContext } from '../context/GenerateContext.js';
 import type { Identifier } from './Identifier.js';
 import { ContentBase } from './ContentBase.js';
 import type { GeneratedValue } from '../types/GeneratedValue.js';
+/**
+ * Constructor arguments for {@link Definition}.
+ *
+ * @template V - The type of generated value this definition contains
+ */
 type ConstructorArgs<V extends GeneratedValue> = {
+    /** The generation context providing pipeline access */
     context: GenerateContext;
+    /** Optional description for JSDoc comments */
     description?: string;
+    /** The identifier for this definition */
     identifier: Identifier;
+    /** The generated value content */
     value: V;
+    /** Whether to skip the export keyword */
     noExport?: boolean;
 };
+/**
+ * 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 declare class Definition<V extends GeneratedValue = GeneratedValue> extends ContentBase {
+    /** The identifier for this definition */
     identifier: Identifier;
+    /** Optional description for JSDoc comments */
     description: string | undefined;
+    /** The generated value content */
     value: V;
+    /** Whether to skip the export keyword */
     noExport?: boolean;
+    /**
+     * 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 }: ConstructorArgs<V>);
+    /**
+     * 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(): string;
 }
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"Definition.d.ts","sourceRoot":"","sources":["../../src/dsl/Definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAEhE,KAAK,eAAe,CAAC,CAAC,SAAS,cAAc,IAAI;IAC/C,OAAO,EAAE,eAAe,CAAA;IACxB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,UAAU,CAAA;IACtB,KAAK,EAAE,CAAC,CAAA;IACR,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED,qBAAa,UAAU,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,CAAE,SAAQ,WAAW;IACpF,UAAU,EAAE,UAAU,CAAA;IACtB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,KAAK,EAAE,CAAC,CAAA;IACR,QAAQ,CAAC,EAAE,OAAO,CAAA;gBAEN,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,eAAe,CAAC,CAAC,CAAC;IAS5E,QAAQ,IAAI,MAAM;CAa5B"}
+{"version":3,"file":"Definition.d.ts","sourceRoot":"","sources":["../../src/dsl/Definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAEhE;;;;GAIG;AACH,KAAK,eAAe,CAAC,CAAC,SAAS,cAAc,IAAI;IAC/C,uDAAuD;IACvD,OAAO,EAAE,eAAe,CAAA;IACxB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,yCAAyC;IACzC,UAAU,EAAE,UAAU,CAAA;IACtB,kCAAkC;IAClC,KAAK,EAAE,CAAC,CAAA;IACR,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoHG;AACH,qBAAa,UAAU,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,CAAE,SAAQ,WAAW;IACpF,yCAAyC;IACzC,UAAU,EAAE,UAAU,CAAA;IAEtB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAE/B,kCAAkC;IAClC,KAAK,EAAE,CAAC,CAAA;IAER,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB;;;;;;;;;;;;;;;;;;;;;;OAsBG;gBACS,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,eAAe,CAAC,CAAC,CAAC;IASrF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACM,QAAQ,IAAI,MAAM;CAa5B"}

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}`