@speclynx/apidom-reference 4.0.3 → 4.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "4.0.3",
+  "version": "4.0.5",
   "description": "Advanced algorithms for semantic ApiDOM manipulations like dereferencing or resolution.",
   "keywords": [
     "apidom",
@@ -254,29 +254,29 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-core": "4.0.3",
-    "@speclynx/apidom-datamodel": "4.0.3",
-    "@speclynx/apidom-error": "4.0.3",
-    "@speclynx/apidom-json-pointer": "4.0.3",
-    "@speclynx/apidom-ns-arazzo-1": "4.0.3",
-    "@speclynx/apidom-ns-asyncapi-2": "4.0.3",
-    "@speclynx/apidom-ns-json-schema-2020-12": "4.0.3",
-    "@speclynx/apidom-ns-openapi-2": "4.0.3",
-    "@speclynx/apidom-ns-openapi-3-0": "4.0.3",
-    "@speclynx/apidom-ns-openapi-3-1": "4.0.3",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "4.0.3",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "4.0.3",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "4.0.3",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "4.0.3",
-    "@speclynx/apidom-parser-adapter-json": "4.0.3",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "4.0.3",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "4.0.3",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "4.0.3",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "4.0.3",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "4.0.3",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "4.0.3",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "4.0.3",
-    "@speclynx/apidom-traverse": "4.0.3",
+    "@speclynx/apidom-core": "4.0.5",
+    "@speclynx/apidom-datamodel": "4.0.5",
+    "@speclynx/apidom-error": "4.0.5",
+    "@speclynx/apidom-json-pointer": "4.0.5",
+    "@speclynx/apidom-ns-arazzo-1": "4.0.5",
+    "@speclynx/apidom-ns-asyncapi-2": "4.0.5",
+    "@speclynx/apidom-ns-json-schema-2020-12": "4.0.5",
+    "@speclynx/apidom-ns-openapi-2": "4.0.5",
+    "@speclynx/apidom-ns-openapi-3-0": "4.0.5",
+    "@speclynx/apidom-ns-openapi-3-1": "4.0.5",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "4.0.5",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "4.0.5",
+    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "4.0.5",
+    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "4.0.5",
+    "@speclynx/apidom-parser-adapter-json": "4.0.5",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "4.0.5",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "4.0.5",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "4.0.5",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "4.0.5",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "4.0.5",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "4.0.5",
+    "@speclynx/apidom-parser-adapter-yaml-1-2": "4.0.5",
+    "@speclynx/apidom-traverse": "4.0.5",
     "@swaggerexpert/arazzo-runtime-expression": "^2.0.3",
     "axios": "^1.13.5",
     "picomatch": "^4.0.3",
@@ -289,7 +289,8 @@
     "axios-mock-adapter": "^2.0.0"
   },
   "files": [
-    "src/",
+    "src/**/*.mjs",
+    "src/**/*.cjs",
     "dist/",
     "types/",
     "LICENSES",
@@ -297,5 +298,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "6ccfa09c02232516215e7de3ead276641957e626"
+  "gitHead": "5a85d2a832eeefb07d03760faa391b457447e966"
 }

package/src/File.ts

@@ -1,63 +0,0 @@
-import { type } from 'ramda';
-import { isString } from 'ramda-adjunct';
-import { ParseResultElement } from '@speclynx/apidom-datamodel';
-
-import * as url from './util/url.ts';
-
-/**
- * This class represents a File object with url and data.
- * @public
- */
-
-export interface FileOptions {
-  readonly uri: string;
-  readonly mediaType?: string;
-  readonly data?: Buffer | DataView | ArrayBuffer | Uint8Array | string;
-  readonly parseResult?: ParseResultElement;
-}
-
-/**
- * @public
- */
-class File {
-  public uri: string;
-
-  public mediaType: string;
-
-  public data?: Buffer | DataView | ArrayBuffer | Uint8Array | string;
-
-  public parseResult?: ParseResultElement;
-
-  constructor({ uri, mediaType = 'text/plain', data, parseResult }: FileOptions) {
-    this.uri = uri;
-    this.mediaType = mediaType;
-    this.data = data;
-    this.parseResult = parseResult;
-  }
-
-  get extension(): string {
-    if (isString(this.uri)) {
-      return url.getExtension(this.uri);
-    }
-    return '';
-  }
-
-  toString(): string {
-    if (typeof this.data === 'string') {
-      return this.data;
-    }
-
-    if (
-      this.data instanceof ArrayBuffer ||
-      ['ArrayBuffer'].includes(type(this.data)) ||
-      ArrayBuffer.isView(this.data)
-    ) {
-      const textDecoder = new TextDecoder('utf-8');
-      return textDecoder.decode(this.data as Buffer | DataView | ArrayBuffer);
-    }
-
-    return String(this.data);
-  }
-}
-
-export default File;

