@speclynx/apidom-reference 2.3.0 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Advanced algorithms for semantic ApiDOM manipulations like dereferencing or resolution.",
   "publishConfig": {
     "access": "public",
@@ -171,6 +171,11 @@
       "require": "./src/dereference/strategies/asyncapi-2/index.cjs",
       "types": "./types/dereference/strategies/asyncapi-2/index.d.ts"
     },
+    "./dereference/strategies/arazzo-1": {
+      "import": "./src/dereference/strategies/arazzo-1/index.mjs",
+      "require": "./src/dereference/strategies/arazzo-1/index.cjs",
+      "types": "./types/dereference/strategies/arazzo-1/index.d.ts"
+    },
     "./dereference/strategies/openapi-2": {
       "import": "./src/dereference/strategies/openapi-2/index.mjs",
       "require": "./src/dereference/strategies/openapi-2/index.cjs",
@@ -213,7 +218,7 @@
     "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",
     "perf": "cross-env BABEL_ENV=es babel ./test/perf/index.ts --out-file ./test/perf/index.mjs --root-mode 'upward' && cross-env NODE_ENV=test node ./test/perf/index.mjs",
     "perf:openapi-3-1-dereference": "cross-env BABEL_ENV=es babel ./test/perf/openapi-3-1-dereference.ts --out-file ./test/perf/openapi-3-1-dereference.mjs --root-mode 'upward' && cross-env NODE_ENV=test node ./test/perf/openapi-3-1-dereference.mjs",
-    "typescript:check-types": "tsc --noEmit && tsc -p ./test/tsconfig.json --noEmit",
+    "typescript:check-types": "tsc --noEmit",
     "typescript:declaration": "tsc -p tsconfig.declaration.json && api-extractor run -l -c ./config/api-extractor/api-extractor.json",
     "prepack": "copyfiles -u 3 ../../LICENSES/* LICENSES && copyfiles -u 2 ../../NOTICE .",
     "postpack": "rimraf NOTICE LICENSES"
@@ -226,28 +231,30 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-core": "^2.3.0",
-    "@speclynx/apidom-datamodel": "^2.3.0",
-    "@speclynx/apidom-error": "^2.3.0",
-    "@speclynx/apidom-json-pointer": "^2.3.0",
-    "@speclynx/apidom-ns-arazzo-1": "^2.3.0",
-    "@speclynx/apidom-ns-asyncapi-2": "^2.3.0",
-    "@speclynx/apidom-ns-openapi-2": "^2.3.0",
-    "@speclynx/apidom-ns-openapi-3-0": "^2.3.0",
-    "@speclynx/apidom-ns-openapi-3-1": "^2.3.0",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "^2.3.0",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "^2.3.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "^2.3.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "^2.3.0",
-    "@speclynx/apidom-parser-adapter-json": "^2.3.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "^2.3.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "^2.3.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "^2.3.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "^2.3.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "^2.3.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "^2.3.0",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "^2.3.0",
-    "@speclynx/apidom-traverse": "^2.3.0",
+    "@speclynx/apidom-core": "^2.5.0",
+    "@speclynx/apidom-datamodel": "^2.5.0",
+    "@speclynx/apidom-error": "^2.5.0",
+    "@speclynx/apidom-json-pointer": "^2.5.0",
+    "@speclynx/apidom-ns-arazzo-1": "^2.5.0",
+    "@speclynx/apidom-ns-asyncapi-2": "^2.5.0",
+    "@speclynx/apidom-ns-json-schema-2020-12": "^2.5.0",
+    "@speclynx/apidom-ns-openapi-2": "^2.5.0",
+    "@speclynx/apidom-ns-openapi-3-0": "^2.5.0",
+    "@speclynx/apidom-ns-openapi-3-1": "^2.5.0",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "^2.5.0",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "^2.5.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "^2.5.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "^2.5.0",
+    "@speclynx/apidom-parser-adapter-json": "^2.5.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "^2.5.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "^2.5.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "^2.5.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "^2.5.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "^2.5.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "^2.5.0",
+    "@speclynx/apidom-parser-adapter-yaml-1-2": "^2.5.0",
+    "@speclynx/apidom-traverse": "^2.5.0",
+    "@swaggerexpert/arazzo-runtime-expression": "^2.0.2",
     "axios": "^1.13.0",
     "minimatch": "^7.4.6",
     "process": "^0.11.10",
@@ -267,5 +274,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "b561fa09e688f1d9b1968b8353f32ddad9a4a803"
+  "gitHead": "6473d0f9ea30c7fe89aae039e91a0859eaf3cd1c"
 }

