@jentic/arazzo-resolver 1.0.0-alpha.3

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@jentic/arazzo-resolver",
+  "version": "1.0.0-alpha.3",
+  "description": "Resolver for Arazzo Documents.",
+  "keywords": [
+    "arazzo",
+    "arazzo-specification",
+    "resolver",
+    "resolve",
+    "dereference",
+    "workflow",
+    "workflows"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "tag": "latest"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "unpkg": "./dist/jentic-arazzo-resolver.browser.min.js",
+  "main": "./src/index.cjs",
+  "exports": {
+    "types": "./types/arazzo-resolver.d.ts",
+    "import": "./src/index.mjs",
+    "require": "./src/index.cjs"
+  },
+  "types": "./types/arazzo-resolver.d.ts",
+  "scripts": {
+    "build": "npm run clean && run-p --max-parallel ${CPU_CORES:-2} typescript:declaration build:es build:cjs build:umd:browser",
+    "build:es": "cross-env BABEL_ENV=es babel src --out-dir src --extensions '.ts' --out-file-extension '.mjs' --root-mode 'upward'",
+    "build:cjs": "cross-env BABEL_ENV=cjs babel src --out-dir src --extensions '.ts' --out-file-extension '.cjs' --root-mode 'upward'",
+    "build:umd:browser": "cross-env BABEL_ENV=browser webpack --config config/webpack/browser.config.js --progress",
+    "lint": "eslint ./",
+    "lint:fix": "eslint ./ --fix",
+    "clean": "rimraf --glob 'src/**/*.mjs' 'src/**/*.cjs' 'test/**/*.mjs' ./dist ./types",
+    "typescript:check-types": "tsc --noEmit",
+    "typescript:declaration": "tsc -p tsconfig.declaration.json && api-extractor run -l -c ./config/api-extractor/api-extractor.json",
+    "test": "npm run build:es && cross-env BABEL_ENV=es babel test --out-dir test --extensions '.ts' --out-file-extension '.mjs' --root-mode 'upward' && cross-env NODE_ENV=test mocha",
+    "prepack": "copyfiles -u 2 ../../LICENSE . && copyfiles -u 2 ../../NOTICE .",
+    "postpack": "rimraf NOTICE LICENSE"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jentic/jentic-arazzo-tools.git"
+  },
+  "author": "Jentic <hello@jentic.com>",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@babel/runtime-corejs3": "^7.28.4",
+    "@speclynx/apidom-core": "2.5.1",
+    "@speclynx/apidom-datamodel": "2.5.1",
+    "@speclynx/apidom-error": "2.5.1",
+    "@speclynx/apidom-ns-arazzo-1": "2.5.1",
+    "@speclynx/apidom-reference": "2.5.1",
+    "type-fest": "^5.4.3"
+  },
+  "files": [
+    "src/**/*.mjs",
+    "src/**/*.cjs",
+    "dist/",
+    "types/arazzo-resolver.d.ts",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "CHANGELOG.md"
+  ]
+}

package/src/dereference.cjs

