@skmtc/core 0.0.792 → 0.0.794

package/script/helpers/tracer.d.ts

@@ -1,4 +1,128 @@
 import type { Logger } from '../deps/jsr.io/@std/log/0.224.14/logger.js';
 import type { StackTrail } from '../context/StackTrail.js';
+/**
+ * Executes a function with distributed tracing support and stack trail management.
+ *
+ * This utility function provides distributed tracing capabilities for the SKMTC
+ * generation pipeline. It manages stack trail tokens that help track execution
+ * context across complex nested operations, making debugging and performance
+ * analysis much easier.
+ *
+ * The tracer ensures proper cleanup of stack trail tokens even if the wrapped
+ * function throws an error, maintaining the integrity of the tracing system.
+ * This is essential for accurate debugging and performance monitoring in
+ * complex code generation scenarios.
+ *
+ * @template T - The return type of the traced function
+ * @param stackTrail - The stack trail instance for tracking execution context
+ * @param token - Token(s) to identify this execution step in traces
+ * @param fn - The function to execute with tracing
+ * @param log - Logger instance for error reporting
+ * @returns The result of the wrapped function execution
+ *
+ * @throws Re-throws any error from the wrapped function after cleanup
+ *
+ * @example Basic tracing usage
+ * ```typescript
+ * import { tracer } from '@skmtc/core';
+ *
+ * class ModelGenerator {
+ *   generateModel(stackTrail: StackTrail, logger: Logger) {
+ *     return tracer(stackTrail, 'generate-model', () => {
+ *       // Complex model generation logic here
+ *       return this.createModelDefinition();
+ *     }, logger);
+ *   }
+ * }
+ * ```
+ *
+ * @example Nested tracing
+ * ```typescript
+ * class ComplexProcessor {
+ *   processSchema(stackTrail: StackTrail, logger: Logger) {
+ *     return tracer(stackTrail, 'process-schema', () => {
+ *       const parsed = tracer(stackTrail, 'parse', () => {
+ *         return this.parseSchema();
+ *       }, logger);
+ *
+ *       const validated = tracer(stackTrail, 'validate', () => {
+ *         return this.validateSchema(parsed);
+ *       }, logger);
+ *
+ *       return tracer(stackTrail, 'transform', () => {
+ *         return this.transformSchema(validated);
+ *       }, logger);
+ *     }, logger);
+ *   }
+ * }
+ *
+ * // Stack trail will show: ['process-schema', 'parse'] -> ['process-schema', 'validate'] -> ['process-schema', 'transform']
+ * ```
+ *
+ * @example Multiple token tracing
+ * ```typescript
+ * const result = tracer(
+ *   stackTrail,
+ *   ['file-generation', 'models.ts'], // Multiple tokens for detailed context
+ *   () => {
+ *     return generateModelsFile();
+ *   },
+ *   logger
+ * );
+ * ```
+ *
+ * @example Error handling with tracing
+ * ```typescript
+ * class SafeGenerator {
+ *   generateWithTracing(stackTrail: StackTrail, logger: Logger) {
+ *     try {
+ *       return tracer(stackTrail, 'risky-operation', () => {
+ *         // This might throw an error
+ *         return this.complexGeneration();
+ *       }, logger);
+ *     } catch (error) {
+ *       // Stack trail is automatically cleaned up
+ *       logger.error(`Generation failed: ${error.message}`);
+ *       return this.fallbackGeneration();
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Performance monitoring
+ * ```typescript
+ * class PerformanceAwareGenerator {
+ *   timedGeneration(stackTrail: StackTrail, logger: Logger) {
+ *     const startTime = Date.now();
+ *
+ *     const result = tracer(stackTrail, 'timed-generation', () => {
+ *       return this.heavyComputation();
+ *     }, logger);
+ *
+ *     const duration = Date.now() - startTime;
+ *     logger.info(`Generation completed in ${duration}ms`);
+ *
+ *     return result;
+ *   }
+ * }
+ * ```
+ *
+ * @example Integration with context classes
+ * ```typescript
+ * // Typically used within context classes like this:
+ * class GenerateContext {
+ *   trace<T>(token: string | string[], fn: () => T): T {
+ *     return tracer(this.stackTrail, token, fn, this.logger);
+ *   }
+ *
+ *   processModel(schema: OasSchema) {
+ *     return this.trace(['model', schema.type], () => {
+ *       // Model processing logic
+ *       return this.createModel(schema);
+ *     });
+ *   }
+ * }
+ * ```
+ */
 export declare const tracer: <T>(stackTrail: StackTrail, token: string | string[], fn: () => T, log: Logger) => T;
 //# sourceMappingURL=tracer.d.ts.map

