@speclynx/apidom-reference 4.0.2 → 4.0.4

package/src/configuration/saturated.mjs

@@ -0,0 +1,80 @@
+import FileResolver from "../resolve/resolvers/file/index-node.mjs";
+import HTTPResolverAxios from "../resolve/resolvers/http-axios/index.mjs";
+import OpenAPI2ResolveStrategy from "../resolve/strategies/openapi-2/index.mjs";
+import OpenAPI3_0ResolveStrategy from "../resolve/strategies/openapi-3-0/index.mjs";
+import OpenAPI3_1ResolveStrategy from "../resolve/strategies/openapi-3-1/index.mjs";
+import AsyncAPI2ResolveStrategy from "../resolve/strategies/asyncapi-2/index.mjs";
+import ApiDOMResolveStrategy from "../resolve/strategies/apidom/index.mjs";
+import OpenAPIJSON2Parser from "../parse/parsers/openapi-json-2/index.mjs";
+import OpenAPIYAML2Parser from "../parse/parsers/openapi-yaml-2/index.mjs";
+import OpenAPIJSON3_0Parser from "../parse/parsers/openapi-json-3-0/index.mjs";
+import OpenAPIYAML3_0Parser from "../parse/parsers/openapi-yaml-3-0/index.mjs";
+import OpenAPIJSON3_1Parser from "../parse/parsers/openapi-json-3-1/index.mjs";
+import OpenAPIYAML3_1Parser from "../parse/parsers/openapi-yaml-3-1/index.mjs";
+import AsyncAPIJSON2Parser from "../parse/parsers/asyncapi-json-2/index.mjs";
+import AsyncAPIYAML2Parser from "../parse/parsers/asyncapi-yaml-2/index.mjs";
+import ArazzoJSON1Parser from "../parse/parsers/arazzo-json-1/index.mjs";
+import ArazzoYAML1Parser from "../parse/parsers/arazzo-yaml-1/index.mjs";
+import APIDOMJSONParser from "../parse/parsers/apidom-json/index.mjs";
+import JSONParser from "../parse/parsers/json/index.mjs";
+import YAMLParser from "../parse/parsers/yaml-1-2/index.mjs";
+import BinaryParser from "../parse/parsers/binary/index-node.mjs";
+import ApiDOMDereferenceStrategy from "../dereference/strategies/apidom/index.mjs";
+import OpenAPI2DereferenceStrategy from "../dereference/strategies/openapi-2/index.mjs";
+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({
+  allowEmpty: true,
+  sourceMap: false
+}), new OpenAPIYAML2Parser({
+  allowEmpty: true,
+  sourceMap: false
+}), new OpenAPIJSON3_0Parser({
+  allowEmpty: true,
+  sourceMap: false
+}), new OpenAPIYAML3_0Parser({
+  allowEmpty: true,
+  sourceMap: false
+}), new OpenAPIJSON3_1Parser({
+  allowEmpty: true,
+  sourceMap: false
+}), new OpenAPIYAML3_1Parser({
+  allowEmpty: true,
+  sourceMap: false
+}), new AsyncAPIJSON2Parser({
+  allowEmpty: true,
+  sourceMap: false
+}), new AsyncAPIYAML2Parser({
+  allowEmpty: true,
+  sourceMap: false
+}), new ArazzoJSON1Parser({
+  allowEmpty: true,
+  sourceMap: false
+}), new ArazzoYAML1Parser({
+  allowEmpty: true,
+  sourceMap: false
+}), new APIDOMJSONParser({
+  allowEmpty: true,
+  sourceMap: false
+}), new JSONParser({
+  allowEmpty: true,
+  sourceMap: false
+}), new YAMLParser({
+  allowEmpty: true,
+  sourceMap: false
+}), new BinaryParser({
+  allowEmpty: true
+})];
+options.resolve.resolvers = [new FileResolver(), new HTTPResolverAxios({
+  timeout: 5000,
+  redirects: 5,
+  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 Arazzo1DereferenceStrategy(), new ApiDOMDereferenceStrategy()];
+options.bundle.strategies = [new OpenAPI3_1BundleStrategy()];
+export * from "../index.mjs";

package/src/dereference/index.cjs

@@ -0,0 +1,90 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.dereferenceApiDOM = exports.default = void 0;
+var _ramda = require("ramda");
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _File = _interopRequireDefault(require("../File.cjs"));
+var plugins = _interopRequireWildcard(require("../util/plugins.cjs"));
+var _UnmatchedDereferenceStrategyError = _interopRequireDefault(require("../errors/UnmatchedDereferenceStrategyError.cjs"));
+var _DereferenceError = _interopRequireDefault(require("../errors/DereferenceError.cjs"));
+var _UnresolvableReferenceError = _interopRequireDefault(require("../errors/UnresolvableReferenceError.cjs"));
+var _index = _interopRequireDefault(require("../parse/index.cjs"));
+var _util = require("../options/util.cjs");
+var url = _interopRequireWildcard(require("../util/url.cjs"));
+/**
+ * Dereferences ApiDOM with all its external references.
+ */
+const dereferenceApiDOM = async (element, options) => {
+  // @ts-ignore
+  let parseResult = element;
+  let surrogateWrapping = false;
+
+  // wrap element into parse result
+  if (!(0, _apidomDatamodel.isParseResultElement)(element)) {
+    const elementClone = (0, _apidomDatamodel.cloneShallow)(element);
+    elementClone.classes.push('result');
+    parseResult = new _apidomDatamodel.ParseResultElement([elementClone]);
+    surrogateWrapping = true;
+  }
+  const file = new _File.default({
+    uri: options.resolve.baseURI,
+    parseResult,
+    mediaType: options.parse.mediaType
+  });
+  const dereferenceStrategies = await plugins.filter('canDereference', [file, options], options.dereference.strategies);
+
+  // we couldn't find any dereference strategy for this File
+  if ((0, _ramda.isEmpty)(dereferenceStrategies)) {
+    throw new _UnmatchedDereferenceStrategyError.default(`Could not find a dereference strategy that can dereference the file "${file.uri}"`);
+  }
+  try {
+    const {
+      result
+    } = await plugins.run('dereference', [file, options], dereferenceStrategies);
+    // unwrap the element from ParseResult assuming first element is the actual result
+    return surrogateWrapping ? result.get(0) : result;
+  } catch (error) {
+    if (error instanceof _UnresolvableReferenceError.default) {
+      throw error;
+    }
+    throw new _DereferenceError.default(`Error while dereferencing file "${file.uri}"`, {
+      cause: error
+    });
+  }
+};
+
+/**
+ * Dereferences a file with all its external references.
+ */
+exports.dereferenceApiDOM = dereferenceApiDOM;
+const dereference = async (uri, options) => {
+  const {
+    refSet
+  } = options.dereference;
+  const sanitizedURI = url.sanitize(uri);
+  let parseResult;
+
+  // if refSet was provided, use it to avoid unnecessary parsing
+  if (refSet !== null && refSet.has(sanitizedURI)) {
+    // @ts-ignore
+    ({
+      value: parseResult
+    } = refSet.find((0, _ramda.propEq)(sanitizedURI, 'uri')));
+  } else {
+    parseResult = await (0, _index.default)(uri, options);
+  }
+  const mergedOptions = (0, _util.merge)(options, {
+    resolve: {
+      baseURI: sanitizedURI
+    },
+    dereference: {
+      // if refSet was not provided, then we can work in mutable mode
+      immutable: options.dereference.immutable && refSet !== null
+    }
+  });
+  return dereferenceApiDOM(parseResult, mergedOptions);
+};
+var _default = exports.default = dereference;

package/src/dereference/index.mjs

@@ -0,0 +1,83 @@
+import { isEmpty, propEq } from 'ramda';
+import { isParseResultElement, ParseResultElement, cloneShallow } from '@speclynx/apidom-datamodel';
+import File from "../File.mjs";
+import * as plugins from "../util/plugins.mjs";
+import UnmatchedDereferenceStrategyError from "../errors/UnmatchedDereferenceStrategyError.mjs";
+import DereferenceError from "../errors/DereferenceError.mjs";
+import UnresolvableReferenceError from "../errors/UnresolvableReferenceError.mjs";
+import parse from "../parse/index.mjs";
+import { merge as mergeOptions } from "../options/util.mjs";
+import * as url from "../util/url.mjs";
+/**
+ * Dereferences ApiDOM with all its external references.
+ */
+export const dereferenceApiDOM = async (element, options) => {
+  // @ts-ignore
+  let parseResult = element;
+  let surrogateWrapping = false;
+
+  // wrap element into parse result
+  if (!isParseResultElement(element)) {
+    const elementClone = cloneShallow(element);
+    elementClone.classes.push('result');
+    parseResult = new ParseResultElement([elementClone]);
+    surrogateWrapping = true;
+  }
+  const file = new File({
+    uri: options.resolve.baseURI,
+    parseResult,
+    mediaType: options.parse.mediaType
+  });
+  const dereferenceStrategies = await plugins.filter('canDereference', [file, options], options.dereference.strategies);
+
+  // we couldn't find any dereference strategy for this File
+  if (isEmpty(dereferenceStrategies)) {
+    throw new UnmatchedDereferenceStrategyError(`Could not find a dereference strategy that can dereference the file "${file.uri}"`);
+  }
+  try {
+    const {
+      result
+    } = await plugins.run('dereference', [file, options], dereferenceStrategies);
+    // unwrap the element from ParseResult assuming first element is the actual result
+    return surrogateWrapping ? result.get(0) : result;
+  } catch (error) {
+    if (error instanceof UnresolvableReferenceError) {
+      throw error;
+    }
+    throw new DereferenceError(`Error while dereferencing file "${file.uri}"`, {
+      cause: error
+    });
+  }
+};
+
+/**
+ * Dereferences a file with all its external references.
+ */
+const dereference = async (uri, options) => {
+  const {
+    refSet
+  } = options.dereference;
+  const sanitizedURI = url.sanitize(uri);
+  let parseResult;
+
+  // if refSet was provided, use it to avoid unnecessary parsing
+  if (refSet !== null && refSet.has(sanitizedURI)) {
+    // @ts-ignore
+    ({
+      value: parseResult
+    } = refSet.find(propEq(sanitizedURI, 'uri')));
+  } else {
+    parseResult = await parse(uri, options);
+  }
+  const mergedOptions = mergeOptions(options, {
+    resolve: {
+      baseURI: sanitizedURI
+    },
+    dereference: {
+      // if refSet was not provided, then we can work in mutable mode
+      immutable: options.dereference.immutable && refSet !== null
+    }
+  });
+  return dereferenceApiDOM(parseResult, mergedOptions);
+};
+export default dereference;

package/src/dereference/strategies/DereferenceStrategy.cjs

@@ -0,0 +1,20 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class DereferenceStrategy {
+  name;
+  constructor({
+    name
+  }) {
+    this.name = name;
+  }
+}
+var _default = exports.default = DereferenceStrategy;

package/src/dereference/strategies/DereferenceStrategy.mjs

@@ -0,0 +1,16 @@
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class DereferenceStrategy {
+  name;
+  constructor({
+    name
+  }) {
+    this.name = name;
+  }
+}
+export default DereferenceStrategy;

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

@@ -0,0 +1,89 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomTraverse = require("@speclynx/apidom-traverse");
+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.ApiDOMDereferenceVisitor = _visitor.default;
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class ApiDOMDereferenceStrategy extends _DereferenceStrategy.default {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'apidom'
+    });
+  }
+  canDereference(file) {
+    return file.mediaType.startsWith('application/vnd.apidom') && (0, _apidomDatamodel.isElement)(file.parseResult?.result);
+  }
+  async dereference(file, options) {
+    const immutableRefSet = options.dereference.refSet ?? new _ReferenceSet.default();
+    const mutableRefSet = new _ReferenceSet.default();
+    let refSet = immutableRefSet;
+    let reference;
+
+    // determine the initial 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: reference,
+      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 = ApiDOMDereferenceStrategy;

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

@@ -0,0 +1,83 @@
+import { isElement, cloneDeep } from '@speclynx/apidom-datamodel';
+import { traverseAsync } from '@speclynx/apidom-traverse';
+import DereferenceStrategy from "../DereferenceStrategy.mjs";
+import Reference from "../../../Reference.mjs";
+import ReferenceSet from "../../../ReferenceSet.mjs";
+import ApiDOMDereferenceVisitor from "./visitor.mjs";
+/**
+ * @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 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 { ApiDOMDereferenceVisitor };
+export default ApiDOMDereferenceStrategy;

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

@@ -0,0 +1,47 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.evaluate = void 0;
+var _ramdaAdjunct = require("ramda-adjunct");
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomTraverse = require("@speclynx/apidom-traverse");
+var _EvaluationElementIdError = _interopRequireDefault(require("../../../../errors/EvaluationElementIdError.cjs"));
+exports.EvaluationElementIdError = _EvaluationElementIdError.default;
+const getElementID = element => {
+  const id = element.meta.get('id');
+  // handle both raw string (new format) and StringElement (legacy Refract without __meta_raw__)
+  return (0, _apidomDatamodel.isElement)(id) ? (0, _apidomCore.toValue)(id) : id;
+};
+const hasElementID = path => {
+  if (!path.node.hasMetaProperty('id')) return false;
+  const id = getElementID(path.node);
+  return typeof id === 'string' && id !== '';
+};
+
+/**
+ * Evaluates element ID against ApiDOM fragment.
+ * @public
+ */
+const evaluate = (elementID, element) => {
+  const {
+    cache
+  } = evaluate;
+  // warm the cache
+  if (!cache.has(element)) {
+    const pathsWithID = (0, _apidomTraverse.filter)(element, hasElementID);
+    cache.set(element, pathsWithID.map(path => path.node));
+  }
+
+  // search for the matching element
+  const result = cache.get(element).find(e => {
+    return getElementID(e) === 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,41 @@
+import { isUndefined } from 'ramda-adjunct';
+import { isElement } from '@speclynx/apidom-datamodel';
+import { toValue } from '@speclynx/apidom-core';
+import { filter } from '@speclynx/apidom-traverse';
+import EvaluationElementIdError from "../../../../errors/EvaluationElementIdError.mjs";
+const getElementID = element => {
+  const id = element.meta.get('id');
+  // handle both raw string (new format) and StringElement (legacy Refract without __meta_raw__)
+  return isElement(id) ? toValue(id) : id;
+};
+const hasElementID = path => {
+  if (!path.node.hasMetaProperty('id')) return false;
+  const id = getElementID(path.node);
+  return typeof id === 'string' && id !== '';
+};
+
+/**
+ * Evaluates element ID against ApiDOM fragment.
+ * @public
+ */
+export const evaluate = (elementID, element) => {
+  const {
+    cache
+  } = evaluate;
+  // warm the cache
+  if (!cache.has(element)) {
+    const pathsWithID = filter(element, hasElementID);
+    cache.set(element, pathsWithID.map(path => path.node));
+  }
+
+  // search for the matching element
+  const result = cache.get(element).find(e => {
+    return getElementID(e) === elementID;
+  });
+  if (isUndefined(result)) {
+    throw new EvaluationElementIdError(`Evaluation failed on element ID: "${elementID}"`);
+  }
+  return result;
+};
+evaluate.cache = new WeakMap();
+export { EvaluationElementIdError };