@@ -0,0 +1,202 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.defaultOptions = void 0;
+exports.dereference = dereference;
+exports.dereferenceElement = dereferenceElement;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _empty = require("@speclynx/apidom-reference/configuration/empty");
+var _arazzo = _interopRequireDefault(require("@speclynx/apidom-reference/dereference/strategies/arazzo-1"));
+var _openapi = _interopRequireDefault(require("@speclynx/apidom-reference/dereference/strategies/openapi-2"));
+var _openapi2 = _interopRequireDefault(require("@speclynx/apidom-reference/dereference/strategies/openapi-3-0"));
+var _openapi3 = _interopRequireDefault(require("@speclynx/apidom-reference/dereference/strategies/openapi-3-1"));
+var _arazzoJson = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/arazzo-json-1"));
+var _arazzoYaml = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/arazzo-yaml-1"));
+var _json = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/json"));
+var _yaml = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/yaml-1-2"));
+var _binary = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/binary"));
+var _file = _interopRequireDefault(require("@speclynx/apidom-reference/resolve/resolvers/file"));
+var _httpAxios = _interopRequireDefault(require("@speclynx/apidom-reference/resolve/resolvers/http-axios"));
+var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+var _apidomCore = require("@speclynx/apidom-core");
+var _DereferenceError = _interopRequireDefault(require("./errors/DereferenceError.cjs"));
+/**
+ * Options for dereferencing Arazzo Documents.
+ * @public
+ */
+
+/**
+ * Default reference options for dereferencing Arazzo Documents.
+ * @public
+ */
+const defaultOptions = exports.defaultOptions = {
+  resolve: {
+    resolvers: [new _file.default({
+      fileAllowList: ['*.json', '*.yaml', '*.yml']
+    }), new _httpAxios.default({
+      timeout: 5000,
+      redirects: 5,
+      withCredentials: false
+    })]
+  },
+  parse: {
+    mediaType: _apidomNsArazzo.mediaTypes.latest(),
+    parsers: [new _arazzoJson.default({
+      allowEmpty: false,
+      sourceMap: false
+    }), new _arazzoYaml.default({
+      allowEmpty: false,
+      sourceMap: false
+    }), new _json.default({
+      allowEmpty: false,
+      sourceMap: false
+    }), new _yaml.default({
+      allowEmpty: false,
+      sourceMap: false
+    }), new _binary.default({
+      allowEmpty: false,
+      sourceMap: false
+    })]
+  },
+  dereference: {
+    strategies: [new _arazzo.default(), new _openapi.default(), new _openapi2.default(), new _openapi3.default()],
+    strategyOpts: {}
+  }
+};
+
+/**
+ * Dereferences an Arazzo Document from a file system path or HTTP(S) URL.
+ *
+ * This function resolves all JSON References ($ref) in the Arazzo Document
+ * and its referenced OpenAPI/AsyncAPI source descriptions.
+ *
+ * @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 for any reason. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Dereference from file
+ * const result = await dereference('/path/to/arazzo.json');
+ *
+ * @example
+ * // Dereference from URL
+ * const result = await dereference('https://example.com/arazzo.yaml');
+ *
+ * @example
+ * // Dereference with custom options
+ * const result = await dereference('/path/to/arazzo.json', customReferenceOptions);
+ * @public
+ */
+async function dereference(uri, options = {}) {
+  const mergedOptions = (0, _empty.mergeOptions)(defaultOptions, options);
+  try {
+    const parseResult = await (0, _empty.dereference)(uri, mergedOptions);
+    parseResult.meta.set('retrievalURI', uri);
+    return parseResult;
+  } catch (error) {
+    throw new _DereferenceError.default(`Failed to dereference Arazzo Document at "${uri}"`, {
+      cause: error
+    });
+  }
+}
+
+/**
+ * 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
+ *
+ * @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 { parse } from '@jentic/arazzo-parser';
+ *
+ * const parseResult = await parse('/path/to/arazzo.json');
+ * const dereferenced = await dereferenceElement(parseResult);
+ * ```
+ *
+ * @example
+ * Dereference ParseResultElement without retrievalURI (from inline parsing)
+ * ```typescript
+ * const parseResult = await parse({ arazzo: '1.0.1', ... });
+ * const dereferenced = await dereferenceElement(parseResult, {
+ *   resolve: { baseURI: 'https://example.com/arazzo.json' },
+ * });
+ * ```
+ *
+ * @example
+ * Dereference child element (e.g., WorkflowElement)
+ * ```typescript
+ * const parseResult = await parse('/path/to/arazzo.json');
+ * const workflow = parseResult.api.workflows.get(0);
+ * const dereferenced = await dereferenceElement(workflow, {
+ *   dereference: { strategyOpts: { parseResult } },
+ * });
+ * ```
+ * @public
+ */
+async function dereferenceElement(element, options = {}) {
+  const mergedOptions = (0, _empty.mergeOptions)(defaultOptions, options);
+  const refSet = mergedOptions.dereference?.refSet ?? new _empty.ReferenceSet();
+  let baseURI = mergedOptions.resolve?.baseURI;
+  if (refSet.size === 0) {
+    if ((0, _apidomDatamodel.isParseResultElement)(element)) {
+      if (element.hasMetaProperty('retrievalURI')) {
+        baseURI = (0, _apidomCore.toValue)(element.meta.get('retrievalURI'));
+      } else if (!baseURI) {
+        throw new _DereferenceError.default('baseURI option is required when dereferencing a ParseResultElement without retrievalURI metadata');
+      }
+    } else if ((0, _apidomDatamodel.isParseResultElement)(mergedOptions.dereference?.strategyOpts?.parseResult)) {
+      // dereferencing child element requires refSet for component resolution
+      const {
+        parseResult
+      } = mergedOptions.dereference.strategyOpts;
+      let rootURI;
+      if (parseResult.hasMetaProperty('retrievalURI')) {
+        rootURI = (0, _apidomCore.toValue)(parseResult.meta.get('retrievalURI'));
+      } else if (baseURI) {
+        rootURI = baseURI;
+      } else {
+        throw new _DereferenceError.default('baseURI option is required when dereferencing a child element without retrievalURI metadata');
+      }
+      const elementReference = new _empty.Reference({
+        uri: `${rootURI}#fragment`,
+        value: new _apidomDatamodel.ParseResultElement([element])
+      });
+      const rootReference = new _empty.Reference({
+        uri: rootURI,
+        value: parseResult
+      });
+      refSet.add(elementReference).add(rootReference);
+      baseURI = rootURI;
+    }
+  }
+  try {
+    return await (0, _empty.dereferenceApiDOM)(element, (0, _empty.mergeOptions)(mergedOptions, {
+      resolve: {
+        baseURI
+      },
+      dereference: {
+        refSet
+      }
+    }));
+  } catch (error) {
+    throw new _DereferenceError.default('Failed to dereference Arazzo Document', {
+      cause: error
+    });
+  }
+}