package/src/configuration/saturated.cjs

@@ -28,14 +28,15 @@ var _index19 = _interopRequireDefault(require("../dereference/strategies/openapi
 var _index20 = _interopRequireDefault(require("../dereference/strategies/openapi-3-0/index.cjs"));
 var _index21 = _interopRequireDefault(require("../dereference/strategies/openapi-3-1/index.cjs"));
 var _index22 = _interopRequireDefault(require("../dereference/strategies/asyncapi-2/index.cjs"));
-var _index23 = _interopRequireDefault(require("../bundle/strategies/openapi-3-1/index.cjs"));
-var _index24 = require("../index.cjs");
-Object.keys(_index24).forEach(function (key) {
+var _index23 = _interopRequireDefault(require("../dereference/strategies/arazzo-1/index.cjs"));
+var _index24 = _interopRequireDefault(require("../bundle/strategies/openapi-3-1/index.cjs"));
+var _index25 = require("../index.cjs");
+Object.keys(_index25).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;
-  if (key in exports && exports[key] === _index24[key]) return;
-  exports[key] = _index24[key];
+  if (key in exports && exports[key] === _index25[key]) return;
+  exports[key] = _index25[key];
 });
-_index24.options.parse.parsers = [new _index7.default({
+_index25.options.parse.parsers = [new _index7.default({
   allowEmpty: true,
   sourceMap: false
 }), new _index8.default({
@@ -77,11 +78,11 @@ _index24.options.parse.parsers = [new _index7.default({
 }), new _indexNode2.default({
   allowEmpty: true
 })];
-_index24.options.resolve.resolvers = [new _indexNode.default(), new _index.default({
+_index25.options.resolve.resolvers = [new _indexNode.default(), new _index.default({
   timeout: 5000,
   redirects: 5,
   withCredentials: false
 })];
-_index24.options.resolve.strategies = [new _index2.default(), new _index3.default(), new _index4.default(), new _index5.default(), new _index6.default()];
-_index24.options.dereference.strategies = [new _index19.default(), new _index20.default(), new _index21.default(), new _index22.default(), new _index18.default()];
-_index24.options.bundle.strategies = [new _index23.default()];
+_index25.options.resolve.strategies = [new _index2.default(), new _index3.default(), new _index4.default(), new _index5.default(), new _index6.default()];
+_index25.options.dereference.strategies = [new _index19.default(), new _index20.default(), new _index21.default(), new _index22.default(), new _index23.default(), new _index18.default()];
+_index25.options.bundle.strategies = [new _index24.default()];

package/src/configuration/saturated.mjs

@@ -24,6 +24,7 @@ import OpenAPI2DereferenceStrategy from "../dereference/strategies/openapi-2/ind
 import OpenAPI3_0DereferenceStrategy from "../dereference/strategies/openapi-3-0/index.mjs";
 import OpenAPI3_1DereferenceStrategy from "../dereference/strategies/openapi-3-1/index.mjs";
 import AsyncAPI2DereferenceStrategy from "../dereference/strategies/asyncapi-2/index.mjs";
+import Arazzo1DereferenceStrategy from "../dereference/strategies/arazzo-1/index.mjs";
 import OpenAPI3_1BundleStrategy from "../bundle/strategies/openapi-3-1/index.mjs";
 import { options } from "../index.mjs";
 options.parse.parsers = [new OpenAPIJSON2Parser({
@@ -74,6 +75,6 @@ options.resolve.resolvers = [new FileResolver(), new HTTPResolverAxios({
   withCredentials: false
 })];
 options.resolve.strategies = [new OpenAPI2ResolveStrategy(), new OpenAPI3_0ResolveStrategy(), new OpenAPI3_1ResolveStrategy(), new AsyncAPI2ResolveStrategy(), new ApiDOMResolveStrategy()];
-options.dereference.strategies = [new OpenAPI2DereferenceStrategy(), new OpenAPI3_0DereferenceStrategy(), new OpenAPI3_1DereferenceStrategy(), new AsyncAPI2DereferenceStrategy(), new ApiDOMDereferenceStrategy()];
+options.dereference.strategies = [new OpenAPI2DereferenceStrategy(), new OpenAPI3_0DereferenceStrategy(), new OpenAPI3_1DereferenceStrategy(), new AsyncAPI2DereferenceStrategy(), new Arazzo1DereferenceStrategy(), new ApiDOMDereferenceStrategy()];
 options.bundle.strategies = [new OpenAPI3_1BundleStrategy()];
 export * from "../index.mjs";

package/src/dereference/strategies/arazzo-1/index.cjs

@@ -0,0 +1,101 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+exports.__esModule = true;
+exports.resolveSchema$refField = exports.resolveSchema$idField = exports.maybeRefractToJSONSchemaElement = exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomTraverse = require("@speclynx/apidom-traverse");
+var _apidomNsArazzo = _interopRequireWildcard(require("@speclynx/apidom-ns-arazzo-1"));
+var _DereferenceStrategy = _interopRequireDefault(require("../DereferenceStrategy.cjs"));
+var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
+var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));
+var _visitor = _interopRequireDefault(require("./visitor.cjs"));
+exports.Arazzo1DereferenceVisitor = _visitor.default;
+var _util = require("./util.cjs");
+exports.resolveSchema$refField = _util.resolveSchema$refField;
+exports.resolveSchema$idField = _util.resolveSchema$idField;
+exports.maybeRefractToJSONSchemaElement = _util.maybeRefractToJSONSchemaElement;
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class Arazzo1DereferenceStrategy extends _DereferenceStrategy.default {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'arazzo-1'
+    });
+  }
+  canDereference(file) {
+    // assert by media type
+    if (file.mediaType !== 'text/plain') {
+      return _apidomNsArazzo.mediaTypes.includes(file.mediaType);
+    }
+
+    // assert by inspecting ApiDOM
+    return (0, _apidomNsArazzo.isArazzoSpecification1Element)(file.parseResult?.api);
+  }
+  async dereference(file, options) {
+    const namespace = new _apidomDatamodel.Namespace().use(_apidomNsArazzo.default);
+    const immutableRefSet = options.dereference.refSet ?? new _ReferenceSet.default();
+    const mutableRefSet = new _ReferenceSet.default();
+    let refSet = immutableRefSet;
+    let reference;
+    if (!immutableRefSet.has(file.uri)) {
+      reference = new _Reference.default({
+        uri: file.uri,
+        value: file.parseResult
+      });
+      immutableRefSet.add(reference);
+    } else {
+      // pre-computed refSet was provided as configuration option
+      reference = immutableRefSet.find(ref => ref.uri === file.uri);
+    }
+
+    /**
+     * Clone refSet due the dereferencing process being mutable.
+     * We don't want to mutate the original refSet and the references.
+     */
+    if (options.dereference.immutable) {
+      immutableRefSet.refs.map(ref => new _Reference.default({
+        ...ref,
+        value: (0, _apidomDatamodel.cloneDeep)(ref.value)
+      })).forEach(ref => mutableRefSet.add(ref));
+      reference = mutableRefSet.find(ref => ref.uri === file.uri);
+      refSet = mutableRefSet;
+    }
+    const visitor = new _visitor.default({
+      reference,
+      namespace,
+      options
+    });
+    const dereferencedElement = await (0, _apidomTraverse.traverseAsync)(refSet.rootRef.value, visitor, {
+      mutable: true
+    });
+
+    /**
+     * If immutable option is set, replay refs from the refSet.
+     */
+    if (options.dereference.immutable) {
+      mutableRefSet.refs.filter(ref => ref.uri.startsWith('immutable://')).map(ref => new _Reference.default({
+        ...ref,
+        uri: ref.uri.replace(/^immutable:\/\//, '')
+      })).forEach(ref => immutableRefSet.add(ref));
+    }
+
+    /**
+     * Release all memory if this refSet was not provided as a configuration option.
+     * If provided as configuration option, then provider is responsible for cleanup.
+     */
+    if (options.dereference.refSet === null) {
+      immutableRefSet.clean();
+    }
+    mutableRefSet.clean();
+    return dereferencedElement;
+  }
+}
+var _default = exports.default = Arazzo1DereferenceStrategy;

package/src/dereference/strategies/arazzo-1/index.mjs

@@ -0,0 +1,91 @@
+import { Namespace, cloneDeep } from '@speclynx/apidom-datamodel';
+import { traverseAsync } from '@speclynx/apidom-traverse';
+import arazzo1Namespace, { isArazzoSpecification1Element, mediaTypes } from '@speclynx/apidom-ns-arazzo-1';
+import DereferenceStrategy from "../DereferenceStrategy.mjs";
+import Reference from "../../../Reference.mjs";
+import ReferenceSet from "../../../ReferenceSet.mjs";
+import Arazzo1DereferenceVisitor from "./visitor.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+class Arazzo1DereferenceStrategy extends DereferenceStrategy {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'arazzo-1'
+    });
+  }
+  canDereference(file) {
+    // assert by media type
+    if (file.mediaType !== 'text/plain') {
+      return mediaTypes.includes(file.mediaType);
+    }
+
+    // assert by inspecting ApiDOM
+    return isArazzoSpecification1Element(file.parseResult?.api);
+  }
+  async dereference(file, options) {
+    const namespace = new Namespace().use(arazzo1Namespace);
+    const immutableRefSet = options.dereference.refSet ?? new ReferenceSet();
+    const mutableRefSet = new ReferenceSet();
+    let refSet = immutableRefSet;
+    let reference;
+    if (!immutableRefSet.has(file.uri)) {
+      reference = new Reference({
+        uri: file.uri,
+        value: file.parseResult
+      });
+      immutableRefSet.add(reference);
+    } else {
+      // pre-computed refSet was provided as configuration option
+      reference = immutableRefSet.find(ref => ref.uri === file.uri);
+    }
+
+    /**
+     * Clone refSet due the dereferencing process being mutable.
+     * We don't want to mutate the original refSet and the references.
+     */
+    if (options.dereference.immutable) {
+      immutableRefSet.refs.map(ref => new Reference({
+        ...ref,
+        value: cloneDeep(ref.value)
+      })).forEach(ref => mutableRefSet.add(ref));
+      reference = mutableRefSet.find(ref => ref.uri === file.uri);
+      refSet = mutableRefSet;
+    }
+    const visitor = new Arazzo1DereferenceVisitor({
+      reference,
+      namespace,
+      options
+    });
+    const dereferencedElement = await traverseAsync(refSet.rootRef.value, visitor, {
+      mutable: true
+    });
+
+    /**
+     * If immutable option is set, replay refs from the refSet.
+     */
+    if (options.dereference.immutable) {
+      mutableRefSet.refs.filter(ref => ref.uri.startsWith('immutable://')).map(ref => new Reference({
+        ...ref,
+        uri: ref.uri.replace(/^immutable:\/\//, '')
+      })).forEach(ref => immutableRefSet.add(ref));
+    }
+
+    /**
+     * Release all memory if this refSet was not provided as a configuration option.
+     * If provided as configuration option, then provider is responsible for cleanup.
+     */
+    if (options.dereference.refSet === null) {
+      immutableRefSet.clean();
+    }
+    mutableRefSet.clean();
+    return dereferencedElement;
+  }
+}
+export { Arazzo1DereferenceVisitor };
+export { resolveSchema$refField, resolveSchema$idField, maybeRefractToJSONSchemaElement } from "./util.mjs";
+export default Arazzo1DereferenceStrategy;

package/src/dereference/strategies/arazzo-1/selectors/$anchor.cjs

@@ -0,0 +1,12 @@
+"use strict";
+
+exports.__esModule = true;
+exports.uriToAnchor = exports.parse = exports.isAnchor = exports.evaluate = exports.JsonSchema$anchorError = exports.InvalidJsonSchema$anchorError = exports.EvaluationJsonSchema$anchorError = void 0;
+var _$anchor = require("../../openapi-3-1/selectors/$anchor.cjs");
+exports.isAnchor = _$anchor.isAnchor;
+exports.uriToAnchor = _$anchor.uriToAnchor;
+exports.parse = _$anchor.parse;
+exports.evaluate = _$anchor.evaluate;
+exports.EvaluationJsonSchema$anchorError = _$anchor.EvaluationJsonSchema$anchorError;
+exports.InvalidJsonSchema$anchorError = _$anchor.InvalidJsonSchema$anchorError;
+exports.JsonSchema$anchorError = _$anchor.JsonSchema$anchorError;

package/src/dereference/strategies/arazzo-1/selectors/$anchor.mjs

@@ -0,0 +1 @@
+export { isAnchor, uriToAnchor, parse, evaluate, EvaluationJsonSchema$anchorError, InvalidJsonSchema$anchorError, JsonSchema$anchorError } from "../../openapi-3-1/selectors/$anchor.mjs";

package/src/dereference/strategies/arazzo-1/selectors/uri.cjs

@@ -0,0 +1,8 @@
+"use strict";
+
+exports.__esModule = true;
+exports.evaluate = exports.JsonSchemaUriError = exports.EvaluationJsonSchemaUriError = void 0;
+var _uri = require("../../openapi-3-1/selectors/uri.cjs");
+exports.evaluate = _uri.evaluate;
+exports.EvaluationJsonSchemaUriError = _uri.EvaluationJsonSchemaUriError;
+exports.JsonSchemaUriError = _uri.JsonSchemaUriError;

package/src/dereference/strategies/arazzo-1/selectors/uri.mjs

@@ -0,0 +1 @@
+export { evaluate, EvaluationJsonSchemaUriError, JsonSchemaUriError } from "../../openapi-3-1/selectors/uri.mjs";

package/src/dereference/strategies/arazzo-1/util.cjs

@@ -0,0 +1,37 @@
+"use strict";
+
+exports.__esModule = true;
+exports.resolveSchema$refField = exports.resolveSchema$idField = exports.refractToJSONSchemaElement = exports.maybeRefractToJSONSchemaElement = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+var _util = require("../openapi-3-1/util.cjs");
+exports.resolveSchema$refField = _util.resolveSchema$refField;
+exports.resolveSchema$idField = _util.resolveSchema$idField;
+/**
+ * Cached version of JSONSchemaElement.refract.
+ */
+const refractToJSONSchemaElement = element => {
+  if (refractToJSONSchemaElement.cache.has(element)) {
+    return refractToJSONSchemaElement.cache.get(element);
+  }
+  const refracted = (0, _apidomNsArazzo.refractJSONSchema)(element);
+  refractToJSONSchemaElement.cache.set(element, refracted);
+  return refracted;
+};
+exports.refractToJSONSchemaElement = refractToJSONSchemaElement;
+refractToJSONSchemaElement.cache = new WeakMap();
+
+/**
+ * @public
+ */
+const maybeRefractToJSONSchemaElement = element => {
+  /**
+   * Conditional version of refractToJSONSchemaElement, that acts as an identity
+   * function for all non-primitive Element instances.
+   */
+  if ((0, _apidomDatamodel.isPrimitiveElement)(element)) {
+    return refractToJSONSchemaElement(element);
+  }
+  return element;
+};
+exports.maybeRefractToJSONSchemaElement = maybeRefractToJSONSchemaElement;

package/src/dereference/strategies/arazzo-1/util.mjs

@@ -0,0 +1,29 @@
+import { isPrimitiveElement } from '@speclynx/apidom-datamodel';
+import { refractJSONSchema } from '@speclynx/apidom-ns-arazzo-1';
+export { resolveSchema$refField, resolveSchema$idField } from "../openapi-3-1/util.mjs";
+/**
+ * Cached version of JSONSchemaElement.refract.
+ */
+export const refractToJSONSchemaElement = element => {
+  if (refractToJSONSchemaElement.cache.has(element)) {
+    return refractToJSONSchemaElement.cache.get(element);
+  }
+  const refracted = refractJSONSchema(element);
+  refractToJSONSchemaElement.cache.set(element, refracted);
+  return refracted;
+};
+refractToJSONSchemaElement.cache = new WeakMap();
+
+/**
+ * @public
+ */
+export const maybeRefractToJSONSchemaElement = element => {
+  /**
+   * Conditional version of refractToJSONSchemaElement, that acts as an identity
+   * function for all non-primitive Element instances.
+   */
+  if (isPrimitiveElement(element)) {
+    return refractToJSONSchemaElement(element);
+  }
+  return element;
+};