@jentic/arazzo-resolver 1.0.0-alpha.3 → 1.0.0-alpha.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jentic/arazzo-resolver",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.31",
   "description": "Resolver for Arazzo Documents.",
   "keywords": [
     "arazzo",
@@ -14,6 +14,7 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org",
+    "provenance": true,
     "tag": "latest"
   },
   "type": "module",
@@ -48,12 +49,18 @@
   "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"
+    "@jentic/arazzo-parser": "1.0.0-alpha.31",
+    "@speclynx/apidom-datamodel": "^4.10.0",
+    "@speclynx/apidom-error": "^4.10.0",
+    "@speclynx/apidom-ns-arazzo-1": "^4.10.0",
+    "@speclynx/apidom-ns-openapi-2": "^4.10.0",
+    "@speclynx/apidom-ns-openapi-3-0": "^4.10.0",
+    "@speclynx/apidom-ns-openapi-3-1": "^4.10.0",
+    "@speclynx/apidom-reference": "^4.10.0",
+    "type-fest": "^5.4.4"
+  },
+  "devDependencies": {
+    "@speclynx/apidom-core": "^4.10.0"
   },
   "files": [
     "src/**/*.mjs",
@@ -64,5 +71,6 @@
     "NOTICE",
     "README.md",
     "CHANGELOG.md"
-  ]
+  ],
+  "gitHead": "3e2d87af578cfe79c329894f3f28ee59f03c1606"
 }

package/src/{dereference.cjs → dereference/arazzo.cjs}

@@ -11,16 +11,12 @@ var _arazzo = _interopRequireDefault(require("@speclynx/apidom-reference/derefer
 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"));
+var _arazzoParser = require("@jentic/arazzo-parser");
+var _DereferenceError = _interopRequireDefault(require("../errors/DereferenceError.cjs"));
 /**
  * Options for dereferencing Arazzo Documents.
  * @public
@@ -32,67 +28,75 @@ var _DereferenceError = _interopRequireDefault(require("./errors/DereferenceErro
  */
 const defaultOptions = exports.defaultOptions = {
   resolve: {
-    resolvers: [new _file.default({
-      fileAllowList: ['*.json', '*.yaml', '*.yml']
-    }), new _httpAxios.default({
-      timeout: 5000,
-      redirects: 5,
-      withCredentials: false
-    })]
+    resolvers: [..._arazzoParser.defaultParseArazzoOptions.resolve.resolvers]
   },
   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
+    parsers: [..._arazzoParser.defaultParseArazzoOptions.parse.parsers, new _json.default({
+      allowEmpty: false
     }), new _yaml.default({
-      allowEmpty: false,
-      sourceMap: false
+      allowEmpty: false
     }), new _binary.default({
-      allowEmpty: false,
-      sourceMap: false
-    })]
+      allowEmpty: false
+    })],
+    parserOpts: {
+      ..._arazzoParser.defaultParseArazzoOptions.parse.parserOpts
+    }
   },
   dereference: {
     strategies: [new _arazzo.default(), new _openapi.default(), new _openapi2.default(), new _openapi3.default()],
-    strategyOpts: {}
+    strategyOpts: {
+      sourceDescriptions: false
+    }
   }
 };
 
 /**
  * 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.
+ * 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 for any reason. The original error is available via the `cause` property.
+ * @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 dereference('/path/to/arazzo.json');
+ * const result = await dereferenceArazzo('/path/to/arazzo.json');
  *
  * @example
  * // Dereference from URL
- * const result = await dereference('https://example.com/arazzo.yaml');
+ * 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 dereference('/path/to/arazzo.json', customReferenceOptions);
+ * const result = await dereferenceArazzo('/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);
+
+    // validate that the dereferenced document is an Arazzo specification
+    if (!(0, _apidomNsArazzo.isArazzoSpecification1Element)(parseResult.api)) {
+      throw new _empty.UnmatchedDereferenceStrategyError(`Could not find a dereference strategy that can dereference "${uri}" as an Arazzo specification`);
+    }
     parseResult.meta.set('retrievalURI', uri);
     return parseResult;
   } catch (error) {
@@ -115,6 +119,12 @@ async function dereference(uri, options = {}) {
  *   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
@@ -123,17 +133,17 @@ async function dereference(uri, options = {}) {
  * @example
  * Dereference ParseResultElement with retrievalURI (from file parsing)
  * ```typescript
- * import { parse } from '@jentic/arazzo-parser';
+ * import { parseArazzo } from '@jentic/arazzo-parser';
  *
- * const parseResult = await parse('/path/to/arazzo.json');
- * const dereferenced = await dereferenceElement(parseResult);
+ * 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 parse({ arazzo: '1.0.1', ... });
- * const dereferenced = await dereferenceElement(parseResult, {
+ * const parseResult = await parseArazzo({ arazzo: '1.0.1', ... });
+ * const dereferenced = await dereferenceArazzoElement(parseResult, {
  *   resolve: { baseURI: 'https://example.com/arazzo.json' },
  * });
  * ```
@@ -141,22 +151,35 @@ async function dereference(uri, options = {}) {
  * @example
  * Dereference child element (e.g., WorkflowElement)
  * ```typescript
- * const parseResult = await parse('/path/to/arazzo.json');
+ * const parseResult = await parseArazzo('/path/to/arazzo.json');
  * const workflow = parseResult.api.workflows.get(0);
- * const dereferenced = await dereferenceElement(workflow, {
+ * 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
  */
 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;
