@speclynx/apidom-reference 1.12.1

package/src/dereference/strategies/openapi-3-1/index.mjs

@@ -0,0 +1,96 @@
+import { propEq } from 'ramda';
+import { createNamespace, visit, cloneDeep } from '@speclynx/apidom-core';
+import openApi3_1Namespace, { getNodeType, isOpenApi3_1Element, keyMap, mediaTypes } from '@speclynx/apidom-ns-openapi-3-1';
+import DereferenceStrategy from "../DereferenceStrategy.mjs";
+import Reference from "../../../Reference.mjs";
+import ReferenceSet from "../../../ReferenceSet.mjs";
+import OpenAPI3_1DereferenceVisitor from "./visitor.mjs";
+// @ts-ignore
+const visitAsync = visit[Symbol.for('nodejs.util.promisify.custom')];
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class OpenAPI3_1DereferenceStrategy extends DereferenceStrategy {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'openapi-3-1'
+    });
+  }
+  canDereference(file) {
+    // assert by media type
+    if (file.mediaType !== 'text/plain') {
+      return mediaTypes.includes(file.mediaType);
+    }
+
+    // assert by inspecting ApiDOM
+    return isOpenApi3_1Element(file.parseResult?.result);
+  }
+  async dereference(file, options) {
+    const namespace = createNamespace(openApi3_1Namespace);
+    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(propEq(file.uri, '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 OpenAPI3_1DereferenceVisitor({
+      reference: reference,
+      namespace,
+      options
+    });
+    const dereferencedElement = await visitAsync(refSet.rootRef.value, visitor, {
+      keyMap,
+      nodeTypeGetter: getNodeType
+    });
+
+    /**
+     * 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 an 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 { OpenAPI3_1DereferenceVisitor };
+export { resolveSchema$refField, resolveSchema$idField, maybeRefractToSchemaElement } from "./util.mjs";
+export default OpenAPI3_1DereferenceStrategy;

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

@@ -0,0 +1,66 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.uriToAnchor = exports.parse = exports.isAnchor = exports.evaluate = exports.JsonSchema$anchorError = void 0;
+var _ramdaAdjunct = require("ramda-adjunct");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-3-1");
+var _url = require("../../../../util/url.cjs");
+var _EvaluationJsonSchema$anchorError = _interopRequireDefault(require("../../../../errors/EvaluationJsonSchema$anchorError.cjs"));
+exports.EvaluationJsonSchema$anchorError = _EvaluationJsonSchema$anchorError.default;
+var _InvalidJsonSchema$anchorError = _interopRequireDefault(require("../../../../errors/InvalidJsonSchema$anchorError.cjs"));
+exports.InvalidJsonSchema$anchorError = _InvalidJsonSchema$anchorError.default;
+var _JsonSchema$anchorError = _interopRequireDefault(require("../../../../errors/JsonSchema$anchorError.cjs"));
+exports.JsonSchema$anchorError = _JsonSchema$anchorError.default;
+/**
+ * @public
+ */
+const isAnchor = uri => {
+  /**
+   *  MUST start with a letter ([A-Za-z]) or underscore ("_"), followed by any number of letters,
+   *  digits ([0-9]), hyphens ("-"), underscores ("_"), and periods (".").
+   *
+   *  https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.2.2
+   */
+  return /^[A-Za-z_][A-Za-z_0-9.-]*$/.test(uri);
+};
+
+/**
+ * @public
+ */
+exports.isAnchor = isAnchor;
+const uriToAnchor = uri => {
+  const hash = (0, _url.getHash)(uri);
+  return (0, _ramdaAdjunct.trimCharsStart)('#', hash);
+};
+
+/**
+ * @public
+ */
+exports.uriToAnchor = uriToAnchor;
+const parse = anchor => {
+  if (!isAnchor(anchor)) {
+    throw new _InvalidJsonSchema$anchorError.default(anchor);
+  }
+  return anchor;
+};
+
+/**
+ * Evaluates JSON Schema $anchor against ApiDOM fragment.
+ * @public
+ */
+exports.parse = parse;
+const evaluate = (anchor, element) => {
+  const token = parse(anchor);
+
+  // @ts-ignore
+  const result = (0, _apidomCore.find)(e => (0, _apidomNsOpenapi.isSchemaElement)(e) && (0, _apidomCore.toValue)(e.$anchor) === token, element);
+  if ((0, _ramdaAdjunct.isUndefined)(result)) {
+    throw new _EvaluationJsonSchema$anchorError.default(`Evaluation failed on token: "${token}"`);
+  }
+
+  // @ts-ignore
+  return result;
+};
+exports.evaluate = evaluate;

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

@@ -0,0 +1,55 @@
+import { trimCharsStart, isUndefined } from 'ramda-adjunct';
+import { find, toValue } from '@speclynx/apidom-core';
+import { isSchemaElement } from '@speclynx/apidom-ns-openapi-3-1';
+import { getHash } from "../../../../util/url.mjs";
+import EvaluationJsonSchema$anchorError from "../../../../errors/EvaluationJsonSchema$anchorError.mjs";
+import InvalidJsonSchema$anchorError from "../../../../errors/InvalidJsonSchema$anchorError.mjs";
+/**
+ * @public
+ */
+export const isAnchor = uri => {
+  /**
+   *  MUST start with a letter ([A-Za-z]) or underscore ("_"), followed by any number of letters,
+   *  digits ([0-9]), hyphens ("-"), underscores ("_"), and periods (".").
+   *
+   *  https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.2.2
+   */
+  return /^[A-Za-z_][A-Za-z_0-9.-]*$/.test(uri);
+};
+
+/**
+ * @public
+ */
+export const uriToAnchor = uri => {
+  const hash = getHash(uri);
+  return trimCharsStart('#', hash);
+};
+
+/**
+ * @public
+ */
+export const parse = anchor => {
+  if (!isAnchor(anchor)) {
+    throw new InvalidJsonSchema$anchorError(anchor);
+  }
+  return anchor;
+};
+
+/**
+ * Evaluates JSON Schema $anchor against ApiDOM fragment.
+ * @public
+ */
+export const evaluate = (anchor, element) => {
+  const token = parse(anchor);
+
+  // @ts-ignore
+  const result = find(e => isSchemaElement(e) && toValue(e.$anchor) === token, element);
+  if (isUndefined(result)) {
+    throw new EvaluationJsonSchema$anchorError(`Evaluation failed on token: "${token}"`);
+  }
+
+  // @ts-ignore
+  return result;
+};
+export { EvaluationJsonSchema$anchorError, InvalidJsonSchema$anchorError };
+export { default as JsonSchema$anchorError } from "../../../../errors/JsonSchema$anchorError.mjs";

package/src/dereference/strategies/openapi-3-1/selectors/uri.cjs

@@ -0,0 +1,50 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+exports.__esModule = true;
+exports.evaluate = exports.JsonSchemaUriError = void 0;
+var _ramdaAdjunct = require("ramda-adjunct");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-3-1");
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var url = _interopRequireWildcard(require("../../../../util/url.cjs"));
+var _EvaluationJsonSchemaUriError = _interopRequireDefault(require("../../../../errors/EvaluationJsonSchemaUriError.cjs"));
+exports.EvaluationJsonSchemaUriError = _EvaluationJsonSchemaUriError.default;
+var _$anchor = require("./$anchor.cjs");
+var _util = require("../util.cjs");
+var _JsonSchemaUriError = _interopRequireDefault(require("../../../../errors/JsonSchemaUriError.cjs"));
+exports.JsonSchemaUriError = _JsonSchemaUriError.default;
+/**
+ * Evaluates JSON Schema $ref containing unknown URI against ApiDOM fragment.
+ * @public
+ */
+const evaluate = (uri, element) => {
+  const {
+    cache
+  } = evaluate;
+  const uriStrippedHash = url.stripHash(uri);
+  const isSchemaElementWith$id = e => (0, _apidomNsOpenapi.isSchemaElement)(e) && typeof e.$id !== 'undefined';
+
+  // warm the cache
+  if (!cache.has(element)) {
+    const schemaObjectElements = (0, _apidomCore.filter)(isSchemaElementWith$id, element);
+    cache.set(element, Array.from(schemaObjectElements));
+  }
+
+  // search for the matching schema
+  const result = cache.get(element).find(e => {
+    const $idBaseURI = (0, _util.resolveSchema$idField)(uriStrippedHash, e);
+    return $idBaseURI === uriStrippedHash;
+  });
+  if ((0, _ramdaAdjunct.isUndefined)(result)) {
+    throw new _EvaluationJsonSchemaUriError.default(`Evaluation failed on URI: "${uri}"`);
+  }
+  if ((0, _$anchor.isAnchor)((0, _$anchor.uriToAnchor)(uri))) {
+    // we're dealing with JSON Schema $anchor here
+    return (0, _$anchor.evaluate)((0, _$anchor.uriToAnchor)(uri), result);
+  }
+  return (0, _apidomJsonPointer.evaluate)(result, _apidomJsonPointer.URIFragmentIdentifier.fromURIReference(uri));
+};
+exports.evaluate = evaluate;
+evaluate.cache = new WeakMap();

package/src/dereference/strategies/openapi-3-1/selectors/uri.mjs

@@ -0,0 +1,42 @@
+import { isUndefined } from 'ramda-adjunct';
+import { filter } from '@speclynx/apidom-core';
+import { isSchemaElement } from '@speclynx/apidom-ns-openapi-3-1';
+import { URIFragmentIdentifier, evaluate as jsonPointerEvaluate } from '@speclynx/apidom-json-pointer';
+import * as url from "../../../../util/url.mjs";
+import EvaluationJsonSchemaUriError from "../../../../errors/EvaluationJsonSchemaUriError.mjs";
+import { isAnchor, uriToAnchor, evaluate as $anchorEvaluate } from "./$anchor.mjs";
+import { resolveSchema$idField } from "../util.mjs";
+/**
+ * Evaluates JSON Schema $ref containing unknown URI against ApiDOM fragment.
+ * @public
+ */
+export const evaluate = (uri, element) => {
+  const {
+    cache
+  } = evaluate;
+  const uriStrippedHash = url.stripHash(uri);
+  const isSchemaElementWith$id = e => isSchemaElement(e) && typeof e.$id !== 'undefined';
+
+  // warm the cache
+  if (!cache.has(element)) {
+    const schemaObjectElements = filter(isSchemaElementWith$id, element);
+    cache.set(element, Array.from(schemaObjectElements));
+  }
+
+  // search for the matching schema
+  const result = cache.get(element).find(e => {
+    const $idBaseURI = resolveSchema$idField(uriStrippedHash, e);
+    return $idBaseURI === uriStrippedHash;
+  });
+  if (isUndefined(result)) {
+    throw new EvaluationJsonSchemaUriError(`Evaluation failed on URI: "${uri}"`);
+  }
+  if (isAnchor(uriToAnchor(uri))) {
+    // we're dealing with JSON Schema $anchor here
+    return $anchorEvaluate(uriToAnchor(uri), result);
+  }
+  return jsonPointerEvaluate(result, URIFragmentIdentifier.fromURIReference(uri));
+};
+evaluate.cache = new WeakMap();
+export { EvaluationJsonSchemaUriError };
+export { default as JsonSchemaUriError } from "../../../../errors/JsonSchemaUriError.mjs";

package/src/dereference/strategies/openapi-3-1/util.cjs

@@ -0,0 +1,67 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+exports.__esModule = true;
+exports.resolveSchema$refField = exports.resolveSchema$idField = exports.refractToSchemaElement = exports.maybeRefractToSchemaElement = void 0;
+var _ramda = require("ramda");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-3-1");
+var url = _interopRequireWildcard(require("../../../util/url.cjs"));
+/**
+ * @public
+ */
+const resolveSchema$refField = (retrievalURI, schemaElement) => {
+  if (typeof schemaElement.$ref === 'undefined') {
+    return undefined;
+  }
+  const hash = url.getHash((0, _apidomCore.toValue)(schemaElement.$ref));
+  const ancestorsSchemaIdentifiers = (0, _apidomCore.toValue)(schemaElement.meta.get('ancestorsSchemaIdentifiers'));
+  const $refBaseURI = (0, _ramda.reduce)((acc, uri) => {
+    return url.resolve(acc, url.sanitize(url.stripHash(uri)));
+  }, retrievalURI, [...ancestorsSchemaIdentifiers, (0, _apidomCore.toValue)(schemaElement.$ref)]);
+  return `${$refBaseURI}${hash === '#' ? '' : hash}`;
+};
+
+/**
+ * @public
+ */
+exports.resolveSchema$refField = resolveSchema$refField;
+const resolveSchema$idField = (retrievalURI, schemaElement) => {
+  if (typeof schemaElement.$id === 'undefined') {
+    return undefined;
+  }
+  const ancestorsSchemaIdentifiers = (0, _apidomCore.toValue)(schemaElement.meta.get('ancestorsSchemaIdentifiers'));
+  return (0, _ramda.reduce)((acc, $id) => {
+    return url.resolve(acc, url.sanitize(url.stripHash($id)));
+  }, retrievalURI, ancestorsSchemaIdentifiers);
+};
+
+/**
+ * Cached version of SchemaElement.refract.
+ */
+exports.resolveSchema$idField = resolveSchema$idField;
+const refractToSchemaElement = element => {
+  if (refractToSchemaElement.cache.has(element)) {
+    return refractToSchemaElement.cache.get(element);
+  }
+  const refracted = _apidomNsOpenapi.SchemaElement.refract(element);
+  refractToSchemaElement.cache.set(element, refracted);
+  return refracted;
+};
+exports.refractToSchemaElement = refractToSchemaElement;
+refractToSchemaElement.cache = new WeakMap();
+
+/**
+ * @public
+ */
+const maybeRefractToSchemaElement = element => {
+  /**
+   * Conditional version of refractToSchemaElement, that acts as an identity
+   * function for all non-primitive Element instances.
+   */
+  if ((0, _apidomCore.isPrimitiveElement)(element)) {
+    return refractToSchemaElement(element);
+  }
+  return element;
+};
+exports.maybeRefractToSchemaElement = maybeRefractToSchemaElement;

package/src/dereference/strategies/openapi-3-1/util.mjs

@@ -0,0 +1,58 @@
+import { reduce } from 'ramda';
+import { isPrimitiveElement, toValue } from '@speclynx/apidom-core';
+import { SchemaElement } from '@speclynx/apidom-ns-openapi-3-1';
+import * as url from "../../../util/url.mjs";
+/**
+ * @public
+ */
+export const resolveSchema$refField = (retrievalURI, schemaElement) => {
+  if (typeof schemaElement.$ref === 'undefined') {
+    return undefined;
+  }
+  const hash = url.getHash(toValue(schemaElement.$ref));
+  const ancestorsSchemaIdentifiers = toValue(schemaElement.meta.get('ancestorsSchemaIdentifiers'));
+  const $refBaseURI = reduce((acc, uri) => {
+    return url.resolve(acc, url.sanitize(url.stripHash(uri)));
+  }, retrievalURI, [...ancestorsSchemaIdentifiers, toValue(schemaElement.$ref)]);
+  return `${$refBaseURI}${hash === '#' ? '' : hash}`;
+};
+
+/**
+ * @public
+ */
+export const resolveSchema$idField = (retrievalURI, schemaElement) => {
+  if (typeof schemaElement.$id === 'undefined') {
+    return undefined;
+  }
+  const ancestorsSchemaIdentifiers = toValue(schemaElement.meta.get('ancestorsSchemaIdentifiers'));
+  return reduce((acc, $id) => {
+    return url.resolve(acc, url.sanitize(url.stripHash($id)));
+  }, retrievalURI, ancestorsSchemaIdentifiers);
+};
+
+/**
+ * Cached version of SchemaElement.refract.
+ */
+export const refractToSchemaElement = element => {
+  if (refractToSchemaElement.cache.has(element)) {
+    return refractToSchemaElement.cache.get(element);
+  }
+  const refracted = SchemaElement.refract(element);
+  refractToSchemaElement.cache.set(element, refracted);
+  return refracted;
+};
+refractToSchemaElement.cache = new WeakMap();
+
+/**
+ * @public
+ */
+export const maybeRefractToSchemaElement = element => {
+  /**
+   * Conditional version of refractToSchemaElement, that acts as an identity
+   * function for all non-primitive Element instances.
+   */
+  if (isPrimitiveElement(element)) {
+    return refractToSchemaElement(element);
+  }
+  return element;
+};