@speclynx/apidom-reference 4.0.3 → 4.0.5

package/src/dereference/util.ts

@@ -1,29 +0,0 @@
-import { Element, isElement } from '@speclynx/apidom-datamodel';
-
-/**
- * @public
- */
-
-export class AncestorLineage<T extends Element> extends Array<Set<T>> {
-  includesCycle(element: T) {
-    return this.filter((ancestors) => ancestors.has(element)).length > 1;
-  }
-
-  includes(searchElement: Set<T> | T, fromIndex?: number): boolean {
-    if (searchElement instanceof Set) {
-      return super.includes(searchElement, fromIndex);
-    }
-    return this.some((ancestors) => ancestors.has(searchElement));
-  }
-
-  findItem(predicate: (item: T) => boolean): T | undefined {
-    for (const set of this) {
-      for (const item of set) {
-        if (isElement(item) && predicate(item)) {
-          return item;
-        }
-      }
-    }
-    return undefined;
-  }
-}

package/src/errors/BundleError.ts

@@ -1,8 +0,0 @@
-import { ApiDOMError } from '@speclynx/apidom-error';
-
-/**
- * @public
- */
-class BundleError extends ApiDOMError {}
-
-export default BundleError;

package/src/errors/DereferenceError.ts

@@ -1,8 +0,0 @@
-import { ApiDOMStructuredError } from '@speclynx/apidom-error';
-
-/**
- * @public
- */
-class DereferenceError extends ApiDOMStructuredError {}
-
-export default DereferenceError;

package/src/errors/EvaluationElementIdError.ts

@@ -1,8 +0,0 @@
-import { ApiDOMError } from '@speclynx/apidom-error';
-
-/**
- * @public
- */
-class EvaluationElementIdError extends ApiDOMError {}
-
-export default EvaluationElementIdError;

package/src/errors/EvaluationJsonSchema$anchorError.ts

@@ -1,8 +0,0 @@
-import JsonSchema$anchorError from './JsonSchema$anchorError.ts';
-
-/**
- * @public
- */
-class EvaluationJsonSchema$anchorError extends JsonSchema$anchorError {}
-
-export default EvaluationJsonSchema$anchorError;

package/src/errors/EvaluationJsonSchemaUriError.ts

@@ -1,8 +0,0 @@
-import JsonSchemaUriError from './JsonSchemaUriError.ts';
-
-/**
- * @public
- */
-class EvaluationJsonSchemaUriError extends JsonSchemaUriError {}
-
-export default EvaluationJsonSchemaUriError;

package/src/errors/InvalidJsonSchema$anchorError.ts

@@ -1,12 +0,0 @@
-import JsonSchema$anchorError from './JsonSchema$anchorError.ts';
-
-/**
- * @public
- */
-class InvalidJsonSchema$anchorError extends JsonSchema$anchorError {
-  constructor(anchor: string) {
-    super(`Invalid JSON Schema $anchor "${anchor}"`);
-  }
-}
-
-export default InvalidJsonSchema$anchorError;

package/src/errors/JsonSchema$anchorError.ts

@@ -1,8 +0,0 @@
-import { ApiDOMError } from '@speclynx/apidom-error';
-
-/**
- * @public
- */
-class JsonSchema$anchorError extends ApiDOMError {}
-
-export default JsonSchema$anchorError;

package/src/errors/JsonSchemaUriError.ts

@@ -1,8 +0,0 @@
-import { ApiDOMError } from '@speclynx/apidom-error';
-
-/**
- * @public
- */
-class JsonSchemaUriError extends ApiDOMError {}
-
-export default JsonSchemaUriError;

package/src/errors/MaximumBundleDepthError.ts

@@ -1,8 +0,0 @@
-import BundleError from './BundleError.ts';
-
-/**
- * @public
- */
-class MaximumBundleDepthError extends BundleError {}
-
-export default MaximumBundleDepthError;

package/src/errors/MaximumDereferenceDepthError.ts

@@ -1,8 +0,0 @@
-import DereferenceError from './DereferenceError.ts';
-
-/**
- * @public
- */
-class MaximumDereferenceDepthError extends DereferenceError {}
-
-export default MaximumDereferenceDepthError;

package/src/errors/MaximumResolveDepthError.ts

@@ -1,8 +0,0 @@
-import ResolveError from './ResolveError.ts';
-
-/**
- * @public
- */
-class MaximumResolveDepthError extends ResolveError {}
-
-export default MaximumResolveDepthError;

package/src/errors/ParseError.ts

@@ -1,8 +0,0 @@
-import { ApiDOMError } from '@speclynx/apidom-error';
-
-/**
- * @public
- */
-class ParseError extends ApiDOMError {}
-
-export default ParseError;

package/src/errors/ParserError.ts

