@skmtc/core 0.0.983 → 0.16.1

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

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

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

@@ -1 +0,0 @@
-{"version":3,"file":"OperationBase.d.ts","sourceRoot":"","sources":["../../../src/dsl/operation/OperationBase.ts"],"names":[],"mappings":"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"}