@skmtc/core 0.0.783 → 0.0.785

package/script/dsl/model/ModelBase.js

@@ -2,21 +2,134 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ModelBase = void 0;
 const ContentBase_js_1 = require("../ContentBase.js");
+/**
+ * Base class for model generators in the SKMTC DSL system.
+ *
+ * `ModelBase` extends {@link ContentBase} to provide specialized functionality for
+ * generating code from OpenAPI schema models. It offers type-safe methods for
+ * inserting related models, managing schema references, and handling enrichments.
+ *
+ * This class serves as the foundation for creating custom model generators that
+ * transform OpenAPI schemas into various code artifacts like TypeScript interfaces,
+ * validation schemas, or database models.
+ *
+ * ## Key Features
+ *
+ * - **Model Insertion**: Insert related models with automatic reference resolution
+ * - **Schema Normalization**: Handle complex schema references and fallbacks
+ * - **Export Management**: Control which models are exported from generated files
+ * - **Enrichment Support**: Extend functionality with custom enrichment data
+ * - **Type Safety**: Full TypeScript support with generic enrichment types
+ *
+ * @template EnrichmentType - Optional type for custom enrichment data
+ *
+ * @example Basic model generator
+ * ```typescript
+ * import { ModelBase, Definition } from '@skmtc/core';
+ *
+ * class TypeScriptInterface extends ModelBase {
+ *   toDefinition(): Definition {
+ *     const schema = this.context.getSchema(this.refName);
+ *
+ *     return new Definition({
+ *       name: this.refName,
+ *       content: `export interface ${this.refName} {
+ *         ${this.generateProperties(schema)}
+ *       }`
+ *     });
+ *   }
+ *
+ *   private generateProperties(schema: OasSchema): string {
+ *     // Generate interface properties from schema
+ *     return Object.entries(schema.properties || {})
+ *       .map(([key, prop]) => `${key}: ${this.getPropertyType(prop)}`)
+ *       .join(';\n  ');
+ *   }
+ * }
+ * ```
+ *
+ * @example With enrichments
+ * ```typescript
+ * type ValidationEnrichment = {
+ *   validators: string[];
+ *   customRules: Record<string, string>;
+ * };
+ *
+ * class ValidationModel extends ModelBase<ValidationEnrichment> {
+ *   toDefinition(): Definition {
+ *     const enrichment = this.settings.enrichment;
+ *     const validators = enrichment?.validators || [];
+ *
+ *     return new Definition({
+ *       name: `${this.refName}Validator`,
+ *       content: this.generateValidator(validators)
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Inserting related models
+ * ```typescript
+ * class ApiModel extends ModelBase {
+ *   toDefinition(): Definition {
+ *     const schema = this.context.getSchema(this.refName);
+ *
+ *     // Insert related models automatically
+ *     if (schema.properties?.user) {
+ *       this.insertNormalizedModel(
+ *         new TypeScriptInterface({ ... }),
+ *         { schema: schema.properties.user, fallbackName: 'User' }
+ *       );
+ *     }
+ *
+ *     return new Definition({
+ *       name: this.refName,
+ *       content: this.generateInterface(schema)
+ *     });
+ *   }
+ * }
+ * ```
+ */
 class ModelBase extends ContentBase_js_1.ContentBase {
+    /**
+     * Creates a new ModelBase instance.
+     *
+     * @param args - Model 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.refName - Reference name for the model being generated
+     *
+     * @example
+     * ```typescript
+     * const model = new ModelBase({
+     *   context: generateContext,
+     *   settings: {
+     *     exportPath: './src/models.ts',
+     *     enrichment: customEnrichments
+     *   },
+     *   generatorKey: 'typescript-models',
+     *   refName: 'UserModel'
+     * });
+     * ```
+     */
     constructor({ context, settings, generatorKey, refName }) {
         super({ context });
+        /** Content settings including export path and enrichment configuration */
         Object.defineProperty(this, "settings", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Reference name for the model being generated */
         Object.defineProperty(this, "refName", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Generator key identifying this generator type */
         Object.defineProperty(this, "generatorKey", {
             enumerable: true,
             configurable: true,
@@ -27,6 +140,43 @@ class ModelBase extends ContentBase_js_1.ContentBase {
         this.refName = refName;
         this.settings = settings;
     }
+    /**
+     * Inserts a related model with forced generation.
+     *
+     * This method adds a related model to the current generation context, ensuring
+     * it will be generated regardless of whether it already exists. The inserted
+     * model will be exported to the same destination path as this model unless
+     * `noExport` is specified.
+     *
+     * @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
+     * ```typescript
+     * class UserModel extends ModelBase {
+     *   toDefinition(): Definition {
+     *     // Insert an address model that's always generated
+     *     const address = this.insertModel(
+     *       new AddressModel({ ... }),
+     *       'Address',
+     *       { noExport: false }
+     *     );
+     *
+     *     return new Definition({
+     *       name: this.refName,
+     *       content: `export interface ${this.refName} {
+     *         address: ${address.value}
+     *       }`
+     *     });
+     *   }
+     * }
+     * ```
+     */
     insertModel(insertable, refName, options = {}) {
         return this.context.insertModel(insertable, refName, {
             generation: 'force',
@@ -34,6 +184,63 @@ class ModelBase extends ContentBase_js_1.ContentBase {
             noExport: options.noExport
         });
     }
+    /**
+     * Inserts a related model with automatic schema normalization and reference resolution.
+     *
+     * This method intelligently handles schema references by automatically resolving
+     * them to appropriate model names. If the schema is a reference, it uses the
+     * referenced name; otherwise it falls back to the provided fallback name.
+     *
+     * This is particularly useful when working with complex nested schemas where
+     * you want to automatically generate models for referenced types.
+     *
+     * @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 (can be reference or actual schema)
+     * @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 schema references
+     * ```typescript
+     * class OrderModel extends ModelBase {
+     *   toDefinition(): Definition {
+     *     const schema = this.context.getSchema(this.refName);
+     *
+     *     // Handle customer property - could be reference or inline schema
+     *     if (schema.properties?.customer) {
+     *       const customer = this.insertNormalizedModel(
+     *         new CustomerModel({ ... }),
+     *         {
+     *           schema: schema.properties.customer,
+     *           fallbackName: 'Customer'
+     *         }
+     *       );
+     *       // customer.refName will be 'Customer' or the referenced schema name
+     *     }
+     *
+     *     return new Definition({ ... });
+     *   }
+     * }
+     * ```
+     *
+     * @example With complex nested schemas
+     * ```typescript
+     * // If schema.properties.items is { $ref: '#/components/schemas/Product' }
+     * // Then the inserted model will use refName 'Product'
+     * const items = this.insertNormalizedModel(
+     *   new ProductModel({ ... }),
+     *   {
+     *     schema: schema.properties.items,
+     *     fallbackName: 'Item' // Won't be used since schema has $ref
+     *   }
+     * );
+     * ```
+     */
     insertNormalizedModel(insertable, { schema, fallbackName }, options = {}) {
         return this.context.insertNormalisedModel(insertable, {
             schema,
@@ -41,6 +248,47 @@ class ModelBase extends ContentBase_js_1.ContentBase {
             destinationPath: this.settings.exportPath
         }, options);
     }
+    /**
+     * Registers a file-level artifact with the generation context.
+     *
+     * This method allows the model 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
+     * model'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 imports
+     * ```typescript
+     * class ApiModel extends ModelBase {
+     *   toDefinition(): Definition {
+     *     // Register an import that all generated models need
+     *     this.register({
+     *       content: "import { BaseModel } from './base';",
+     *       phase: 'pre'
+     *     });
+     *
+     *     return new Definition({ ... });
+     *   }
+     * }
+     * ```
+     *
+     * @example Registering type exports
+     * ```typescript
+     * class TypeModel extends ModelBase {
+     *   toDefinition(): Definition {
+     *     this.register({
+     *       content: "export type * from './types';",
+     *       phase: 'post'
+     *     });
+     *
+     *     return new Definition({ ... });
+     *   }
+     * }
+     * ```
+     */
     register(args) {
         this.context.register({
             ...args,

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

@@ -12,17 +12,192 @@ import type { RefName } from '../../types/RefName.js';
 import { OasSchema } from '../../oas/schema/Schema.js';
 import { OasRef } from '../../oas/ref/Ref.js';
 import { 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: GenerateContext;
+    /** 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<'force'>, 'noExport'>): Inserted<V, 'force', EnrichmentType>;
     insertModel<V extends GeneratedValue, EnrichmentType = undefined>(insertable: ModelInsertable<V, EnrichmentType>, refName: RefName, options?: Pick<InsertModelOptions<'force'>, 'noExport'>): Inserted<V, 'force', EnrichmentType>;
     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<'force'>, 'noExport'>): InsertNormalisedModelReturn<V, Schema>;

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

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

package/script/dsl/operation/OperationBase.js

@@ -2,21 +2,150 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OperationBase = void 0;
 const ContentBase_js_1 = require("../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}');
+ *       }`
+ *     });
+ *   }
+ * }
+ * ```
+ */
 class OperationBase extends ContentBase_js_1.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,
@@ -27,6 +156,43 @@ class OperationBase extends ContentBase_js_1.ContentBase {
         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, {
             generation: 'force',