@@ -1,8 +0,0 @@
-import ParseError from './ParseError.ts';
-
-/**
- * @public
- */
-class ParserError extends ParseError {}
-
-export default ParserError;

package/src/errors/PluginError.ts

@@ -1,15 +0,0 @@
-import { ApiDOMError } from '@speclynx/apidom-error';
-
-/**
- * @public
- */
-class PluginError extends ApiDOMError {
-  public plugin: any;
-
-  constructor(message: string, options: { cause?: Error; plugin: any }) {
-    super(message, { cause: options.cause });
-    this.plugin = options.plugin;
-  }
-}
-
-export default PluginError;

package/src/errors/ResolveError.ts

@@ -1,8 +0,0 @@
-import { ApiDOMStructuredError } from '@speclynx/apidom-error';
-
-/**
- * @public
- */
-class ResolveError extends ApiDOMStructuredError {}
-
-export default ResolveError;

package/src/errors/ResolverError.ts

@@ -1,8 +0,0 @@
-import ResolveError from './ResolveError.ts';
-
-/**
- * @public
- */
-class ResolverError extends ResolveError {}
-
-export default ResolverError;

package/src/errors/UnmatchedBundleStrategyError.ts

@@ -1,8 +0,0 @@
-import BundleError from './BundleError.ts';
-
-/**
- * @public
- */
-class UnmatchedBundleStrategyError extends BundleError {}
-
-export default UnmatchedBundleStrategyError;

package/src/errors/UnmatchedDereferenceStrategyError.ts

@@ -1,8 +0,0 @@
-import DereferenceError from './DereferenceError.ts';
-
-/**
- * @public
- */
-class UnmatchedDereferenceStrategyError extends DereferenceError {}
-
-export default UnmatchedDereferenceStrategyError;

package/src/errors/UnmatchedParserError.ts

@@ -1,8 +0,0 @@
-import ParserError from './ParserError.ts';
-
-/**
- * @public
- */
-class UnmatchedParserError extends ParserError {}
-
-export default UnmatchedParserError;

package/src/errors/UnmatchedResolveStrategyError.ts

@@ -1,8 +0,0 @@
-import ResolveError from './ResolveError.ts';
-
-/**
- * @public
- */
-class UnmatchedResolveStrategyError extends ResolveError {}
-
-export default UnmatchedResolveStrategyError;

package/src/errors/UnmatchedResolverError.ts

@@ -1,8 +0,0 @@
-import ResolverError from './ResolverError.ts';
-
-/**
- * @public
- */
-class UnmatchedResolverError extends ResolverError {}
-
-export default UnmatchedResolverError;

package/src/errors/UnresolvableReferenceError.ts

@@ -1,8 +0,0 @@
-import DereferenceError from './DereferenceError.ts';
-
-/**
- * @public
- */
-class UnresolvableReferenceError extends DereferenceError {}
-
-export default UnresolvableReferenceError;

package/src/index.ts

