@speclynx/apidom-reference 1.12.1

package/src/dereference/strategies/apidom/index.mjs

@@ -0,0 +1,84 @@
+import { isElement, cloneDeep, visit } from '@speclynx/apidom-core';
+import DereferenceStrategy from "../DereferenceStrategy.mjs";
+import Reference from "../../../Reference.mjs";
+import ReferenceSet from "../../../ReferenceSet.mjs";
+import ApiDOMDereferenceVisitor from "./visitor.mjs";
+// @ts-ignore
+const visitAsync = visit[Symbol.for('nodejs.util.promisify.custom')];
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class ApiDOMDereferenceStrategy extends DereferenceStrategy {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'apidom'
+    });
+  }
+  canDereference(file) {
+    return file.mediaType.startsWith('application/vnd.apidom') && isElement(file.parseResult?.result);
+  }
+  async dereference(file, options) {
+    const immutableRefSet = options.dereference.refSet ?? new ReferenceSet();
+    const mutableRefSet = new ReferenceSet();
+    let refSet = immutableRefSet;
+    let reference;
+
+    // determine the initial 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 ApiDOMDereferenceVisitor({
+      reference: reference,
+      options
+    });
+    const dereferencedElement = await visitAsync(refSet.rootRef.value, visitor);
+
+    /**
+     * 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 { ApiDOMDereferenceVisitor };
+export default ApiDOMDereferenceStrategy;

package/src/dereference/strategies/apidom/selectors/element-id.cjs

@@ -0,0 +1,36 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.evaluate = void 0;
+var _ramdaAdjunct = require("ramda-adjunct");
+var _apidomCore = require("@speclynx/apidom-core");
+var _EvaluationElementIdError = _interopRequireDefault(require("../../../../errors/EvaluationElementIdError.cjs"));
+exports.EvaluationElementIdError = _EvaluationElementIdError.default;
+const hasElementID = element => !!element.id;
+
+/**
+ * Evaluates element ID against ApiDOM fragment.
+ * @public
+ */
+const evaluate = (elementID, element) => {
+  const {
+    cache
+  } = evaluate;
+  // warm the cache
+  if (!cache.has(element)) {
+    const elementsWithID = (0, _apidomCore.filter)(hasElementID, element);
+    cache.set(element, Array.from(elementsWithID));
+  }
+
+  // search for the matching element
+  const result = cache.get(element).find(e => {
+    return String((0, _apidomCore.toValue)(e.id)) === elementID;
+  });
+  if ((0, _ramdaAdjunct.isUndefined)(result)) {
+    throw new _EvaluationElementIdError.default(`Evaluation failed on element ID: "${elementID}"`);
+  }
+  return result;
+};
+exports.evaluate = evaluate;
+evaluate.cache = new WeakMap();

package/src/dereference/strategies/apidom/selectors/element-id.mjs

@@ -0,0 +1,30 @@
+import { isUndefined } from 'ramda-adjunct';
+import { filter, toValue } from '@speclynx/apidom-core';
+import EvaluationElementIdError from "../../../../errors/EvaluationElementIdError.mjs";
+const hasElementID = element => !!element.id;
+
+/**
+ * Evaluates element ID against ApiDOM fragment.
+ * @public
+ */
+export const evaluate = (elementID, element) => {
+  const {
+    cache
+  } = evaluate;
+  // warm the cache
+  if (!cache.has(element)) {
+    const elementsWithID = filter(hasElementID, element);
+    cache.set(element, Array.from(elementsWithID));
+  }
+
+  // search for the matching element
+  const result = cache.get(element).find(e => {
+    return String(toValue(e.id)) === elementID;
+  });
+  if (isUndefined(result)) {
+    throw new EvaluationElementIdError(`Evaluation failed on element ID: "${elementID}"`);
+  }
+  return result;
+};
+evaluate.cache = new WeakMap();
+export { EvaluationElementIdError };

package/src/dereference/strategies/apidom/visitor.cjs