package/src/dereference.mjs

@@ -0,0 +1,194 @@
+import { isParseResultElement, ParseResultElement } from '@speclynx/apidom-datamodel';
+import { dereference as dereferenceURI, dereferenceApiDOM as dereferenceApiDOMElement, mergeOptions, ReferenceSet, Reference } from '@speclynx/apidom-reference/configuration/empty';
+import Arazzo1DereferenceStrategy from '@speclynx/apidom-reference/dereference/strategies/arazzo-1';
+import OpenAPI2DereferenceStrategy from '@speclynx/apidom-reference/dereference/strategies/openapi-2';
+import OpenAPI3_0DereferenceStrategy from '@speclynx/apidom-reference/dereference/strategies/openapi-3-0';
+import OpenAPI3_1DereferenceStrategy from '@speclynx/apidom-reference/dereference/strategies/openapi-3-1';
+import ArazzoJSON1Parser from '@speclynx/apidom-reference/parse/parsers/arazzo-json-1';
+import ArazzoYAML1Parser from '@speclynx/apidom-reference/parse/parsers/arazzo-yaml-1';
+import JSONParser from '@speclynx/apidom-reference/parse/parsers/json';
+import YAMLParser from '@speclynx/apidom-reference/parse/parsers/yaml-1-2';
+import BinaryParser from '@speclynx/apidom-reference/parse/parsers/binary';
+import FileResolver from '@speclynx/apidom-reference/resolve/resolvers/file';
+import HTTPResolverAxios from '@speclynx/apidom-reference/resolve/resolvers/http-axios';
+import { mediaTypes } from '@speclynx/apidom-ns-arazzo-1';
+import { toValue } from '@speclynx/apidom-core';
+import DereferenceError from "./errors/DereferenceError.mjs";
+/**
+ * Options for dereferencing Arazzo Documents.
+ * @public
+ */
+/**
+ * Default reference options for dereferencing Arazzo Documents.
+ * @public
+ */
+export const defaultOptions = {
+  resolve: {
+    resolvers: [new FileResolver({
+      fileAllowList: ['*.json', '*.yaml', '*.yml']
+    }), new HTTPResolverAxios({
+      timeout: 5000,
+      redirects: 5,
+      withCredentials: false
+    })]
+  },
+  parse: {
+    mediaType: mediaTypes.latest(),
+    parsers: [new ArazzoJSON1Parser({
+      allowEmpty: false,
+      sourceMap: false
+    }), new ArazzoYAML1Parser({
+      allowEmpty: false,
+      sourceMap: false
+    }), new JSONParser({
+      allowEmpty: false,
+      sourceMap: false
+    }), new YAMLParser({
+      allowEmpty: false,
+      sourceMap: false
+    }), new BinaryParser({
+      allowEmpty: false,
+      sourceMap: false
+    })]
+  },
+  dereference: {
+    strategies: [new Arazzo1DereferenceStrategy(), new OpenAPI2DereferenceStrategy(), new OpenAPI3_0DereferenceStrategy(), new OpenAPI3_1DereferenceStrategy()],
+    strategyOpts: {}
+  }
+};
+
+/**
+ * Dereferences an Arazzo Document from a file system path or HTTP(S) URL.
+ *
+ * This function resolves all JSON References ($ref) in the Arazzo Document
+ * and its referenced OpenAPI/AsyncAPI source descriptions.
+ *
+ * @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 for any reason. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Dereference from file
+ * const result = await dereference('/path/to/arazzo.json');
+ *
+ * @example
+ * // Dereference from URL
+ * const result = await dereference('https://example.com/arazzo.yaml');
+ *
+ * @example
+ * // Dereference with custom options
+ * const result = await dereference('/path/to/arazzo.json', customReferenceOptions);
+ * @public
+ */
+export async function dereference(uri, options = {}) {
+  const mergedOptions = mergeOptions(defaultOptions, options);
+  try {
+    const parseResult = await dereferenceURI(uri, mergedOptions);
+    parseResult.meta.set('retrievalURI', uri);
+    return parseResult;
+  } catch (error) {
+    throw new DereferenceError(`Failed to dereference Arazzo Document at "${uri}"`, {
+      cause: error
+    });
+  }
+}
+
+/**
+ * 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
+ *
+ * @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 { parse } from '@jentic/arazzo-parser';
+ *
+ * const parseResult = await parse('/path/to/arazzo.json');
+ * const dereferenced = await dereferenceElement(parseResult);
+ * ```
+ *
+ * @example
+ * Dereference ParseResultElement without retrievalURI (from inline parsing)
+ * ```typescript
+ * const parseResult = await parse({ arazzo: '1.0.1', ... });
+ * const dereferenced = await dereferenceElement(parseResult, {
+ *   resolve: { baseURI: 'https://example.com/arazzo.json' },
+ * });
+ * ```
+ *
+ * @example
+ * Dereference child element (e.g., WorkflowElement)
+ * ```typescript
+ * const parseResult = await parse('/path/to/arazzo.json');
+ * const workflow = parseResult.api.workflows.get(0);
+ * const dereferenced = await dereferenceElement(workflow, {
+ *   dereference: { strategyOpts: { parseResult } },
+ * });
+ * ```
+ * @public
+ */
+export async function dereferenceElement(element, options = {}) {
+  const mergedOptions = mergeOptions(defaultOptions, options);
+  const refSet = mergedOptions.dereference?.refSet ?? new ReferenceSet();
+  let baseURI = mergedOptions.resolve?.baseURI;
+  if (refSet.size === 0) {
+    if (isParseResultElement(element)) {
+      if (element.hasMetaProperty('retrievalURI')) {
+        baseURI = toValue(element.meta.get('retrievalURI'));
+      } else if (!baseURI) {
+        throw new DereferenceError('baseURI option is required when dereferencing a ParseResultElement without retrievalURI metadata');
+      }
+    } else if (isParseResultElement(mergedOptions.dereference?.strategyOpts?.parseResult)) {
+      // dereferencing child element requires refSet for component resolution
+      const {
+        parseResult
+      } = mergedOptions.dereference.strategyOpts;
+      let rootURI;
+      if (parseResult.hasMetaProperty('retrievalURI')) {
+        rootURI = toValue(parseResult.meta.get('retrievalURI'));
+      } else if (baseURI) {
+        rootURI = baseURI;
+      } else {
+        throw new DereferenceError('baseURI option is required when dereferencing a child element without retrievalURI metadata');
+      }
+      const elementReference = new Reference({
+        uri: `${rootURI}#fragment`,
+        value: new ParseResultElement([element])
+      });
+      const rootReference = new Reference({
+        uri: rootURI,
+        value: parseResult
+      });
+      refSet.add(elementReference).add(rootReference);
+      baseURI = rootURI;
+    }
+  }
+  try {
+    return await dereferenceApiDOMElement(element, mergeOptions(mergedOptions, {
+      resolve: {
+        baseURI
+      },
+      dereference: {
+        refSet
+      }
+    }));
+  } catch (error) {
+    throw new DereferenceError('Failed to dereference Arazzo Document', {
+      cause: error
+    });
+  }
+}