package/src/Reference.ts

@@ -1,38 +0,0 @@
-import { Element } from '@speclynx/apidom-datamodel';
-
-import ReferenceSet from './ReferenceSet.ts';
-
-/**
- * @public
- */
-export interface ReferenceOptions<T = Element> {
-  readonly uri: string;
-  readonly depth?: number;
-  readonly refSet?: ReferenceSet;
-  readonly value: T;
-}
-
-/**
- * @public
- */
-class Reference<T = Element> {
-  public readonly uri: string;
-
-  public readonly depth: number;
-
-  public readonly value: T;
-
-  public refSet?: ReferenceSet;
-
-  public readonly errors: Array<Error>;
-
-  constructor({ uri, depth = 0, refSet, value }: ReferenceOptions<T>) {
-    this.uri = uri;
-    this.value = value;
-    this.depth = depth;
-    this.refSet = refSet;
-    this.errors = [];
-  }
-}
-
-export default Reference;

package/src/ReferenceSet.ts

@@ -1,73 +0,0 @@
-import { isNotUndefined, isString } from 'ramda-adjunct';
-
-import type Reference from './Reference.ts';
-
-/**
- * @public
- */
-export interface ReferenceSetOptions {
-  readonly refs?: Reference[];
-  readonly circular?: boolean;
-}
-
-/**
- * @public
- */
-class ReferenceSet {
-  public rootRef?: Reference;
-
-  public readonly refs: Reference[];
-
-  public circular: boolean;
-
-  constructor({ refs = [], circular = false }: ReferenceSetOptions = {}) {
-    this.refs = [];
-    this.circular = circular;
-    refs.forEach(this.add.bind(this));
-  }
-
-  get size(): number {
-    return this.refs.length;
-  }
-
-  add(reference: Reference): this {
-    if (!this.has(reference)) {
-      this.refs.push(reference);
-      this.rootRef = this.rootRef === undefined ? reference : this.rootRef;
-      reference.refSet = this;
-    }
-    return this;
-  }
-
-  merge(anotherRefSet: this): this {
-    for (const reference of anotherRefSet.values()) {
-      this.add(reference);
-    }
-    return this;
-  }
-
-  has(thing: string | Reference): boolean {
-    const uri = isString(thing) ? thing : thing.uri;
-    return isNotUndefined(this.find((ref: Reference) => ref.uri === uri));
-  }
-
-  find(
-    predicate: (value: Reference, index: number, obj: Reference[]) => boolean,
-  ): Reference | undefined {
-    return this.refs.find(predicate);
-  }
-
-  *values() {
-    yield* this.refs;
-  }
-
-  clean() {
-    this.refs.forEach((ref: Reference) => {
-      ref.refSet = undefined;
-    });
-    this.rootRef = undefined;
-    this.refs.length = 0;
-  }
-}
-
-export default ReferenceSet;

package/src/bundle/index.ts

@@ -1,57 +0,0 @@
-import { isEmpty, propEq } from 'ramda';
-import { ParseResultElement } from '@speclynx/apidom-datamodel';
-
-import File from '../File.ts';
-import * as plugins from '../util/plugins.ts';
-import UnmatchedBundleStrategyError from '../errors/UnmatchedBundleStrategyError.ts';
-import BundleError from '../errors/BundleError.ts';
-import parse from '../parse/index.ts';
-import { merge as mergeOptions } from '../options/util.ts';
-import * as url from '../util/url.ts';
-import type { ReferenceOptions } from '../options/index.ts';
-
-/**
- * Bundle a file with all its external references to a compound document.
- */
-const bundle = async (uri: string, options: ReferenceOptions): Promise<ParseResultElement> => {
-  const { refSet } = options.bundle;
-  const sanitizedURI = url.sanitize(uri);
-  const mergedOptions = mergeOptions(options, { resolve: { baseURI: sanitizedURI } });
-  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, mergedOptions);
-  }
-
-  const file = new File({
-    uri: mergedOptions.resolve.baseURI,
-    parseResult,
-    mediaType: mergedOptions.parse.mediaType,
-  });
-
-  const bundleStrategies = await plugins.filter(
-    'canBundle',
-    [file, mergedOptions],
-    mergedOptions.bundle.strategies,
-  );
-
-  // we couldn't find any bundle strategy for this File
-  if (isEmpty(bundleStrategies)) {
-    throw new UnmatchedBundleStrategyError(
-      `Could not find a bundle strategy that can bundle the file "${file.uri}"`,
-    );
-  }
-
-  try {
-    const { result } = await plugins.run('bundle', [file, mergedOptions], bundleStrategies);
-    return result;
-  } catch (error: any) {
-    throw new BundleError(`Error while bundling file "${file.uri}"`, { cause: error });
-  }
-};
-
-export default bundle;

