@speclynx/apidom-reference 1.12.1

package/src/index.mjs

@@ -0,0 +1,101 @@
+import File from "./File.mjs";
+import ReferenceSet from "./ReferenceSet.mjs";
+import * as url from "./util/url.mjs";
+import defaultOptions from "./options/index.mjs";
+import { merge as mergeOptions } from "./options/util.mjs";
+import parseFn from "./parse/index.mjs";
+import resolveFn, { resolveApiDOM as resolveApiDOMFn } from "./resolve/index.mjs";
+import { readFile as readFileFn } from "./resolve/util.mjs";
+import dereferenceFn, { dereferenceApiDOM as dereferenceApiDOMFn } from "./dereference/index.mjs";
+import bundleFn from "./bundle/index.mjs";
+export { url };
+export { default as Parser } from "./parse/parsers/Parser.mjs";
+export { default as Resolver } from "./resolve/resolvers/Resolver.mjs";
+export { default as HTTPResolver } from "./resolve/resolvers/HTTPResolver.mjs";
+export { default as ResolveStrategy } from "./resolve/strategies/ResolveStrategy.mjs";
+export { default as DereferenceStrategy } from "./dereference/strategies/DereferenceStrategy.mjs";
+export { AncestorLineage as DereferenceAncestorLineage } from "./dereference/util.mjs";
+export { default as BundleStrategy } from "./bundle/strategies/BundleStrategy.mjs";
+export { default as options } from "./options/index.mjs";
+export { merge as mergeOptions } from "./options/util.mjs";
+export { File };
+export { default as Reference } from "./Reference.mjs";
+export { ReferenceSet };
+export { default as BundleError } from "./errors/BundleError.mjs";
+export { default as MaximumBundleDepthError } from "./errors/MaximumBundleDepthError.mjs";
+export { default as UnmatchedBundleStrategyError } from "./errors/UnmatchedBundleStrategyError.mjs";
+export { default as DereferenceError } from "./errors/DereferenceError.mjs";
+export { default as EvaluationElementIdError } from "./errors/EvaluationElementIdError.mjs";
+export { default as EvaluationJsonSchema$anchorError } from "./errors/EvaluationJsonSchema$anchorError.mjs";
+export { default as EvaluationJsonSchemaUriError } from "./errors/EvaluationJsonSchemaUriError.mjs";
+export { default as InvalidJsonSchema$anchorError } from "./errors/InvalidJsonSchema$anchorError.mjs";
+export { default as JsonSchema$anchorError } from "./errors/JsonSchema$anchorError.mjs";
+export { default as JsonSchemaURIError } from "./errors/JsonSchemaUriError.mjs";
+export { default as MaximumDereferenceDepthError } from "./errors/MaximumDereferenceDepthError.mjs";
+export { default as MaximumResolveDepthError } from "./errors/MaximumResolveDepthError.mjs";
+export { default as ParseError } from "./errors/ParseError.mjs";
+export { default as ParserError } from "./errors/ParserError.mjs";
+export { default as PluginError } from "./errors/PluginError.mjs";
+export { default as ResolveError } from "./errors/ResolveError.mjs";
+export { default as ResolverError } from "./errors/ResolverError.mjs";
+export { default as UnmatchedDereferenceStrategyError } from "./errors/UnmatchedDereferenceStrategyError.mjs";
+export { default as UnmatchedResolveStrategyError } from "./errors/UnmatchedResolveStrategyError.mjs";
+export { default as UnmatchedResolverError } from "./errors/UnmatchedResolverError.mjs";
+/**
+ * @public
+ */
+export const readFile = async (uri, options = {}) => {
+  const mergedOptions = mergeOptions(defaultOptions, options);
+  const file = new File({
+    uri: url.sanitize(uri)
+  });
+  return readFileFn(file, mergedOptions);
+};
+
+/**
+ * @public
+ */
+export const parse = async (uri, options = {}) => {
+  const mergedOptions = mergeOptions(defaultOptions, options);
+  return parseFn(uri, mergedOptions);
+};
+
+/**
+ * @public
+ */
+export const resolve = async (uri, options = {}) => {
+  const mergedOptions = mergeOptions(defaultOptions, options);
+  return resolveFn(uri, mergedOptions);
+};
+
+/**
+ * @public
+ */
+export const resolveApiDOM = async (element, options = {}) => {
+  const mergedOptions = mergeOptions(defaultOptions, options);
+  return resolveApiDOMFn(element, mergedOptions);
+};
+
+/**
+ * @public
+ */
+export const dereference = async (uri, options = {}) => {
+  const mergedOptions = mergeOptions(defaultOptions, options);
+  return dereferenceFn(uri, mergedOptions);
+};
+
+/**
+ * @public
+ */
+export const dereferenceApiDOM = async (element, options = {}) => {
+  const mergedOptions = mergeOptions(defaultOptions, options);
+  return dereferenceApiDOMFn(element, mergedOptions);
+};
+
+/**
+ * @public
+ */
+export const bundle = async (uri, options = {}) => {
+  const mergedOptions = mergeOptions(defaultOptions, options);
+  return bundleFn(uri, mergedOptions);
+};