package/src/errors/DereferenceError.cjs

@@ -0,0 +1,15 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomError = require("@speclynx/apidom-error");
+/**
+ * Error thrown when dereferencing an Arazzo document or element fails.
+ * @public
+ */
+class DereferenceError extends _apidomError.ApiDOMError {
+  constructor(message, options) {
+    super(message, options);
+  }
+}
+var _default = exports.default = DereferenceError;

package/src/errors/DereferenceError.mjs

@@ -0,0 +1,12 @@
+import { ApiDOMError } from '@speclynx/apidom-error';
+
+/**
+ * Error thrown when dereferencing an Arazzo document or element fails.
+ * @public
+ */
+class DereferenceError extends ApiDOMError {
+  constructor(message, options) {
+    super(message, options);
+  }
+}
+export default DereferenceError;

package/src/index.cjs

@@ -0,0 +1,14 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.dereferenceElement = exports.dereferenceArazzoElement = exports.dereferenceArazzo = exports.dereference = exports.defaultDereferenceOptions = exports.defaultDereferenceArazzoOptions = exports.DereferenceError = void 0;
+var _dereference = require("./dereference.cjs");
+exports.defaultDereferenceOptions = _dereference.defaultOptions;
+exports.defaultDereferenceArazzoOptions = _dereference.defaultOptions;
+exports.dereference = _dereference.dereference;
+exports.dereferenceElement = _dereference.dereferenceElement;
+exports.dereferenceArazzo = _dereference.dereference;
+exports.dereferenceArazzoElement = _dereference.dereferenceElement;
+var _DereferenceError = _interopRequireDefault(require("./errors/DereferenceError.cjs"));
+exports.DereferenceError = _DereferenceError.default;

