@skmtc/core 0.0.984 → 0.16.1

package/esm/dsl/operation/OperationBase.js

@@ -1,407 +0,0 @@
-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,
-            writable: true,
-            value: void 0
-        });
-        this.generatorKey = generatorKey;
-        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, {
-            destinationPath: this.settings.exportPath,
-            noExport: options.noExport
-        });
-    }
-    /**
-     * Inserts a related model with forced generation.
-     *
-     * This method adds a model to the current generation context, typically used
-     * for request/response models or other types related to the operation. The model
-     * will be generated and can be referenced in the operation code.
-     *
-     * @template V - Type of generated value returned by the insertable
-     * @template EnrichmentType - Type of enrichment data for the insertable
-     * @param insertable - The model generator to insert
-     * @param refName - Reference name for the inserted model
-     * @param options - Insertion options
-     * @param options.noExport - Whether to skip exporting the inserted model
-     * @returns Inserted model reference with generated value
-     *
-     * @example Inserting request/response models
-     * ```typescript
-     * class ApiOperation extends OperationBase {
-     *   toDefinition(): Definition {
-     *     // Insert request model
-     *     const requestModel = this.insertModel(
-     *       new RequestModel({ ... }),
-     *       'CreateUserRequest'
-     *     );
-     *
-     *     // Insert response model
-     *     const responseModel = this.insertModel(
-     *       new ResponseModel({ ... }),
-     *       'CreateUserResponse'
-     *     );
-     *
-     *     return new Definition({
-     *       name: this.operation.operationId,
-     *       content: `async ${this.operation.operationId}(data: ${requestModel.value}): Promise<${responseModel.value}> {
-     *         return this.request('${this.operation.method}', '${this.operation.path}', data);
-     *       }`
-     *     });
-     *   }
-     * }
-     * ```
-     */
-    insertModel(insertable, refName, options = {}) {
-        return this.context.insertModel(insertable, refName, {
-            destinationPath: this.settings.exportPath,
-            noExport: options.noExport
-        });
-    }
-    /**
-     * Inserts a related model with automatic schema normalization and reference resolution.
-     *
-     * This method intelligently handles schema references from operation request/response
-     * bodies, automatically resolving schema references to appropriate model names.
-     * This is particularly useful for operations with complex request/response schemas.
-     *
-     * @template V - Type of generated value returned by the insertable
-     * @template Schema - Type of OpenAPI schema (schema object, reference, or void)
-     * @template EnrichmentType - Type of enrichment data for the insertable
-     * @param insertable - The model generator to insert
-     * @param args - Schema normalization arguments
-     * @param args.schema - The OpenAPI schema to normalize (from request/response)
-     * @param args.fallbackName - Name to use if schema is not a reference
-     * @param options - Insertion options
-     * @param options.noExport - Whether to skip exporting the inserted model
-     * @returns Inserted model reference with normalized name and generated value
-     *
-     * @example Handling operation request/response schemas
-     * ```typescript
-     * class RestApiOperation extends OperationBase {
-     *   toDefinition(): Definition {
-     *     const operation = this.operation;
-     *
-     *     // Handle request body schema
-     *     let requestType = 'void';
-     *     const requestSchema = operation.requestBody?.content?.['application/json']?.schema;
-     *     if (requestSchema) {
-     *       const requestModel = this.insertNormalizedModel(
-     *         new TypeScriptInterface({ ... }),
-     *         {
-     *           schema: requestSchema,
-     *           fallbackName: `${operation.operationId}Request`
-     *         }
-     *       );
-     *       requestType = requestModel.value;
-     *     }
-     *
-     *     // Handle response schema
-     *     const responseSchema = operation.responses?.['200']?.content?.['application/json']?.schema;
-     *     const responseModel = this.insertNormalizedModel(
-     *       new TypeScriptInterface({ ... }),
-     *       {
-     *         schema: responseSchema,
-     *         fallbackName: `${operation.operationId}Response`
-     *       }
-     *     );
-     *
-     *     return new Definition({
-     *       name: operation.operationId,
-     *       content: `async ${operation.operationId}(data: ${requestType}): Promise<${responseModel.value}>`
-     *     });
-     *   }
-     * }
-     * ```
-     */
-    insertNormalizedModel(insertable, { schema, fallbackName }, options = {}) {
-        return this.context.insertNormalisedModel(insertable, {
-            schema,
-            fallbackName,
-            destinationPath: this.settings.exportPath
-        }, options);
-    }
-    /**
-     * Defines and registers a new definition in the generation context.
-     *
-     * This is an experimental method that allows creating and registering
-     * definitions directly without going through the standard insertion flow.
-     * Use with caution as the API may change in future versions.
-     *
-     * @experimental This method's API may change in future versions
-     * @template V - Type of generated value
-     * @param args - Definition arguments
-     * @param args.identifier - Unique identifier for the definition
-     * @param args.value - The generated value to associate with the definition
-     * @param args.noExport - Whether to skip exporting the definition
-     * @returns The created and registered definition
-     *
-     * @example Creating inline definitions
-     * ```typescript
-     * class InlineHelperOperation extends OperationBase {
-     *   toDefinition(): Definition {
-     *     // Create an inline helper function
-     *     const helper = this.defineAndRegister({
-     *       identifier: 'validateRequest',
-     *       value: 'function validateRequest(data: any) { ... }',
-     *       noExport: true
-     *     });
-     *
-     *     return new Definition({
-     *       name: this.operation.operationId,
-     *       content: `async ${this.operation.operationId}(data: any) {
-     *         ${helper.value}(data);
-     *         return this.request('${this.operation.method}', '${this.operation.path}', data);
-     *       }`
-     *     });
-     *   }
-     * }
-     * ```
-     */
-    defineAndRegister({ identifier, value, noExport }) {
-        return this.context.defineAndRegister({
-            identifier,
-            value,
-            destinationPath: this.settings.exportPath,
-            noExport
-        });
-    }
-    /**
-     * Registers a file-level artifact with the generation context.
-     *
-     * This method allows the operation generator to register additional content
-     * (like imports, exports, or file-level definitions) that should be included
-     * in the generated file. The registration is automatically scoped to this
-     * operation's export path.
-     *
-     * @param args - Registration arguments
-     * @param args.content - The content to register (import, export, etc.)
-     * @param args.phase - When to register the content ('pre' or 'post')
-     *
-     * @example Registering API client imports
-     * ```typescript
-     * class HttpOperation extends OperationBase {
-     *   toDefinition(): Definition {
-     *     // Register imports needed for HTTP operations
-     *     this.register({
-     *       content: "import { ApiClient } from './client';",
-     *       phase: 'pre'
-     *     });
-     *
-     *     this.register({
-     *       content: "import { RequestOptions } from './types';",
-     *       phase: 'pre'
-     *     });
-     *
-     *     return new Definition({ ... });
-     *   }
-     * }
-     * ```
-     *
-     * @example Registering utility exports
-     * ```typescript
-     * class ApiOperationGroup extends OperationBase {
-     *   toDefinition(): Definition {
-     *     // Register a utility export after all operations
-     *     this.register({
-     *       content: "export const API_VERSION = '1.0';",
-     *       phase: 'post'
-     *     });
-     *
-     *     return new Definition({ ... });
-     *   }
-     * }
-     * ```
-     */
-    register(args) {
-        this.context.register({
-            ...args,
-            destinationPath: this.settings.exportPath
-        });
-    }
-}

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