package/src/options/index.cjs

@@ -0,0 +1,185 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _ramda = require("ramda");
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+const defaultOptions = {
+  parse: {
+    /**
+     * This is media type that will be used to parse the input.
+     */
+    mediaType: 'text/plain',
+    /**
+     * Determines how different types of files will be parsed.
+     *
+     * You can add additional parsers of your own, replace an existing one with
+     * your own implementation, or remove any resolver by removing it from the list.
+     * It's recommended to keep the order of parser from most specific ones to most generic ones.
+     */
+    parsers: [],
+    /**
+     * These options are merged with parser plugin instance before the plugin is run.
+     */
+    parserOpts: {}
+  },
+  resolve: {
+    /**
+     * baseURI serves as a base for all relative URL found in ApiDOM references.
+     */
+    baseURI: '',
+    /**
+     * Determines how References will be resolved.
+     *
+     * You can add additional resolvers of your own, replace an existing one with
+     * your own implementation, or remove any resolver by removing it from the list.
+     */
+    resolvers: [],
+    /**
+     * These options are merged with resolver plugin instance before the plugin is run.
+     */
+    resolverOpts: {},
+    /**
+     * Determines strategies how References are identified and processed by resolvers.
+     * Strategy is determined by media type.
+     *
+     * You can add additional resolver strategies of your own, replace an existing one with
+     * your own implementation, or remove any resolve strategy by removing it from the list.
+     */
+    strategies: [],
+    /**
+     * These options are available in resolver strategy `canResolve` and `resolve` methods.
+     */
+    strategyOpts: {},
+    /**
+     * Determines whether internal references will be resolved.
+     * Internal references will simply be ignored.
+     */
+    internal: true,
+    /**
+     * Determines whether external references will be resolved.
+     * If this option is disabled, then none of above resolvers will be called.
+     * Instead, external references will simply be ignored.
+     */
+    external: true,
+    /**
+     * Determines the maximum depth of resolve algorithms.
+     * By default, there is no limit.
+     *
+     * This option tracks the depth of the file tree not the depth of the dereference path.
+     *
+     * It can be set to any positive integer number or zero (0).
+     *
+     * The resolver should throw MaximumResolverDepthError if resolution depth
+     * is exceeded by this option.
+     */
+    maxDepth: +Infinity
+  },
+  dereference: {
+    /**
+     * Determines strategies how ApiDOM is dereferenced.
+     * Strategy is determined by media type or by inspecting ApiDOM to be dereferenced.
+     *
+     * You can add additional dereference strategies of your own, replace an existing one with
+     * your own implementation, or remove any dereference strategy by removing it from the list.
+     */
+    strategies: [],
+    /**
+     * These options are available in dereference strategy `canDereference` and `dereference` methods.
+     */
+    strategyOpts: {},
+    /**
+     * This option accepts an instance of pre-computed ReferenceSet.
+     * If provided it will speed up the dereferencing significantly as the external
+     * resolution doesn't need to happen anymore.
+     */
+    refSet: null,
+    /**
+     * Determines the maximum depth of dereferencing.
+     * By default, there is no limit.
+     *
+     * The maxDepth represents a number of references that needed to be followed
+     * before the eventual value was reached.
+     *
+     * It can be set to any positive integer number or zero (0).
+     *
+     * The dereferencing should throw MaximumDereferenceDepthError if dereferencing depth
+     * is exceeded by this option.
+     */
+    maxDepth: +Infinity,
+    /**
+     * Determines how circular references are handled.
+     *
+     * "ignore" - circular reference are allowed
+     * "replace" - circular references are not allowed and are translated to RefElement
+     * "error" - circular references are not allowed and will throw an error
+     */
+    circular: 'ignore',
+    /**
+     * This function is used to replace circular references when `circular` option is set to "replace".
+     * By default, it's an identity function. It means that circular references are replaced with RefElement.
+     */
+    circularReplacer: _ramda.identity,
+    /**
+     * Determines whether the dereferencing process will be immutable.
+     * By default, the dereferencing process is immutable, which means that the original
+     * ApiDOM passed to the dereference process is NOT modified.
+     *
+     * true - the dereferencing process will be immutable (deep cloning of ApiDOM is involved)
+     * false - the dereferencing process will be mutable
+     */
+    immutable: true
+  },
+  bundle: {
+    /**
+     * Determines strategies how ApiDOM is bundled.
+     * Strategy is determined by media type or by inspecting ApiDOM to be bundled.
+     *
+     * You can add additional bundle strategies of your own, replace an existing one with
+     * your own implementation, or remove any bundle strategy by removing it from the list.
+     */
+    strategies: [],
+    /**
+     * This option accepts an instance of pre-computed ReferenceSet.
+     * If provided it will speed up the bundling significantly as the external
+     * resolution doesn't need to happen anymore.
+     */
+    refSet: null,
+    /**
+     * Determines the maximum depth of bundling.
+     * By default, there is no limit.
+     *
+     * The maxDepth represents a number of references that needed to be followed
+     * before the eventual value was reached.
+     *
+     * It can be set to any positive integer number or zero (0).
+     *
+     * The bundling should throw MaximumBundleDepthError if bundling depth
+     * is exceeded by this option.
+     */
+    maxDepth: +Infinity
+  }
+};
+var _default = exports.default = defaultOptions;