package/src/index.mjs

@@ -0,0 +1,2 @@
+export { defaultOptions as defaultDereferenceOptions, defaultOptions as defaultDereferenceArazzoOptions, dereference, dereferenceElement, dereference as dereferenceArazzo, dereferenceElement as dereferenceArazzoElement } from "./dereference.mjs";
+export { default as DereferenceError } from "./errors/DereferenceError.mjs";

package/types/arazzo-resolver.d.ts

@@ -0,0 +1,109 @@
+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';
+
+/**
+ * Default reference options for dereferencing Arazzo Documents.
+ * @public
+ */
+declare const defaultOptions: DereferenceOptions;
+export { defaultOptions as defaultDereferenceArazzoOptions }
+export { defaultOptions as defaultDereferenceOptions }
+
+/**
+ * Dereferences an Arazzo Document from a file system path or HTTP(S) URL.
+ *
+ * This function resolves all JSON References ($ref) in the Arazzo Document
+ * and its referenced OpenAPI/AsyncAPI source descriptions.
+ *
+ * @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 for any reason. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Dereference from file
+ * const result = await dereference('/path/to/arazzo.json');
+ *
+ * @example
+ * // Dereference from URL
+ * const result = await dereference('https://example.com/arazzo.yaml');
+ *
+ * @example
+ * // Dereference with custom options
+ * const result = await dereference('/path/to/arazzo.json', customReferenceOptions);
+ * @public
+ */
+declare function dereference(uri: string, options?: DereferenceOptions): Promise<ParseResultElement>;
+export { dereference }
+export { dereference as dereferenceArazzo }
+
+/**
+ * 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
+ *
+ * @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 { parse } from '@jentic/arazzo-parser';
+ *
+ * const parseResult = await parse('/path/to/arazzo.json');
+ * const dereferenced = await dereferenceElement(parseResult);
+ * ```
+ *
+ * @example
+ * Dereference ParseResultElement without retrievalURI (from inline parsing)
+ * ```typescript
+ * const parseResult = await parse({ arazzo: '1.0.1', ... });
+ * const dereferenced = await dereferenceElement(parseResult, {
+ *   resolve: { baseURI: 'https://example.com/arazzo.json' },
+ * });
+ * ```
+ *
+ * @example
+ * Dereference child element (e.g., WorkflowElement)
+ * ```typescript
+ * const parseResult = await parse('/path/to/arazzo.json');
+ * const workflow = parseResult.api.workflows.get(0);
+ * const dereferenced = await dereferenceElement(workflow, {
+ *   dereference: { strategyOpts: { parseResult } },
+ * });
+ * ```
+ * @public
+ */
+declare function dereferenceElement<T extends Element_2>(element: T, options?: DereferenceOptions): Promise<T>;
+export { dereferenceElement as dereferenceArazzoElement }
+export { dereferenceElement }
+
+/**
+ * Error thrown when dereferencing an Arazzo document or element fails.
+ * @public
+ */
+export declare class DereferenceError extends ApiDOMError {
+    constructor(message?: string, options?: ApiDOMErrorOptions);
+}
+
+/**
+ * Options for dereferencing Arazzo Documents.
+ * @public
+ */
+export declare type DereferenceOptions = PartialDeep<ApiDOMReferenceOptions>;
+
+export { }