@@ -1,135 +0,0 @@
-import { ParseResultElement, Element } from '@speclynx/apidom-datamodel';
-
-import File from './File.ts';
-import ReferenceSet from './ReferenceSet.ts';
-import * as url from './util/url.ts';
-import defaultOptions from './options/index.ts';
-import { merge as mergeOptions } from './options/util.ts';
-import parseFn from './parse/index.ts';
-import resolveFn, { resolveApiDOM as resolveApiDOMFn } from './resolve/index.ts';
-import { readFile as readFileFn } from './resolve/util.ts';
-import dereferenceFn, { dereferenceApiDOM as dereferenceApiDOMFn } from './dereference/index.ts';
-import bundleFn from './bundle/index.ts';
-
-export { url };
-
-export { default as Parser } from './parse/parsers/Parser.ts';
-export type { ParserOptions } from './parse/parsers/Parser.ts';
-
-export { default as Resolver } from './resolve/resolvers/Resolver.ts';
-export { default as HTTPResolver } from './resolve/resolvers/HTTPResolver.ts';
-export type { HTTPResolverOptions, CacheOptions } from './resolve/resolvers/HTTPResolver.ts';
-export { default as ResolveStrategy } from './resolve/strategies/ResolveStrategy.ts';
-export type { ResolverOptions } from './resolve/resolvers/Resolver.ts';
-export type { ResolveStrategyOptions } from './resolve/strategies/ResolveStrategy.ts';
-
-export { default as DereferenceStrategy } from './dereference/strategies/DereferenceStrategy.ts';
-export type { DereferenceStrategyOptions } from './dereference/strategies/DereferenceStrategy.ts';
-export { AncestorLineage as DereferenceAncestorLineage } from './dereference/util.ts';
-
-export { default as BundleStrategy } from './bundle/strategies/BundleStrategy.ts';
-export type { BundleStrategyOptions } from './bundle/strategies/BundleStrategy.ts';
-
-export { default as options } from './options/index.ts';
-export { merge as mergeOptions } from './options/util.ts';
-export type {
-  ReferenceOptions as ApiDOMReferenceOptions,
-  ReferenceBundleOptions as ApiDOMReferenceBundleOptions,
-  ReferenceDereferenceOptions as ApiDOMReferenceDereferenceOptions,
-  ReferenceParseOptions as ApiDOMReferenceParseOptions,
-  ReferenceResolveOptions as ApiDOMReferenceResolveOptions,
-} from './options/index.ts';
-
-export { File };
-export { default as Reference } from './Reference.ts';
-export { ReferenceSet };
-export type { FileOptions } from './File.ts';
-export type { ReferenceOptions } from './Reference.ts';
-export type { ReferenceSetOptions } from './ReferenceSet.ts';
-
-export { default as BundleError } from './errors/BundleError.ts';
-export { default as MaximumBundleDepthError } from './errors/MaximumBundleDepthError.ts';
-export { default as UnmatchedBundleStrategyError } from './errors/UnmatchedBundleStrategyError.ts';
-export { default as DereferenceError } from './errors/DereferenceError.ts';
-export { default as UnresolvableReferenceError } from './errors/UnresolvableReferenceError.ts';
-export { default as EvaluationElementIdError } from './errors/EvaluationElementIdError.ts';
-export { default as EvaluationJsonSchema$anchorError } from './errors/EvaluationJsonSchema$anchorError.ts';
-export { default as EvaluationJsonSchemaUriError } from './errors/EvaluationJsonSchemaUriError.ts';
-export { default as InvalidJsonSchema$anchorError } from './errors/InvalidJsonSchema$anchorError.ts';
-export { default as JsonSchema$anchorError } from './errors/JsonSchema$anchorError.ts';
-export { default as JsonSchemaURIError } from './errors/JsonSchemaUriError.ts';
-export { default as MaximumDereferenceDepthError } from './errors/MaximumDereferenceDepthError.ts';
-export { default as MaximumResolveDepthError } from './errors/MaximumResolveDepthError.ts';
-export { default as ParseError } from './errors/ParseError.ts';
-export { default as ParserError } from './errors/ParserError.ts';
-export { default as PluginError } from './errors/PluginError.ts';
-export { default as ResolveError } from './errors/ResolveError.ts';
-export { default as ResolverError } from './errors/ResolverError.ts';
-export { default as UnmatchedDereferenceStrategyError } from './errors/UnmatchedDereferenceStrategyError.ts';
-export { default as UnmatchedResolveStrategyError } from './errors/UnmatchedResolveStrategyError.ts';
-export { default as UnmatchedResolverError } from './errors/UnmatchedResolverError.ts';
-export { default as UnmatchedParserError } from './errors/UnmatchedParserError.ts';
-
-/**
- * @public
- */
-export const readFile = async (uri: string, options = {}): Promise<Buffer> => {
-  const mergedOptions = mergeOptions(defaultOptions, options);
-  const file = new File({ uri: url.sanitize(uri) });
-
-  return readFileFn(file, mergedOptions);
-};
-
-/**
- * @public
- */
-export const parse = async (uri: string, options = {}): Promise<ParseResultElement> => {
-  const mergedOptions = mergeOptions(defaultOptions, options);
-  return parseFn(uri, mergedOptions);
-};
-
-/**
- * @public
- */
-export const resolve = async (uri: string, options = {}): Promise<ReferenceSet> => {
-  const mergedOptions = mergeOptions(defaultOptions, options);
-  return resolveFn(uri, mergedOptions);
-};
-
-/**
- * @public
- */
-export const resolveApiDOM = async <T extends Element>(
-  element: T,
-  options = {},
-): Promise<ReferenceSet> => {
-  const mergedOptions = mergeOptions(defaultOptions, options);
-  return resolveApiDOMFn(element, mergedOptions);
-};
-
-/**
- * @public
- */
-export const dereference = async (uri: string, options = {}): Promise<ParseResultElement> => {
-  const mergedOptions = mergeOptions(defaultOptions, options);
-  return dereferenceFn(uri, mergedOptions);
-};
-
-/**
- * @public
- */
-export const dereferenceApiDOM = async <T extends Element>(
-  element: T,
-  options = {},
-): Promise<T> => {
-  const mergedOptions = mergeOptions(defaultOptions, options);
-  return dereferenceApiDOMFn(element, mergedOptions);
-};
-
-/**
- * @public
- */
-export const bundle = async (uri: string, options = {}): Promise<ParseResultElement> => {
-  const mergedOptions = mergeOptions(defaultOptions, options);
-  return bundleFn(uri, mergedOptions);
-};

package/src/options/index.ts

@@ -1,239 +0,0 @@
-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.ts

@@ -1,22 +0,0 @@
-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);
-};