package/src/options/index.mjs

@@ -0,0 +1,182 @@
+import { identity } from 'ramda';
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+const defaultOptions = {
+  parse: {
+    /**
+     * This is media type that will be used to parse the input.
+     */
+    mediaType: 'text/plain',
+    /**
+     * Determines how different types of files will be parsed.
+     *
+     * You can add additional parsers of your own, replace an existing one with
+     * your own implementation, or remove any resolver by removing it from the list.
+     * It's recommended to keep the order of parser from most specific ones to most generic ones.
+     */
+    parsers: [],
+    /**
+     * These options are merged with parser plugin instance before the plugin is run.
+     */
+    parserOpts: {}
+  },
+  resolve: {
+    /**
+     * baseURI serves as a base for all relative URL found in ApiDOM references.
+     */
+    baseURI: '',
+    /**
+     * Determines how References will be resolved.
+     *
+     * You can add additional resolvers of your own, replace an existing one with
+     * your own implementation, or remove any resolver by removing it from the list.
+     */
+    resolvers: [],
+    /**
+     * These options are merged with resolver plugin instance before the plugin is run.
+     */
+    resolverOpts: {},
+    /**
+     * Determines strategies how References are identified and processed by resolvers.
+     * Strategy is determined by media type.
+     *
+     * You can add additional resolver strategies of your own, replace an existing one with
+     * your own implementation, or remove any resolve strategy by removing it from the list.
+     */
+    strategies: [],
+    /**
+     * These options are available in resolver strategy `canResolve` and `resolve` methods.
+     */
+    strategyOpts: {},
+    /**
+     * Determines whether internal references will be resolved.
+     * Internal references will simply be ignored.
+     */
+    internal: true,
+    /**
+     * Determines whether external references will be resolved.
+     * If this option is disabled, then none of above resolvers will be called.
+     * Instead, external references will simply be ignored.
+     */
+    external: true,
+    /**
+     * Determines the maximum depth of resolve algorithms.
+     * By default, there is no limit.
+     *
+     * This option tracks the depth of the file tree not the depth of the dereference path.
+     *
+     * It can be set to any positive integer number or zero (0).
+     *
+     * The resolver should throw MaximumResolverDepthError if resolution depth
+     * is exceeded by this option.
+     */
+    maxDepth: +Infinity
+  },
+  dereference: {
+    /**
+     * Determines strategies how ApiDOM is dereferenced.
+     * Strategy is determined by media type or by inspecting ApiDOM to be dereferenced.
+     *
+     * You can add additional dereference strategies of your own, replace an existing one with
+     * your own implementation, or remove any dereference strategy by removing it from the list.
+     */
+    strategies: [],
+    /**
+     * These options are available in dereference strategy `canDereference` and `dereference` methods.
+     */
+    strategyOpts: {},
+    /**
+     * This option accepts an instance of pre-computed ReferenceSet.
+     * If provided it will speed up the dereferencing significantly as the external
+     * resolution doesn't need to happen anymore.
+     */
+    refSet: null,
+    /**
+     * Determines the maximum depth of dereferencing.
+     * By default, there is no limit.
+     *
+     * The maxDepth represents a number of references that needed to be followed
+     * before the eventual value was reached.
+     *
+     * It can be set to any positive integer number or zero (0).
+     *
+     * The dereferencing should throw MaximumDereferenceDepthError if dereferencing depth
+     * is exceeded by this option.
+     */
+    maxDepth: +Infinity,
+    /**
+     * Determines how circular references are handled.
+     *
+     * "ignore" - circular reference are allowed
+     * "replace" - circular references are not allowed and are translated to RefElement
+     * "error" - circular references are not allowed and will throw an error
+     */
+    circular: 'ignore',
+    /**
+     * This function is used to replace circular references when `circular` option is set to "replace".
+     * By default, it's an identity function. It means that circular references are replaced with RefElement.
+     */
+    circularReplacer: identity,
+    /**
+     * Determines whether the dereferencing process will be immutable.
+     * By default, the dereferencing process is immutable, which means that the original
+     * ApiDOM passed to the dereference process is NOT modified.
+     *
+     * true - the dereferencing process will be immutable (deep cloning of ApiDOM is involved)
+     * false - the dereferencing process will be mutable
+     */
+    immutable: true
+  },
+  bundle: {
+    /**
+     * Determines strategies how ApiDOM is bundled.
+     * Strategy is determined by media type or by inspecting ApiDOM to be bundled.
+     *
+     * You can add additional bundle strategies of your own, replace an existing one with
+     * your own implementation, or remove any bundle strategy by removing it from the list.
+     */
+    strategies: [],
+    /**
+     * This option accepts an instance of pre-computed ReferenceSet.
+     * If provided it will speed up the bundling significantly as the external
+     * resolution doesn't need to happen anymore.
+     */
+    refSet: null,
+    /**
+     * Determines the maximum depth of bundling.
+     * By default, there is no limit.
+     *
+     * The maxDepth represents a number of references that needed to be followed
+     * before the eventual value was reached.
+     *
+     * It can be set to any positive integer number or zero (0).
+     *
+     * The bundling should throw MaximumBundleDepthError if bundling depth
+     * is exceeded by this option.
+     */
+    maxDepth: +Infinity
+  }
+};
+export default defaultOptions;