@@ -0,0 +1,165 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ramda = require("ramda");
+var _apidomError = require("@speclynx/apidom-error");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var _MaximumResolveDepthError = _interopRequireDefault(require("../../../errors/MaximumResolveDepthError.cjs"));
+var url = _interopRequireWildcard(require("../../../util/url.cjs"));
+var _index = _interopRequireDefault(require("../../../parse/index.cjs"));
+var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
+var _elementId = require("./selectors/element-id.cjs");
+// @ts-ignore
+const visitAsync = _apidomCore.visit[Symbol.for('nodejs.util.promisify.custom')];
+
+/**
+ * The following rules apply:
+ *
+ * 1. When referencing an element in the local document, the id of the element MAY be used
+ * 2. When referencing remote elements, an absolute URL or relative URL MAY be used
+ * 3. When a URL fragment exists in the URL given, it references the element with the matching id in the given document. The URL fragment MAY need to be URL decoded before making a match.
+ * 4. When a URL fragment does not exist, the URL references the root element
+ * 5. When path is used, it references the given property of the referenced element
+ * 6. When path is used in an element that includes the data of the pointer (such as with ref), the referenced path MAY need to be converted to a refract structure in order to be valid
+ *
+ * WARNING: this implementation only supports referencing elements in the local document. Points 2-4 are not supported.
+ * @public
+ */
+
+/**
+ * @public
+ */
+class ApiDOMDereferenceVisitor {
+  reference;
+  options;
+  constructor({
+    reference,
+    options
+  }) {
+    this.reference = reference;
+    this.options = options;
+  }
+  toBaseURI(uri) {
+    return url.resolve(this.reference.uri, url.sanitize(url.stripHash(uri)));
+  }
+  async toReference(uri) {
+    // detect maximum depth of resolution
+    if (this.reference.depth >= this.options.resolve.maxDepth) {
+      throw new _MaximumResolveDepthError.default(`Maximum resolution depth of ${this.options.resolve.maxDepth} has been exceeded by file "${this.reference.uri}"`);
+    }
+    const baseURI = this.toBaseURI(uri);
+    const {
+      refSet
+    } = this.reference;
+
+    // we've already processed this Reference in past
+    if (refSet.has(baseURI)) {
+      return refSet.find((0, _ramda.propEq)(baseURI, 'uri'));
+    }
+    const parseResult = await (0, _index.default)(url.unsanitize(baseURI), {
+      ...this.options,
+      parse: {
+        ...this.options.parse,
+        mediaType: 'text/plain'
+      }
+    });
+
+    // register new mutable reference with a refSet
+    const mutableReference = new _Reference.default({
+      uri: baseURI,
+      value: (0, _apidomCore.cloneDeep)(parseResult),
+      depth: this.reference.depth + 1
+    });
+    refSet.add(mutableReference);
+    if (this.options.dereference.immutable) {
+      // register new immutable reference with a refSet
+      const immutableReference = new _Reference.default({
+        uri: `immutable://${baseURI}`,
+        value: parseResult,
+        depth: this.reference.depth + 1
+      });
+      refSet.add(immutableReference);
+    }
+    return mutableReference;
+  }
+  async RefElement(refElement, key, parent, path, ancestors) {
+    const refURI = (0, _apidomCore.toValue)(refElement);
+    const refNormalizedURI = refURI.includes('#') ? refURI : `#${refURI}`;
+    const retrievalURI = this.toBaseURI(refNormalizedURI);
+    const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+    const isExternalReference = !isInternalReference;
+
+    // ignore resolving internal RefElements
+    if (!this.options.resolve.internal && isInternalReference) {
+      // skip traversing this ref element
+      return false;
+    }
+    // ignore resolving external RefElements
+    if (!this.options.resolve.external && isExternalReference) {
+      // skip traversing this ref element
+      return false;
+    }
+    const reference = await this.toReference(refNormalizedURI);
+    const refBaseURI = url.resolve(retrievalURI, refNormalizedURI);
+    const elementID = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference(refBaseURI);
+    let referencedElement = (0, _elementId.evaluate)(elementID, reference.value.result);
+    if (!(0, _apidomCore.isElement)(referencedElement)) {
+      throw new _apidomError.ApiDOMError(`Referenced element with id="${elementID}" was not found`);
+    }
+    if (refElement === referencedElement) {
+      throw new _apidomError.ApiDOMError('RefElement cannot reference itself');
+    }
+    if ((0, _apidomCore.isRefElement)(referencedElement)) {
+      throw new _apidomError.ApiDOMError('RefElement cannot reference another RefElement');
+    }
+    if (isExternalReference) {
+      // dive deep into the fragment
+      const visitor = new ApiDOMDereferenceVisitor({
+        reference,
+        options: this.options
+      });
+      referencedElement = await visitAsync(referencedElement, visitor);
+    }
+
+    /**
+     * When path is used, it references the given property of the referenced element
+     */
+    const referencedElementPath = (0, _apidomCore.toValue)(refElement.path);
+    if (referencedElementPath !== 'element' && (0, _apidomCore.isElement)(referencedElement)) {
+      referencedElement = (0, _apidomCore.refract)(referencedElement[referencedElementPath]);
+    }
+
+    /**
+     * Transclusion of a Ref Element SHALL be defined in the if/else block below.
+     */
+    if ((0, _apidomCore.isObjectElement)(referencedElement) && (0, _apidomCore.isObjectElement)(ancestors[ancestors.length - 1]) && Array.isArray(parent) && typeof key === 'number') {
+      /**
+       * If the Ref Element is held by an Object Element and references an Object Element,
+       * its content entries SHALL be inserted in place of the Ref Element.
+       */
+      parent.splice(key, 1, ...referencedElement.content);
+    } else if ((0, _apidomCore.isArrayElement)(referencedElement) && Array.isArray(parent) && typeof key === 'number') {
+      /**
+       * If the Ref Element is held by an Array Element and references an Array Element,
+       * its content entries SHALL be inserted in place of the Ref Element.
+       */
+      parent.splice(key, 1, ...referencedElement.content);
+    } else if ((0, _apidomCore.isMemberElement)(parent)) {
+      /**
+       * The Ref Element is substituted by the Element it references.
+       */
+      parent.value = referencedElement;
+    } else if (Array.isArray(parent)) {
+      /**
+       * The Ref Element is substituted by the Element it references.
+       */
+      parent[key] = referencedElement;
+    }
+    return !parent ? referencedElement : false;
+  }
+}
+var _default = exports.default = ApiDOMDereferenceVisitor;

