@skmtc/core 0.0.785 → 0.0.786

package/esm/types/GeneratorKeys.js

@@ -1,23 +1,148 @@
 import "../_dnt.polyfills.js";
 import { isMethod } from './Method.js';
+/**
+ * Creates an operation generator key from generator ID and operation details.
+ *
+ * Operation generator keys uniquely identify generators processing specific
+ * API operations. The key format is: `generatorId|path|method`
+ *
+ * @param args - Operation generator key arguments
+ * @returns A branded OperationGeneratorKey
+ *
+ * @example With explicit path and method
+ * ```typescript
+ * const key = toOperationGeneratorKey({
+ *   generatorId: 'api-client',
+ *   path: '/users/{id}',
+ *   method: 'get'
+ * });
+ * // Result: 'api-client|/users/{id}|get' (branded)
+ * ```
+ *
+ * @example With OasOperation object
+ * ```typescript
+ * const operation = new OasOperation({
+ *   path: '/posts',
+ *   method: 'post',
+ *   // ... other operation details
+ * });
+ *
+ * const key = toOperationGeneratorKey({
+ *   generatorId: 'rest-client',
+ *   operation
+ * });
+ * // Result: 'rest-client|/posts|post' (branded)
+ * ```
+ */
 export const toOperationGeneratorKey = ({ generatorId, ...rest }) => {
     const { path, method } = 'operation' in rest ? rest.operation : rest;
     const nakedKey = `${generatorId}|${path}|${method}`;
     return nakedKey;
 };
+/**
+ * Creates a model generator key from generator ID and schema reference name.
+ *
+ * Model generator keys uniquely identify generators processing specific
+ * OpenAPI schema models. The key format is: `generatorId|refName`
+ *
+ * @param args - Model generator key arguments
+ * @returns A branded ModelGeneratorKey
+ *
+ * @example
+ * ```typescript
+ * const key = toModelGeneratorKey({
+ *   generatorId: 'typescript-interfaces',
+ *   refName: 'User'
+ * });
+ * // Result: 'typescript-interfaces|User' (branded)
+ *
+ * const validationKey = toModelGeneratorKey({
+ *   generatorId: 'zod-schemas',
+ *   refName: 'CreateUserRequest'
+ * });
+ * // Result: 'zod-schemas|CreateUserRequest' (branded)
+ * ```
+ */
 export const toModelGeneratorKey = ({ generatorId, refName }) => {
     const nakedKey = `${generatorId}|${refName}`;
     return nakedKey;
 };
+/**
+ * Creates a generator-only key for global/utility generators.
+ *
+ * Generator-only keys identify generators that produce artifacts not tied
+ * to specific operations or models, such as configuration files, base classes,
+ * utilities, or documentation.
+ *
+ * @param args - Generator-only key arguments
+ * @returns A branded GeneratorOnlyKey
+ *
+ * @example
+ * ```typescript
+ * const configKey = toGeneratorOnlyKey({
+ *   generatorId: 'api-config'
+ * });
+ * // Result: 'api-config' (branded)
+ *
+ * const utilsKey = toGeneratorOnlyKey({
+ *   generatorId: 'common-utilities'
+ * });
+ * // Result: 'common-utilities' (branded)
+ * ```
+ */
 export const toGeneratorOnlyKey = ({ generatorId }) => {
     const nakedKey = `${generatorId}`;
     return nakedKey;
 };
+/**
+ * Type guard to check if a value is a valid GeneratorKey.
+ *
+ * This function validates that the argument is one of the three
+ * generator key types: operation, model, or generator-only.
+ *
+ * @param arg - Value to check
+ * @returns True if the value is a valid GeneratorKey
+ *
+ * @example
+ * ```typescript
+ * const key = 'api-client|/users|get';
+ *
+ * if (isGeneratorKey(key)) {
+ *   // key is now typed as GeneratorKey
+ *   const generatorId = toGeneratorId(key);
+ *   console.log(generatorId); // 'api-client'
+ * }
+ * ```
+ */
 export const isGeneratorKey = (arg) => {
     return (isModelGeneratorKey(arg) ||
         isOperationGeneratorKey(arg) ||
         isGeneratorOnlyKey(arg));
 };
