@skmtc/core 0.0.788 → 0.0.789

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"}

package/script/dsl/Inserted.js

@@ -1,14 +1,158 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Inserted = void 0;
+/**
+ * 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)
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ */
 class Inserted {
+    /**
+     * 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 }) {
+        /** Content settings including identifier and export path */
         Object.defineProperty(this, "settings", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The generated definition with its value */
         Object.defineProperty(this, "definition", {
             enumerable: true,
             configurable: true,
@@ -18,15 +162,102 @@ class Inserted {
         this.settings = settings;
         this.definition = definition;
     }
+    /**
+     * 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() {
         return this.settings.identifier.name;
     }
+    /**
+     * 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() {
         return this.settings.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() {
         return this.settings.exportPath;
     }
+    /**
+     * 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() {
         return this.definition?.value;
     }

package/script/helpers/refFns.d.ts

@@ -2,11 +2,171 @@ import "../_dnt.polyfills.js";
 import type { RefName } from '../types/RefName.js';
 import type { OpenAPIV3 } from 'openapi-types';
 import type { ReferenceObject } from '../oas/_merge-all-of/types.js';
+/**
+ * Extracts a reference name from an OpenAPI $ref string.
+ *
+ * This function parses JSON Pointer references (like '#/components/schemas/User')
+ * and extracts the final component as a branded RefName type. It's used throughout
+ * the SKMTC system to convert string references into type-safe reference names.
+ *
+ * @param $ref - The OpenAPI reference string (e.g., '#/components/schemas/User')
+ * @returns The extracted reference name as a branded RefName type
+ *
+ * @throws {Error} When the reference string is invalid or empty
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { toRefName } from '@skmtc/core/helpers';
+ *
+ * const refName = toRefName('#/components/schemas/User');
+ * console.log(refName); // 'User' (typed as RefName)
+ *
+ * const responseRef = toRefName('#/components/responses/ErrorResponse');
+ * console.log(responseRef); // 'ErrorResponse' (typed as RefName)
+ * ```
+ *
+ * @example Error cases
+ * ```typescript
+ * // These will throw errors:
+ * toRefName('invalid/ref/'); // Error: 'Invalid reference'
+ * toRefName('#/components/schemas/'); // Error: 'Invalid reference'
+ * ```
+ *
+ * @example Integration with OAS processing
+ * ```typescript
+ * class SchemaProcessor {
+ *   processReference(ref: string) {
+ *     const refName = toRefName(ref);
+ *     const schema = this.document.components.schemas[refName];
+ *     return this.processSchema(schema, refName);
+ *   }
+ * }
+ * ```
+ */
 export declare const toRefName: ($ref: string) => RefName;
+/**
+ * Type representing an object with a $ref property.
+ */
 type Ref = {
+    /** The OpenAPI reference string */
     $ref: string;
 };
+/**
+ * Type guard function to check if a value is an OpenAPI reference object.
+ *
+ * This function performs runtime type checking to determine if an unknown value
+ * is an OpenAPI Reference Object (contains a $ref property with a string value).
+ * It's essential for safely handling mixed schema/reference data during processing.
+ *
+ * @param value - The value to check for reference properties
+ * @returns True if the value is a reference object, false otherwise
+ *
+ * @example Basic type checking
+ * ```typescript
+ * import { isRef } from '@skmtc/core/helpers';
+ *
+ * const schemaOrRef: unknown = { $ref: '#/components/schemas/User' };
+ *
+ * if (isRef(schemaOrRef)) {
+ *   // TypeScript now knows schemaOrRef has a $ref property
+ *   console.log(schemaOrRef.$ref); // Safe to access
+ *   const refName = toRefName(schemaOrRef.$ref);
+ * } else {
+ *   // Handle as actual schema object
+ *   console.log('Direct schema object');
+ * }
+ * ```
+ *
+ * @example Processing mixed data
+ * ```typescript
+ * function processSchemaOrRef(data: unknown) {
+ *   if (isRef(data)) {
+ *     // Handle reference
+ *     return resolveReference(data.$ref);
+ *   } else {
+ *     // Handle direct schema
+ *     return processSchema(data as SchemaObject);
+ *   }
+ * }
+ * ```
+ *
+ * @example Array processing
+ * ```typescript
+ * const mixedArray: unknown[] = [
+ *   { type: 'string' },
+ *   { $ref: '#/components/schemas/User' },
+ *   { type: 'number' }
+ * ];
+ *
+ * const references = mixedArray.filter(isRef);
+ * const schemas = mixedArray.filter(item => !isRef(item));
+ * ```
+ */
 export declare const isRef: (value: unknown) => value is Ref;
+/**
+ * Creates a reference resolver function for an OpenAPI document.
+ *
+ * This higher-order function returns a resolver that can dereference OpenAPI
+ * JSON Pointer references within the context of a specific document. It handles
+ * nested references by recursively resolving reference chains until it reaches
+ * an actual schema object.
+ *
+ * The resolver is particularly useful during schema processing where you need
+ * to follow reference chains to get the actual schema definitions.
+ *
+ * @param oasDocument - The OpenAPI document containing the schemas to resolve against
+ * @returns A function that resolves reference objects to schema objects
+ *
+ * @throws {Error} When a reference cannot be resolved or points to a non-existent schema
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { toGetRef } from '@skmtc/core/helpers';
+ *
+ * const resolver = toGetRef(openApiDocument);
+ *
+ * const userSchema = resolver({ $ref: '#/components/schemas/User' });
+ * console.log(userSchema.type); // 'object'
+ * console.log(userSchema.properties); // User properties
+ * ```
+ *
+ * @example Resolving nested references
+ * ```typescript
+ * // If User references Address, and Address references Country
+ * const resolver = toGetRef(document);
+ *
+ * // This will follow the chain: User -> Address -> Country
+ * const resolvedSchema = resolver({ $ref: '#/components/schemas/User' });
+ * // Returns the final resolved schema object
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * const resolver = toGetRef(document);
+ *
+ * try {
+ *   const schema = resolver({ $ref: '#/components/schemas/NonExistent' });
+ * } catch (error) {
+ *   console.error('Reference resolution failed:', error.message);
+ *   // Error: Invalid reference: #/components/schemas/NonExistent
+ * }
+ * ```
+ *
+ * @example Integration with schema processing
+ * ```typescript
+ * class SchemaProcessor {
+ *   private resolver = toGetRef(this.document);
+ *
+ *   processProperty(property: SchemaObject | ReferenceObject) {
+ *     if (isRef(property)) {
+ *       const resolved = this.resolver(property);
+ *       return this.processSchema(resolved);
+ *     }
+ *     return this.processSchema(property);
+ *   }
+ * }
+ * ```
+ */
 export declare const toGetRef: (oasDocument: OpenAPIV3.Document) => ({ $ref }: ReferenceObject) => OpenAPIV3.SchemaObject;
 export {};
 //# sourceMappingURL=refFns.d.ts.map