@skmtc/core 0.0.782 → 0.0.785

package/esm/dsl/operation/OperationBase.d.ts

@@ -12,17 +12,192 @@ import type { RefName } from '../../types/RefName.js';
 import { OasSchema } from '../../oas/schema/Schema.js';
 import { OasRef } from '../../oas/ref/Ref.js';
 import { OasVoid } from '../../oas/void/Void.js';
+/**
+ * Constructor arguments for {@link OperationBase}.
+ *
+ * @template EnrichmentType - Optional type for custom enrichment data
+ */
 export type OperationBaseArgs<EnrichmentType = undefined> = {
+    /** The generation context providing access to the processing pipeline */
     context: GenerateContext;
+    /** Content settings including export path and enrichment configuration */
     settings: ContentSettings<EnrichmentType>;
+    /** Unique identifier for this generator type */
     generatorKey: GeneratorKey;
+    /** The OpenAPI operation being processed */
     operation: OasOperation;
 };
+/**
+ * Base class for operation generators in the SKMTC DSL system.
+ *
+ * `OperationBase` extends {@link ContentBase} to provide specialized functionality for
+ * generating code from OpenAPI operations. It offers type-safe methods for inserting
+ * related operations and models, managing complex operation dependencies, and handling
+ * enrichments specific to API operations.
+ *
+ * This class serves as the foundation for creating custom operation generators that
+ * transform OpenAPI operations into various code artifacts like API clients, server
+ * handlers, validation middleware, or documentation.
+ *
+ * ## Key Features
+ *
+ * - **Operation Insertion**: Insert related operations with automatic dependency tracking
+ * - **Model Integration**: Seamlessly insert related models from operation schemas
+ * - **Schema Normalization**: Handle complex request/response schema references
+ * - **Export Management**: Control which operations are exported from generated files
+ * - **Enrichment Support**: Extend functionality with operation-specific enrichment data
+ * - **Type Safety**: Full TypeScript support with generic enrichment types
+ *
+ * @template EnrichmentType - Optional type for custom enrichment data
+ *
+ * @example Basic API client generator
+ * ```typescript
+ * import { OperationBase, Definition } from '@skmtc/core';
+ *
+ * class ApiClientMethod extends OperationBase {
+ *   toDefinition(): Definition {
+ *     const { method, path, operationId } = this.operation;
+ *
+ *     return new Definition({
+ *       name: operationId || `${method}${this.pascalCasePath()}`,
+ *       content: `async ${operationId}(${this.generateParameters()}) {
+ *         return this.request('${method}', '${path}', ${this.generateRequestBody()});
+ *       }`
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example With request/response models
+ * ```typescript
+ * class TypedApiMethod extends OperationBase {
+ *   toDefinition(): Definition {
+ *     const operation = this.operation;
+ *
+ *     // Generate request model if needed
+ *     let requestType = 'void';
+ *     if (operation.requestBody?.content?.['application/json']?.schema) {
+ *       const requestModel = this.insertNormalizedModel(
+ *         new RequestModel({ ... }),
+ *         {
+ *           schema: operation.requestBody.content['application/json'].schema,
+ *           fallbackName: `${operation.operationId}Request`
+ *         }
+ *       );
+ *       requestType = requestModel.value;
+ *     }
+ *
+ *     // Generate response model
+ *     const responseSchema = operation.responses?.['200']?.content?.['application/json']?.schema;
+ *     const responseModel = this.insertNormalizedModel(
+ *       new ResponseModel({ ... }),
+ *       { schema: responseSchema, fallbackName: `${operation.operationId}Response` }
+ *     );
+ *
+ *     return new Definition({
+ *       name: operation.operationId,
+ *       content: `async ${operation.operationId}(data: ${requestType}): Promise<${responseModel.value}> {
+ *         return this.request('${operation.method}', '${operation.path}', data);
+ *       }`
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example With enrichments
+ * ```typescript
+ * type AuthEnrichment = {
+ *   requiresAuth: boolean;
+ *   permissions: string[];
+ * };
+ *
+ * class SecuredApiMethod extends OperationBase<AuthEnrichment> {
+ *   toDefinition(): Definition {
+ *     const enrichment = this.settings.enrichment;
+ *     const requiresAuth = enrichment?.requiresAuth ?? false;
+ *
+ *     const authCheck = requiresAuth
+ *       ? 'this.checkAuth();'
+ *       : '';
+ *
+ *     return new Definition({
+ *       name: this.operation.operationId,
+ *       content: `async ${this.operation.operationId}() {
+ *         ${authCheck}
+ *         return this.request('${this.operation.method}', '${this.operation.path}');
+ *       }`
+ *     });
+ *   }
+ * }
+ * ```
+ */
 export declare class OperationBase<EnrichmentType = undefined> extends ContentBase {
+    /** Content settings including export path and enrichment configuration */
     settings: ContentSettings<EnrichmentType>;
+    /** The OpenAPI operation being processed */
     operation: OasOperation;
+    /** Generator key identifying this generator type */
     generatorKey: GeneratorKey;
+    /**
+     * Creates a new OperationBase instance.
+     *
+     * @param args - Operation generator configuration
+     * @param args.context - The generation context providing pipeline access
+     * @param args.settings - Content settings with export path and enrichments
+     * @param args.generatorKey - Unique identifier for this generator type
+     * @param args.operation - The OpenAPI operation being processed
+     *
+     * @example
+     * ```typescript
+     * const operation = new OperationBase({
+     *   context: generateContext,
+     *   settings: {
+     *     exportPath: './src/api.ts',
+     *     enrichment: customEnrichments
+     *   },
+     *   generatorKey: 'api-client',
+     *   operation: oasOperation
+     * });
+     * ```
+     */
     constructor({ context, generatorKey, settings, operation }: OperationBaseArgs<EnrichmentType>);
+    /**
+     * Inserts a related operation with forced generation.
+     *
+     * This method adds a related operation to the current generation context, ensuring
+     * it will be generated regardless of whether it already exists. This is useful for
+     * operations that depend on other operations or need to generate helper operations.
+     *
+     * @template V - Type of generated value returned by the insertable
+     * @template EnrichmentType - Type of enrichment data for the insertable
+     * @param insertable - The operation generator to insert
+     * @param operation - The OpenAPI operation to process
+     * @param options - Insertion options
+     * @param options.noExport - Whether to skip exporting the inserted operation
+     * @returns Inserted operation reference with generated value
+     *
+     * @example Inserting helper operations
+     * ```typescript
+     * class CrudApiClient extends OperationBase {
+     *   toDefinition(): Definition {
+     *     // Insert a related validation operation
+     *     const validator = this.insertOperation(
+     *       new ValidationOperation({ ... }),
+     *       this.operation,
+     *       { noExport: true }
+     *     );
+     *
+     *     return new Definition({
+     *       name: this.operation.operationId,
+     *       content: `async ${this.operation.operationId}(data: any) {
+     *         ${validator.value}(data);
+     *         return this.request('${this.operation.method}', '${this.operation.path}', data);
+     *       }`
+     *     });
+     *   }
+     * }
+     * ```
+     */
     insertOperation<V extends GeneratedValue, EnrichmentType = undefined>(insertable: OperationInsertable<V, EnrichmentType>, operation: OasOperation, options?: Pick<InsertOperationOptions<'force'>, 'noExport'>): Inserted<V, 'force', EnrichmentType>;
     insertModel<V extends GeneratedValue, EnrichmentType = undefined>(insertable: ModelInsertable<V, EnrichmentType>, refName: RefName, options?: Pick<InsertModelOptions<'force'>, 'noExport'>): Inserted<V, 'force', EnrichmentType>;
     insertNormalizedModel<V extends GeneratedValue, Schema extends OasSchema | OasRef<'schema'> | OasVoid, EnrichmentType = undefined>(insertable: ModelInsertable<V, EnrichmentType>, { schema, fallbackName }: Omit<InsertNormalisedModelArgs<Schema>, 'destinationPath'>, options?: Pick<InsertModelOptions<'force'>, 'noExport'>): InsertNormalisedModelReturn<V, Schema>;

package/esm/dsl/operation/OperationBase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OperationBase.d.ts","sourceRoot":"","sources":["../../../src/dsl/operation/OperationBase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAA;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EAEf,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,yBAAyB,EACzB,2BAA2B,EAC5B,MAAM,kCAAkC,CAAA;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AAEhD,MAAM,MAAM,iBAAiB,CAAC,cAAc,GAAG,SAAS,IAAI;IAC1D,OAAO,EAAE,eAAe,CAAA;IACxB,QAAQ,EAAE,eAAe,CAAC,cAAc,CAAC,CAAA;IACzC,YAAY,EAAE,YAAY,CAAA;IAC1B,SAAS,EAAE,YAAY,CAAA;CACxB,CAAA;AAED,qBAAa,aAAa,CAAC,cAAc,GAAG,SAAS,CAAE,SAAQ,WAAW;IACxE,QAAQ,EAAE,eAAe,CAAC,cAAc,CAAC,CAAA;IACzC,SAAS,EAAE,YAAY,CAAA;IACd,YAAY,EAAE,YAAY,CAAA;gBAEvB,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,iBAAiB,CAAC,cAAc,CAAC;IAQ7F,eAAe,CAAC,CAAC,SAAS,cAAc,EAAE,cAAc,GAAG,SAAS,EAClE,UAAU,EAAE,mBAAmB,CAAC,CAAC,EAAE,cAAc,CAAC,EAClD,SAAS,EAAE,YAAY,EACvB,OAAO,GAAE,IAAI,CAAC,sBAAsB,CAAC,OAAO,CAAC,EAAE,UAAU,CAAM,GAC9D,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC;IAQvC,WAAW,CAAC,CAAC,SAAS,cAAc,EAAE,cAAc,GAAG,SAAS,EAC9D,UAAU,EAAE,eAAe,CAAC,CAAC,EAAE,cAAc,CAAC,EAC9C,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,UAAU,CAAM,GAC1D,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC;IAQvC,qBAAqB,CACnB,CAAC,SAAS,cAAc,EACxB,MAAM,SAAS,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,OAAO,EACrD,cAAc,GAAG,SAAS,EAE1B,UAAU,EAAE,eAAe,CAAC,CAAC,EAAE,cAAc,CAAC,EAC9C,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,IAAI,CAAC,yBAAyB,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC,EACpF,OAAO,GAAE,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,UAAU,CAAM,GAC1D,2BAA2B,CAAC,CAAC,EAAE,MAAM,CAAC;IAYzC,oBAAoB;IACpB,iBAAiB,CAAC,CAAC,SAAS,cAAc,EAAE,EAC1C,UAAU,EACV,KAAK,EACL,QAAQ,EACT,EAAE,IAAI,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,iBAAiB,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAS3D,QAAQ,CAAC,IAAI,EAAE,gBAAgB;CAMzC"}
+{"version":3,"file":"OperationBase.d.ts","sourceRoot":"","sources":["../../../src/dsl/operation/OperationBase.ts"],"names":[],"mappings":"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"}

package/esm/dsl/operation/OperationBase.js

@@ -1,19 +1,148 @@
 import { ContentBase } from '../ContentBase.js';
+/**
+ * Base class for operation generators in the SKMTC DSL system.
+ *
+ * `OperationBase` extends {@link ContentBase} to provide specialized functionality for
+ * generating code from OpenAPI operations. It offers type-safe methods for inserting
+ * related operations and models, managing complex operation dependencies, and handling
+ * enrichments specific to API operations.
+ *
+ * This class serves as the foundation for creating custom operation generators that
+ * transform OpenAPI operations into various code artifacts like API clients, server
+ * handlers, validation middleware, or documentation.
+ *
+ * ## Key Features
+ *
+ * - **Operation Insertion**: Insert related operations with automatic dependency tracking
+ * - **Model Integration**: Seamlessly insert related models from operation schemas
+ * - **Schema Normalization**: Handle complex request/response schema references
+ * - **Export Management**: Control which operations are exported from generated files
+ * - **Enrichment Support**: Extend functionality with operation-specific enrichment data
+ * - **Type Safety**: Full TypeScript support with generic enrichment types
+ *
+ * @template EnrichmentType - Optional type for custom enrichment data
+ *
+ * @example Basic API client generator
+ * ```typescript
+ * import { OperationBase, Definition } from '@skmtc/core';
+ *
+ * class ApiClientMethod extends OperationBase {
+ *   toDefinition(): Definition {
+ *     const { method, path, operationId } = this.operation;
+ *
+ *     return new Definition({
+ *       name: operationId || `${method}${this.pascalCasePath()}`,
+ *       content: `async ${operationId}(${this.generateParameters()}) {
+ *         return this.request('${method}', '${path}', ${this.generateRequestBody()});
+ *       }`
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example With request/response models
+ * ```typescript
+ * class TypedApiMethod extends OperationBase {
+ *   toDefinition(): Definition {
+ *     const operation = this.operation;
+ *
+ *     // Generate request model if needed
+ *     let requestType = 'void';
+ *     if (operation.requestBody?.content?.['application/json']?.schema) {
+ *       const requestModel = this.insertNormalizedModel(
+ *         new RequestModel({ ... }),
+ *         {
+ *           schema: operation.requestBody.content['application/json'].schema,
+ *           fallbackName: `${operation.operationId}Request`
+ *         }
+ *       );
+ *       requestType = requestModel.value;
+ *     }
+ *
+ *     // Generate response model
+ *     const responseSchema = operation.responses?.['200']?.content?.['application/json']?.schema;
+ *     const responseModel = this.insertNormalizedModel(
+ *       new ResponseModel({ ... }),
+ *       { schema: responseSchema, fallbackName: `${operation.operationId}Response` }
+ *     );
+ *
+ *     return new Definition({
+ *       name: operation.operationId,
+ *       content: `async ${operation.operationId}(data: ${requestType}): Promise<${responseModel.value}> {
+ *         return this.request('${operation.method}', '${operation.path}', data);
+ *       }`
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example With enrichments
+ * ```typescript
+ * type AuthEnrichment = {
+ *   requiresAuth: boolean;
+ *   permissions: string[];
+ * };
+ *
+ * class SecuredApiMethod extends OperationBase<AuthEnrichment> {
+ *   toDefinition(): Definition {
+ *     const enrichment = this.settings.enrichment;
+ *     const requiresAuth = enrichment?.requiresAuth ?? false;
+ *
+ *     const authCheck = requiresAuth
+ *       ? 'this.checkAuth();'
+ *       : '';
+ *
+ *     return new Definition({
+ *       name: this.operation.operationId,
+ *       content: `async ${this.operation.operationId}() {
+ *         ${authCheck}
+ *         return this.request('${this.operation.method}', '${this.operation.path}');
+ *       }`
+ *     });
+ *   }
+ * }
+ * ```
+ */
 export class OperationBase extends ContentBase {
+    /**
+     * Creates a new OperationBase instance.
+     *
+     * @param args - Operation generator configuration
+     * @param args.context - The generation context providing pipeline access
+     * @param args.settings - Content settings with export path and enrichments
+     * @param args.generatorKey - Unique identifier for this generator type
+     * @param args.operation - The OpenAPI operation being processed
+     *
+     * @example
+     * ```typescript
+     * const operation = new OperationBase({
+     *   context: generateContext,
+     *   settings: {
+     *     exportPath: './src/api.ts',
+     *     enrichment: customEnrichments
+     *   },
+     *   generatorKey: 'api-client',
+     *   operation: oasOperation
+     * });
+     * ```
+     */
     constructor({ context, generatorKey, settings, operation }) {
         super({ context });
+        /** Content settings including export path and enrichment configuration */
         Object.defineProperty(this, "settings", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The OpenAPI operation being processed */
         Object.defineProperty(this, "operation", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Generator key identifying this generator type */
         Object.defineProperty(this, "generatorKey", {
             enumerable: true,
             configurable: true,
@@ -24,6 +153,43 @@ export class OperationBase extends ContentBase {
         this.operation = operation;
         this.settings = settings;
     }
+    /**
+     * Inserts a related operation with forced generation.
+     *
+     * This method adds a related operation to the current generation context, ensuring
+     * it will be generated regardless of whether it already exists. This is useful for
+     * operations that depend on other operations or need to generate helper operations.
+     *
+     * @template V - Type of generated value returned by the insertable
+     * @template EnrichmentType - Type of enrichment data for the insertable
+     * @param insertable - The operation generator to insert
+     * @param operation - The OpenAPI operation to process
+     * @param options - Insertion options
+     * @param options.noExport - Whether to skip exporting the inserted operation
+     * @returns Inserted operation reference with generated value
+     *
+     * @example Inserting helper operations
+     * ```typescript
+     * class CrudApiClient extends OperationBase {
+     *   toDefinition(): Definition {
+     *     // Insert a related validation operation
+     *     const validator = this.insertOperation(
+     *       new ValidationOperation({ ... }),
+     *       this.operation,
+     *       { noExport: true }
+     *     );
+     *
+     *     return new Definition({
+     *       name: this.operation.operationId,
+     *       content: `async ${this.operation.operationId}(data: any) {
+     *         ${validator.value}(data);
+     *         return this.request('${this.operation.method}', '${this.operation.path}', data);
+     *       }`
+     *     });
+     *   }
+     * }
+     * ```
+     */
     insertOperation(insertable, operation, options = {}) {
         return this.context.insertOperation(insertable, operation, {
             generation: 'force',

package/esm/helpers/strings.d.ts

@@ -1,9 +1,72 @@
+/**
+ * Capitalizes the first character of a string.
+ *
+ * @param str - The string to capitalize
+ * @returns The string with the first character uppercased
+ *
+ * @example
+ * ```typescript
+ * capitalize('hello world'); // 'Hello world'
+ * capitalize('API'); // 'API'
+ * capitalize(''); // ''
+ * ```
+ */
 import "../_dnt.polyfills.js";
 export declare const capitalize: (str: string) => string;
+/**
+ * Decapitalizes (lowercases) the first character of a string.
+ *
+ * @param str - The string to decapitalize
+ * @returns The string with the first character lowercased
+ *
+ * @example
+ * ```typescript
+ * decapitalize('Hello World'); // 'hello World'
+ * decapitalize('API'); // 'aPI'
+ * decapitalize(''); // ''
+ * ```
+ */
 export declare const decapitalize: (str: string) => string;
+/**
+ * Options for controlling camelCase conversion behavior.
+ */
 type CamelCaseOptions = {
+    /** Whether to capitalize the first character (PascalCase) */
     upperFirst?: boolean;
 };
+/**
+ * Converts a string to camelCase, removing non-alphanumeric characters.
+ *
+ * This function handles various input formats including kebab-case, snake_case,
+ * space-separated words, and mixed formats. It intelligently capitalizes words
+ * after the first unless `upperFirst` is specified.
+ *
+ * @param str - The string to convert to camelCase
+ * @param options - Options to control the conversion
+ * @param options.upperFirst - Whether to capitalize the first character (default: false)
+ * @returns The camelCase version of the input string
+ *
+ * @example Basic usage
+ * ```typescript
+ * camelCase('hello world'); // 'helloWorld'
+ * camelCase('user-name'); // 'userName'
+ * camelCase('api_key'); // 'apiKey'
+ * camelCase('HTTP-Response'); // 'httpResponse'
+ * ```
+ *
+ * @example PascalCase (upperFirst)
+ * ```typescript
+ * camelCase('user profile', { upperFirst: true }); // 'UserProfile'
+ * camelCase('api-client', { upperFirst: true }); // 'ApiClient'
+ * ```
+ *
+ * @example Complex inputs
+ * ```typescript
+ * camelCase('get-user-by-id'); // 'getUserById'
+ * camelCase('XML_HTTP_Request'); // 'xmlHttpRequest'
+ * camelCase('2fa-enabled'); // '2faEnabled'
+ * ```
+ */
 export declare const camelCase: (str: string, { upperFirst }?: CamelCaseOptions) => string;
 export {};
 //# sourceMappingURL=strings.d.ts.map

package/esm/helpers/strings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strings.d.ts","sourceRoot":"","sources":["../../src/helpers/strings.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,MAExC,CAAA;AAED,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,KAAG,MAE1C,CAAA;AAED,KAAK,gBAAgB,GAAG;IACtB,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB,CAAA;AAED,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,EAAE,iBAAgB,gBAAqB,KAAG,MAgB9E,CAAA"}
+{"version":3,"file":"strings.d.ts","sourceRoot":"","sources":["../../src/helpers/strings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,sBAAsB,CAAC;AAE9B,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,MAExC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,KAAG,MAE1C,CAAA;AAED;;GAEG;AACH,KAAK,gBAAgB,GAAG;IACtB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,EAAE,iBAAgB,gBAAqB,KAAG,MAgB9E,CAAA"}

package/esm/helpers/strings.js

@@ -1,10 +1,69 @@
+/**
+ * Capitalizes the first character of a string.
+ *
+ * @param str - The string to capitalize
+ * @returns The string with the first character uppercased
+ *
+ * @example
+ * ```typescript
+ * capitalize('hello world'); // 'Hello world'
+ * capitalize('API'); // 'API'
+ * capitalize(''); // ''
+ * ```
+ */
 import "../_dnt.polyfills.js";
 export const capitalize = (str) => {
     return str.charAt(0).toUpperCase() + str.slice(1);
 };
+/**
+ * Decapitalizes (lowercases) the first character of a string.
+ *
+ * @param str - The string to decapitalize
+ * @returns The string with the first character lowercased
+ *
+ * @example
+ * ```typescript
+ * decapitalize('Hello World'); // 'hello World'
+ * decapitalize('API'); // 'aPI'
+ * decapitalize(''); // ''
+ * ```
+ */
 export const decapitalize = (str) => {
     return str.charAt(0).toLocaleLowerCase() + str.slice(1);
 };
+/**
+ * Converts a string to camelCase, removing non-alphanumeric characters.
+ *
+ * This function handles various input formats including kebab-case, snake_case,
+ * space-separated words, and mixed formats. It intelligently capitalizes words
+ * after the first unless `upperFirst` is specified.
+ *
+ * @param str - The string to convert to camelCase
+ * @param options - Options to control the conversion
+ * @param options.upperFirst - Whether to capitalize the first character (default: false)
+ * @returns The camelCase version of the input string
+ *
+ * @example Basic usage
+ * ```typescript
+ * camelCase('hello world'); // 'helloWorld'
+ * camelCase('user-name'); // 'userName'
+ * camelCase('api_key'); // 'apiKey'
+ * camelCase('HTTP-Response'); // 'httpResponse'
+ * ```
+ *
+ * @example PascalCase (upperFirst)
+ * ```typescript
+ * camelCase('user profile', { upperFirst: true }); // 'UserProfile'
+ * camelCase('api-client', { upperFirst: true }); // 'ApiClient'
+ * ```
+ *
+ * @example Complex inputs
+ * ```typescript
+ * camelCase('get-user-by-id'); // 'getUserById'
+ * camelCase('XML_HTTP_Request'); // 'xmlHttpRequest'
+ * camelCase('2fa-enabled'); // '2faEnabled'
+ * ```
+ */
 export const camelCase = (str, { upperFirst } = {}) => {
     let doCapitalize = Boolean(upperFirst);
     const camelCased = str.replace(/[^a-zA-Z0-9]+([a-zA-Z0-9]+)/g, (_, matched) => {

package/esm/mod.d.ts

@@ -1,3 +1,69 @@
+/**
+ * @module SKMTC Core
+ *
+ * SKMTC (Schema Kit Mapping & Type Conversion) is a powerful TypeScript/Deno library
+ * for processing OpenAPI v3 documents and generating code artifacts. It provides a
+ * comprehensive three-phase pipeline for parsing, generating, and rendering OpenAPI
+ * schemas into various output formats.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { toArtifacts } from '@skmtc/core';
+ *
+ * const result = await toArtifacts({
+ *   traceId: 'my-trace',
+ *   spanId: 'my-span',
+ *   documentObject: openApiDoc,
+ *   settings: clientSettings,
+ *   toGeneratorConfigMap: () => generatorMap,
+ *   startAt: Date.now(),
+ *   silent: false
+ * });
+ *
+ * console.log(result.artifacts); // Generated code files
+ * console.log(result.manifest);  // Generation metadata
+ * ```
+ *
+ * ## Architecture
+ *
+ * The library follows a three-phase pipeline:
+ * - **Parse Phase**: Converts OpenAPI v3 JSON into internal OAS objects
+ * - **Generate Phase**: Transforms OAS objects into generator artifacts
+ * - **Render Phase**: Renders artifacts to formatted files
+ *
+ * ## Key Components
+ *
+ * - {@link CoreContext} - Main orchestration class for the pipeline
+ * - {@link toArtifacts} - Primary transformation function
+ * - {@link ContentBase} - Base class for creating generators
+ * - {@link ModelBase} and {@link OperationBase} - DSL building blocks
+ * - {@link List} - Powerful string manipulation and code generation utility
+ *
+ * ## Type System
+ *
+ * The library provides comprehensive TypeScript types for OpenAPI schemas,
+ * generator configurations, and output artifacts. All major types are
+ * validated using Valibot schemas for runtime safety.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { CoreContext } from '@skmtc/core';
+ *
+ * const context = new CoreContext({
+ *   spanId: 'my-span',
+ *   silent: false
+ * });
+ *
+ * const result = await context.toArtifacts({
+ *   documentObject: myOpenApiDoc,
+ *   settings: mySettings,
+ *   toGeneratorConfigMap: () => myGenerators,
+ *   prettier: prettierConfig,
+ *   silent: false
+ * });
+ * ```
+ */
 import "./_dnt.polyfills.js";
 export * from './app/validate.js';
 export * from './context/CoreContext.js';

package/esm/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAC7B,cAAc,mBAAmB,CAAA;AACjC,cAAc,0BAA0B,CAAA;AACxC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,2BAA2B,CAAA;AACzC,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,0BAA0B,CAAA;AACxC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,4BAA4B,CAAA;AAC1C,cAAc,6BAA6B,CAAA;AAC3C,cAAc,sBAAsB,CAAA;AACpC,cAAc,kCAAkC,CAAA;AAChD,cAAc,oCAAoC,CAAA;AAClD,cAAc,oCAAoC,CAAA;AAClD,cAAc,qCAAqC,CAAA;AACnD,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,2BAA2B,CAAA;AACzC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,sBAAsB,CAAA;AACpC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,qCAAqC,CAAA;AACnD,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,sCAAsC,CAAA;AACpD,cAAc,4BAA4B,CAAA;AAC1C,cAAc,oBAAoB,CAAA;AAClC,cAAc,0BAA0B,CAAA;AACxC,cAAc,wBAAwB,CAAA;AACtC,cAAc,wBAAwB,CAAA;AACtC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,kBAAkB,CAAA;AAChC,cAAc,kCAAkC,CAAA;AAChD,cAAc,4BAA4B,CAAA;AAC1C,cAAc,wBAAwB,CAAA;AACtC,cAAc,wBAAwB,CAAA;AACtC,cAAc,kBAAkB,CAAA;AAChC,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,2BAA2B,CAAA;AACzC,cAAc,wBAAwB,CAAA;AACtC,cAAc,qBAAqB,CAAA;AACnC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,wBAAwB,CAAA;AACtC,cAAc,2BAA2B,CAAA;AACzC,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,2BAA2B,CAAA;AACzC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,mCAAmC,CAAA;AACjD,cAAc,6BAA6B,CAAA;AAC3C,cAAc,2BAA2B,CAAA;AACzC,cAAc,sBAAsB,CAAA;AACpC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,uCAAuC,CAAA;AACrD,cAAc,gCAAgC,CAAA;AAC9C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,iCAAiC,CAAA"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,OAAO,qBAAqB,CAAC;AAG7B,cAAc,mBAAmB,CAAA;AACjC,cAAc,0BAA0B,CAAA;AACxC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,2BAA2B,CAAA;AACzC,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,0BAA0B,CAAA;AACxC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,4BAA4B,CAAA;AAC1C,cAAc,6BAA6B,CAAA;AAC3C,cAAc,sBAAsB,CAAA;AACpC,cAAc,kCAAkC,CAAA;AAChD,cAAc,oCAAoC,CAAA;AAClD,cAAc,oCAAoC,CAAA;AAClD,cAAc,qCAAqC,CAAA;AACnD,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,2BAA2B,CAAA;AACzC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,sBAAsB,CAAA;AACpC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,qCAAqC,CAAA;AACnD,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,sCAAsC,CAAA;AACpD,cAAc,4BAA4B,CAAA;AAC1C,cAAc,oBAAoB,CAAA;AAClC,cAAc,0BAA0B,CAAA;AACxC,cAAc,wBAAwB,CAAA;AACtC,cAAc,wBAAwB,CAAA;AACtC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,kBAAkB,CAAA;AAChC,cAAc,kCAAkC,CAAA;AAChD,cAAc,4BAA4B,CAAA;AAC1C,cAAc,wBAAwB,CAAA;AACtC,cAAc,wBAAwB,CAAA;AACtC,cAAc,kBAAkB,CAAA;AAChC,cAAc,sBAAsB,CAAA;AACpC,cAAc,0BAA0B,CAAA;AACxC,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA;AACpC,cAAc,2BAA2B,CAAA;AACzC,cAAc,wBAAwB,CAAA;AACtC,cAAc,qBAAqB,CAAA;AACnC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,wBAAwB,CAAA;AACtC,cAAc,2BAA2B,CAAA;AACzC,cAAc,0BAA0B,CAAA;AACxC,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,2BAA2B,CAAA;AACzC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,mCAAmC,CAAA;AACjD,cAAc,6BAA6B,CAAA;AAC3C,cAAc,2BAA2B,CAAA;AACzC,cAAc,sBAAsB,CAAA;AACpC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,uCAAuC,CAAA;AACrD,cAAc,gCAAgC,CAAA;AAC9C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,iCAAiC,CAAA"}