package/src/options/util.cjs

@@ -0,0 +1,24 @@
+"use strict";
+
+exports.__esModule = true;
+exports.merge = void 0;
+var _ramda = require("ramda");
+var _ramdaAdjunct = require("ramda-adjunct");
+var _url = require("../util/url.cjs");
+/**
+ * Algorithm for deep merging options.
+ */
+
+const baseURILens = (0, _ramda.lens)((0, _ramda.path)(['resolve', 'baseURI']), (0, _ramda.assocPath)(['resolve', 'baseURI']));
+const baseURIDefault = baseURI => (0, _ramdaAdjunct.isEmptyString)(baseURI) ? (0, _url.cwd)() : baseURI;
+
+/**
+ * @public
+ */
+
+const merge = (lObj, rObj) => {
+  const withoutDefaults = (0, _ramda.mergeDeepRight)(lObj, rObj);
+  // @ts-ignore
+  return (0, _ramda.over)(baseURILens, baseURIDefault, withoutDefaults);
+};
+exports.merge = merge;

package/src/options/util.mjs

@@ -0,0 +1,19 @@
+import { mergeDeepRight, lens, path, assocPath, over } from 'ramda';
+import { isEmptyString } from 'ramda-adjunct';
+import { cwd } from "../util/url.mjs";
+/**
+ * Algorithm for deep merging options.
+ */
+
+const baseURILens = lens(path(['resolve', 'baseURI']), assocPath(['resolve', 'baseURI']));
+const baseURIDefault = baseURI => isEmptyString(baseURI) ? cwd() : baseURI;
+
+/**
+ * @public
+ */
+
+export const merge = (lObj, rObj) => {
+  const withoutDefaults = mergeDeepRight(lObj, rObj);
+  // @ts-ignore
+  return over(baseURILens, baseURIDefault, withoutDefaults);
+};