package/src/bundle/strategies/BundleStrategy.ts

@@ -1,27 +0,0 @@
-import { ParseResultElement } from '@speclynx/apidom-datamodel';
-
-import File from '../../File.ts';
-import type { ReferenceOptions } from '../../options/index.ts';
-
-/**
- * @public
- */
-export interface BundleStrategyOptions {
-  readonly name: string;
-}
-
-/**
- * @public
- */
-abstract class BundleStrategy {
-  public readonly name: string;
-
-  constructor({ name }: BundleStrategyOptions) {
-    this.name = name;
-  }
-
-  abstract canBundle(file: File, options: ReferenceOptions): boolean;
-  abstract bundle(file: File, options: ReferenceOptions): Promise<ParseResultElement>;
-}
-
-export default BundleStrategy;

package/src/bundle/strategies/openapi-3-1/index.ts

@@ -1,57 +0,0 @@
-import { ParseResultElement } from '@speclynx/apidom-datamodel';
-import { mediaTypes, isOpenApi3_1Element } from '@speclynx/apidom-ns-openapi-3-1';
-
-import File from '../../../File.ts';
-import BundleStrategy, { BundleStrategyOptions } from '../BundleStrategy.ts';
-
-export type {
-  default as DereferenceStrategy,
-  DereferenceStrategyOptions,
-} from '../../../dereference/strategies/DereferenceStrategy.ts';
-export type { default as File, FileOptions } from '../../../File.ts';
-export type { default as Reference, ReferenceOptions } from '../../../Reference.ts';
-export type { default as ReferenceSet, ReferenceSetOptions } from '../../../ReferenceSet.ts';
-export type {
-  ReferenceOptions as ApiDOMReferenceOptions,
-  ReferenceBundleOptions as ApiDOMReferenceBundleOptions,
-  ReferenceDereferenceOptions as ApiDOMReferenceDereferenceOptions,
-  ReferenceParseOptions as ApiDOMReferenceParseOptions,
-  ReferenceResolveOptions as ApiDOMReferenceResolveOptions,
-} from '../../../options/index.ts';
-export type { default as Parser, ParserOptions } from '../../../parse/parsers/Parser.ts';
-export type { default as Resolver, ResolverOptions } from '../../../resolve/resolvers/Resolver.ts';
-export type {
-  default as ResolveStrategy,
-  ResolveStrategyOptions,
-} from '../../../resolve/strategies/ResolveStrategy.ts';
-export type { default as BundleStrategy, BundleStrategyOptions } from '../BundleStrategy.ts';
-
-/**
- * @public
- */
-export interface OpenAPI3_1BundleStrategyOptions extends Omit<BundleStrategyOptions, 'name'> {}
-
-/**
- * @public
- */
-class OpenAPI3_1BundleStrategy extends BundleStrategy {
-  constructor(options?: OpenAPI3_1BundleStrategyOptions) {
-    super({ ...(options ?? {}), name: 'openapi-3-1' });
-  }
-
-  canBundle(file: File): boolean {
-    // assert by media type
-    if (file.mediaType !== 'text/plain') {
-      return mediaTypes.includes(file.mediaType);
-    }
-
-    // assert by inspecting ApiDOM
-    return isOpenApi3_1Element(file.parseResult?.result);
-  }
-
-  async bundle(file: File): Promise<ParseResultElement> {
-    return file.parseResult!;
-  }
-}
-
-export default OpenAPI3_1BundleStrategy;

package/src/configuration/empty.ts

@@ -1 +0,0 @@
-export * from '../index.ts';

package/src/configuration/saturated.ts

