@speclynx/apidom-reference 4.0.1 → 4.0.3

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [4.0.3](https://github.com/speclynx/apidom/compare/v4.0.2...v4.0.3) (2026-03-11)
+
+### Bug Fixes
+
+- **release:** fix v4.0.2 failed release ([b4dc1c4](https://github.com/speclynx/apidom/commit/b4dc1c48e8d9b2986a70e49b5554eb0a166d7528))
+
+## [4.0.2](https://github.com/speclynx/apidom/compare/v4.0.1...v4.0.2) (2026-03-11)
+
+**Note:** Version bump only for package @speclynx/apidom-reference
+
 ## [4.0.1](https://github.com/speclynx/apidom/compare/v4.0.0...v4.0.1) (2026-03-11)
 
 **Note:** Version bump only for package @speclynx/apidom-reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "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.1",
-    "@speclynx/apidom-datamodel": "4.0.1",
-    "@speclynx/apidom-error": "4.0.1",
-    "@speclynx/apidom-json-pointer": "4.0.1",
-    "@speclynx/apidom-ns-arazzo-1": "4.0.1",
-    "@speclynx/apidom-ns-asyncapi-2": "4.0.1",
-    "@speclynx/apidom-ns-json-schema-2020-12": "4.0.1",
-    "@speclynx/apidom-ns-openapi-2": "4.0.1",
-    "@speclynx/apidom-ns-openapi-3-0": "4.0.1",
-    "@speclynx/apidom-ns-openapi-3-1": "4.0.1",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "4.0.1",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "4.0.1",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "4.0.1",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "4.0.1",
-    "@speclynx/apidom-parser-adapter-json": "4.0.1",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "4.0.1",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "4.0.1",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "4.0.1",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "4.0.1",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "4.0.1",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "4.0.1",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "4.0.1",
-    "@speclynx/apidom-traverse": "4.0.1",
+    "@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",
     "@swaggerexpert/arazzo-runtime-expression": "^2.0.3",
     "axios": "^1.13.5",
     "picomatch": "^4.0.3",
@@ -289,8 +289,7 @@
     "axios-mock-adapter": "^2.0.0"
   },
   "files": [
-    "src/**/*.mjs",
-    "src/**/*.cjs",
+    "src/",
     "dist/",
     "types/",
     "LICENSES",
@@ -298,5 +297,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "223132a9b00081ca04842efc2736a491f7876f44"
+  "gitHead": "6ccfa09c02232516215e7de3ead276641957e626"
 }

package/src/File.cjs

@@ -0,0 +1,50 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ramda = require("ramda");
+var _ramdaAdjunct = require("ramda-adjunct");
+var url = _interopRequireWildcard(require("./util/url.cjs"));
+/**
+ * This class represents a File object with url and data.
+ * @public
+ */
+
+/**
+ * @public
+ */
+class File {
+  uri;
+  mediaType;
+  data;
+  parseResult;
+  constructor({
+    uri,
+    mediaType = 'text/plain',
+    data,
+    parseResult
+  }) {
+    this.uri = uri;
+    this.mediaType = mediaType;
+    this.data = data;
+    this.parseResult = parseResult;
+  }
+  get extension() {
+    if ((0, _ramdaAdjunct.isString)(this.uri)) {
+      return url.getExtension(this.uri);
+    }
+    return '';
+  }
+  toString() {
+    if (typeof this.data === 'string') {
+      return this.data;
+    }
+    if (this.data instanceof ArrayBuffer || ['ArrayBuffer'].includes((0, _ramda.type)(this.data)) || ArrayBuffer.isView(this.data)) {
+      const textDecoder = new TextDecoder('utf-8');
+      return textDecoder.decode(this.data);
+    }
+    return String(this.data);
+  }
+}
+var _default = exports.default = File;

package/src/File.mjs

@@ -0,0 +1,44 @@
+import { type } from 'ramda';
+import { isString } from 'ramda-adjunct';
+import * as url from "./util/url.mjs";
+/**
+ * This class represents a File object with url and data.
+ * @public
+ */
+/**
+ * @public
+ */
+class File {
+  uri;
+  mediaType;
+  data;
+  parseResult;
+  constructor({
+    uri,
+    mediaType = 'text/plain',
+    data,
+    parseResult
+  }) {
+    this.uri = uri;
+    this.mediaType = mediaType;
+    this.data = data;
+    this.parseResult = parseResult;
+  }
+  get extension() {
+    if (isString(this.uri)) {
+      return url.getExtension(this.uri);
+    }
+    return '';
+  }
+  toString() {
+    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);
+    }
+    return String(this.data);
+  }
+}
+export default File;

package/src/File.ts

@@ -0,0 +1,63 @@
+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.cjs