package/script/helpers/tracer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../src/helpers/tracer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4CAA4C,CAAA;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAE1D,eAAO,MAAM,MAAM,GAAI,CAAC,EACtB,YAAY,UAAU,EACtB,OAAO,MAAM,GAAG,MAAM,EAAE,EACxB,IAAI,MAAM,CAAC,EACX,KAAK,MAAM,MAgBZ,CAAA"}
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../src/helpers/tracer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4CAA4C,CAAA;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2HG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,EACtB,YAAY,UAAU,EACtB,OAAO,MAAM,GAAG,MAAM,EAAE,EACxB,IAAI,MAAM,CAAC,EACX,KAAK,MAAM,MAgBZ,CAAA"}

package/script/helpers/tracer.js

@@ -1,6 +1,130 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.tracer = void 0;
+/**
+ * Executes a function with distributed tracing support and stack trail management.
+ *
+ * This utility function provides distributed tracing capabilities for the SKMTC
+ * generation pipeline. It manages stack trail tokens that help track execution
+ * context across complex nested operations, making debugging and performance
+ * analysis much easier.
+ *
+ * The tracer ensures proper cleanup of stack trail tokens even if the wrapped
+ * function throws an error, maintaining the integrity of the tracing system.
+ * This is essential for accurate debugging and performance monitoring in
+ * complex code generation scenarios.
+ *
+ * @template T - The return type of the traced function
+ * @param stackTrail - The stack trail instance for tracking execution context
+ * @param token - Token(s) to identify this execution step in traces
+ * @param fn - The function to execute with tracing
+ * @param log - Logger instance for error reporting
+ * @returns The result of the wrapped function execution
+ *
+ * @throws Re-throws any error from the wrapped function after cleanup
+ *
+ * @example Basic tracing usage
+ * ```typescript
+ * import { tracer } from '@skmtc/core';
+ *
+ * class ModelGenerator {
+ *   generateModel(stackTrail: StackTrail, logger: Logger) {
+ *     return tracer(stackTrail, 'generate-model', () => {
+ *       // Complex model generation logic here
+ *       return this.createModelDefinition();
+ *     }, logger);
+ *   }
+ * }
+ * ```
+ *
+ * @example Nested tracing
+ * ```typescript
+ * class ComplexProcessor {
+ *   processSchema(stackTrail: StackTrail, logger: Logger) {
+ *     return tracer(stackTrail, 'process-schema', () => {
+ *       const parsed = tracer(stackTrail, 'parse', () => {
+ *         return this.parseSchema();
+ *       }, logger);
+ *
+ *       const validated = tracer(stackTrail, 'validate', () => {
+ *         return this.validateSchema(parsed);
+ *       }, logger);
+ *
+ *       return tracer(stackTrail, 'transform', () => {
+ *         return this.transformSchema(validated);
+ *       }, logger);
+ *     }, logger);
+ *   }
+ * }
+ *
+ * // Stack trail will show: ['process-schema', 'parse'] -> ['process-schema', 'validate'] -> ['process-schema', 'transform']
+ * ```
+ *
+ * @example Multiple token tracing
+ * ```typescript
+ * const result = tracer(
+ *   stackTrail,
+ *   ['file-generation', 'models.ts'], // Multiple tokens for detailed context
+ *   () => {
+ *     return generateModelsFile();
+ *   },
+ *   logger
+ * );
+ * ```
+ *
+ * @example Error handling with tracing
+ * ```typescript
+ * class SafeGenerator {
+ *   generateWithTracing(stackTrail: StackTrail, logger: Logger) {
+ *     try {
+ *       return tracer(stackTrail, 'risky-operation', () => {
+ *         // This might throw an error
+ *         return this.complexGeneration();
+ *       }, logger);
+ *     } catch (error) {
+ *       // Stack trail is automatically cleaned up
+ *       logger.error(`Generation failed: ${error.message}`);
+ *       return this.fallbackGeneration();
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Performance monitoring
+ * ```typescript
+ * class PerformanceAwareGenerator {
+ *   timedGeneration(stackTrail: StackTrail, logger: Logger) {
+ *     const startTime = Date.now();
+ *
+ *     const result = tracer(stackTrail, 'timed-generation', () => {
+ *       return this.heavyComputation();
+ *     }, logger);
+ *
+ *     const duration = Date.now() - startTime;
+ *     logger.info(`Generation completed in ${duration}ms`);
+ *
+ *     return result;
+ *   }
+ * }
+ * ```
+ *
+ * @example Integration with context classes
+ * ```typescript
+ * // Typically used within context classes like this:
+ * class GenerateContext {
+ *   trace<T>(token: string | string[], fn: () => T): T {
+ *     return tracer(this.stackTrail, token, fn, this.logger);
+ *   }
+ *
+ *   processModel(schema: OasSchema) {
+ *     return this.trace(['model', schema.type], () => {
+ *       // Model processing logic
+ *       return this.createModel(schema);
+ *     });
+ *   }
+ * }
+ * ```
+ */
 const tracer = (stackTrail, token, fn, log) => {
     stackTrail.append(token);
     try {

package/script/oas/schema/Schema.d.ts

@@ -7,8 +7,125 @@ import type { OasObject } from '../object/Object.js';
 import type { OasString } from '../string/String.js';
 import type { OasUnknown } from '../unknown/Unknown.js';
 import type { OasUnion } from '../union/Union.js';
+/**
+ * Union type representing all possible OpenAPI Schema objects in the SKMTC system.
+ *
+ * `OasSchema` is the fundamental type for representing any OpenAPI schema definition
+ * after it has been parsed and processed by the SKMTC pipeline. It encompasses all
+ * JSON Schema types supported by OpenAPI 3.x specifications, providing type-safe
+ * access to schema properties and validation constraints.
+ *
+ * This union type is used throughout the system for schema processing, type generation,
+ * and validation. Each variant corresponds to a specific JSON Schema type with its
+ * own set of properties and validation rules.
+ *
+ * ## Supported Schema Types
+ *
+ * - **{@link OasArray}**: Array schemas with item type definitions and constraints
+ * - **{@link OasBoolean}**: Boolean schemas with optional default values
+ * - **{@link OasInteger}**: Integer schemas with numeric constraints and formats
+ * - **{@link OasNumber}**: Number schemas with numeric constraints and formats
+ * - **{@link OasObject}**: Object schemas with properties, required fields, and constraints
+ * - **{@link OasString}**: String schemas with length constraints, patterns, and formats
+ * - **{@link OasUnknown}**: Schemas with unknown or mixed types
+ * - **{@link OasUnion}**: Union schemas representing oneOf/anyOf/allOf constructs
+ *
+ * @example Type checking and processing
+ * ```typescript
+ * import type { OasSchema } from '@skmtc/core';
+ *
+ * function processSchema(schema: OasSchema): string {
+ *   if (schema.type === 'object') {
+ *     // TypeScript knows this is OasObject
+ *     return `Object with ${Object.keys(schema.properties || {}).length} properties`;
+ *   } else if (schema.type === 'array') {
+ *     // TypeScript knows this is OasArray
+ *     return `Array of ${schema.items.type} items`;
+ *   } else if (schema.type === 'string') {
+ *     // TypeScript knows this is OasString
+ *     return `String${schema.format ? ` (${schema.format})` : ''}`;
+ *   }
+ *   // Handle other types...
+ *   return `${schema.type} type`;
+ * }
+ * ```
+ *
+ * @example Schema validation and constraints
+ * ```typescript
+ * function validateSchemaConstraints(schema: OasSchema, value: unknown): boolean {
+ *   switch (schema.type) {
+ *     case 'string':
+ *       if (typeof value !== 'string') return false;
+ *       if (schema.minLength && value.length < schema.minLength) return false;
+ *       if (schema.maxLength && value.length > schema.maxLength) return false;
+ *       if (schema.pattern && !new RegExp(schema.pattern).test(value)) return false;
+ *       return true;
+ *
+ *     case 'integer':
+ *     case 'number':
+ *       if (typeof value !== 'number') return false;
+ *       if (schema.minimum && value < schema.minimum) return false;
+ *       if (schema.maximum && value > schema.maximum) return false;
+ *       return true;
+ *
+ *     case 'array':
+ *       if (!Array.isArray(value)) return false;
+ *       if (schema.minItems && value.length < schema.minItems) return false;
+ *       if (schema.maxItems && value.length > schema.maxItems) return false;
+ *       return true;
+ *
+ *     default:
+ *       return true;
+ *   }
+ * }
+ * ```
+ *
+ * @example Code generation based on schema type
+ * ```typescript
+ * class TypeScriptGenerator {
+ *   generateType(schema: OasSchema): string {
+ *     switch (schema.type) {
+ *       case 'object':
+ *         return this.generateInterface(schema);
+ *       case 'array':
+ *         return `Array<${this.generateType(schema.items)}>`;
+ *       case 'string':
+ *         if (schema.enums) {
+ *           return schema.enums.map(e => `'${e}'`).join(' | ');
+ *         }
+ *         return 'string';
+ *       case 'integer':
+ *       case 'number':
+ *         return 'number';
+ *       case 'boolean':
+ *         return 'boolean';
+ *       case 'union':
+ *         return schema.variants.map(v => this.generateType(v)).join(' | ');
+ *       default:
+ *         return 'unknown';
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export type OasSchema = OasArray | OasBoolean | OasInteger | OasNumber | OasObject | OasString | OasUnknown | OasUnion;
+/**
+ * Configuration options for JSON Schema conversion operations.
+ *
+ * These options control how OAS schemas are converted back to JSON Schema format,
+ * particularly around reference resolution and schema inlining behavior.
+ *
+ * @example
+ * ```typescript
+ * const options: ToJsonSchemaOptions = {
+ *   resolve: true  // Resolve $ref references during conversion
+ * };
+ *
+ * const jsonSchema = schema.toJsonSchema(options);
+ * ```
+ */
 export type ToJsonSchemaOptions = {
+    /** Whether to resolve $ref references during conversion (default: false) */
     resolve: boolean;
 };
 //# sourceMappingURL=Schema.d.ts.map

package/script/oas/schema/Schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Schema.d.ts","sourceRoot":"","sources":["../../../src/oas/schema/Schema.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAEjD,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,UAAU,GACV,UAAU,GACV,SAAS,GACT,SAAS,GACT,SAAS,GACT,UAAU,GACV,QAAQ,CAAA;AAEZ,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA"}
+{"version":3,"file":"Schema.d.ts","sourceRoot":"","sources":["../../../src/oas/schema/Schema.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoGG;AACH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,UAAU,GACV,UAAU,GACV,SAAS,GACT,SAAS,GACT,SAAS,GACT,UAAU,GACV,QAAQ,CAAA;AAEZ;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA"}

package/script/typescript/PathParams.d.ts

@@ -2,18 +2,216 @@ import type { GenerateContext } from '../context/GenerateContext.js';
 import { Definition } from '../dsl/Definition.js';
 import type { TypeSystemObject } from '../types/TypeSystem.js';
 import { FunctionParameter } from './FunctionParameter.js';
+/**
+ * Constructor arguments for {@link PathParams}.
+ */
 type ConstructorArgs = {
+    /** The generation context for registering types and handling imports */
     context: GenerateContext;
+    /** Optional argument name for the parameter (if undefined, uses destructuring) */
     argName?: string;
+    /** Name of the TypeScript type to generate */
     typeName: string;
+    /** The type system object defining the parameter structure */
     typeValue: TypeSystemObject;
+    /** OpenAPI path template with parameter placeholders */
     pathTemplate: string;
 };
+/**
+ * Manages path parameter type definitions and function parameters for API endpoints.
+ *
+ * `PathParams` is a utility class that combines type generation, function parameter
+ * handling, and path templating for OpenAPI path parameters. It creates TypeScript
+ * type definitions for path parameters and generates the corresponding function
+ * parameters that can be used in API client methods.
+ *
+ * This class is essential for generating type-safe API clients where path parameters
+ * are properly typed and validated at compile time. It handles both destructured
+ * parameters (when no argument name is provided) and named parameters.
+ *
+ * ## Key Features
+ *
+ * - **Type Definition Generation**: Creates TypeScript types for path parameters
+ * - **Function Parameter Integration**: Generates properly typed function parameters
+ * - **Path Template Processing**: Converts OpenAPI paths to template literals
+ * - **Destructuring Support**: Handles both named and destructured parameter patterns
+ * - **Context Integration**: Fully integrated with the SKMTC generation pipeline
+ *
+ * @example Basic path parameters with destructuring
+ * ```typescript
+ * import { PathParams } from '@skmtc/core';
+ *
+ * const pathParams = new PathParams({
+ *   context: generateContext,
+ *   typeName: 'GetUserParams',
+ *   typeValue: {
+ *     type: 'object',
+ *     objectProperties: {
+ *       properties: {
+ *         id: { type: 'string' },
+ *         format: { type: 'string' }
+ *       }
+ *     }
+ *   },
+ *   pathTemplate: '/users/{id}'
+ * });
+ *
+ * console.log(pathParams.path); // '/users/${id}'
+ * ```
+ *
+ * @example Named parameter usage
+ * ```typescript
+ * const namedPathParams = new PathParams({
+ *   context: generateContext,
+ *   argName: 'params',
+ *   typeName: 'UserPathParams',
+ *   typeValue: {
+ *     type: 'object',
+ *     objectProperties: {
+ *       properties: {
+ *         userId: { type: 'string' },
+ *         projectId: { type: 'string' }
+ *       }
+ *     }
+ *   },
+ *   pathTemplate: '/users/{userId}/projects/{projectId}'
+ * });
+ *
+ * console.log(pathParams.path); // '/users/${params.userId}/projects/${params.projectId}'
+ * ```
+ *
+ * @example API client method generation
+ * ```typescript
+ * class ApiMethodGenerator {
+ *   generateGetMethod(operationPath: string, parameters: any) {
+ *     const pathParams = new PathParams({
+ *       context: this.context,
+ *       argName: 'pathParams',
+ *       typeName: 'PathParameters',
+ *       typeValue: parameters,
+ *       pathTemplate: operationPath
+ *     });
+ *
+ *     return `
+ * async getData(${pathParams.parameter.toString()}) {
+ *   const url = \`${pathParams.path}\`;
+ *   return this.client.get(url);
+ * }`;
+ *   }
+ * }
+ *
+ * // Generates:
+ * // async getData(pathParams: PathParameters) {
+ * //   const url = `/users/${pathParams.userId}/projects/${pathParams.projectId}`;
+ * //   return this.client.get(url);
+ * // }
+ * ```
+ *
+ * @example With destructured parameters
+ * ```typescript
+ * const destructuredParams = new PathParams({
+ *   context: generateContext,
+ *   // No argName provided, so uses destructuring
+ *   typeName: 'OrderParams',
+ *   typeValue: {
+ *     type: 'object',
+ *     objectProperties: {
+ *       properties: {
+ *         orderId: { type: 'string' },
+ *         customerId: { type: 'string' }
+ *       }
+ *     }
+ *   },
+ *   pathTemplate: '/customers/{customerId}/orders/{orderId}'
+ * });
+ *
+ * // Function parameter will be: { orderId, customerId }: OrderParams
+ * // Path template will be: '/customers/${customerId}/orders/${orderId}'
+ * ```
+ *
+ * @example Complex nested path parameters
+ * ```typescript
+ * const complexPathParams = new PathParams({
+ *   context: generateContext,
+ *   argName: 'pathData',
+ *   typeName: 'ComplexPathParams',
+ *   typeValue: {
+ *     type: 'object',
+ *     objectProperties: {
+ *       properties: {
+ *         orgId: { type: 'string' },
+ *         projectId: { type: 'string' },
+ *         issueId: { type: 'number' },
+ *         commentId: { type: 'string' }
+ *       }
+ *     }
+ *   },
+ *   pathTemplate: '/orgs/{orgId}/projects/{projectId}/issues/{issueId}/comments/{commentId}'
+ * });
+ *
+ * // Generates path: '/orgs/${pathData.orgId}/projects/${pathData.projectId}/issues/${pathData.issueId}/comments/${pathData.commentId}'
+ * ```
+ *
+ * @example Integration with operation generation
+ * ```typescript
+ * class OperationGenerator {
+ *   generateOperation(operation: OasOperation) {
+ *     const pathParameters = this.extractPathParameters(operation);
+ *
+ *     if (pathParameters.length > 0) {
+ *       const pathParams = new PathParams({
+ *         context: this.context,
+ *         typeName: `${operation.operationId}PathParams`,
+ *         typeValue: this.buildParametersType(pathParameters),
+ *         pathTemplate: operation.path
+ *       });
+ *
+ *       return this.generateMethodWithPathParams(operation, pathParams);
+ *     }
+ *
+ *     return this.generateSimpleMethod(operation);
+ *   }
+ * }
+ * ```
+ */
 export declare class PathParams {
+    /** The generation context used for type registration and imports */
     context: GenerateContext;
+    /** The TypeScript type definition for the path parameters */
     typeDefinition: Definition<TypeSystemObject>;
+    /** The function parameter representation for method signatures */
     parameter: FunctionParameter;
+    /** The processed path template with parameter substitutions */
     path: string;
+    /**
+     * Creates a new PathParams instance with type definitions and path processing.
+     *
+     * The constructor sets up the complete parameter handling pipeline:
+     * 1. Creates a TypeScript type definition for the parameters
+     * 2. Generates a function parameter (either named or destructured)
+     * 3. Processes the path template for runtime interpolation
+     *
+     * @param args - Configuration for path parameter generation
+     *
+     * @example
+     * ```typescript
+     * const pathParams = new PathParams({
+     *   context: generateContext,
+     *   argName: 'params',
+     *   typeName: 'UserPathParams',
+     *   typeValue: {
+     *     type: 'object',
+     *     objectProperties: {
+     *       properties: {
+     *         id: { type: 'string' },
+     *         format: { type: 'string' }
+     *       }
+     *     }
+     *   },
+     *   pathTemplate: '/users/{id}/profile'
+     * });
+     * ```
+     */
     constructor({ context, argName, typeName, typeValue, pathTemplate }: ConstructorArgs);
 }
 export {};

package/script/typescript/PathParams.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PathParams.d.ts","sourceRoot":"","sources":["../../src/typescript/PathParams.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAG1D,KAAK,eAAe,GAAG;IACrB,OAAO,EAAE,eAAe,CAAA;IACxB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,gBAAgB,CAAA;IAC3B,YAAY,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,qBAAa,UAAU;IACrB,OAAO,EAAE,eAAe,CAAA;IACxB,cAAc,EAAE,UAAU,CAAC,gBAAgB,CAAC,CAAA;IAC5C,SAAS,EAAE,iBAAiB,CAAA;IAC5B,IAAI,EAAE,MAAM,CAAA;gBAEA,EACV,OAAO,EACP,OAAO,EACP,QAAQ,EACR,SAAS,EACT,YAAY,EACb,EAAE,eAAe;CAwBnB"}
+{"version":3,"file":"PathParams.d.ts","sourceRoot":"","sources":["../../src/typescript/PathParams.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAG1D;;GAEG;AACH,KAAK,eAAe,GAAG;IACrB,wEAAwE;IACxE,OAAO,EAAE,eAAe,CAAA;IACxB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAA;IAChB,8DAA8D;IAC9D,SAAS,EAAE,gBAAgB,CAAA;IAC3B,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAA;CACrB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4JG;AACH,qBAAa,UAAU;IACrB,oEAAoE;IACpE,OAAO,EAAE,eAAe,CAAA;IAExB,6DAA6D;IAC7D,cAAc,EAAE,UAAU,CAAC,gBAAgB,CAAC,CAAA;IAE5C,kEAAkE;IAClE,SAAS,EAAE,iBAAiB,CAAA;IAE5B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAA;IAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;gBACS,EACV,OAAO,EACP,OAAO,EACP,QAAQ,EACR,SAAS,EACT,YAAY,EACb,EAAE,eAAe;CAwBnB"}