package/src/parse/index.cjs

@@ -0,0 +1,69 @@
+"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 _ramda = require("ramda");
+var url = _interopRequireWildcard(require("../util/url.cjs"));
+var _File = _interopRequireDefault(require("../File.cjs"));
+var plugins = _interopRequireWildcard(require("../util/plugins.cjs"));
+var _ParseError = _interopRequireDefault(require("../errors/ParseError.cjs"));
+var _UnmatchedResolverError = _interopRequireDefault(require("../errors/UnmatchedResolverError.cjs"));
+var _util = require("../resolve/util.cjs");
+/**
+ * Parses the given file's contents, using the configured parser plugins.
+ */
+const parseFile = async (file, options) => {
+  const optsBoundParsers = options.parse.parsers.map(parser => {
+    const clonedParser = Object.create(parser);
+    return Object.assign(clonedParser, options.parse.parserOpts);
+  });
+  const parsers = await plugins.filter('canParse', [file, options], optsBoundParsers);
+
+  // we couldn't find any parser for this File
+  if ((0, _ramda.isEmpty)(parsers)) {
+    throw new _UnmatchedResolverError.default(file.uri);
+  }
+  try {
+    const {
+      plugin,
+      result
+    } = await plugins.run('parse', [file, options], parsers);
+
+    // empty files handling
+    if (!plugin.allowEmpty && result.isEmpty) {
+      return Promise.reject(new _ParseError.default(`Error while parsing file "${file.uri}". File is empty.`));
+    }
+    return result;
+  } catch (error) {
+    throw new _ParseError.default(`Error while parsing file "${file.uri}"`, {
+      cause: error
+    });
+  }
+};
+
+/**
+ * Parses a file into ApiDOM.
+ */
+const parse = async (uri, options) => {
+  /**
+   * If the path is a filesystem path, then convert it to a URL.
+   *
+   * NOTE: According to the JSON Reference spec, these should already be URLs,
+   * but, in practice, many people use local filesystem paths instead.
+   * So we're being generous here and doing the conversion automatically.
+   * This is not intended to be a 100% bulletproof solution.
+   * If it doesn't work for your use-case, then use a URL instead.
+   */
+  const file = new _File.default({
+    uri: url.sanitize(url.stripHash(uri)),
+    mediaType: options.parse.mediaType
+  });
+  const data = await (0, _util.readFile)(file, options);
+  return parseFile(new _File.default({
+    ...file,
+    data
+  }), options);
+};
+var _default = exports.default = parse;