@@ -1,72 +0,0 @@
-import FileResolver from '../resolve/resolvers/file/index-node.ts';
-import HTTPResolverAxios from '../resolve/resolvers/http-axios/index.ts';
-import OpenAPI2ResolveStrategy from '../resolve/strategies/openapi-2/index.ts';
-import OpenAPI3_0ResolveStrategy from '../resolve/strategies/openapi-3-0/index.ts';
-import OpenAPI3_1ResolveStrategy from '../resolve/strategies/openapi-3-1/index.ts';
-import AsyncAPI2ResolveStrategy from '../resolve/strategies/asyncapi-2/index.ts';
-import ApiDOMResolveStrategy from '../resolve/strategies/apidom/index.ts';
-import OpenAPIJSON2Parser from '../parse/parsers/openapi-json-2/index.ts';
-import OpenAPIYAML2Parser from '../parse/parsers/openapi-yaml-2/index.ts';
-import OpenAPIJSON3_0Parser from '../parse/parsers/openapi-json-3-0/index.ts';
-import OpenAPIYAML3_0Parser from '../parse/parsers/openapi-yaml-3-0/index.ts';
-import OpenAPIJSON3_1Parser from '../parse/parsers/openapi-json-3-1/index.ts';
-import OpenAPIYAML3_1Parser from '../parse/parsers/openapi-yaml-3-1/index.ts';
-import AsyncAPIJSON2Parser from '../parse/parsers/asyncapi-json-2/index.ts';
-import AsyncAPIYAML2Parser from '../parse/parsers/asyncapi-yaml-2/index.ts';
-import ArazzoJSON1Parser from '../parse/parsers/arazzo-json-1/index.ts';
-import ArazzoYAML1Parser from '../parse/parsers/arazzo-yaml-1/index.ts';
-import APIDOMJSONParser from '../parse/parsers/apidom-json/index.ts';
-import JSONParser from '../parse/parsers/json/index.ts';
-import YAMLParser from '../parse/parsers/yaml-1-2/index.ts';
-import BinaryParser from '../parse/parsers/binary/index-node.ts';
-import ApiDOMDereferenceStrategy from '../dereference/strategies/apidom/index.ts';
-import OpenAPI2DereferenceStrategy from '../dereference/strategies/openapi-2/index.ts';
-import OpenAPI3_0DereferenceStrategy from '../dereference/strategies/openapi-3-0/index.ts';
-import OpenAPI3_1DereferenceStrategy from '../dereference/strategies/openapi-3-1/index.ts';
-import AsyncAPI2DereferenceStrategy from '../dereference/strategies/asyncapi-2/index.ts';
-import Arazzo1DereferenceStrategy from '../dereference/strategies/arazzo-1/index.ts';
-import OpenAPI3_1BundleStrategy from '../bundle/strategies/openapi-3-1/index.ts';
-import { options } from '../index.ts';
-
-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.ts';

package/src/dereference/index.ts

@@ -1,96 +0,0 @@
-import { isEmpty, propEq } from 'ramda';
-import {
-  Element,
-  isParseResultElement,
-  ParseResultElement,
-  cloneShallow,
-} from '@speclynx/apidom-datamodel';
-
-import File from '../File.ts';
-import * as plugins from '../util/plugins.ts';
-import UnmatchedDereferenceStrategyError from '../errors/UnmatchedDereferenceStrategyError.ts';
-import DereferenceError from '../errors/DereferenceError.ts';
-import UnresolvableReferenceError from '../errors/UnresolvableReferenceError.ts';
-import parse from '../parse/index.ts';
-import { merge as mergeOptions } from '../options/util.ts';
-import * as url from '../util/url.ts';
-import type { ReferenceOptions } from '../options/index.ts';
-
-/**
- * Dereferences ApiDOM with all its external references.
- */
-export const dereferenceApiDOM = async <T extends Element>(
-  element: T,
-  options: ReferenceOptions,
-): Promise<T> => {
-  // @ts-ignore
-  let parseResult: ParseResultElement = 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: any) {
-    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: string, options: ReferenceOptions): Promise<ParseResultElement> => {
-  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.ts

@@ -1,27 +0,0 @@
-import { Element } from '@speclynx/apidom-datamodel';
-
-import File from '../../File.ts';
-import type { ReferenceOptions } from '../../options/index.ts';
-
-/**
- * @public
- */
-export interface DereferenceStrategyOptions {
-  readonly name: string;
-}
-
-/**
- * @public
- */
-abstract class DereferenceStrategy {
-  public readonly name: string;
-
-  constructor({ name }: DereferenceStrategyOptions) {
-    this.name = name;
-  }
-
-  abstract canDereference(file: File, options: ReferenceOptions): boolean;
-  abstract dereference(file: File, options: ReferenceOptions): Promise<Element>;
-}
-
-export default DereferenceStrategy;