@skmtc/core 0.0.793 → 0.0.794

package/esm/helpers/tracer.js

@@ -1,3 +1,127 @@
+/**
+ * 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 const tracer = (stackTrail, token, fn, log) => {
     stackTrail.append(token);
     try {

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

package/esm/typescript/PathParams.js

@@ -2,26 +2,216 @@ import { Definition } from '../dsl/Definition.js';
 import { Identifier } from '../dsl/Identifier.js';
 import { FunctionParameter } from './FunctionParameter.js';
 import { toPathTemplate } from './toPathTemplate.js';
+/**
+ * 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 class PathParams {
+    /**
+     * 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 }) {
+        /** The generation context used for type registration and imports */
         Object.defineProperty(this, "context", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The TypeScript type definition for the path parameters */
         Object.defineProperty(this, "typeDefinition", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The function parameter representation for method signatures */
         Object.defineProperty(this, "parameter", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The processed path template with parameter substitutions */
         Object.defineProperty(this, "path", {
             enumerable: true,
             configurable: true,