@skmtc/core 0.0.785 → 0.0.787

package/esm/types/GeneratorType.d.ts

@@ -1,8 +1,127 @@
 import type { OperationConfig } from '../dsl/operation/types.js';
 import type { ModelConfig } from '../dsl/model/types.js';
+/**
+ * Union type representing all possible generator configurations.
+ *
+ * Generator configurations define how different types of generators should
+ * process OpenAPI documents. This includes both operation generators (which
+ * process API endpoints) and model generators (which process data schemas).
+ *
+ * @template EnrichmentType - Optional type for custom enrichment data
+ *
+ * @example
+ * ```typescript
+ * import { GeneratorConfig } from '@skmtc/core';
+ *
+ * // Operation generator configuration
+ * const apiClientConfig: GeneratorConfig = {
+ *   type: 'operation',
+ *   generatorId: 'api-client',
+ *   settings: {
+ *     exportPath: './src/api/client.ts',
+ *     enrichment: customEnrichments
+ *   },
+ *   toGenerator: (args) => new ApiClientGenerator(args)
+ * };
+ *
+ * // Model generator configuration
+ * const typescriptModels: GeneratorConfig = {
+ *   type: 'model',
+ *   generatorId: 'typescript-models',
+ *   settings: {
+ *     exportPath: './src/types/models.ts'
+ *   },
+ *   toGenerator: (args) => new TypeScriptModelGenerator(args)
+ * };
+ * ```
+ */
 export type GeneratorConfig<EnrichmentType = undefined> = OperationConfig<EnrichmentType> | ModelConfig<EnrichmentType>;
+/**
+ * Type-safe mapping of generator configurations.
+ *
+ * This type preserves the structure and types of generator configurations
+ * within a map, ensuring that each generator maintains its specific
+ * configuration type and enrichment data.
+ *
+ * @template G - The generator configuration type
+ * @template EnrichmentType - The enrichment type for the generators
+ *
+ * @example
+ * ```typescript
+ * type MyGenerators = {
+ *   'api-client': OperationConfig<ApiEnrichment>;
+ *   'typescript-models': ModelConfig<ModelEnrichment>;
+ *   'validation': ModelConfig<ValidationEnrichment>;
+ * };
+ *
+ * type MyGeneratorsMap = GeneratorsMap<MyGenerators, undefined>;
+ * // Preserves the exact structure and types of MyGenerators
+ * ```
+ */
 export type GeneratorsMap<G extends GeneratorConfig<EnrichmentType>, EnrichmentType> = {
     [K in keyof G]: G[K];
 };
+/**
+ * Container type for a complete generators map with optional enrichment.
+ *
+ * This type represents a complete mapping of generators that can process
+ * an OpenAPI document. It's used as the main configuration structure
+ * passed to the SKMTC processing pipeline.
+ *
+ * @template EnrichmentType - Optional type for custom enrichment data across all generators
+ *
+ * @example Basic generators map
+ * ```typescript
+ * import { GeneratorsMapContainer } from '@skmtc/core';
+ *
+ * const generators: GeneratorsMapContainer = {
+ *   'api-client': {
+ *     type: 'operation',
+ *     generatorId: 'api-client',
+ *     settings: { exportPath: './src/api.ts' },
+ *     toGenerator: (args) => new ApiClientGenerator(args)
+ *   },
+ *   'typescript-models': {
+ *     type: 'model',
+ *     generatorId: 'typescript-models',
+ *     settings: { exportPath: './src/models.ts' },
+ *     toGenerator: (args) => new TypeScriptModels(args)
+ *   }
+ * };
+ *
+ * // Use with toArtifacts
+ * const result = await toArtifacts({
+ *   documentObject: openApiDoc,
+ *   settings: clientSettings,
+ *   toGeneratorConfigMap: () => generators,
+ *   traceId: 'generation',
+ *   spanId: 'main',
+ *   startAt: Date.now()
+ * });
+ * ```
+ *
+ * @example With enrichments
+ * ```typescript
+ * type MyEnrichments = {
+ *   customValidation: boolean;
+ *   generateComments: boolean;
+ * };
+ *
+ * const enrichedGenerators: GeneratorsMapContainer<MyEnrichments> = {
+ *   'enhanced-models': {
+ *     type: 'model',
+ *     generatorId: 'enhanced-models',
+ *     settings: {
+ *       exportPath: './src/enhanced.ts',
+ *       enrichment: {
+ *         customValidation: true,
+ *         generateComments: true
+ *       }
+ *     },
+ *     toGenerator: (args) => new EnhancedModelGenerator(args)
+ *   }
+ * };
+ * ```
+ */
 export type GeneratorsMapContainer<EnrichmentType = undefined> = GeneratorsMap<GeneratorConfig<EnrichmentType>, EnrichmentType>;
 //# sourceMappingURL=GeneratorType.d.ts.map

