import type { OasRefData } from './ref-types.js';
import type { OasSchema, ToJsonSchemaOptions } from '../schema/Schema.js';
import type { OasResponse } from '../response/Response.js';
import type { OasParameter } from '../parameter/Parameter.js';
import type { OasExample } from '../example/Example.js';
import type { OasRequestBody } from '../requestBody/RequestBody.js';
import type { OasHeader } from '../header/Header.js';
import type { OasDocument } from '../document/Document.js';
import type { RefName } from '../../types/RefName.js';
import type { OpenAPIV3 } from 'openapi-types';
import type { OasSecurityScheme } from '../securitySchemes/SecurityScheme.js';
/**
 * Field data for creating OAS reference objects.
 *
 * @template T - The type of component being referenced (e.g., 'schema', 'response')
 */
export type RefFields<T extends OasRefData['refType']> = {
    refType: T;
    $ref: string;
};
/**
 * Represents an OpenAPI reference ($ref) in the SKMTC OAS processing system.
 *
 * The `OasRef` class handles OpenAPI JSON Reference Objects that point to reusable
 * components within the same document. It provides type-safe reference resolution
 * with support for chained references and circular reference detection.
 *
 * ## Key Features
 *
 * - **Type Safety**: Generic parameter ensures resolved types match the reference type
 * - **Lazy Resolution**: References are resolved on-demand, not during construction
 * - **Chain Resolution**: Handles references that point to other references
 * - **Circular Detection**: Prevents infinite loops with maximum lookup limits
 * - **Type Validation**: Ensures resolved objects match expected reference types
 *
 * @template T - The type of component this reference points to
 *
 * @example Basic reference resolution
 * ```typescript
 * import { OasRef } from '@skmtc/core';
 *
 * // Reference to a schema component
 * const userRef = new OasRef<'schema'>({
 *   refType: 'schema',
 *   $ref: '#/components/schemas/User'
 * }, document);
 *
 * // Resolve the reference
 * const userSchema = userRef.resolve();
 * console.log(userSchema.properties); // Access resolved schema properties
 * ```
 *
 * @example Working with different reference types
 * ```typescript
 * // Schema reference
 * const schemaRef = new OasRef<'schema'>({
 *   refType: 'schema',
 *   $ref: '#/components/schemas/Product'
 * }, document);
 *
 * // Response reference
 * const responseRef = new OasRef<'response'>({
 *   refType: 'response',
 *   $ref: '#/components/responses/ErrorResponse'
 * }, document);
 *
 * // Parameter reference
 * const paramRef = new OasRef<'parameter'>({
 *   refType: 'parameter',
 *   $ref: '#/components/parameters/PageSize'
 * }, document);
 * ```
 *
 * @example Reference checking and conditional resolution
 * ```typescript
 * function processSchemaOrRef(schema: OasSchema | OasRef<'schema'>) {
 *   if (schema.isRef()) {
 *     // Handle reference
 *     const refName = schema.toRefName();
 *     console.log(`Processing reference: ${refName}`);
 *
 *     // Resolve only when needed
 *     const resolved = schema.resolve();
 *     return processed(resolved);
 *   } else {
 *     // Handle direct schema
 *     return process(schema);
 *   }
 * }
 * ```
 *
 * @example Chained reference handling
 * ```typescript
 * // References can point to other references
 * const chainedRef = new OasRef<'schema'>({
 *   refType: 'schema',
 *   $ref: '#/components/schemas/AliasToUser'
 * }, document);
 *
 * // resolve() automatically follows the chain
 * const finalSchema = chainedRef.resolve(); // Follows chain to final schema
 *
 * // resolveOnce() resolves only one step
 * const oneStep = chainedRef.resolveOnce(); // May still be a reference
 * ```
 */
export declare class OasRef<T extends OasRefData['refType']> {
    #private;
    /** OAS type identifier */
    oasType: 'ref';
    /** Type identifier */
    type: 'ref';
    /**
     * Creates a new OAS reference instance.
     *
     * @param fields - Reference field data including refType and $ref
     * @param oasDocument - Document containing the referenced component
     */
    constructor(fields: RefFields<T>, oasDocument: OasDocument);
    /**
     * Type guard to check if this instance is a reference.
     *
     * @returns Always true for OasRef instances
     */
    isRef(): this is OasRef<T>;
    /**
     * Recursively resolves this reference to its final target component.
     *
     * Follows reference chains until reaching a non-reference component,
     * with protection against infinite loops.
     *
     * @param lookupsPerformed - Internal counter to prevent infinite recursion
     * @returns The resolved component
     * @throws Error if maximum lookup depth is exceeded
     */
    resolve(lookupsPerformed?: number): ResolvedRef<T>;
    /**
     * Resolves this reference one level, potentially returning another reference.
     *
     * @returns Either the resolved component or another reference in the chain
     */
    resolveOnce(): OasRef<T> | ResolvedRef<T>;
    toRefName(): RefName;
    get $ref(): string;
    get refType(): OasRefData['refType'];
    get oasDocument(): OasDocument;
    toJsonSchema({ resolve }: ToJsonSchemaOptions): OpenAPIV3.ReferenceObject | ResolvedRefJsonType<T>;
    toJSON(): object;
}
/**
 * Type representing the JSON schema result from resolving a reference.
 *
 * @template T - The type of component being referenced
 */
export type ResolvedRefJsonType<T extends OasRefData['refType']> = ReturnType<ResolvedRef<T>['toJsonSchema']>;
/**
 * Union type of all OAS component types that can be referenced.
 *
 * Includes all OpenAPI component types that support $ref resolution.
 */
export type OasComponentType = OasSchema | OasResponse | OasParameter | OasExample | OasRequestBody | OasHeader | OasSecurityScheme;
/**
 * Type representing a resolved reference to a specific component type.
 *
 * @template T - The type of component being referenced (e.g., 'schema', 'response')
 */
export type ResolvedRef<T extends OasRefData['refType']> = Extract<OasComponentType, {
    oasType: T;
}>;
//# sourceMappingURL=Ref.d.ts.map