@skmtc/core 0.0.785 → 0.0.787

package/script/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/script/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/script/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/script/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/script/types/Method.js

@@ -36,6 +36,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isMethod = exports.methods = exports.method = exports.methodValuesNoTrace = exports.methodValues = void 0;
 require("../_dnt.polyfills.js");
 const v = __importStar(require("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.
+ */
 exports.methodValues = [
     'get',
     'put',
@@ -46,7 +52,36 @@ exports.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.
+ */
 exports.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');
+ * }
+ * ```
+ */
 exports.method = v.union([
     v.literal('get'),
     v.literal('post'),
@@ -57,7 +92,56 @@ exports.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');
+ * }
+ * ```
+ */
 exports.methods = v.array(exports.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
+ * ```
+ */
 const isMethod = (arg) => {
     return v.safeParse(exports.method, arg).success;
 };

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