package/esm/types/GeneratorType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GeneratorType.d.ts","sourceRoot":"","sources":["../../src/types/GeneratorType.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD,MAAM,MAAM,eAAe,CAAC,cAAc,GAAG,SAAS,IAClD,eAAe,CAAC,cAAc,CAAC,GAC/B,WAAW,CAAC,cAAc,CAAC,CAAA;AAE/B,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,eAAe,CAAC,cAAc,CAAC,EAAE,cAAc,IAAI;KACpF,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACrB,CAAA;AAED,MAAM,MAAM,sBAAsB,CAAC,cAAc,GAAG,SAAS,IAAI,aAAa,CAC5E,eAAe,CAAC,cAAc,CAAC,EAC/B,cAAc,CACf,CAAA"}
+{"version":3,"file":"GeneratorType.d.ts","sourceRoot":"","sources":["../../src/types/GeneratorType.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,eAAe,CAAC,cAAc,GAAG,SAAS,IAClD,eAAe,CAAC,cAAc,CAAC,GAC/B,WAAW,CAAC,cAAc,CAAC,CAAA;AAE/B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,eAAe,CAAC,cAAc,CAAC,EAAE,cAAc,IAAI;KACpF,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACrB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,MAAM,MAAM,sBAAsB,CAAC,cAAc,GAAG,SAAS,IAAI,aAAa,CAC5E,eAAe,CAAC,cAAc,CAAC,EAC/B,cAAc,CACf,CAAA"}

package/esm/types/Method.d.ts

@@ -1,7 +1,42 @@
 import "../_dnt.polyfills.js";
 import * as v from 'valibot';
+/**
+ * Array of all valid HTTP methods supported by OpenAPI v3.
+ *
+ * This constant array includes all HTTP methods that can be used
+ * in OpenAPI path operations, as defined by the OpenAPI specification.
+ */
 export declare const methodValues: readonly ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+/**
+ * Array of HTTP methods excluding TRACE.
+ *
+ * This is a filtered version of {@link methodValues} that excludes the TRACE method,
+ * which is sometimes excluded from API operations for security reasons.
+ */
 export declare const methodValuesNoTrace: string[];
+/**
+ * Valibot schema for validating HTTP method strings.
+ *
+ * This union schema validates that a string value is one of the valid
+ * HTTP methods supported by OpenAPI. Used throughout the codebase for
+ * runtime validation of method values.
+ *
+ * @example
+ * ```typescript
+ * import * as v from 'valibot';
+ * import { method } from '@skmtc/core';
+ *
+ * // Valid method
+ * const result1 = v.parse(method, 'get'); // 'get'
+ *
+ * // Invalid method throws ValiError
+ * try {
+ *   v.parse(method, 'invalid');
+ * } catch (error) {
+ *   console.log('Invalid method');
+ * }
+ * ```
+ */
 export declare const method: v.UnionSchema<[
     v.LiteralSchema<'get', undefined>,
     v.LiteralSchema<'post', undefined>,
@@ -12,7 +47,81 @@ export declare const method: v.UnionSchema<[
     v.LiteralSchema<'options', undefined>,
     v.LiteralSchema<'trace', undefined>
 ], undefined>;
+/**
+ * TypeScript type representing valid HTTP methods.
+ *
+ * This union type includes all HTTP methods supported by OpenAPI v3 operations.
+ * It's used throughout the codebase for type safety when working with API methods.
+ *
+ * @example
+ * ```typescript
+ * import { Method } from '@skmtc/core';
+ *
+ * function processOperation(method: Method, path: string) {
+ *   switch (method) {
+ *     case 'get':
+ *       return handleGet(path);
+ *     case 'post':
+ *       return handlePost(path);
+ *     // ... handle other methods
+ *     default:
+ *       // TypeScript ensures exhaustive checking
+ *       const _exhaustive: never = method;
+ *       throw new Error(`Unhandled method: ${method}`);
+ *   }
+ * }
+ * ```
+ */
 export type Method = 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace';
+/**
+ * Valibot schema for validating arrays of HTTP methods.
+ *
+ * This schema validates that an array contains only valid HTTP method strings.
+ * Useful for validating configuration objects that specify multiple methods.
+ *
+ * @example
+ * ```typescript
+ * import * as v from 'valibot';
+ * import { methods } from '@skmtc/core';
+ *
+ * // Valid methods array
+ * const validMethods = v.parse(methods, ['get', 'post', 'put']); // ['get', 'post', 'put']
+ *
+ * // Invalid methods array throws ValiError
+ * try {
+ *   v.parse(methods, ['get', 'invalid', 'post']);
+ * } catch (error) {
+ *   console.log('Invalid methods in array');
+ * }
+ * ```
+ */
 export declare const methods: v.ArraySchema<typeof method, undefined>;
+/**
+ * Type guard to check if a value is a valid HTTP Method.
+ *
+ * This function uses the Valibot schema to safely determine if an unknown
+ * value is a valid HTTP method string. It's particularly useful when parsing
+ * user input or external data.
+ *
+ * @param arg - Value to check
+ * @returns True if the value is a valid Method
+ *
+ * @example
+ * ```typescript
+ * import { isMethod } from '@skmtc/core';
+ *
+ * function handleRequest(methodStr: unknown, path: string) {
+ *   if (isMethod(methodStr)) {
+ *     // methodStr is now typed as Method
+ *     console.log(`Processing ${methodStr.toUpperCase()} ${path}`);
+ *   } else {
+ *     throw new Error(`Invalid HTTP method: ${methodStr}`);
+ *   }
+ * }
+ *
+ * handleRequest('get', '/users');    // Works
+ * handleRequest('invalid', '/users'); // Throws error
+ * ```
+ */
 export declare const isMethod: (arg: unknown) => arg is Method;
 //# sourceMappingURL=Method.d.ts.map

package/esm/types/Method.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Method.d.ts","sourceRoot":"","sources":["../../src/types/Method.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,eAAO,MAAM,YAAY,gFASf,CAAA;AAEV,eAAO,MAAM,mBAAmB,UAA+D,CAAA;AAE/F,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,WAAW,CAChC;IACE,CAAC,CAAC,aAAa,CAAC,KAAK,EAAE,SAAS,CAAC;IACjC,CAAC,CAAC,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC;IAClC,CAAC,CAAC,aAAa,CAAC,KAAK,EAAE,SAAS,CAAC;IACjC,CAAC,CAAC,aAAa,CAAC,OAAO,EAAE,SAAS,CAAC;IACnC,CAAC,CAAC,aAAa,CAAC,QAAQ,EAAE,SAAS,CAAC;IACpC,CAAC,CAAC,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC;IAClC,CAAC,CAAC,aAAa,CAAC,SAAS,EAAE,SAAS,CAAC;IACrC,CAAC,CAAC,aAAa,CAAC,OAAO,EAAE,SAAS,CAAC;CACpC,EACD,SAAS,CAUT,CAAA;AAEF,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAA;AAI/F,eAAO,MAAM,OAAO,EAAE,CAAC,CAAC,WAAW,CAAC,OAAO,MAAM,EAAE,SAAS,CAAmB,CAAA;AAE/E,eAAO,MAAM,QAAQ,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,MAE9C,CAAA"}
+{"version":3,"file":"Method.d.ts","sourceRoot":"","sources":["../../src/types/Method.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;GAKG;AACH,eAAO,MAAM,YAAY,gFASf,CAAA;AAEV;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,UAA+D,CAAA;AAE/F;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,WAAW,CAChC;IACE,CAAC,CAAC,aAAa,CAAC,KAAK,EAAE,SAAS,CAAC;IACjC,CAAC,CAAC,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC;IAClC,CAAC,CAAC,aAAa,CAAC,KAAK,EAAE,SAAS,CAAC;IACjC,CAAC,CAAC,aAAa,CAAC,OAAO,EAAE,SAAS,CAAC;IACnC,CAAC,CAAC,aAAa,CAAC,QAAQ,EAAE,SAAS,CAAC;IACpC,CAAC,CAAC,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC;IAClC,CAAC,CAAC,aAAa,CAAC,SAAS,EAAE,SAAS,CAAC;IACrC,CAAC,CAAC,aAAa,CAAC,OAAO,EAAE,SAAS,CAAC;CACpC,EACD,SAAS,CAUT,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAA;AAG/F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,OAAO,EAAE,CAAC,CAAC,WAAW,CAAC,OAAO,MAAM,EAAE,SAAS,CAAmB,CAAA;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,MAE9C,CAAA"}

package/esm/types/Method.js

@@ -1,5 +1,11 @@
 import "../_dnt.polyfills.js";
 import * as v from 'valibot';
+/**
+ * Array of all valid HTTP methods supported by OpenAPI v3.
+ *
+ * This constant array includes all HTTP methods that can be used
+ * in OpenAPI path operations, as defined by the OpenAPI specification.
+ */
 export const methodValues = [
     'get',
     'put',
@@ -10,7 +16,36 @@ export const methodValues = [
     'patch',
     'trace'
 ];
+/**
+ * Array of HTTP methods excluding TRACE.
+ *
+ * This is a filtered version of {@link methodValues} that excludes the TRACE method,
+ * which is sometimes excluded from API operations for security reasons.
+ */
 export const methodValuesNoTrace = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch'];
+/**
+ * Valibot schema for validating HTTP method strings.
+ *
+ * This union schema validates that a string value is one of the valid
+ * HTTP methods supported by OpenAPI. Used throughout the codebase for
+ * runtime validation of method values.
+ *
+ * @example
+ * ```typescript
+ * import * as v from 'valibot';
+ * import { method } from '@skmtc/core';
+ *
+ * // Valid method
+ * const result1 = v.parse(method, 'get'); // 'get'
+ *
+ * // Invalid method throws ValiError
+ * try {
+ *   v.parse(method, 'invalid');
+ * } catch (error) {
+ *   console.log('Invalid method');
+ * }
+ * ```
+ */
 export const method = v.union([
     v.literal('get'),
     v.literal('post'),
@@ -21,7 +56,56 @@ export const method = v.union([
     v.literal('options'),
     v.literal('trace')
 ]);
+/**
+ * Valibot schema for validating arrays of HTTP methods.
+ *
+ * This schema validates that an array contains only valid HTTP method strings.
+ * Useful for validating configuration objects that specify multiple methods.
+ *
+ * @example
+ * ```typescript
+ * import * as v from 'valibot';
+ * import { methods } from '@skmtc/core';
+ *
+ * // Valid methods array
+ * const validMethods = v.parse(methods, ['get', 'post', 'put']); // ['get', 'post', 'put']
+ *
+ * // Invalid methods array throws ValiError
+ * try {
+ *   v.parse(methods, ['get', 'invalid', 'post']);
+ * } catch (error) {
+ *   console.log('Invalid methods in array');
+ * }
+ * ```
+ */
 export const methods = v.array(method);
+/**
+ * Type guard to check if a value is a valid HTTP Method.
+ *
+ * This function uses the Valibot schema to safely determine if an unknown
+ * value is a valid HTTP method string. It's particularly useful when parsing
+ * user input or external data.
+ *
+ * @param arg - Value to check
+ * @returns True if the value is a valid Method
+ *
+ * @example
+ * ```typescript
+ * import { isMethod } from '@skmtc/core';
+ *
+ * function handleRequest(methodStr: unknown, path: string) {
+ *   if (isMethod(methodStr)) {
+ *     // methodStr is now typed as Method
+ *     console.log(`Processing ${methodStr.toUpperCase()} ${path}`);
+ *   } else {
+ *     throw new Error(`Invalid HTTP method: ${methodStr}`);
+ *   }
+ * }
+ *
+ * handleRequest('get', '/users');    // Works
+ * handleRequest('invalid', '/users'); // Throws error
+ * ```
+ */
 export const isMethod = (arg) => {
     return v.safeParse(method, arg).success;
 };

package/esm/types/RefName.d.ts

@@ -1,4 +1,65 @@
 import "../_dnt.polyfills.js";
 import type { Brand } from './Brand.js';
+/**
+ * Branded type representing a reference name for OpenAPI schemas.
+ *
+ * `RefName` is a branded string type that ensures type safety when working
+ * with schema reference names throughout the SKMTC system. It prevents
+ * accidental mixing of regular strings with schema reference identifiers.
+ *
+ * Reference names typically correspond to keys in the OpenAPI `components.schemas`
+ * section and are used to create cross-references between different parts
+ * of the schema definition.
+ *
+ * @example
+ * ```typescript
+ * import { RefName } from '@skmtc/core';
+ *
+ * // RefName is extracted from OpenAPI schema references
+ * const userRefName: RefName = 'User' as RefName;
+ * const productRefName: RefName = 'Product' as RefName;
+ *
+ * // Used in schema references
+ * const userRef = new OasRef({
+ *   refName: userRefName, // Type-safe reference name
+ *   ref: '#/components/schemas/User'
+ * });
+ * ```
+ *
+ * @example In generator contexts
+ * ```typescript
+ * class ModelGenerator extends ModelBase {
+ *   constructor(args: { refName: RefName; ... }) {
+ *     super(args);
+ *     // this.refName is guaranteed to be a valid schema reference
+ *   }
+ *
+ *   toDefinition(): Definition {
+ *     // RefName ensures we're working with valid schema identifiers
+ *     const schemaName = this.refName; // Type: RefName
+ *     return new Definition({
+ *       identifier: Identifier.createType(schemaName),
+ *       // ...
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Type safety benefits
+ * ```typescript
+ * function processSchema(refName: RefName) {
+ *   // RefName brand ensures this is a valid schema reference
+ *   console.log(`Processing schema: ${refName}`);
+ * }
+ *
+ * const validRef: RefName = 'User' as RefName;
+ * const regularString = 'just a string';
+ *
+ * processSchema(validRef);     // ✅ Works - RefName type
+ * processSchema(regularString); // ❌ TypeScript error - string is not RefName
+ * ```
+ *
+ * @see {@link Brand} for the underlying branding mechanism
+ */
 export type RefName = Brand<string, 'RefName'>;
 //# sourceMappingURL=RefName.d.ts.map

package/esm/types/RefName.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RefName.d.ts","sourceRoot":"","sources":["../../src/types/RefName.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA"}
+{"version":3,"file":"RefName.d.ts","sourceRoot":"","sources":["../../src/types/RefName.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skmtc/core",
-  "version": "0.0.785",
+  "version": "0.0.787",
   "repository": {
     "type": "git",
     "url": "https://github.com/skmtc/skmtc.git"

package/script/dsl/ContentSettings.d.ts

@@ -1,18 +1,182 @@
 import type { Identifier } from './Identifier.js';
+/**
+ * Arguments for creating empty ContentSettings without enrichments.
+ */
 type EmptyArgs = {
+    /** The path where generated content will be exported */
     exportPath: string;
+    /** The identifier for the content being generated */
     identifier: Identifier;
 };
+/**
+ * Arguments for creating ContentSettings with enrichments.
+ *
+ * @template EnrichmentType - The type of enrichment data
+ */
 type CreateArgs<EnrichmentType = undefined> = {
+    /** The identifier for the content being generated */
     identifier: Identifier;
+    /** The path where generated content will be exported */
     exportPath: string;
+    /** Custom enrichment data for extending generation */
     enrichments: EnrichmentType;
 };
+/**
+ * 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}`
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ */
 export declare class ContentSettings<EnrichmentType = undefined> {
+    /** The identifier for the content being generated */
     identifier: Identifier;
+    /** The path where generated content will be exported */
     exportPath: string;
+    /** Custom enrichment data for extending generation */
     enrichments: EnrichmentType;
+    /**
+     * 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 }: CreateArgs<EnrichmentType>);
+    /**
+     * 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 }: EmptyArgs): ContentSettings<undefined>;
 }
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"ContentSettings.d.ts","sourceRoot":"","sources":["../../src/dsl/ContentSettings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,KAAK,SAAS,GAAG;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,UAAU,CAAA;CACvB,CAAA;AAED,KAAK,UAAU,CAAC,cAAc,GAAG,SAAS,IAAI;IAC5C,UAAU,EAAE,UAAU,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,cAAc,CAAA;CAC5B,CAAA;AAED,qBAAa,eAAe,CAAC,cAAc,GAAG,SAAS;IACrD,UAAU,EAAE,UAAU,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,cAAc,CAAA;gBACf,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,EAAE,UAAU,CAAC,cAAc,CAAC;IAM/E,MAAM,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,UAAU,EAAE,EAAE,SAAS,GAAG,eAAe,CAAC,SAAS,CAAC;CAOhF"}
+{"version":3,"file":"ContentSettings.d.ts","sourceRoot":"","sources":["../../src/dsl/ContentSettings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD;;GAEG;AACH,KAAK,SAAS,GAAG;IACf,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAA;IAClB,qDAAqD;IACrD,UAAU,EAAE,UAAU,CAAA;CACvB,CAAA;AAED;;;;GAIG;AACH,KAAK,UAAU,CAAC,cAAc,GAAG,SAAS,IAAI;IAC5C,qDAAqD;IACrD,UAAU,EAAE,UAAU,CAAA;IACtB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAA;IAClB,sDAAsD;IACtD,WAAW,EAAE,cAAc,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4FG;AACH,qBAAa,eAAe,CAAC,cAAc,GAAG,SAAS;IACrD,qDAAqD;IACrD,UAAU,EAAE,UAAU,CAAA;IAEtB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAA;IAElB,sDAAsD;IACtD,WAAW,EAAE,cAAc,CAAA;IAE3B;;;;;;;;;;;;;;;;;;;OAmBG;gBACS,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,EAAE,UAAU,CAAC,cAAc,CAAC;IAM/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,MAAM,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,UAAU,EAAE,EAAE,SAAS,GAAG,eAAe,CAAC,SAAS,CAAC;CAOhF"}