package/src/parse/index.mjs

@@ -0,0 +1,63 @@
+import { isEmpty } from 'ramda';
+import * as url from "../util/url.mjs";
+import File from "../File.mjs";
+import * as plugins from "../util/plugins.mjs";
+import ParseError from "../errors/ParseError.mjs";
+import UnmatchedResolverError from "../errors/UnmatchedResolverError.mjs";
+import { readFile } from "../resolve/util.mjs";
+/**
+ * Parses the given file's contents, using the configured parser plugins.
+ */
+const parseFile = async (file, options) => {
+  const optsBoundParsers = options.parse.parsers.map(parser => {
+    const clonedParser = Object.create(parser);
+    return Object.assign(clonedParser, options.parse.parserOpts);
+  });
+  const parsers = await plugins.filter('canParse', [file, options], optsBoundParsers);
+
+  // we couldn't find any parser for this File
+  if (isEmpty(parsers)) {
+    throw new UnmatchedResolverError(file.uri);
+  }
+  try {
+    const {
+      plugin,
+      result
+    } = await plugins.run('parse', [file, options], parsers);
+
+    // empty files handling
+    if (!plugin.allowEmpty && result.isEmpty) {
+      return Promise.reject(new ParseError(`Error while parsing file "${file.uri}". File is empty.`));
+    }
+    return result;
+  } catch (error) {
+    throw new ParseError(`Error while parsing file "${file.uri}"`, {
+      cause: error
+    });
+  }
+};
+
+/**
+ * Parses a file into ApiDOM.
+ */
+const parse = async (uri, options) => {
+  /**
+   * If the path is a filesystem path, then convert it to a URL.
+   *
+   * NOTE: According to the JSON Reference spec, these should already be URLs,
+   * but, in practice, many people use local filesystem paths instead.
+   * So we're being generous here and doing the conversion automatically.
+   * This is not intended to be a 100% bulletproof solution.
+   * If it doesn't work for your use-case, then use a URL instead.
+   */
+  const file = new File({
+    uri: url.sanitize(url.stripHash(uri)),
+    mediaType: options.parse.mediaType
+  });
+  const data = await readFile(file, options);
+  return parseFile(new File({
+    ...file,
+    data
+  }), options);
+};
+export default parse;

package/src/parse/parsers/Parser.cjs

@@ -0,0 +1,48 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class Parser {
+  name;
+
+  /**
+   * Whether to allow "empty" files. This includes zero-byte files.
+   */
+  allowEmpty;
+
+  /**
+   * Whether to generate source map during parsing.
+   */
+  sourceMap;
+
+  /**
+   * List of supported file extensions.
+   */
+  fileExtensions;
+
+  /**
+   * List of supported media types.
+   */
+  mediaTypes;
+  constructor({
+    name,
+    allowEmpty = true,
+    sourceMap = false,
+    fileExtensions = [],
+    mediaTypes = []
+  }) {
+    this.name = name;
+    this.allowEmpty = allowEmpty;
+    this.sourceMap = sourceMap;
+    this.fileExtensions = fileExtensions;
+    this.mediaTypes = mediaTypes;
+  }
+}
+var _default = exports.default = Parser;