package/src/dereference/strategies/apidom/visitor.mjs

@@ -0,0 +1,159 @@
+import { propEq } from 'ramda';
+import { ApiDOMError } from '@speclynx/apidom-error';
+import { isElement, isMemberElement, isArrayElement, isObjectElement, isRefElement, toValue, refract, visit, cloneDeep } from '@speclynx/apidom-core';
+import { URIFragmentIdentifier } from '@speclynx/apidom-json-pointer';
+import MaximumResolveDepthError from "../../../errors/MaximumResolveDepthError.mjs";
+import * as url from "../../../util/url.mjs";
+import parse from "../../../parse/index.mjs";
+import Reference from "../../../Reference.mjs";
+import { evaluate } from "./selectors/element-id.mjs";
+// @ts-ignore
+const visitAsync = visit[Symbol.for('nodejs.util.promisify.custom')];
+
+/**
+ * The following rules apply:
+ *
+ * 1. When referencing an element in the local document, the id of the element MAY be used
+ * 2. When referencing remote elements, an absolute URL or relative URL MAY be used
+ * 3. When a URL fragment exists in the URL given, it references the element with the matching id in the given document. The URL fragment MAY need to be URL decoded before making a match.
+ * 4. When a URL fragment does not exist, the URL references the root element
+ * 5. When path is used, it references the given property of the referenced element
+ * 6. When path is used in an element that includes the data of the pointer (such as with ref), the referenced path MAY need to be converted to a refract structure in order to be valid
+ *
+ * WARNING: this implementation only supports referencing elements in the local document. Points 2-4 are not supported.
+ * @public
+ */
+
+/**
+ * @public
+ */
+class ApiDOMDereferenceVisitor {
+  reference;
+  options;
+  constructor({
+    reference,
+    options
+  }) {
+    this.reference = reference;
+    this.options = options;
+  }
+  toBaseURI(uri) {
+    return url.resolve(this.reference.uri, url.sanitize(url.stripHash(uri)));
+  }
+  async toReference(uri) {
+    // detect maximum depth of resolution
+    if (this.reference.depth >= this.options.resolve.maxDepth) {
+      throw new MaximumResolveDepthError(`Maximum resolution depth of ${this.options.resolve.maxDepth} has been exceeded by file "${this.reference.uri}"`);
+    }
+    const baseURI = this.toBaseURI(uri);
+    const {
+      refSet
+    } = this.reference;
+
+    // we've already processed this Reference in past
+    if (refSet.has(baseURI)) {
+      return refSet.find(propEq(baseURI, 'uri'));
+    }
+    const parseResult = await parse(url.unsanitize(baseURI), {
+      ...this.options,
+      parse: {
+        ...this.options.parse,
+        mediaType: 'text/plain'
+      }
+    });
+
+    // register new mutable reference with a refSet
+    const mutableReference = new Reference({
+      uri: baseURI,
+      value: cloneDeep(parseResult),
+      depth: this.reference.depth + 1
+    });
+    refSet.add(mutableReference);
+    if (this.options.dereference.immutable) {
+      // register new immutable reference with a refSet
+      const immutableReference = new Reference({
+        uri: `immutable://${baseURI}`,
+        value: parseResult,
+        depth: this.reference.depth + 1
+      });
+      refSet.add(immutableReference);
+    }
+    return mutableReference;
+  }
+  async RefElement(refElement, key, parent, path, ancestors) {
+    const refURI = toValue(refElement);
+    const refNormalizedURI = refURI.includes('#') ? refURI : `#${refURI}`;
+    const retrievalURI = this.toBaseURI(refNormalizedURI);
+    const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+    const isExternalReference = !isInternalReference;
+
+    // ignore resolving internal RefElements
+    if (!this.options.resolve.internal && isInternalReference) {
+      // skip traversing this ref element
+      return false;
+    }
+    // ignore resolving external RefElements
+    if (!this.options.resolve.external && isExternalReference) {
+      // skip traversing this ref element
+      return false;
+    }
+    const reference = await this.toReference(refNormalizedURI);
+    const refBaseURI = url.resolve(retrievalURI, refNormalizedURI);
+    const elementID = URIFragmentIdentifier.fromURIReference(refBaseURI);
+    let referencedElement = evaluate(elementID, reference.value.result);
+    if (!isElement(referencedElement)) {
+      throw new ApiDOMError(`Referenced element with id="${elementID}" was not found`);
+    }
+    if (refElement === referencedElement) {
+      throw new ApiDOMError('RefElement cannot reference itself');
+    }
+    if (isRefElement(referencedElement)) {
+      throw new ApiDOMError('RefElement cannot reference another RefElement');
+    }
+    if (isExternalReference) {
+      // dive deep into the fragment
+      const visitor = new ApiDOMDereferenceVisitor({
+        reference,
+        options: this.options
+      });
+      referencedElement = await visitAsync(referencedElement, visitor);
+    }
+
+    /**
+     * When path is used, it references the given property of the referenced element
+     */
+    const referencedElementPath = toValue(refElement.path);
+    if (referencedElementPath !== 'element' && isElement(referencedElement)) {
+      referencedElement = refract(referencedElement[referencedElementPath]);
+    }
+
+    /**
+     * Transclusion of a Ref Element SHALL be defined in the if/else block below.
+     */
+    if (isObjectElement(referencedElement) && isObjectElement(ancestors[ancestors.length - 1]) && Array.isArray(parent) && typeof key === 'number') {
+      /**
+       * If the Ref Element is held by an Object Element and references an Object Element,
+       * its content entries SHALL be inserted in place of the Ref Element.
+       */
+      parent.splice(key, 1, ...referencedElement.content);
+    } else if (isArrayElement(referencedElement) && Array.isArray(parent) && typeof key === 'number') {
+      /**
+       * If the Ref Element is held by an Array Element and references an Array Element,
+       * its content entries SHALL be inserted in place of the Ref Element.
+       */
+      parent.splice(key, 1, ...referencedElement.content);
+    } else if (isMemberElement(parent)) {
+      /**
+       * The Ref Element is substituted by the Element it references.
+       */
+      parent.value = referencedElement;
+    } else if (Array.isArray(parent)) {
+      /**
+       * The Ref Element is substituted by the Element it references.
+       */
+      parent[key] = referencedElement;
+    }
+    return !parent ? referencedElement : false;
+  }
+}
+export default ApiDOMDereferenceVisitor;