+  let mediaType = 'text/plain';
   if (refSet.size === 0) {
     if ((0, _apidomDatamodel.isParseResultElement)(element)) {
+      if ((0, _apidomNsArazzo.isArazzoSpecification1Element)(element.api)) {
+        mediaType = _apidomNsArazzo.mediaTypes.latest();
+      }
       if (element.hasMetaProperty('retrievalURI')) {
-        baseURI = (0, _apidomCore.toValue)(element.meta.get('retrievalURI'));
+        baseURI = element.meta.get('retrievalURI');
       } else if (!baseURI) {
         throw new _DereferenceError.default('baseURI option is required when dereferencing a ParseResultElement without retrievalURI metadata');
       }
@@ -166,8 +189,11 @@ async function dereferenceElement(element, options = {}) {
         parseResult
       } = mergedOptions.dereference.strategyOpts;
       let rootURI;
+      if ((0, _apidomNsArazzo.isArazzoSpecification1Element)(parseResult.api)) {
+        mediaType = _apidomNsArazzo.mediaTypes.latest();
+      }
       if (parseResult.hasMetaProperty('retrievalURI')) {
-        rootURI = (0, _apidomCore.toValue)(parseResult.meta.get('retrievalURI'));
+        rootURI = parseResult.meta.get('retrievalURI');
       } else if (baseURI) {
         rootURI = baseURI;
       } else {
@@ -190,6 +216,9 @@ async function dereferenceElement(element, options = {}) {
       resolve: {
         baseURI
       },
+      parse: {
+        mediaType
+      },
       dereference: {
         refSet
       }

package/src/{dereference.mjs → dereference/arazzo.mjs}

@@ -1,19 +1,15 @@
 import { isParseResultElement, ParseResultElement } from '@speclynx/apidom-datamodel';
-import { dereference as dereferenceURI, dereferenceApiDOM as dereferenceApiDOMElement, mergeOptions, ReferenceSet, Reference } from '@speclynx/apidom-reference/configuration/empty';
+import { dereference as dereferenceURI, dereferenceApiDOM as dereferenceApiDOMElement, mergeOptions, ReferenceSet, Reference, UnmatchedDereferenceStrategyError } 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 OpenAPI30DereferenceStrategy from '@speclynx/apidom-reference/dereference/strategies/openapi-3-0';
+import OpenAPI31DereferenceStrategy from '@speclynx/apidom-reference/dereference/strategies/openapi-3-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";
+import { isArazzoSpecification1Element, mediaTypes } from '@speclynx/apidom-ns-arazzo-1';
+import { defaultParseArazzoOptions as parserDefaultOptions } from '@jentic/arazzo-parser';
+import DereferenceError from "../errors/DereferenceError.mjs";
 /**
  * Options for dereferencing Arazzo Documents.
  * @public
@@ -24,67 +20,75 @@ import DereferenceError from "./errors/DereferenceError.mjs";
  */
 export const defaultOptions = {
   resolve: {
-    resolvers: [new FileResolver({
-      fileAllowList: ['*.json', '*.yaml', '*.yml']
-    }), new HTTPResolverAxios({
-      timeout: 5000,
-      redirects: 5,
-      withCredentials: false
-    })]
+    resolvers: [...parserDefaultOptions.resolve.resolvers]
   },
   parse: {
-    mediaType: mediaTypes.latest(),
-    parsers: [new ArazzoJSON1Parser({
-      allowEmpty: false,
-      sourceMap: false
-    }), new ArazzoYAML1Parser({
-      allowEmpty: false,
-      sourceMap: false
-    }), new JSONParser({
-      allowEmpty: false,
-      sourceMap: false
+    parsers: [...parserDefaultOptions.parse.parsers, new JSONParser({
+      allowEmpty: false
     }), new YAMLParser({
-      allowEmpty: false,
-      sourceMap: false
+      allowEmpty: false
     }), new BinaryParser({
-      allowEmpty: false,
-      sourceMap: false
-    })]
+      allowEmpty: false
+    })],
+    parserOpts: {
+      ...parserDefaultOptions.parse.parserOpts
+    }
   },
   dereference: {
-    strategies: [new Arazzo1DereferenceStrategy(), new OpenAPI2DereferenceStrategy(), new OpenAPI3_0DereferenceStrategy(), new OpenAPI3_1DereferenceStrategy()],
-    strategyOpts: {}
+    strategies: [new Arazzo1DereferenceStrategy(), new OpenAPI2DereferenceStrategy(), new OpenAPI30DereferenceStrategy(), new OpenAPI31DereferenceStrategy()],
+    strategyOpts: {
+      sourceDescriptions: false
+    }
   }
 };
 
 /**
  * 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.
+ * 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 for any reason. The original error is available via the `cause` property.
+ * @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 dereference('/path/to/arazzo.json');
+ * const result = await dereferenceArazzo('/path/to/arazzo.json');
  *
  * @example
  * // Dereference from URL
- * const result = await dereference('https://example.com/arazzo.yaml');
+ * 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 dereference('/path/to/arazzo.json', customReferenceOptions);
+ * const result = await dereferenceArazzo('/path/to/arazzo.json', customReferenceOptions);
  * @public
  */
 export async function dereference(uri, options = {}) {
   const mergedOptions = mergeOptions(defaultOptions, options);
   try {
     const parseResult = await dereferenceURI(uri, mergedOptions);
+
+    // validate that the dereferenced document is an Arazzo specification
+    if (!isArazzoSpecification1Element(parseResult.api)) {
+      throw new UnmatchedDereferenceStrategyError(`Could not find a dereference strategy that can dereference "${uri}" as an Arazzo specification`);
+    }
     parseResult.meta.set('retrievalURI', uri);
     return parseResult;
   } catch (error) {
@@ -107,6 +111,12 @@ export async function dereference(uri, options = {}) {
  *   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
@@ -115,17 +125,17 @@ export async function dereference(uri, options = {}) {
  * @example
  * Dereference ParseResultElement with retrievalURI (from file parsing)
  * ```typescript
- * import { parse } from '@jentic/arazzo-parser';
+ * import { parseArazzo } from '@jentic/arazzo-parser';
  *
- * const parseResult = await parse('/path/to/arazzo.json');
- * const dereferenced = await dereferenceElement(parseResult);
+ * 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 parse({ arazzo: '1.0.1', ... });
- * const dereferenced = await dereferenceElement(parseResult, {
+ * const parseResult = await parseArazzo({ arazzo: '1.0.1', ... });
+ * const dereferenced = await dereferenceArazzoElement(parseResult, {
  *   resolve: { baseURI: 'https://example.com/arazzo.json' },
  * });
  * ```
@@ -133,22 +143,35 @@ export async function dereference(uri, options = {}) {
  * @example
  * Dereference child element (e.g., WorkflowElement)
  * ```typescript
- * const parseResult = await parse('/path/to/arazzo.json');
+ * const parseResult = await parseArazzo('/path/to/arazzo.json');
  * const workflow = parseResult.api.workflows.get(0);
- * const dereferenced = await dereferenceElement(workflow, {
+ * 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 async function dereferenceElement(element, options = {}) {
   const mergedOptions = mergeOptions(defaultOptions, options);
   const refSet = mergedOptions.dereference?.refSet ?? new ReferenceSet();
   let baseURI = mergedOptions.resolve?.baseURI;
+  let mediaType = 'text/plain';
   if (refSet.size === 0) {
     if (isParseResultElement(element)) {
+      if (isArazzoSpecification1Element(element.api)) {
+        mediaType = mediaTypes.latest();
+      }
       if (element.hasMetaProperty('retrievalURI')) {
-        baseURI = toValue(element.meta.get('retrievalURI'));
+        baseURI = element.meta.get('retrievalURI');
       } else if (!baseURI) {
         throw new DereferenceError('baseURI option is required when dereferencing a ParseResultElement without retrievalURI metadata');
       }
@@ -158,8 +181,11 @@ export async function dereferenceElement(element, options = {}) {
         parseResult
       } = mergedOptions.dereference.strategyOpts;
       let rootURI;
+      if (isArazzoSpecification1Element(parseResult.api)) {
+        mediaType = mediaTypes.latest();
+      }
       if (parseResult.hasMetaProperty('retrievalURI')) {
-        rootURI = toValue(parseResult.meta.get('retrievalURI'));
+        rootURI = parseResult.meta.get('retrievalURI');
       } else if (baseURI) {
         rootURI = baseURI;
       } else {
@@ -182,6 +208,9 @@ export async function dereferenceElement(element, options = {}) {
       resolve: {
         baseURI
       },
+      parse: {
+        mediaType
+      },
       dereference: {
         refSet
       }