@@ -1,111 +0,0 @@
-import type { OperationInsertable } from './types.js';
-import type { OasOperation } from '../../oas/operation/Operation.js';
-import type { ContentSettings } from '../ContentSettings.js';
-import type { GeneratedDefinition } from '../GeneratedValue.js';
-import type { GeneratedValue } from '../GeneratedValue.js';
-import type { GenerateContextType } from '../../context/generateTypes.js';
-type CreateOperationArgs<V extends GeneratedValue, EnrichmentType = undefined> = {
-    context: GenerateContextType;
-    insertable: OperationInsertable<V, EnrichmentType>;
-    operation: OasOperation;
-    destinationPath?: string;
-    noExport?: boolean;
-};
-/**
- * Driver class for generating operation-based artifacts from OpenAPI operations.
- *
- * The `OperationDriver` manages the transformation of OpenAPI operation objects
- * into code artifacts, handling path generation, identifier resolution, and
- * definition management. It serves as the core orchestrator for operation-based
- * code generation in the SKMTC pipeline.
- *
- * @template V - Type of generated values produced by this driver
- * @template T - Type of generation strategy (e.g., 'function', 'class', 'hook')
- * @template EnrichmentType - Type of enrichments that can be applied
- *
- * @example Basic usage in an operation generator
- * ```typescript
- * class APIClientGenerator extends OperationBase {
- *   generate() {
- *     const driver = new OperationDriver({
- *       context: this.context,
- *       insertable: this,
- *       operation: this.operation,
- *       generation: 'function'
- *     });
- *
- *     const functionCode = driver.definition.toValueString();
- *     const file = this.createFile(functionCode);
- *     this.register({ file });
- *   }
- * }
- * ```
- */
-export declare class OperationDriver<V extends GeneratedValue, EnrichmentType = undefined> {
-    /** The generation context providing access to OAS objects and utilities */
-    context: GenerateContextType;
-    /** The insertable object that provides generation configuration */
-    insertable: OperationInsertable<V, EnrichmentType>;
-    /** The OpenAPI operation object being processed */
-    operation: OasOperation;
-    /** Content settings for customizing generation behavior */
-    settings: ContentSettings<EnrichmentType>;
-    /** Optional custom destination path for generated files */
-    destinationPath?: string;
-    /** The generated definition containing the transformed operation */
-    definition: GeneratedDefinition<V>;
-    /** Whether to exclude this operation from exports */
-    noExport?: boolean;
-    /**
-     * Creates a new OperationDriver instance.
-     *
-     * @param args - Configuration for the operation driver
-     * @param args.context - Generation context
-     * @param args.insertable - Insertable providing generation configuration
-     * @param args.operation - OpenAPI operation to process
-     * @param args.destinationPath - Optional custom destination path
-     * @param args.noExport - Whether to exclude from exports
-     */
-    constructor({ context, insertable, operation, destinationPath, noExport }: CreateOperationArgs<V, EnrichmentType>);
-    /**
-     * Applies generation configuration to create the operation definition.
-     *
-     * This method handles the core generation logic for operations, including
-     * identifier resolution, export path management, and import registration
-     * for cross-file dependencies.
-     *
-     * @template T - The generation type
-     * @param args - Apply configuration arguments
-     * @param args.generation - Optional generation type (unused currently)
-     * @param args.destinationPath - Optional destination path for imports
-     * @returns Generated definition for the operation
-     */
-    private apply;
-    /**
-     * Retrieves or creates a definition for the operation.
-     *
-     * This method first checks for cached definitions to avoid duplicate generation,
-     * then creates a new definition if none exists. It handles the complete operation
-     * transformation process including schema resolution and value generation.
-     *
-     * @param args - Definition retrieval arguments
-     * @param args.identifier - The identifier for the definition
-     * @param args.exportPath - The export path for the definition
-     * @returns Operation definition instance
-     */
-    private getDefinition;
-    /**
-     * Type guard to verify a definition matches the expected generated value type.
-     *
-     * This method performs type narrowing to ensure a cached definition is compatible
-     * with the current generation requirements, including export path validation.
-     *
-     * @template V - The expected generated value type
-     * @param definition - The definition to verify (may be undefined)
-     * @param exportPath - Expected export path for validation
-     * @returns True if definition matches expected type and constraints
-     */
-    private affirmDefinition;
-}
-export {};
-//# sourceMappingURL=OperationDriver.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"OperationDriver.d.ts","sourceRoot":"","sources":["../../../src/dsl/operation/OperationDriver.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;AAI5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAEzE,KAAK,mBAAmB,CAAC,CAAC,SAAS,cAAc,EAAE,cAAc,GAAG,SAAS,IAAI;IAC/E,OAAO,EAAE,mBAAmB,CAAA;IAC5B,UAAU,EAAE,mBAAmB,CAAC,CAAC,EAAE,cAAc,CAAC,CAAA;IAClD,SAAS,EAAE,YAAY,CAAA;IACvB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,eAAe,CAAC,CAAC,SAAS,cAAc,EAAE,cAAc,GAAG,SAAS;IAC/E,2EAA2E;IAC3E,OAAO,EAAE,mBAAmB,CAAA;IAC5B,mEAAmE;IACnE,UAAU,EAAE,mBAAmB,CAAC,CAAC,EAAE,cAAc,CAAC,CAAA;IAClD,mDAAmD;IACnD,SAAS,EAAE,YAAY,CAAA;IACvB,2DAA2D;IAC3D,QAAQ,EAAE,eAAe,CAAC,cAAc,CAAC,CAAA;IACzC,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,oEAAoE;IACpE,UAAU,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAA;IAClC,qDAAqD;IACrD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB;;;;;;;;;OASG;gBACS,EACV,OAAO,EACP,UAAU,EACV,SAAS,EACT,eAAe,EACf,QAAQ,EACT,EAAE,mBAAmB,CAAC,CAAC,EAAE,cAAc,CAAC;IAczC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,KAAK;IAeb;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IA+BrB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,gBAAgB;CAqBzB"}