+/**
+ * Type guard to check if a value is a valid OperationGeneratorKey.
+ *
+ * Validates that the argument is a string with the correct format:
+ * `generatorId|path|method` where each part is non-empty and method
+ * is a valid HTTP method.
+ *
+ * @param arg - Value to check
+ * @returns True if the value is a valid OperationGeneratorKey
+ *
+ * @example
+ * ```typescript
+ * const key = 'api-client|/users/{id}|get';
+ *
+ * if (isOperationGeneratorKey(key)) {
+ *   // key is now typed as OperationGeneratorKey
+ *   const obj = fromGeneratorKey(key);
+ *   console.log(obj.type);        // 'operation'
+ *   console.log(obj.generatorId); // 'api-client'
+ *   console.log(obj.path);        // '/users/{id}'
+ *   console.log(obj.method);      // 'get'
+ * }
+ * ```
+ */
 export const isOperationGeneratorKey = (arg) => {
     if (typeof arg !== 'string') {
         return false;
@@ -38,6 +163,28 @@ export const isOperationGeneratorKey = (arg) => {
     }
     return true;
 };
+/**
+ * Type guard to check if a value is a valid ModelGeneratorKey.
+ *
+ * Validates that the argument is a string with the correct format:
+ * `generatorId|refName` where both parts are non-empty strings.
+ *
+ * @param arg - Value to check
+ * @returns True if the value is a valid ModelGeneratorKey
+ *
+ * @example
+ * ```typescript
+ * const key = 'zod-schemas|User';
+ *
+ * if (isModelGeneratorKey(key)) {
+ *   // key is now typed as ModelGeneratorKey
+ *   const obj = fromGeneratorKey(key);
+ *   console.log(obj.type);        // 'model'
+ *   console.log(obj.generatorId); // 'zod-schemas'
+ *   console.log(obj.refName);     // 'User'
+ * }
+ * ```
+ */
 export const isModelGeneratorKey = (arg) => {
     if (typeof arg !== 'string') {
         return false;
@@ -55,12 +202,65 @@ export const isModelGeneratorKey = (arg) => {
     }
     return true;
 };
+/**
+ * Type guard to check if a value is a valid GeneratorOnlyKey.
+ *
+ * Validates that the argument is a non-empty string. Generator-only keys
+ * are simple strings containing just the generator ID.
+ *
+ * @param arg - Value to check
+ * @returns True if the value is a valid GeneratorOnlyKey
+ *
+ * @example
+ * ```typescript
+ * const key = 'api-config';
+ *
+ * if (isGeneratorOnlyKey(key)) {
+ *   // key is now typed as GeneratorOnlyKey
+ *   const obj = fromGeneratorKey(key);
+ *   console.log(obj.type);        // 'generator-only'
+ *   console.log(obj.generatorId); // 'api-config'
+ * }
+ * ```
+ */
 export const isGeneratorOnlyKey = (arg) => {
     if (typeof arg !== 'string') {
         return false;
     }
     return Boolean(arg.length);
 };
+/**
+ * Extracts the generator ID from any type of GeneratorKey.
+ *
+ * This utility function parses the generator key to extract just the
+ * generator identifier, regardless of the key type. For operation and
+ * model keys, it extracts the first part before the pipe. For generator-only
+ * keys, it returns the entire key since it's just the generator ID.
+ *
+ * @param generatorKey - Any type of generator key
+ * @returns The generator ID string
+ *
+ * @example
+ * ```typescript
+ * const opKey = toOperationGeneratorKey({
+ *   generatorId: 'api-client',
+ *   path: '/users',
+ *   method: 'get'
+ * });
+ * console.log(toGeneratorId(opKey)); // 'api-client'
+ *
+ * const modelKey = toModelGeneratorKey({
+ *   generatorId: 'typescript-types',
+ *   refName: 'User'
+ * });
+ * console.log(toGeneratorId(modelKey)); // 'typescript-types'
+ *
+ * const globalKey = toGeneratorOnlyKey({
+ *   generatorId: 'utilities'
+ * });
+ * console.log(toGeneratorId(globalKey)); // 'utilities'
+ * ```
+ */
 export const toGeneratorId = (generatorKey) => {
     if (isOperationGeneratorKey(generatorKey)) {
         return generatorKey.split('|')[0];
@@ -70,6 +270,49 @@ export const toGeneratorId = (generatorKey) => {
     }
     return generatorKey;
 };
+/**
+ * Parses a GeneratorKey into its structured object representation.
+ *
+ * This function decomposes any generator key into a structured object
+ * with discriminated union types, making it easier to work with the
+ * key components in a type-safe manner.
+ *
+ * @param generatorKey - Any type of generator key to parse
+ * @returns Parsed generator key object with discriminated type
+ *
+ * @example Operation key parsing
+ * ```typescript
+ * const opKey = 'api-client|/users/{id}|get' as OperationGeneratorKey;
+ * const parsed = fromGeneratorKey(opKey);
+ *
+ * if (parsed.type === 'operation') {
+ *   console.log(parsed.generatorId); // 'api-client'
+ *   console.log(parsed.path);        // '/users/{id}'
+ *   console.log(parsed.method);      // 'get'
+ * }
+ * ```
+ *
+ * @example Model key parsing
+ * ```typescript
+ * const modelKey = 'zod-schemas|User' as ModelGeneratorKey;
+ * const parsed = fromGeneratorKey(modelKey);
+ *
+ * if (parsed.type === 'model') {
+ *   console.log(parsed.generatorId); // 'zod-schemas'
+ *   console.log(parsed.refName);     // 'User'
+ * }
+ * ```
+ *
+ * @example Generator-only key parsing
+ * ```typescript
+ * const globalKey = 'utilities' as GeneratorOnlyKey;
+ * const parsed = fromGeneratorKey(globalKey);
+ *
+ * if (parsed.type === 'generator-only') {
+ *   console.log(parsed.generatorId); // 'utilities'
+ * }
+ * ```
+ */
 export const fromGeneratorKey = (generatorKey) => {
     if (isOperationGeneratorKey(generatorKey)) {
         const [generatorId, path, method] = generatorKey.split('|');

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/package.json

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