@@ -0,0 +1,31 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class Reference {
+  uri;
+  depth;
+  value;
+  refSet;
+  errors;
+  constructor({
+    uri,
+    depth = 0,
+    refSet,
+    value
+  }) {
+    this.uri = uri;
+    this.value = value;
+    this.depth = depth;
+    this.refSet = refSet;
+    this.errors = [];
+  }
+}
+var _default = exports.default = Reference;

package/src/Reference.mjs

@@ -0,0 +1,27 @@
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class Reference {
+  uri;
+  depth;
+  value;
+  refSet;
+  errors;
+  constructor({
+    uri,
+    depth = 0,
+    refSet,
+    value
+  }) {
+    this.uri = uri;
+    this.value = value;
+    this.depth = depth;
+    this.refSet = refSet;
+    this.errors = [];
+  }
+}
+export default Reference;

package/src/Reference.ts

@@ -0,0 +1,38 @@
+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.cjs

@@ -0,0 +1,60 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _ramdaAdjunct = require("ramda-adjunct");
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class ReferenceSet {
+  rootRef;
+  refs;
+  circular;
+  constructor({
+    refs = [],
+    circular = false
+  } = {}) {
+    this.refs = [];
+    this.circular = circular;
+    refs.forEach(this.add.bind(this));
+  }
+  get size() {
+    return this.refs.length;
+  }
+  add(reference) {
+    if (!this.has(reference)) {
+      this.refs.push(reference);
+      this.rootRef = this.rootRef === undefined ? reference : this.rootRef;
+      reference.refSet = this;
+    }
+    return this;
+  }
+  merge(anotherRefSet) {
+    for (const reference of anotherRefSet.values()) {
+      this.add(reference);
+    }
+    return this;
+  }
+  has(thing) {
+    const uri = (0, _ramdaAdjunct.isString)(thing) ? thing : thing.uri;
+    return (0, _ramdaAdjunct.isNotUndefined)(this.find(ref => ref.uri === uri));
+  }
+  find(predicate) {
+    return this.refs.find(predicate);
+  }
+  *values() {
+    yield* this.refs;
+  }
+  clean() {
+    this.refs.forEach(ref => {
+      ref.refSet = undefined;
+    });
+    this.rootRef = undefined;
+    this.refs.length = 0;
+  }
+}
+var _default = exports.default = ReferenceSet;

package/src/ReferenceSet.mjs

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

package/src/ReferenceSet.ts

@@ -0,0 +1,73 @@
+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.cjs

@@ -0,0 +1,61 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ramda = require("ramda");
+var _File = _interopRequireDefault(require("../File.cjs"));
+var plugins = _interopRequireWildcard(require("../util/plugins.cjs"));
+var _UnmatchedBundleStrategyError = _interopRequireDefault(require("../errors/UnmatchedBundleStrategyError.cjs"));
+var _BundleError = _interopRequireDefault(require("../errors/BundleError.cjs"));
+var _index = _interopRequireDefault(require("../parse/index.cjs"));
+var _util = require("../options/util.cjs");
+var url = _interopRequireWildcard(require("../util/url.cjs"));
+/**
+ * Bundle a file with all its external references to a compound document.
+ */
+const bundle = async (uri, options) => {
+  const {
+    refSet
+  } = options.bundle;
+  const sanitizedURI = url.sanitize(uri);
+  const mergedOptions = (0, _util.merge)(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((0, _ramda.propEq)(sanitizedURI, 'uri')));
+  } else {
+    parseResult = await (0, _index.default)(uri, mergedOptions);
+  }
+  const file = new _File.default({
+    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 ((0, _ramda.isEmpty)(bundleStrategies)) {
+    throw new _UnmatchedBundleStrategyError.default(`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) {
+    throw new _BundleError.default(`Error while bundling file "${file.uri}"`, {
+      cause: error
+    });
+  }
+};
+var _default = exports.default = bundle;

package/src/bundle/index.mjs

@@ -0,0 +1,55 @@
+import { isEmpty, propEq } from 'ramda';
+import File from "../File.mjs";
+import * as plugins from "../util/plugins.mjs";
+import UnmatchedBundleStrategyError from "../errors/UnmatchedBundleStrategyError.mjs";
+import BundleError from "../errors/BundleError.mjs";
+import parse from "../parse/index.mjs";
+import { merge as mergeOptions } from "../options/util.mjs";
+import * as url from "../util/url.mjs";
+/**
+ * Bundle a file with all its external references to a compound document.
+ */
+const bundle = async (uri, options) => {
+  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) {
+    throw new BundleError(`Error while bundling file "${file.uri}"`, {
+      cause: error
+    });
+  }
+};
+export default bundle;