@usearazzo/resolver 1.0.1-alpha.10

package/types/resolver.d.ts

@@ -0,0 +1,529 @@
+import { ApiDOMError } from '@speclynx/apidom-error';
+import { ApiDOMErrorOptions } from '@speclynx/apidom-error';
+import type { ApiDOMReferenceOptions } from '@speclynx/apidom-reference/configuration/empty';
+import { Element as Element_2 } from '@speclynx/apidom-datamodel';
+import { ParseResultElement } from '@speclynx/apidom-datamodel';
+import type { PartialDeep } from 'type-fest';
+import { ReferenceSet } from '@speclynx/apidom-reference/configuration/empty';
+
+/**
+ * Bundles an Arazzo Document from a file system path or HTTP(S) URL.
+ *
+ * This function embeds every external JSON Schema resource reached through
+ * JSON References ($ref) into the Components Object of the Arazzo Document,
+ * producing a single compound document.
+ *
+ * @param uri - A file system path or HTTP(S) URL to the Arazzo Document
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the bundled Arazzo Document as ApiDOM element
+ * @throws BundleError - When bundling fails or document is not an Arazzo specification. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Bundle from file
+ * const result = await bundleArazzo('/path/to/arazzo.json');
+ *
+ * @example
+ * // Bundle from URL
+ * const result = await bundleArazzo('https://example.com/arazzo.yaml');
+ *
+ * @example
+ * // Bundle with custom options
+ * const result = await bundleArazzo('/path/to/arazzo.json', customReferenceOptions);
+ * @public
+ */
+export declare function bundleArazzo(uri: string, options?: BundleArazzoOptions): Promise<ParseResultElement>;
+
+/**
+ * Options for bundling Arazzo Documents.
+ * @public
+ */
+export declare type BundleArazzoOptions = PartialDeep<ApiDOMReferenceOptions>;
+
+/**
+ * Error thrown when bundling an Arazzo or OpenAPI document fails.
+ * @public
+ */
+export declare class BundleError extends ApiDOMError {
+    constructor(message?: string, options?: ApiDOMErrorOptions);
+}
+
+/**
+ * Bundles an OpenAPI Document from a file system path or HTTP(S) URL.
+ *
+ * This function hoists every external document reached through JSON References ($ref)
+ * into the components of the OpenAPI Document, producing a single compound document.
+ *
+ * Supports OpenAPI 2.0 (Swagger), OpenAPI 3.0.x, and OpenAPI 3.1.x.
+ *
+ * @param uri - A file system path or HTTP(S) URL to the OpenAPI Document
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the bundled OpenAPI Document as ApiDOM element
+ * @throws BundleError - When bundling fails or document is not an OpenAPI specification. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Bundle from file
+ * const result = await bundleOpenAPI('/path/to/openapi.json');
+ *
+ * @example
+ * // Bundle from URL
+ * const result = await bundleOpenAPI('https://example.com/openapi.yaml');
+ *
+ * @example
+ * // Bundle with custom options
+ * const result = await bundleOpenAPI('/path/to/openapi.json', customReferenceOptions);
+ * @public
+ */
+export declare function bundleOpenAPI(uri: string, options?: BundleOpenAPIOptions): Promise<ParseResultElement>;
+
+/**
+ * Options for bundling OpenAPI Documents.
+ * @public
+ */
+export declare type BundleOpenAPIOptions = PartialDeep<ApiDOMReferenceOptions>;
+
+/**
+ * Default reference options for bundling Arazzo Documents.
+ *
+ * Bundling reads only the bundle strategies plus the resolvers and parsers that fetch
+ * external documents, so no resolve or dereference strategies are configured.
+ * @public
+ */
+export declare const defaultBundleArazzoOptions: BundleArazzoOptions;
+
+/**
+ * Default reference options for bundling OpenAPI Documents.
+ *
+ * Bundling reads only the bundle strategies plus the resolvers and parsers that fetch
+ * external documents, so no resolve or dereference strategies are configured.
+ * @public
+ */
+export declare const defaultBundleOpenAPIOptions: BundleOpenAPIOptions;
+
+/**
+ * Default reference options for dereferencing Arazzo Documents.
+ * @public
+ */
+export declare const defaultDereferenceArazzoOptions: DereferenceArazzoOptions;
+
+/**
+ * Default reference options for dereferencing OpenAPI Documents.
+ * @public
+ */
+export declare const defaultDereferenceOpenAPIOptions: DereferenceOpenAPIOptions;
+
+/**
+ * Default reference options for resolving Arazzo Documents.
+ *
+ * The resolve strategies delegate to the dereference strategies of the same name,
+ * so the dereference defaults are carried over and only the resolve strategies are added.
+ * @public
+ */
+export declare const defaultResolveArazzoOptions: ResolveArazzoOptions;
+
+/**
+ * Default reference options for resolving OpenAPI Documents.
+ *
+ * The resolve strategies delegate to the dereference strategies of the same name,
+ * so the dereference defaults are carried over and only the resolve strategies are added.
+ * @public
+ */
+export declare const defaultResolveOpenAPIOptions: ResolveOpenAPIOptions;
+
+/**
+ * Dereferences an Arazzo Document from a file system path or HTTP(S) URL.
+ *
+ * This function resolves all JSON References ($ref) and Reusable Object references
+ * ($components.*) in the Arazzo Document.
+ *
+ * Source descriptions can optionally be dereferenced using strategy options:
+ * - `sourceDescriptions`: `true` (all) or `['name1', 'name2']` (specific names only)
+ * - `sourceDescriptionsMaxDepth`: Maximum recursion depth for nested Arazzo source descriptions (default: `+Infinity`)
+ *
+ * Options can be passed globally via `strategyOpts` or strategy-specific via `strategyOpts['arazzo-1']`.
+ *
+ * @param uri - A file system path or HTTP(S) URL to the Arazzo Document
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the dereferenced Arazzo Document as ApiDOM element
+ * @throws DereferenceError - When dereferencing fails or document is not an Arazzo specification. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Dereference from file
+ * const result = await dereferenceArazzo('/path/to/arazzo.json');
+ *
+ * @example
+ * // Dereference from URL
+ * const result = await dereferenceArazzo('https://example.com/arazzo.yaml');
+ *
+ * @example
+ * Dereference with source descriptions
+ * ```typescript
+ * const result = await dereferenceArazzo('/path/to/arazzo.json', {
+ *   dereference: { strategyOpts: { sourceDescriptions: true } },
+ * });
+ * ```
+ *
+ * @example
+ * // Dereference with custom options
+ * const result = await dereferenceArazzo('/path/to/arazzo.json', customReferenceOptions);
+ * @public
+ */
+export declare function dereferenceArazzo(uri: string, options?: DereferenceArazzoOptions): Promise<ParseResultElement>;
+
+/**
+ * Dereferences an ApiDOM element representing an Arazzo Document.
+ *
+ * This function resolves all JSON References ($ref) and Reusable Object references
+ * ($components.*) in the Arazzo Document element.
+ *
+ * Supported scenarios:
+ * - ParseResultElement with retrievalURI metadata: baseURI derived automatically
+ * - ParseResultElement without retrievalURI: requires `options.resolve.baseURI`
+ * - Child element (e.g., WorkflowElement) with parseResult in strategyOpts:
+ *   requires `options.dereference.strategyOpts.parseResult` for component resolution,
+ *   and `options.resolve.baseURI` if parseResult lacks retrievalURI metadata
+ *
+ * Source descriptions can optionally be dereferenced using strategy options:
+ * - `sourceDescriptions`: `true` (all) or `['name1', 'name2']` (specific names only)
+ * - `sourceDescriptionsMaxDepth`: Maximum recursion depth for nested Arazzo source descriptions (default: `+Infinity`)
+ *
+ * Options can be passed globally via `strategyOpts` or strategy-specific via `strategyOpts['arazzo-1']`.
+ *
+ * @param element - An ApiDOM element (ParseResultElement or child element like WorkflowElement)
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the dereferenced element
+ * @throws DereferenceError - When baseURI is required but not provided, or when dereferencing fails
+ *
+ * @example
+ * Dereference ParseResultElement with retrievalURI (from file parsing)
+ * ```typescript
+ * import { parseArazzo } from '@usearazzo/parser';
+ *
+ * const parseResult = await parseArazzo('/path/to/arazzo.json');
+ * const dereferenced = await dereferenceArazzoElement(parseResult);
+ * ```
+ *
+ * @example
+ * Dereference ParseResultElement without retrievalURI (from inline parsing)
+ * ```typescript
+ * const parseResult = await parseArazzo({ arazzo: '1.0.1', ... });
+ * const dereferenced = await dereferenceArazzoElement(parseResult, {
+ *   resolve: { baseURI: 'https://example.com/arazzo.json' },
+ * });
+ * ```
+ *
+ * @example
+ * Dereference child element (e.g., WorkflowElement)
+ * ```typescript
+ * const parseResult = await parseArazzo('/path/to/arazzo.json');
+ * const workflow = parseResult.api.workflows.get(0);
+ * const dereferenced = await dereferenceArazzoElement(workflow, {
+ *   dereference: { strategyOpts: { parseResult } },
+ * });
+ * ```
+ *
+ * @example
+ * Dereference with source descriptions
+ * ```typescript
+ * const parseResult = await parseArazzo('/path/to/arazzo.json');
+ * const dereferenced = await dereferenceArazzoElement(parseResult, {
+ *   dereference: { strategyOpts: { sourceDescriptions: true } },
+ * });
+ * ```
+ * @public
+ */
+export declare function dereferenceArazzoElement<T extends Element_2>(element: T, options?: DereferenceArazzoOptions): Promise<T>;
+
+/**
+ * Options for dereferencing Arazzo Documents.
+ * @public
+ */
+export declare type DereferenceArazzoOptions = PartialDeep<ApiDOMReferenceOptions>;
+
+/**
+ * Error thrown when dereferencing an Arazzo document or element fails.
+ * @public
+ */
+export declare class DereferenceError extends ApiDOMError {
+    constructor(message?: string, options?: ApiDOMErrorOptions);
+}
+
+/**
+ * Dereferences an OpenAPI Document from a file system path or HTTP(S) URL.
+ *
+ * This function resolves all JSON References ($ref) in the OpenAPI Document.
+ *
+ * Supports OpenAPI 2.0 (Swagger), OpenAPI 3.0.x, and OpenAPI 3.1.x.
+ *
+ * @param uri - A file system path or HTTP(S) URL to the OpenAPI Document
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the dereferenced OpenAPI Document as ApiDOM element
+ * @throws DereferenceError - When dereferencing fails or document is not an OpenAPI specification. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Dereference from file
+ * const result = await dereferenceOpenAPI('/path/to/openapi.json');
+ *
+ * @example
+ * // Dereference from URL
+ * const result = await dereferenceOpenAPI('https://example.com/openapi.yaml');
+ *
+ * @example
+ * // Dereference with custom options
+ * const result = await dereferenceOpenAPI('/path/to/openapi.json', customReferenceOptions);
+ * @public
+ */
+export declare function dereferenceOpenAPI(uri: string, options?: DereferenceOpenAPIOptions): Promise<ParseResultElement>;
+
+/**
+ * Dereferences an ApiDOM element representing an OpenAPI Document.
+ *
+ * This function resolves all JSON References ($ref) in the OpenAPI Document element.
+ *
+ * Supported scenarios:
+ * - ParseResultElement with retrievalURI metadata: baseURI derived automatically
+ * - ParseResultElement without retrievalURI: requires `options.resolve.baseURI`
+ * - Child element (e.g., PathItemElement) with parseResult in strategyOpts:
+ *   requires `options.dereference.strategyOpts.parseResult` for component resolution,
+ *   and `options.resolve.baseURI` if parseResult lacks retrievalURI metadata
+ *
+ * @param element - An ApiDOM element (ParseResultElement or child element like PathItemElement)
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the dereferenced element
+ * @throws DereferenceError - When baseURI is required but not provided, or when dereferencing fails
+ *
+ * @example
+ * Dereference ParseResultElement with retrievalURI (from file parsing)
+ * ```typescript
+ * import { parseOpenAPI } from '@usearazzo/parser';
+ *
+ * const parseResult = await parseOpenAPI('/path/to/openapi.json');
+ * const dereferenced = await dereferenceOpenAPIElement(parseResult);
+ * ```
+ *
+ * @example
+ * Dereference ParseResultElement without retrievalURI (from inline parsing)
+ * ```typescript
+ * const parseResult = await parseOpenAPI({ openapi: '3.1.0', ... });
+ * const dereferenced = await dereferenceOpenAPIElement(parseResult, {
+ *   resolve: { baseURI: 'https://example.com/openapi.json' },
+ * });
+ * ```
+ *
+ * @example
+ * Dereference child element (e.g., PathItemElement)
+ * ```typescript
+ * const parseResult = await parseOpenAPI('/path/to/openapi.json');
+ * const pathItem = parseResult.api.paths.get('/users');
+ * const dereferenced = await dereferenceOpenAPIElement(pathItem, {
+ *   dereference: { strategyOpts: { parseResult } },
+ * });
+ * ```
+ * @public
+ */
+export declare function dereferenceOpenAPIElement<T extends Element_2>(element: T, options?: DereferenceOpenAPIOptions): Promise<T>;
+
+/**
+ * Options for dereferencing OpenAPI Documents.
+ * @public
+ */
+export declare type DereferenceOpenAPIOptions = PartialDeep<ApiDOMReferenceOptions>;
+
+export { ReferenceSet }
+
+/**
+ * Resolves an Arazzo Document from a file system path or HTTP(S) URL.
+ *
+ * This function collects the Arazzo Document and every external document its
+ * JSON References ($ref) reach into a ReferenceSet. Nothing is dereferenced;
+ * the root reference of the set holds the parsed entry document.
+ *
+ * The `dereference.refSet` option is ignored: resolving always builds a fresh ReferenceSet.
+ *
+ * @param uri - A file system path or HTTP(S) URL to the Arazzo Document
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the ReferenceSet of the Arazzo Document and its external references
+ * @throws ResolveError - When resolving fails or document is not an Arazzo specification. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Resolve from file
+ * const refSet = await resolveArazzo('/path/to/arazzo.json');
+ *
+ * @example
+ * // Resolve from URL
+ * const refSet = await resolveArazzo('https://example.com/arazzo.yaml');
+ *
+ * @example
+ * // Resolve with custom options
+ * const refSet = await resolveArazzo('/path/to/arazzo.json', customReferenceOptions);
+ * @public
+ */
+export declare function resolveArazzo(uri: string, options?: ResolveArazzoOptions): Promise<ReferenceSet>;
+
+/**
+ * Resolves an ApiDOM element representing an Arazzo Document.
+ *
+ * This function collects the element and every external document its
+ * JSON References ($ref) reach into a ReferenceSet. Nothing is dereferenced
+ * and the element itself is left untouched.
+ *
+ * Supported scenarios:
+ * - ParseResultElement with retrievalURI metadata: baseURI derived automatically
+ * - ParseResultElement without retrievalURI: requires `options.resolve.baseURI`
+ * - Child element (e.g., WorkflowElement) with parseResult in strategyOpts:
+ *   requires `options.dereference.strategyOpts.parseResult`,
+ *   and `options.resolve.baseURI` if parseResult lacks retrievalURI metadata
+ * - Child element without parseResult: requires `options.resolve.baseURI` and
+ *   `options.parse.mediaType`, since the element alone cannot identify the document kind
+ *
+ * For a child element the root reference of the returned set is keyed by the root document
+ * URI but holds a ParseResultElement wrapping a copy of the child, not the root document.
+ * The set describes the references reachable from the child and is not a whole-document set.
+ *
+ * The `dereference.refSet` option is ignored: resolving always builds a fresh ReferenceSet.
+ *
+ * @param element - An ApiDOM element (ParseResultElement or child element like WorkflowElement)
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the ReferenceSet of the element and its external references
+ * @throws ResolveError - When baseURI is required but not provided, when the document is not an Arazzo specification, or when resolving fails
+ *
+ * @example
+ * Resolve ParseResultElement with retrievalURI (from file parsing)
+ * ```typescript
+ * import { parseArazzo } from '@usearazzo/parser';
+ *
+ * const parseResult = await parseArazzo('/path/to/arazzo.json');
+ * const refSet = await resolveArazzoElement(parseResult);
+ * ```
+ *
+ * @example
+ * Resolve ParseResultElement without retrievalURI (from inline parsing)
+ * ```typescript
+ * const parseResult = await parseArazzo({ arazzo: '1.0.1', ... });
+ * const refSet = await resolveArazzoElement(parseResult, {
+ *   resolve: { baseURI: 'https://example.com/arazzo.json' },
+ * });
+ * ```
+ *
+ * @example
+ * Resolve child element (e.g., WorkflowElement)
+ * ```typescript
+ * const parseResult = await parseArazzo('/path/to/arazzo.json');
+ * const workflow = parseResult.api.workflows.get(0);
+ * const refSet = await resolveArazzoElement(workflow, {
+ *   dereference: { strategyOpts: { parseResult } },
+ * });
+ * ```
+ * @public
+ */
+export declare function resolveArazzoElement<T extends Element_2>(element: T, options?: ResolveArazzoOptions): Promise<ReferenceSet>;
+
+/**
+ * Options for resolving Arazzo Documents.
+ * @public
+ */
+export declare type ResolveArazzoOptions = PartialDeep<ApiDOMReferenceOptions>;
+
+/**
+ * Error thrown when resolving an Arazzo or OpenAPI document or element fails.
+ * @public
+ */
+export declare class ResolveError extends ApiDOMError {
+    constructor(message?: string, options?: ApiDOMErrorOptions);
+}
+
+/**
+ * Resolves an OpenAPI Document from a file system path or HTTP(S) URL.
+ *
+ * This function collects the OpenAPI Document and every external document its
+ * JSON References ($ref) reach into a ReferenceSet. Nothing is dereferenced;
+ * the root reference of the set holds the parsed entry document.
+ *
+ * Supports OpenAPI 2.0 (Swagger), OpenAPI 3.0.x, and OpenAPI 3.1.x.
+ *
+ * The `dereference.refSet` option is ignored: resolving always builds a fresh ReferenceSet.
+ *
+ * @param uri - A file system path or HTTP(S) URL to the OpenAPI Document
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the ReferenceSet of the OpenAPI Document and its external references
+ * @throws ResolveError - When resolving fails or document is not an OpenAPI specification. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Resolve from file
+ * const refSet = await resolveOpenAPI('/path/to/openapi.json');
+ *
+ * @example
+ * // Resolve from URL
+ * const refSet = await resolveOpenAPI('https://example.com/openapi.yaml');
+ *
+ * @example
+ * // Resolve with custom options
+ * const refSet = await resolveOpenAPI('/path/to/openapi.json', customReferenceOptions);
+ * @public
+ */
+export declare function resolveOpenAPI(uri: string, options?: ResolveOpenAPIOptions): Promise<ReferenceSet>;
+
+/**
+ * Resolves an ApiDOM element representing an OpenAPI Document.
+ *
+ * This function collects the element and every external document its
+ * JSON References ($ref) reach into a ReferenceSet. Nothing is dereferenced
+ * and the element itself is left untouched.
+ *
+ * Supported scenarios:
+ * - ParseResultElement with retrievalURI metadata: baseURI derived automatically
+ * - ParseResultElement without retrievalURI: requires `options.resolve.baseURI`
+ * - Child element (e.g., PathItemElement) with parseResult in strategyOpts:
+ *   requires `options.dereference.strategyOpts.parseResult`,
+ *   and `options.resolve.baseURI` if parseResult lacks retrievalURI metadata
+ * - Child element without parseResult: requires `options.resolve.baseURI` and
+ *   `options.parse.mediaType`, since the element alone cannot identify the document kind
+ *
+ * For a child element the root reference of the returned set is keyed by the root document
+ * URI but holds a ParseResultElement wrapping a copy of the child, not the root document.
+ * The set describes the references reachable from the child and is not a whole-document set.
+ *
+ * The `dereference.refSet` option is ignored: resolving always builds a fresh ReferenceSet.
+ *
+ * @param element - An ApiDOM element (ParseResultElement or child element like PathItemElement)
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the ReferenceSet of the element and its external references
+ * @throws ResolveError - When baseURI is required but not provided, when the document is not an OpenAPI specification, or when resolving fails
+ *
+ * @example
+ * Resolve ParseResultElement with retrievalURI (from file parsing)
+ * ```typescript
+ * import { parseOpenAPI } from '@usearazzo/parser';
+ *
+ * const parseResult = await parseOpenAPI('/path/to/openapi.json');
+ * const refSet = await resolveOpenAPIElement(parseResult);
+ * ```
+ *
+ * @example
+ * Resolve ParseResultElement without retrievalURI (from inline parsing)
+ * ```typescript
+ * const parseResult = await parseOpenAPI({ openapi: '3.1.0', ... });
+ * const refSet = await resolveOpenAPIElement(parseResult, {
+ *   resolve: { baseURI: 'https://example.com/openapi.json' },
+ * });
+ * ```
+ *
+ * @example
+ * Resolve child element (e.g., PathItemElement)
+ * ```typescript
+ * const parseResult = await parseOpenAPI('/path/to/openapi.json');
+ * const pathItem = parseResult.api.paths.get('/users');
+ * const refSet = await resolveOpenAPIElement(pathItem, {
+ *   dereference: { strategyOpts: { parseResult } },
+ * });
+ * ```
+ * @public
+ */
+export declare function resolveOpenAPIElement<T extends Element_2>(element: T, options?: ResolveOpenAPIOptions): Promise<ReferenceSet>;
+
+/**
+ * Options for resolving OpenAPI Documents.
+ * @public
+ */
+export declare type ResolveOpenAPIOptions = PartialDeep<ApiDOMReferenceOptions>;
+
+export { }