package/src/dereference/strategies/asyncapi-2/index.cjs

@@ -0,0 +1,100 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomNsAsyncapi = _interopRequireWildcard(require("@speclynx/apidom-ns-asyncapi-2"));
+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.AsyncAPI2DereferenceVisitor = _visitor.default;
+// @ts-ignore
+const visitAsync = _apidomCore.visit[Symbol.for('nodejs.util.promisify.custom')];
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class AsyncAPI2DereferenceStrategy extends _DereferenceStrategy.default {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'asyncapi-2'
+    });
+  }
+  canDereference(file) {
+    // assert by media type
+    if (file.mediaType !== 'text/plain') {
+      return _apidomNsAsyncapi.mediaTypes.includes(file.mediaType);
+    }
+
+    // assert by inspecting ApiDOM
+    return (0, _apidomNsAsyncapi.isAsyncApi2Element)(file.parseResult?.api);
+  }
+  async dereference(file, options) {
+    const namespace = (0, _apidomCore.createNamespace)(_apidomNsAsyncapi.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, _apidomCore.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 visitAsync(refSet.rootRef.value, visitor, {
+      keyMap: _apidomNsAsyncapi.keyMap,
+      nodeTypeGetter: _apidomNsAsyncapi.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.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 = AsyncAPI2DereferenceStrategy;

package/src/dereference/strategies/asyncapi-2/index.mjs

@@ -0,0 +1,94 @@
+import { createNamespace, visit, cloneDeep } from '@speclynx/apidom-core';
+import asyncApi2Namespace, { getNodeType, isAsyncApi2Element, keyMap, mediaTypes } from '@speclynx/apidom-ns-asyncapi-2';
+import DereferenceStrategy from "../DereferenceStrategy.mjs";
+import Reference from "../../../Reference.mjs";
+import ReferenceSet from "../../../ReferenceSet.mjs";
+import AsyncAPI2DereferenceVisitor from "./visitor.mjs";
+// @ts-ignore
+const visitAsync = visit[Symbol.for('nodejs.util.promisify.custom')];
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class AsyncAPI2DereferenceStrategy extends DereferenceStrategy {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'asyncapi-2'
+    });
+  }
+  canDereference(file) {
+    // assert by media type
+    if (file.mediaType !== 'text/plain') {
+      return mediaTypes.includes(file.mediaType);
+    }
+
+    // assert by inspecting ApiDOM
+    return isAsyncApi2Element(file.parseResult?.api);
+  }
+  async dereference(file, options) {
+    const namespace = createNamespace(asyncApi2Namespace);
+    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 AsyncAPI2DereferenceVisitor({
+      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 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 { AsyncAPI2DereferenceVisitor };
+export default AsyncAPI2DereferenceStrategy;