@speclynx/apidom-reference 4.0.2 → 4.0.3

package/src/options/index.cjs

@@ -0,0 +1,194 @@
+"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,
+    /**
+     * Controls error handling during dereferencing.
+     *
+     * false - fail fast, throw on first error (default)
+     * true - skip unresolvable references silently, continue dereferencing
+     * (error) => void - callback invoked for each error; if the callback
+     *   itself throws, dereferencing stops with that error
+     */
+    continueOnError: false
+  },
+  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,191 @@
+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,
+    /**
+     * Controls error handling during dereferencing.
+     *
+     * false - fail fast, throw on first error (default)
+     * true - skip unresolvable references silently, continue dereferencing
+     * (error) => void - callback invoked for each error; if the callback
+     *   itself throws, dereferencing stops with that error
+     */
+    continueOnError: false
+  },
+  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/index.ts

@@ -0,0 +1,239 @@
+import { identity } from 'ramda';
+import type { RefElement } from '@speclynx/apidom-datamodel';
+
+import type Parser from '../parse/parsers/Parser.ts';
+import type Resolver from '../resolve/resolvers/Resolver.ts';
+import type ResolveStrategy from '../resolve/strategies/ResolveStrategy.ts';
+import type DereferenceStrategy from '../dereference/strategies/DereferenceStrategy.ts';
+import type ReferenceSet from '../ReferenceSet.ts';
+import type BundleStrategy from '../bundle/strategies/BundleStrategy.ts';
+import type UnresolvableReferenceError from '../errors/UnresolvableReferenceError.ts';
+
+/**
+ * @public
+ */
+export interface ReferenceParseOptions {
+  mediaType: string;
+  parsers: Array<Parser>;
+  parserOpts: Record<string, any>;
+}
+
+/**
+ * @public
+ */
+export interface ReferenceResolveOptions {
+  baseURI: string;
+  resolvers: Array<Resolver>;
+  resolverOpts: Record<string, any>;
+  strategies: Array<ResolveStrategy>;
+  strategyOpts: Record<string, any>;
+  internal: boolean;
+  external: boolean;
+  maxDepth: number;
+}
+
+/**
+ * @public
+ */
+export interface ReferenceDereferenceOptions {
+  strategies: Array<DereferenceStrategy>;
+  strategyOpts: Record<string, any>;
+  refSet: null | ReferenceSet;
+  maxDepth: number;
+  circular: 'ignore' | 'replace' | 'error';
+  circularReplacer: (ref: RefElement) => unknown;
+  immutable: boolean;
+  continueOnError: boolean | ((error: UnresolvableReferenceError) => void);
+}
+
+/**
+ * @public
+ */
+export interface ReferenceBundleOptions {
+  strategies: Array<BundleStrategy>;
+  refSet: null | ReferenceSet;
+  maxDepth: number;
+}
+
+/**
+ * @public
+ */
+export interface ReferenceOptions {
+  readonly parse: ReferenceParseOptions;
+  readonly resolve: ReferenceResolveOptions;
+  readonly dereference: ReferenceDereferenceOptions;
+  readonly bundle: ReferenceBundleOptions;
+}
+
+/**
+ * @public
+ */
+const defaultOptions: ReferenceOptions = {
+  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,
+    /**
+     * Controls error handling during dereferencing.
+     *
+     * false - fail fast, throw on first error (default)
+     * true - skip unresolvable references silently, continue dereferencing
+     * (error) => void - callback invoked for each error; if the callback
+     *   itself throws, dereferencing stops with that error
+     */
+    continueOnError: false,
+  },
+  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/options/util.ts

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