@skmtc/core 0.0.788 → 0.0.790

package/script/context/RenderContext.d.ts

@@ -8,16 +8,206 @@ import type * as log from '../deps/jsr.io/@std/log/0.224.14/mod.js';
 import { File } from '../dsl/File.js';
 import type { Preview, Mapping } from '../types/Preview.js';
 import type { JsonFile } from '../dsl/JsonFile.js';
+/**
+ * Constructor arguments for {@link RenderContext}.
+ */
 type ConstructorArgs = {
+    /** Map of generated files to render */
     files: Map<string, File | JsonFile>;
+    /** Preview data for generated content */
     previews: Record<string, Record<string, Preview>>;
+    /** Mapping data for file relationships */
     mappings: Record<string, Record<string, Mapping>>;
+    /** Optional Prettier configuration for code formatting */
     prettierConfig?: PrettierConfigType;
+    /** Base path for resolving file paths */
     basePath: string | undefined;
+    /** Stack trail for distributed tracing */
     stackTrail: StackTrail;
+    /** Logger instance for debug information */
     logger: log.Logger;
+    /** Function to capture result status */
     captureCurrentResult: (result: ResultType) => void;
 };
+/**
+ * The rendering context for the final phase of the SKMTC transformation pipeline.
+ *
+ * `RenderContext` is responsible for taking the generated artifacts from the generation
+ * phase and rendering them into their final form with proper formatting, path resolution,
+ * and file preparation. It handles code formatting via Prettier, path normalization,
+ * and produces the final artifacts ready for writing to the filesystem.
+ *
+ * This context represents the culmination of the three-phase SKMTC pipeline, transforming
+ * generator outputs into production-ready code files with proper formatting and structure.
+ *
+ * ## Key Features
+ *
+ * - **Code Formatting**: Automatic Prettier formatting for generated TypeScript/JavaScript code
+ * - **Path Resolution**: Intelligent path resolution with base path support
+ * - **Content Collation**: Combines all generated content into organized file structures
+ * - **Metadata Generation**: Tracks file statistics (lines, characters) and relationships
+ * - **Error Tracking**: Comprehensive error handling with Sentry integration
+ * - **Performance Monitoring**: Built-in tracing and performance measurement
+ *
+ * @example Basic rendering usage
+ * ```typescript
+ * import { RenderContext } from '@skmtc/core';
+ *
+ * const renderContext = new RenderContext({
+ *   files: generatedFiles,
+ *   previews: previewData,
+ *   mappings: mappingData,
+ *   prettierConfig: {
+ *     semi: false,
+ *     singleQuote: true,
+ *     trailingComma: 'all'
+ *   },
+ *   basePath: './src/generated',
+ *   stackTrail: traceStack,
+ *   logger: myLogger,
+ *   captureCurrentResult: (result) => console.log(result)
+ * });
+ *
+ * const rendered = await renderContext.render();
+ *
+ * // Access rendered files
+ * Object.entries(rendered.artifacts).forEach(([path, content]) => {
+ *   console.log(`Rendered ${path}: ${rendered.files[path].lines} lines`);
+ *   // Write to filesystem
+ *   await Deno.writeTextFile(path, content);
+ * });
+ * ```
+ *
+ * @example With custom Prettier configuration
+ * ```typescript
+ * const renderContext = new RenderContext({
+ *   files: generatedFiles,
+ *   previews: {},
+ *   mappings: {},
+ *   prettierConfig: {
+ *     parser: 'typescript',
+ *     printWidth: 120,
+ *     tabWidth: 2,
+ *     semi: true,
+ *     singleQuote: true,
+ *     trailingComma: 'es5',
+ *     bracketSpacing: true,
+ *     arrowParens: 'avoid'
+ *   },
+ *   basePath: './packages/api-client/src',
+ *   stackTrail: stack,
+ *   logger: logger,
+ *   captureCurrentResult: resultHandler
+ * });
+ *
+ * const result = await renderContext.render();
+ *
+ * // All TypeScript files are automatically formatted
+ * console.log('Formatted files:', Object.keys(result.artifacts).length);
+ * ```
+ *
+ * @example Processing render results
+ * ```typescript
+ * const rendered = await renderContext.render();
+ *
+ * // Analyze file statistics
+ * const totalLines = Object.values(rendered.files)
+ *   .reduce((sum, file) => sum + file.lines, 0);
+ * const totalChars = Object.values(rendered.files)
+ *   .reduce((sum, file) => sum + file.characters, 0);
+ *
+ * console.log(`Generated ${Object.keys(rendered.artifacts).length} files`);
+ * console.log(`Total lines: ${totalLines}`);
+ * console.log(`Total characters: ${totalChars}`);
+ *
+ * // Check for large files
+ * const largeFiles = Object.entries(rendered.files)
+ *   .filter(([_, metadata]) => metadata.lines > 1000)
+ *   .map(([path, metadata]) => ({ path, lines: metadata.lines }));
+ *
+ * if (largeFiles.length > 0) {
+ *   console.log('Large files detected:', largeFiles);
+ * }
+ *
+ * // Access preview and mapping data
+ * console.log('Previews available:', Object.keys(rendered.previews));
+ * console.log('Mappings available:', Object.keys(rendered.mappings));
+ * ```
+ *
+ * @example Integration with CoreContext
+ * ```typescript
+ * // Typically used within CoreContext.toArtifacts()
+ * class CustomCoreContext extends CoreContext {
+ *   async renderWithPostProcessing(
+ *     files: Map<string, File | JsonFile>,
+ *     previews: Record<string, Record<string, Preview>>,
+ *     mappings: Record<string, Record<string, Mapping>>
+ *   ) {
+ *     const renderContext = new RenderContext({
+ *       files,
+ *       previews,
+ *       mappings,
+ *       prettierConfig: this.prettierConfig,
+ *       basePath: this.settings?.basePath,
+ *       stackTrail: this.stackTrail,
+ *       logger: this.logger,
+ *       captureCurrentResult: this.captureCurrentResult.bind(this)
+ *     });
+ *
+ *     const rendered = await renderContext.render();
+ *
+ *     // Post-process rendered files
+ *     const processedArtifacts: Record<string, string> = {};
+ *
+ *     for (const [path, content] of Object.entries(rendered.artifacts)) {
+ *       // Add file headers, license notices, etc.
+ *       const processedContent = this.addFileHeader(content, path);
+ *       processedArtifacts[path] = processedContent;
+ *     }
+ *
+ *     return {
+ *       ...rendered,
+ *       artifacts: processedArtifacts
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * @example Error handling during rendering
+ * ```typescript
+ * try {
+ *   const renderContext = new RenderContext({
+ *     files: generatedFiles,
+ *     previews: {},
+ *     mappings: {},
+ *     prettierConfig: prettierConfig,
+ *     basePath: './invalid-path', // This might cause issues
+ *     stackTrail: stack,
+ *     logger: logger,
+ *     captureCurrentResult: (result) => {
+ *       if (result === 'error') {
+ *         console.error('Render error detected');
+ *       }
+ *     }
+ *   });
+ *
+ *   const result = await renderContext.render();
+ *
+ *   // Check if any files failed to render
+ *   const failedFiles = Object.entries(result.files)
+ *     .filter(([path, metadata]) => metadata.lines === 0)
+ *     .map(([path]) => path);
+ *
+ *   if (failedFiles.length > 0) {
+ *     console.warn('Files with no content:', failedFiles);
+ *   }
+ *
+ * } catch (error) {
+ *   console.error('Render operation failed:', error);
+ *   // Sentry automatically captures the error
+ * }
+ * ```
+ */
 export declare class RenderContext {
     #private;
     files: Map<string, File | JsonFile>;

package/script/context/RenderContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RenderContext.d.ts","sourceRoot":"","sources":["../../src/context/RenderContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAEpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAGrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,KAAK,GAAG,MAAM,yCAAyC,CAAA;AACnE,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAA;AACrC,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAE3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAElD,KAAK,eAAe,GAAG;IACrB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,QAAQ,CAAC,CAAA;IACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACjD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACjD,cAAc,CAAC,EAAE,kBAAkB,CAAA;IACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,UAAU,EAAE,UAAU,CAAA;IACtB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAA;IAClB,oBAAoB,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAA;CACnD,CAAA;AAsBD,qBAAa,aAAa;;IACxB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,QAAQ,CAAC,CAAA;IACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACjD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAEjD,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,MAAM,EAAE,GAAG,CAAC,MAAM,CAAA;IAElB,oBAAoB,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAA;gBACtC,EACV,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,QAAQ,EACR,MAAM,EACN,UAAU,EACV,oBAAoB,EACrB,EAAE,eAAe;IAWZ,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;IAiBhD,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAuC3C,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAIlD,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,QAAQ;IAU1C,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS;CAO7D"}
+{"version":3,"file":"RenderContext.d.ts","sourceRoot":"","sources":["../../src/context/RenderContext.ts"],"names":[],"mappings":"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"}

package/script/context/RenderContext.js

@@ -56,6 +56,185 @@ const toResolvedArtifactPath_js_1 = require("../helpers/toResolvedArtifactPath.j
 const tracer_js_1 = require("../helpers/tracer.js");
 const File_js_1 = require("../dsl/File.js");
 const prettier = __importStar(require("prettier"));
+/**
+ * The rendering context for the final phase of the SKMTC transformation pipeline.
+ *
+ * `RenderContext` is responsible for taking the generated artifacts from the generation
+ * phase and rendering them into their final form with proper formatting, path resolution,
+ * and file preparation. It handles code formatting via Prettier, path normalization,
+ * and produces the final artifacts ready for writing to the filesystem.
+ *
+ * This context represents the culmination of the three-phase SKMTC pipeline, transforming
+ * generator outputs into production-ready code files with proper formatting and structure.
+ *
+ * ## Key Features
+ *
+ * - **Code Formatting**: Automatic Prettier formatting for generated TypeScript/JavaScript code
+ * - **Path Resolution**: Intelligent path resolution with base path support
+ * - **Content Collation**: Combines all generated content into organized file structures
+ * - **Metadata Generation**: Tracks file statistics (lines, characters) and relationships
+ * - **Error Tracking**: Comprehensive error handling with Sentry integration
+ * - **Performance Monitoring**: Built-in tracing and performance measurement
+ *
+ * @example Basic rendering usage
+ * ```typescript
+ * import { RenderContext } from '@skmtc/core';
+ *
+ * const renderContext = new RenderContext({
+ *   files: generatedFiles,
+ *   previews: previewData,
+ *   mappings: mappingData,
+ *   prettierConfig: {
+ *     semi: false,
+ *     singleQuote: true,
+ *     trailingComma: 'all'
+ *   },
+ *   basePath: './src/generated',
+ *   stackTrail: traceStack,
+ *   logger: myLogger,
+ *   captureCurrentResult: (result) => console.log(result)
+ * });
+ *
+ * const rendered = await renderContext.render();
+ *
+ * // Access rendered files
+ * Object.entries(rendered.artifacts).forEach(([path, content]) => {
+ *   console.log(`Rendered ${path}: ${rendered.files[path].lines} lines`);
+ *   // Write to filesystem
+ *   await Deno.writeTextFile(path, content);
+ * });
+ * ```
+ *
+ * @example With custom Prettier configuration
+ * ```typescript
+ * const renderContext = new RenderContext({
+ *   files: generatedFiles,
+ *   previews: {},
+ *   mappings: {},
+ *   prettierConfig: {
+ *     parser: 'typescript',
+ *     printWidth: 120,
+ *     tabWidth: 2,
+ *     semi: true,
+ *     singleQuote: true,
+ *     trailingComma: 'es5',
+ *     bracketSpacing: true,
+ *     arrowParens: 'avoid'
+ *   },
+ *   basePath: './packages/api-client/src',
+ *   stackTrail: stack,
+ *   logger: logger,
+ *   captureCurrentResult: resultHandler
+ * });
+ *
+ * const result = await renderContext.render();
+ *
+ * // All TypeScript files are automatically formatted
+ * console.log('Formatted files:', Object.keys(result.artifacts).length);
+ * ```
+ *
+ * @example Processing render results
+ * ```typescript
+ * const rendered = await renderContext.render();
+ *
+ * // Analyze file statistics
+ * const totalLines = Object.values(rendered.files)
+ *   .reduce((sum, file) => sum + file.lines, 0);
+ * const totalChars = Object.values(rendered.files)
+ *   .reduce((sum, file) => sum + file.characters, 0);
+ *
+ * console.log(`Generated ${Object.keys(rendered.artifacts).length} files`);
+ * console.log(`Total lines: ${totalLines}`);
+ * console.log(`Total characters: ${totalChars}`);
+ *
+ * // Check for large files
+ * const largeFiles = Object.entries(rendered.files)
+ *   .filter(([_, metadata]) => metadata.lines > 1000)
+ *   .map(([path, metadata]) => ({ path, lines: metadata.lines }));
+ *
+ * if (largeFiles.length > 0) {
+ *   console.log('Large files detected:', largeFiles);
+ * }
+ *
+ * // Access preview and mapping data
+ * console.log('Previews available:', Object.keys(rendered.previews));
+ * console.log('Mappings available:', Object.keys(rendered.mappings));
+ * ```
+ *
+ * @example Integration with CoreContext
+ * ```typescript
+ * // Typically used within CoreContext.toArtifacts()
+ * class CustomCoreContext extends CoreContext {
+ *   async renderWithPostProcessing(
+ *     files: Map<string, File | JsonFile>,
+ *     previews: Record<string, Record<string, Preview>>,
+ *     mappings: Record<string, Record<string, Mapping>>
+ *   ) {
+ *     const renderContext = new RenderContext({
+ *       files,
+ *       previews,
+ *       mappings,
+ *       prettierConfig: this.prettierConfig,
+ *       basePath: this.settings?.basePath,
+ *       stackTrail: this.stackTrail,
+ *       logger: this.logger,
+ *       captureCurrentResult: this.captureCurrentResult.bind(this)
+ *     });
+ *
+ *     const rendered = await renderContext.render();
+ *
+ *     // Post-process rendered files
+ *     const processedArtifacts: Record<string, string> = {};
+ *
+ *     for (const [path, content] of Object.entries(rendered.artifacts)) {
+ *       // Add file headers, license notices, etc.
+ *       const processedContent = this.addFileHeader(content, path);
+ *       processedArtifacts[path] = processedContent;
+ *     }
+ *
+ *     return {
+ *       ...rendered,
+ *       artifacts: processedArtifacts
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * @example Error handling during rendering
+ * ```typescript
+ * try {
+ *   const renderContext = new RenderContext({
+ *     files: generatedFiles,
+ *     previews: {},
+ *     mappings: {},
+ *     prettierConfig: prettierConfig,
+ *     basePath: './invalid-path', // This might cause issues
+ *     stackTrail: stack,
+ *     logger: logger,
+ *     captureCurrentResult: (result) => {
+ *       if (result === 'error') {
+ *         console.error('Render error detected');
+ *       }
+ *     }
+ *   });
+ *
+ *   const result = await renderContext.render();
+ *
+ *   // Check if any files failed to render
+ *   const failedFiles = Object.entries(result.files)
+ *     .filter(([path, metadata]) => metadata.lines === 0)
+ *     .map(([path]) => path);
+ *
+ *   if (failedFiles.length > 0) {
+ *     console.warn('Files with no content:', failedFiles);
+ *   }
+ *
+ * } catch (error) {
+ *   console.error('Render operation failed:', error);
+ *   // Sentry automatically captures the error
+ * }
+ * ```
+ */
 class RenderContext {
     constructor({ files, previews, mappings, prettierConfig, basePath, logger, stackTrail, captureCurrentResult }) {
         Object.defineProperty(this, "files", {

package/script/dsl/Inserted.d.ts

@@ -1,17 +1,257 @@
 import type { GeneratedDefinition, GeneratedValue, GenerationType } from '../types/GeneratedValue.js';
 import type { ContentSettings } from './ContentSettings.js';
 import type { Identifier } from './Identifier.js';
+/**
+ * Constructor arguments for {@link Inserted}.
+ *
+ * @template V - The type of generated value
+ * @template T - The generation type ('force' or 'lazy')
+ * @template EnrichmentType - Optional enrichment data type
+ */
 type ConstructorArgs<V extends GeneratedValue, T extends GenerationType, EnrichmentType> = {
+    /** Content settings including identifier and export path */
     settings: ContentSettings<EnrichmentType>;
+    /** The generated definition with its value */
     definition: GeneratedDefinition<V, T>;
 };
+/**
+ * Represents a successfully inserted generator artifact in the SKMTC DSL system.
+ *
+ * The `Inserted` class is returned when generators are inserted into the generation
+ * context, providing access to the generated content, metadata, and configuration.
+ * It acts as a bridge between the insertion process and the consuming code that
+ * needs to reference or use the generated artifacts.
+ *
+ * This class provides type-safe access to generated values with proper handling
+ * of both forced and lazy generation modes, ensuring the correct optionality
+ * of the generated content based on the generation strategy used.
+ *
+ * ## Key Features
+ *
+ * - **Type Safety**: Generic parameters preserve exact types from generators
+ * - **Generation Modes**: Handles both 'force' and 'lazy' generation strategies
+ * - **Metadata Access**: Provides access to identifiers, export paths, and settings
+ * - **Value Extraction**: Type-safe value extraction with proper optionality
+ * - **Enrichment Support**: Full support for custom enrichment data types
+ *
+ * @template V - The type of generated value (preserves generator output type)
+ * @template T - The generation type ('force' ensures non-null, 'lazy' allows undefined)
+ * @template EnrichmentType - Optional type for custom enrichment data
+ *
+ * @example Basic usage with forced generation
+ * ```typescript
+ * import { Inserted } from '@skmtc/core';
+ *
+ * class MyGenerator extends ModelBase {
+ *   generate(): Definition {
+ *     // Insert a related model with forced generation
+ *     const userModel = this.insertModel(
+ *       new UserModelGenerator({ ... }),
+ *       'User'
+ *     ); // Returns Inserted<UserModelValue, 'force', EnrichmentType>
+ *
+ *     // Access the generated value (guaranteed to be present)
+ *     const userTypeName = userModel.toValue(); // UserModelValue (not undefined)
+ *     const exportPath = userModel.toExportPath(); // './src/models.ts'
+ *     const identifier = userModel.toName(); // 'User'
+ *
+ *     return new Definition({
+ *       identifier: Identifier.createType(this.refName),
+ *       value: {
+ *         generatorKey: this.generatorKey,
+ *         content: `export interface Order { user: ${userTypeName}; }`
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Working with lazy generation
+ * ```typescript
+ * class ConditionalGenerator extends ModelBase {
+ *   generate(): Definition {
+ *     // Insert with lazy generation (may not generate if already exists)
+ *     const optionalModel = this.insertModel(
+ *       new OptionalModelGenerator({ ... }),
+ *       'OptionalModel',
+ *       { generation: 'lazy' }
+ *     ); // Returns Inserted<OptionalValue, 'lazy', EnrichmentType>
+ *
+ *     // Value might be undefined with lazy generation
+ *     const value = optionalModel.toValue(); // OptionalValue | undefined
+ *
+ *     if (value) {
+ *       // Use the generated value
+ *       return this.createDefinitionWith(value);
+ *     } else {
+ *       // Handle case where generation was skipped
+ *       return this.createFallbackDefinition();
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Accessing insertion metadata
+ * ```typescript
+ * class MetadataAwareGenerator extends OperationBase {
+ *   generate(): Definition {
+ *     const requestModel = this.insertModel(
+ *       new RequestModelGenerator({ ... }),
+ *       'CreateUserRequest'
+ *     );
+ *
+ *     // Access various metadata
+ *     const modelName = requestModel.toName(); // 'CreateUserRequest'
+ *     const identifier = requestModel.toIdentifier(); // Full Identifier object
+ *     const exportPath = requestModel.toExportPath(); // './src/api/types.ts'
+ *     const enrichments = requestModel.settings.enrichments; // Custom data
+ *
+ *     console.log(`Generated ${modelName} in ${exportPath}`);
+ *
+ *     return new Definition({
+ *       identifier: Identifier.createVariable(this.operation.operationId!),
+ *       value: {
+ *         generatorKey: this.generatorKey,
+ *         content: `async function createUser(data: ${modelName}) { ... }`
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example With enrichment data
+ * ```typescript
+ * type ValidationEnrichment = {
+ *   validators: string[];
+ *   required: boolean;
+ * };
+ *
+ * class EnrichedGenerator extends ModelBase<ValidationEnrichment> {
+ *   generate(): Definition {
+ *     const validatedModel = this.insertModel(
+ *       new ValidatedModelGenerator({ ... }),
+ *       'ValidatedUser'
+ *     ); // Returns Inserted<ModelValue, 'force', ValidationEnrichment>
+ *
+ *     // Access enrichment data
+ *     const enrichment = validatedModel.settings.enrichments;
+ *     const validators = enrichment?.validators ?? [];
+ *     const isRequired = enrichment?.required ?? false;
+ *
+ *     return new Definition({
+ *       identifier: Identifier.createType(this.refName),
+ *       value: {
+ *         generatorKey: this.generatorKey,
+ *         content: this.generateWithValidation(validatedModel.toValue(), validators)
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ */
 export declare class Inserted<V extends GeneratedValue, T extends GenerationType, EnrichmentType> {
+    /** Content settings including identifier and export path */
     settings: ContentSettings<EnrichmentType>;
+    /** The generated definition with its value */
     definition: GeneratedDefinition<V, T>;
+    /**
+     * Creates a new Inserted instance.
+     *
+     * @param args - Insertion configuration
+     * @param args.settings - Content settings with identifier and export path
+     * @param args.definition - The generated definition containing the value
+     */
     constructor({ settings, definition }: ConstructorArgs<V, T, EnrichmentType>);
+    /**
+     * Gets the name of the inserted artifact.
+     *
+     * This method returns the string name from the identifier, which is commonly
+     * used when referencing the generated artifact in code or templates.
+     *
+     * @returns The name of the inserted artifact
+     *
+     * @example
+     * ```typescript
+     * const userModel = this.insertModel(generator, 'User');
+     * const name = userModel.toName(); // 'User'
+     *
+     * // Use in generated code
+     * const code = `interface Order { user: ${name}; }`;
+     * ```
+     */
     toName(): string;
+    /**
+     * Gets the full identifier of the inserted artifact.
+     *
+     * This method returns the complete Identifier object, which includes both
+     * the name and type information. Useful when you need access to entity type
+     * or type annotations.
+     *
+     * @returns The complete Identifier object
+     *
+     * @example
+     * ```typescript
+     * const model = this.insertModel(generator, 'User');
+     * const identifier = model.toIdentifier();
+     *
+     * console.log(identifier.name);        // 'User'
+     * console.log(identifier.entityType);  // EntityType instance
+     * console.log(identifier.typeName);    // Optional type annotation
+     * ```
+     */
     toIdentifier(): Identifier;
+    /**
+     * Gets the export path where the artifact was generated.
+     *
+     * This method returns the file path where the generated artifact is located,
+     * which is useful for creating import statements or understanding the file
+     * structure of generated code.
+     *
+     * @returns The export path of the generated artifact
+     *
+     * @example
+     * ```typescript
+     * const userModel = this.insertModel(generator, 'User');
+     * const exportPath = userModel.toExportPath(); // './src/models/User.ts'
+     *
+     * // Create import statement
+     * const importStmt = `import { User } from '${exportPath}';`;
+     * ```
+     */
     toExportPath(): string;
+    /**
+     * Gets the generated value from the inserted artifact.
+     *
+     * This method returns the actual generated content with proper type safety
+     * based on the generation mode. For 'force' generation, the value is guaranteed
+     * to be present. For 'lazy' generation, the value might be undefined if
+     * generation was skipped.
+     *
+     * @returns The generated value, with optionality based on generation type
+     *
+     * @example Forced generation (guaranteed value)
+     * ```typescript
+     * const userModel = this.insertModel(generator, 'User'); // 'force' by default
+     * const value = userModel.toValue(); // UserModelValue (never undefined)
+     *
+     * // Safe to use directly
+     * const code = `type OrderUser = ${value};`;
+     * ```
+     *
+     * @example Lazy generation (optional value)
+     * ```typescript
+     * const optionalModel = this.insertModel(generator, 'Optional', { generation: 'lazy' });
+     * const value = optionalModel.toValue(); // OptionalValue | undefined
+     *
+     * if (value) {
+     *   // Use the generated value
+     *   const code = `type Optional = ${value};`;
+     * } else {
+     *   // Handle missing value (generation was skipped)
+     *   const code = 'type Optional = any; // Fallback';
+     * }
+     * ```
+     */
     toValue(): T extends 'force' ? V : V | undefined;
 }
 export {};

package/script/dsl/Inserted.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Inserted.d.ts","sourceRoot":"","sources":["../../src/dsl/Inserted.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACd,cAAc,EACf,MAAM,4BAA4B,CAAA;AACnC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,KAAK,eAAe,CAAC,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,cAAc,EAAE,cAAc,IAAI;IACzF,QAAQ,EAAE,eAAe,CAAC,cAAc,CAAC,CAAA;IACzC,UAAU,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;CACtC,CAAA;AAED,qBAAa,QAAQ,CAAC,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,cAAc,EAAE,cAAc;IACtF,QAAQ,EAAE,eAAe,CAAC,cAAc,CAAC,CAAA;IACzC,UAAU,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;gBACzB,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC;IAK3E,MAAM,IAAI,MAAM;IAIhB,YAAY,IAAI,UAAU;IAI1B,YAAY,IAAI,MAAM;IAItB,OAAO,IAAI,CAAC,SAAS,OAAO,GAAG,CAAC,GAAG,CAAC,GAAG,SAAS;CAGjD"}
+{"version":3,"file":"Inserted.d.ts","sourceRoot":"","sources":["../../src/dsl/Inserted.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACd,cAAc,EACf,MAAM,4BAA4B,CAAA;AACnC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD;;;;;;GAMG;AACH,KAAK,eAAe,CAAC,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,cAAc,EAAE,cAAc,IAAI;IACzF,4DAA4D;IAC5D,QAAQ,EAAE,eAAe,CAAC,cAAc,CAAC,CAAA;IACzC,8CAA8C;IAC9C,UAAU,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;CACtC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsIG;AACH,qBAAa,QAAQ,CAAC,CAAC,SAAS,cAAc,EAAE,CAAC,SAAS,cAAc,EAAE,cAAc;IACtF,4DAA4D;IAC5D,QAAQ,EAAE,eAAe,CAAC,cAAc,CAAC,CAAA;IAEzC,8CAA8C;IAC9C,UAAU,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAErC;;;;;;OAMG;gBACS,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC;IAK3E;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,IAAI,MAAM;IAIhB;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,IAAI,UAAU;IAI1B;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,OAAO,IAAI,CAAC,SAAS,OAAO,GAAG,CAAC,GAAG,CAAC,GAAG,SAAS;CAGjD"}