@skmtc/core 0.0.782 → 0.0.783

package/script/context/CoreContext.js

@@ -57,18 +57,93 @@ const tracer_js_1 = require("../helpers/tracer.js");
 const ResultsLog_js_1 = require("../helpers/ResultsLog.js");
 const Sentry = __importStar(require("@sentry/node"));
 const join_js_1 = require("../deps/jsr.io/@std/path/1.1.2/join.js");
+/**
+ * The main orchestration class for the SKMTC transformation pipeline.
+ *
+ * `CoreContext` manages the three-phase process of transforming OpenAPI v3 documents
+ * into code artifacts. It coordinates parsing, generation, and rendering phases while
+ * providing logging, tracing, and error handling capabilities.
+ *
+ * ## Pipeline Phases
+ *
+ * 1. **Parse Phase**: Uses {@link ParseContext} to convert OpenAPI JSON into OAS objects
+ * 2. **Generate Phase**: Uses {@link GenerateContext} to transform OAS objects with generators
+ * 3. **Render Phase**: Uses {@link RenderContext} to format and prepare final artifacts
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { CoreContext } from '@skmtc/core';
+ *
+ * const context = new CoreContext({
+ *   spanId: 'user-api-generation',
+ *   logsPath: './logs',
+ *   silent: false
+ * });
+ *
+ * const result = await context.toArtifacts({
+ *   documentObject: openApiDoc,
+ *   settings: clientSettings,
+ *   toGeneratorConfigMap: () => generators,
+ *   prettier: prettierConfig,
+ *   silent: false
+ * });
+ * ```
+ *
+ * @example Using individual phases
+ * ```typescript
+ * const context = new CoreContext({
+ *   spanId: 'custom-pipeline',
+ *   silent: true
+ * });
+ *
+ * // Parse phase only
+ * const { oasDocument } = context.parse(openApiDoc);
+ *
+ * // Then use document for custom processing
+ * console.log('Parsed schemas:', Object.keys(oasDocument.components.schemas));
+ * ```
+ */
 class CoreContext {
+    /**
+     * Creates a new CoreContext instance.
+     *
+     * @param args - Configuration for the context
+     * @param args.spanId - Unique identifier for this transformation span
+     * @param args.logsPath - Optional directory path for log files
+     * @param args.silent - Whether to suppress console output
+     *
+     * @example
+     * ```typescript
+     * // Basic context with console logging
+     * const context = new CoreContext({
+     *   spanId: 'my-generation',
+     *   silent: false
+     * });
+     *
+     * // Context with file logging
+     * const context = new CoreContext({
+     *   spanId: 'batch-job-123',
+     *   logsPath: './logs/generation',
+     *   silent: true
+     * });
+     * ```
+     */
     constructor({ spanId, logsPath, silent }) {
         _CoreContext_instances.add(this);
+        /** Logger instance for the context */
         Object.defineProperty(this, "logger", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Current execution phase for pipeline tracking */
         _CoreContext_phase.set(this, void 0);
+        /** Results log for tracking generation outcomes */
         _CoreContext_results.set(this, void 0);
+        /** Stack trail for distributed tracing */
         _CoreContext_stackTrail.set(this, void 0);
+        /** Whether to suppress console output */
         Object.defineProperty(this, "silent", {
             enumerable: true,
             configurable: true,
@@ -80,6 +155,38 @@ class CoreContext {
         this.logger = __classPrivateFieldGet(this, _CoreContext_instances, "m", _CoreContext_setupLogger).call(this, { spanId, logsPath });
         this.silent = silent;
     }
+    /**
+     * Parses an OpenAPI v3 document into internal OAS objects.
+     *
+     * This method executes only the parse phase of the pipeline, converting
+     * the raw OpenAPI JSON into structured OAS objects that can be used for
+     * generation or custom processing.
+     *
+     * @param documentObject - The OpenAPI v3 document to parse
+     * @returns An object containing the parsed OAS document
+     *
+     * @example
+     * ```typescript
+     * import { CoreContext } from '@skmtc/core';
+     *
+     * const context = new CoreContext({
+     *   spanId: 'parse-only',
+     *   silent: true
+     * });
+     *
+     * const { oasDocument } = context.parse(openApiDoc);
+     *
+     * // Access parsed components
+     * console.log('Models:', Object.keys(oasDocument.components.schemas));
+     * console.log('Paths:', Object.keys(oasDocument.paths));
+     *
+     * // Use for custom processing
+     * const userModel = oasDocument.components.schemas['User'];
+     * if (userModel && !userModel.isRef()) {
+     *   console.log('User properties:', Object.keys(userModel.properties));
+     * }
+     * ```
+     */
     parse(documentObject) {
         __classPrivateFieldSet(this, _CoreContext_phase, __classPrivateFieldGet(this, _CoreContext_instances, "m", _CoreContext_setupParsePhase).call(this, documentObject), "f");
         const oasDocument = __classPrivateFieldGet(this, _CoreContext_phase, "f").context.parse();
@@ -87,6 +194,77 @@ class CoreContext {
             oasDocument
         };
     }
+    /**
+     * Executes the complete transformation pipeline to generate code artifacts.
+     *
+     * This method orchestrates all three phases:
+     * 1. **Parse**: Convert OpenAPI document to OAS objects
+     * 2. **Generate**: Transform OAS objects using generators
+     * 3. **Render**: Format and prepare final artifacts
+     *
+     * The result includes both the generated code files and comprehensive metadata
+     * about the generation process, including file mappings, previews, and results.
+     *
+     * @param args - Configuration for the artifact generation
+     * @param args.documentObject - The OpenAPI v3 document to process
+     * @param args.settings - Client settings for customization
+     * @param args.toGeneratorConfigMap - Function returning generator configuration
+     * @param args.prettier - Optional Prettier configuration for code formatting
+     * @param args.silent - Whether to suppress console output during generation
+     * @returns Promise resolving to rendered artifacts and metadata
+     *
+     * @example Complete pipeline
+     * ```typescript
+     * const context = new CoreContext({
+     *   spanId: 'api-client-gen',
+     *   silent: false
+     * });
+     *
+     * const result = await context.toArtifacts({
+     *   documentObject: openApiDoc,
+     *   settings: {
+     *     basePath: './src/api',
+     *     skip: {
+     *       models: ['Internal*'],
+     *       operations: {
+     *         '/health': ['get'],
+     *         '/debug/**': ['*']
+     *       }
+     *     }
+     *   },
+     *   toGeneratorConfigMap: () => ({
+     *     models: {
+     *       generator: MyModelGenerator,
+     *       settings: { includeValidation: true }
+     *     },
+     *     operations: {
+     *       generator: MyOperationGenerator,
+     *       settings: { generateTypes: true }
+     *     }
+     *   }),
+     *   prettier: {
+     *     semi: false,
+     *     singleQuote: true,
+     *     trailingComma: 'all'
+     *   },
+     *   silent: false
+     * });
+     *
+     * // Access generated artifacts
+     * console.log('Generated files:', Object.keys(result.artifacts));
+     *
+     * // Write to filesystem
+     * for (const [path, content] of Object.entries(result.artifacts)) {
+     *   await Deno.writeTextFile(path, content);
+     * }
+     *
+     * // Access metadata
+     * console.log('Generation results:', result.results);
+     * console.log('File mappings:', result.files);
+     * ```
+     *
+     * @throws Will throw an error if any phase of the pipeline fails
+     */
     async toArtifacts({ documentObject, settings, toGeneratorConfigMap, prettier }) {
         try {
             const oasDocument = this.trace('parse', () => {

package/script/dsl/ContentBase.d.ts

@@ -1,15 +1,130 @@
 import type { GenerateContext } from '../context/GenerateContext.js';
 import type { RegisterArgs } from '../context/GenerateContext.js';
 import type { GeneratorKey } from '../types/GeneratorKeys.js';
+/**
+ * Constructor arguments for {@link ContentBase}.
+ */
 type ContentBaseArgs = {
+    /** The generation context providing OAS objects and utilities */
     context: GenerateContext;
+    /** Optional generator key for tracking and identification */
     generatorKey?: GeneratorKey;
 };
+/**
+ * Base class for all content generators in the SKMTC DSL system.
+ *
+ * `ContentBase` provides the foundation for creating custom generators that transform
+ * OpenAPI Schema (OAS) objects into code artifacts. It handles registration with the
+ * generation context, skipping logic, and provides access to the pipeline's utilities.
+ *
+ * ## Generator Lifecycle
+ *
+ * 1. **Construction**: Initialize with context and optional generator key
+ * 2. **Registration**: Call {@link register} to add artifacts to the pipeline
+ * 3. **Generation**: Implement custom logic using context utilities
+ * 4. **Rendering**: Artifacts are automatically rendered by the pipeline
+ *
+ * @example Basic generator
+ * ```typescript
+ * import { ContentBase } from '@skmtc/core';
+ *
+ * class MyModelGenerator extends ContentBase {
+ *   generate() {
+ *     // Skip if not needed
+ *     if (this.shouldSkip()) return;
+ *
+ *     // Access OAS objects through context
+ *     const schemas = this.context.oasDocument.components.schemas;
+ *
+ *     for (const [name, schema] of Object.entries(schemas)) {
+ *       if (schema.isRef()) continue;
+ *
+ *       const file = new File({
+ *         context: this.context,
+ *         path: `./models/${name}.ts`,
+ *         content: this.generateModelContent(schema)
+ *       });
+ *
+ *       // Register the file for rendering
+ *       this.register({ file });
+ *     }
+ *   }
+ *
+ *   private generateModelContent(schema: OasObject): string {
+ *     // Custom model generation logic
+ *     return `export interface ${schema.name} { ... }`;
+ *   }
+ * }
+ * ```
+ *
+ * @example Generator with skipping logic
+ * ```typescript
+ * class ConditionalGenerator extends ContentBase {
+ *   generate() {
+ *     // Check if generation should be skipped
+ *     if (this.shouldSkipBasedOnSettings()) {
+ *       this.skip('Disabled in settings');
+ *       return;
+ *     }
+ *
+ *     // Continue with generation...
+ *     const file = this.createOutputFile();
+ *     this.register({ file });
+ *   }
+ *
+ *   private shouldSkipBasedOnSettings(): boolean {
+ *     return this.context.settings?.skip?.models?.includes('MyModel') ?? false;
+ *   }
+ * }
+ * ```
+ */
 export declare class ContentBase {
+    /** The generation context providing access to OAS objects and utilities */
     context: GenerateContext;
+    /** Whether this generator has been skipped */
     skipped: boolean;
+    /** Optional generator key for identification and tracking */
     generatorKey: GeneratorKey | undefined;
+    /**
+     * Creates a new ContentBase instance.
+     *
+     * @param args - Construction arguments
+     * @param args.context - The generation context
+     * @param args.generatorKey - Optional generator key
+     */
     constructor({ context, generatorKey }: ContentBaseArgs);
+    /**
+     * Registers generated artifacts with the rendering pipeline.
+     *
+     * This method is called by generator implementations to add files,
+     * JSON artifacts, or other content to the generation output.
+     *
+     * @param args - The artifacts to register
+     * @param args.file - Optional file to register
+     * @param args.jsonFile - Optional JSON file to register
+     *
+     * @example Registering a file
+     * ```typescript
+     * const file = new File({
+     *   context: this.context,
+     *   path: './output.ts',
+     *   content: 'export const value = 42;'
+     * });
+     *
+     * this.register({ file });
+     * ```
+     *
+     * @example Registering JSON data
+     * ```typescript
+     * const jsonFile = new JsonFile({
+     *   context: this.context,
+     *   path: './config.json',
+     *   data: { version: '1.0.0', features: ['api'] }
+     * });
+     *
+     * this.register({ jsonFile });
+     * ```
+     */
     register(args: RegisterArgs): void;
 }
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"ContentBase.d.ts","sourceRoot":"","sources":["../../src/dsl/ContentBase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAE7D,KAAK,eAAe,GAAG;IACrB,OAAO,EAAE,eAAe,CAAA;IACxB,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED,qBAAa,WAAW;IACtB,OAAO,EAAE,eAAe,CAAA;IACxB,OAAO,EAAE,OAAO,CAAQ;IACxB,YAAY,EAAE,YAAY,GAAG,SAAS,CAAA;gBAE1B,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,eAAe;IAKtD,QAAQ,CAAC,IAAI,EAAE,YAAY;CAG5B"}
+{"version":3,"file":"ContentBase.d.ts","sourceRoot":"","sources":["../../src/dsl/ContentBase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAE7D;;GAEG;AACH,KAAK,eAAe,GAAG;IACrB,iEAAiE;IACjE,OAAO,EAAE,eAAe,CAAA;IACxB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,qBAAa,WAAW;IACtB,2EAA2E;IAC3E,OAAO,EAAE,eAAe,CAAA;IAExB,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAQ;IAExB,6DAA6D;IAC7D,YAAY,EAAE,YAAY,GAAG,SAAS,CAAA;IAEtC;;;;;;OAMG;gBACS,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,eAAe;IAKtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;CAGnC"}

package/script/dsl/ContentBase.js

@@ -1,20 +1,98 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContentBase = void 0;
+/**
+ * Base class for all content generators in the SKMTC DSL system.
+ *
+ * `ContentBase` provides the foundation for creating custom generators that transform
+ * OpenAPI Schema (OAS) objects into code artifacts. It handles registration with the
+ * generation context, skipping logic, and provides access to the pipeline's utilities.
+ *
+ * ## Generator Lifecycle
+ *
+ * 1. **Construction**: Initialize with context and optional generator key
+ * 2. **Registration**: Call {@link register} to add artifacts to the pipeline
+ * 3. **Generation**: Implement custom logic using context utilities
+ * 4. **Rendering**: Artifacts are automatically rendered by the pipeline
+ *
+ * @example Basic generator
+ * ```typescript
+ * import { ContentBase } from '@skmtc/core';
+ *
+ * class MyModelGenerator extends ContentBase {
+ *   generate() {
+ *     // Skip if not needed
+ *     if (this.shouldSkip()) return;
+ *
+ *     // Access OAS objects through context
+ *     const schemas = this.context.oasDocument.components.schemas;
+ *
+ *     for (const [name, schema] of Object.entries(schemas)) {
+ *       if (schema.isRef()) continue;
+ *
+ *       const file = new File({
+ *         context: this.context,
+ *         path: `./models/${name}.ts`,
+ *         content: this.generateModelContent(schema)
+ *       });
+ *
+ *       // Register the file for rendering
+ *       this.register({ file });
+ *     }
+ *   }
+ *
+ *   private generateModelContent(schema: OasObject): string {
+ *     // Custom model generation logic
+ *     return `export interface ${schema.name} { ... }`;
+ *   }
+ * }
+ * ```
+ *
+ * @example Generator with skipping logic
+ * ```typescript
+ * class ConditionalGenerator extends ContentBase {
+ *   generate() {
+ *     // Check if generation should be skipped
+ *     if (this.shouldSkipBasedOnSettings()) {
+ *       this.skip('Disabled in settings');
+ *       return;
+ *     }
+ *
+ *     // Continue with generation...
+ *     const file = this.createOutputFile();
+ *     this.register({ file });
+ *   }
+ *
+ *   private shouldSkipBasedOnSettings(): boolean {
+ *     return this.context.settings?.skip?.models?.includes('MyModel') ?? false;
+ *   }
+ * }
+ * ```
+ */
 class ContentBase {
+    /**
+     * Creates a new ContentBase instance.
+     *
+     * @param args - Construction arguments
+     * @param args.context - The generation context
+     * @param args.generatorKey - Optional generator key
+     */
     constructor({ context, generatorKey }) {
+        /** The generation context providing access to OAS objects and utilities */
         Object.defineProperty(this, "context", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Whether this generator has been skipped */
         Object.defineProperty(this, "skipped", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: false
         });
+        /** Optional generator key for identification and tracking */
         Object.defineProperty(this, "generatorKey", {
             enumerable: true,
             configurable: true,
@@ -24,6 +102,38 @@ class ContentBase {
         this.context = context;
         this.generatorKey = generatorKey;
     }
+    /**
+     * Registers generated artifacts with the rendering pipeline.
+     *
+     * This method is called by generator implementations to add files,
+     * JSON artifacts, or other content to the generation output.
+     *
+     * @param args - The artifacts to register
+     * @param args.file - Optional file to register
+     * @param args.jsonFile - Optional JSON file to register
+     *
+     * @example Registering a file
+     * ```typescript
+     * const file = new File({
+     *   context: this.context,
+     *   path: './output.ts',
+     *   content: 'export const value = 42;'
+     * });
+     *
+     * this.register({ file });
+     * ```
+     *
+     * @example Registering JSON data
+     * ```typescript
+     * const jsonFile = new JsonFile({
+     *   context: this.context,
+     *   path: './config.json',
+     *   data: { version: '1.0.0', features: ['api'] }
+     * });
+     *
+     * this.register({ jsonFile });
+     * ```
+     */
     register(args) {
         this.context.register(args);
     }

package/script/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/script/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/script/helpers/strings.js

@@ -1,15 +1,74 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.camelCase = exports.decapitalize = exports.capitalize = void 0;
+/**
+ * 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(''); // ''
+ * ```
+ */
 require("../_dnt.polyfills.js");
 const capitalize = (str) => {
     return str.charAt(0).toUpperCase() + str.slice(1);
 };
 exports.capitalize = capitalize;
+/**
+ * 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(''); // ''
+ * ```
+ */
 const decapitalize = (str) => {
     return str.charAt(0).toLocaleLowerCase() + str.slice(1);
 };
 exports.decapitalize = decapitalize;
+/**
+ * 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'
+ * ```
+ */
 const camelCase = (str, { upperFirst } = {}) => {
     let doCapitalize = Boolean(upperFirst);
     const camelCased = str.replace(/[^a-zA-Z0-9]+([a-zA-Z0-9]+)/g, (_, matched) => {