@speclynx/apidom-core 3.2.0 → 4.0.0

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [4.0.0](https://github.com/speclynx/apidom/compare/v3.2.1...v4.0.0) (2026-03-11)
+
+**Note:** Version bump only for package @speclynx/apidom-core
+
+## [3.2.1](https://github.com/speclynx/apidom/compare/v3.2.0...v3.2.1) (2026-03-09)
+
+**Note:** Version bump only for package @speclynx/apidom-core
+
 # [3.2.0](https://github.com/speclynx/apidom/compare/v3.1.0...v3.2.0) (2026-03-08)
 
 ### Features

package/dist/apidom-core.browser.js

@@ -28058,7 +28058,9 @@ class Path {
    *
    * @example
    * // For a path to $.paths['/pets'].get in an OpenAPI document:
+   * ```
    * path.getPathKeys(); // => ['paths', '/pets', 'get']
+   * ```
    */
   getPathKeys() {
     const keys = [];
@@ -28093,18 +28095,22 @@ class Path {
    *          or Normalized JSONPath like "$['paths']['/pets']['get']['responses']['200']"
    *
    * @example
+   * ```
    * // JSON Pointer examples:
    * path.formatPath(); // "" (root)
    * path.formatPath(); // "/info"
    * path.formatPath(); // "/paths/~1pets/get"
    * path.formatPath(); // "/paths/~1users~1{id}/parameters/0"
+   * ```
    *
    * @example
+   * ```
    * // JSONPath examples:
    * path.formatPath('jsonpath'); // "$" (root)
    * path.formatPath('jsonpath'); // "$['info']"
    * path.formatPath('jsonpath'); // "$['paths']['/pets']['get']"
    * path.formatPath('jsonpath'); // "$['paths']['/users/{id}']['parameters'][0]"
+   * ```
    */
   formatPath(pathFormat = 'jsonpointer') {
     const parts = this.getPathKeys();
@@ -28312,15 +28318,15 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _traversal_mjs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(2078);
 
 /**
- * Finds all elements matching the predicate.
+ * Finds all paths whose elements match the predicate.
  * @public
  */
 const filter = (element, predicate) => {
   const result = [];
   (0,_traversal_mjs__WEBPACK_IMPORTED_MODULE_0__.traverse)(element, {
     enter(path) {
-      if (predicate(path.node)) {
-        result.push(path.node);
+      if (predicate(path)) {
+        result.push(path);
       }
     }
   });
@@ -28345,7 +28351,7 @@ __webpack_require__.r(__webpack_exports__);
  * @public
  */
 /**
- * Finds the most inner node at the given offset.
+ * Finds the path of the most inner node at the given offset.
  * If includeRightBound is set, also finds nodes that end at the given offset.
  * @public
  */
@@ -28370,7 +28376,7 @@ const findAtOffset = (element, options) => {
       const endOffset = node.endOffset;
       const isWithinOffsetRange = offset >= startOffset && (offset < endOffset || includeRightBound && offset <= endOffset);
       if (isWithinOffsetRange) {
-        result.push(node);
+        result.push(path);
         return; // push to stack and dive in
       }
       path.skip(); // skip entire sub-tree
@@ -28392,15 +28398,15 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _traversal_mjs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(2078);
 
 /**
- * Find first element that satisfies the provided predicate.
+ * Finds first path whose element satisfies the provided predicate.
  * @public
  */
 const find = (element, predicate) => {
   let result;
   (0,_traversal_mjs__WEBPACK_IMPORTED_MODULE_0__.traverse)(element, {
     enter(path) {
-      if (predicate(path.node)) {
-        result = path.node;
+      if (predicate(path)) {
+        result = path;
         path.stop();
       }
     }
@@ -28418,9 +28424,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__)
 /* harmony export */ });
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(5162);
-/* harmony import */ var _traversal_mjs__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(2078);
-
+/* harmony import */ var _traversal_mjs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(2078);
 
 /**
  * @public
@@ -28429,7 +28433,7 @@ __webpack_require__.r(__webpack_exports__);
  * @public
  */
 /**
- * Executes the callback on this element and all descendants.
+ * Executes the callback on this element's path and all descendant paths.
  * @public
  */
 const forEach = (element, options) => {
@@ -28437,15 +28441,15 @@ const forEach = (element, options) => {
   let predicate;
   if (typeof options === 'function') {
     callback = options;
-    predicate = _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isElement;
+    predicate = () => true;
   } else {
     callback = options.callback ?? (() => {});
-    predicate = options.predicate ?? _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isElement;
+    predicate = options.predicate ?? (() => true);
   }
-  (0,_traversal_mjs__WEBPACK_IMPORTED_MODULE_1__.traverse)(element, {
+  (0,_traversal_mjs__WEBPACK_IMPORTED_MODULE_0__.traverse)(element, {
     enter(path) {
-      if (predicate(path.node)) {
-        callback(path.node);
+      if (predicate(path)) {
+        callback(path);
       }
     }
   });
@@ -28492,11 +28496,11 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _filter_mjs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(5247);
 
 /**
- * Complement of filter. Finds all elements NOT matching the predicate.
+ * Complement of filter. Finds all paths whose elements do NOT match the predicate.
  * @public
  */
 const reject = (element, predicate) => {
-  return (0,_filter_mjs__WEBPACK_IMPORTED_MODULE_0__["default"])(element, el => !predicate(el));
+  return (0,_filter_mjs__WEBPACK_IMPORTED_MODULE_0__["default"])(element, path => !predicate(path));
 };
 /* harmony default export */ const __WEBPACK_DEFAULT_EXPORT__ = (reject);
 
@@ -28512,7 +28516,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _find_mjs__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(4860);
 
 /**
- * Tests whether at least one element passes the predicate.
+ * Tests whether at least one path's element passes the predicate.
  * @public
  */
 const some = (element, predicate) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-core",
-  "version": "3.2.0",
+  "version": "4.0.0",
   "description": "Tools for manipulating ApiDOM structures.",
   "keywords": [
     "apidom",
@@ -57,9 +57,9 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-datamodel": "3.2.0",
-    "@speclynx/apidom-error": "3.2.0",
-    "@speclynx/apidom-traverse": "3.2.0",
+    "@speclynx/apidom-datamodel": "4.0.0",
+    "@speclynx/apidom-error": "4.0.0",
+    "@speclynx/apidom-traverse": "4.0.0",
     "ramda": "~0.32.0",
     "ramda-adjunct": "^6.0.0",
     "short-unique-id": "^5.3.2",
@@ -76,5 +76,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "eeb2f01cd34fb0a95617f02bc1b6683aefc028f2"
+  "gitHead": "384ff82a1bb68d015fd6801de641898b4b582876"
 }

package/src/fields/fixed-fields.cjs

@@ -1,47 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.default = void 0;
-exports.fixedFields = fixedFields;
-var _apidomDatamodel = require("@speclynx/apidom-datamodel");
-/**
- * Represents a fixed field definition.
- * @public
- */
-
-/**
- * @public
- */
-
-/**
- * Returns the fixed fields for an Element class or instance.
- *
- * @param elementOrClass - Element instance or class
- * @param options - Options for return format
- * @returns Array of fixed fields, or object indexed by name if options.indexed is true
- *
- * @example
- * ```ts
- * import { fixedFields } from '@speclynx/apidom-core';
- *
- * // Get fixed fields as array
- * const fields = fixedFields(ParameterElement);
- *
- * // Get fixed fields as indexed object for O(1) lookups
- * const fieldsIndex = fixedFields(ParameterElement, { indexed: true });
- * if (Object.hasOwn(fieldsIndex, 'description')) {
- *   // field exists
- * }
- * ```
- *
- * @public
- */
-function fixedFields(elementOrClass, options) {
-  const constructor = elementOrClass instanceof _apidomDatamodel.Element ? elementOrClass.constructor : elementOrClass;
-  const fields = constructor.fixedFields ?? [];
-  if (options?.indexed) {
-    return Object.fromEntries(fields.map(f => [f.name, f]));
-  }
-  return fields;
-}
-var _default = exports.default = fixedFields;

package/src/fields/fixed-fields.mjs

@@ -1,43 +0,0 @@
-import { Element } from '@speclynx/apidom-datamodel';
-
-/**
- * Represents a fixed field definition.
- * @public
- */
-
-/**
- * @public
- */
-
-/**
- * Returns the fixed fields for an Element class or instance.
- *
- * @param elementOrClass - Element instance or class
- * @param options - Options for return format
- * @returns Array of fixed fields, or object indexed by name if options.indexed is true
- *
- * @example
- * ```ts
- * import { fixedFields } from '@speclynx/apidom-core';
- *
- * // Get fixed fields as array
- * const fields = fixedFields(ParameterElement);
- *
- * // Get fixed fields as indexed object for O(1) lookups
- * const fieldsIndex = fixedFields(ParameterElement, { indexed: true });
- * if (Object.hasOwn(fieldsIndex, 'description')) {
- *   // field exists
- * }
- * ```
- *
- * @public
- */
-export function fixedFields(elementOrClass, options) {
-  const constructor = elementOrClass instanceof Element ? elementOrClass.constructor : elementOrClass;
-  const fields = constructor.fixedFields ?? [];
-  if (options?.indexed) {
-    return Object.fromEntries(fields.map(f => [f.name, f]));
-  }
-  return fields;
-}
-export default fixedFields;

package/src/fields/index.cjs

@@ -1,8 +0,0 @@
-"use strict";
-
-var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
-exports.__esModule = true;
-exports.fixedFields = exports.default = void 0;
-var _fixedFields = _interopRequireWildcard(require("./fixed-fields.cjs"));
-exports.fixedFields = _fixedFields.fixedFields;
-exports.default = _fixedFields.default;

package/src/fields/index.mjs

@@ -1 +0,0 @@
-export { fixedFields, default } from "./fixed-fields.mjs";

package/src/identity/errors/ElementIdentityError.cjs

@@ -1,22 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.default = void 0;
-var _apidomError = require("@speclynx/apidom-error");
-/**
- * @public
- */
-
-/**
- * @public
- */
-class ElementIdentityError extends _apidomError.ApiDOMStructuredError {
-  value;
-  constructor(message, structuredOptions) {
-    super(message, structuredOptions);
-    if (typeof structuredOptions !== 'undefined') {
-      this.value = structuredOptions.value;
-    }
-  }
-}
-var _default = exports.default = ElementIdentityError;

package/src/identity/errors/ElementIdentityError.mjs

@@ -1,19 +0,0 @@
-import { ApiDOMStructuredError } from '@speclynx/apidom-error';
-
-/**
- * @public
- */
-
-/**
- * @public
- */
-class ElementIdentityError extends ApiDOMStructuredError {
-  value;
-  constructor(message, structuredOptions) {
-    super(message, structuredOptions);
-    if (typeof structuredOptions !== 'undefined') {
-      this.value = structuredOptions.value;
-    }
-  }
-}
-export default ElementIdentityError;

package/src/identity/index.cjs

@@ -1,64 +0,0 @@
-"use strict";
-
-var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
-exports.__esModule = true;
-exports.defaultIdentityManager = exports.IdentityManager = void 0;
-var _apidomDatamodel = require("@speclynx/apidom-datamodel");
-var _shortUniqueId = _interopRequireDefault(require("short-unique-id"));
-var _ElementIdentityError = _interopRequireDefault(require("./errors/ElementIdentityError.cjs"));
-/**
- * @public
- */
-class IdentityManager {
-  uuid;
-  identityMap;
-  constructor({
-    length = 6
-  } = {}) {
-    this.uuid = new _shortUniqueId.default({
-      length
-    });
-    this.identityMap = new WeakMap();
-  }
-  identify(element) {
-    if (!(0, _apidomDatamodel.isElement)(element)) {
-      throw new _ElementIdentityError.default('Cannot not identify the element. `element` is neither structurally compatible nor a subclass of an Element class.', {
-        value: element
-      });
-    }
-
-    // use already assigned identity
-    if (element.hasMetaProperty('id')) {
-      const existingId = element.id;
-      if (typeof existingId === 'string' && existingId !== '') {
-        return existingId;
-      }
-    }
-
-    // assign identity in immutable way
-    if (this.identityMap.has(element)) {
-      return this.identityMap.get(element);
-    }
-
-    // return element identity
-    const id = this.generateId();
-    this.identityMap.set(element, id);
-    return id;
-  }
-  forget(element) {
-    if (this.identityMap.has(element)) {
-      this.identityMap.delete(element);
-      return true;
-    }
-    return false;
-  }
-  generateId() {
-    return this.uuid.randomUUID();
-  }
-}
-
-/**
- * @public
- */
-exports.IdentityManager = IdentityManager;
-const defaultIdentityManager = exports.defaultIdentityManager = new IdentityManager();

package/src/identity/index.mjs

@@ -1,58 +0,0 @@
-import { isElement } from '@speclynx/apidom-datamodel';
-import ShortUniqueId from 'short-unique-id';
-import ElementIdentityError from "./errors/ElementIdentityError.mjs";
-/**
- * @public
- */
-export class IdentityManager {
-  uuid;
-  identityMap;
-  constructor({
-    length = 6
-  } = {}) {
-    this.uuid = new ShortUniqueId({
-      length
-    });
-    this.identityMap = new WeakMap();
-  }
-  identify(element) {
-    if (!isElement(element)) {
-      throw new ElementIdentityError('Cannot not identify the element. `element` is neither structurally compatible nor a subclass of an Element class.', {
-        value: element
-      });
-    }
-
-    // use already assigned identity
-    if (element.hasMetaProperty('id')) {
-      const existingId = element.id;
-      if (typeof existingId === 'string' && existingId !== '') {
-        return existingId;
-      }
-    }
-
-    // assign identity in immutable way
-    if (this.identityMap.has(element)) {
-      return this.identityMap.get(element);
-    }
-
-    // return element identity
-    const id = this.generateId();
-    this.identityMap.set(element, id);
-    return id;
-  }
-  forget(element) {
-    if (this.identityMap.has(element)) {
-      this.identityMap.delete(element);
-      return true;
-    }
-    return false;
-  }
-  generateId() {
-    return this.uuid.randomUUID();
-  }
-}
-
-/**
- * @public
- */
-export const defaultIdentityManager = new IdentityManager();

package/src/index.cjs

@@ -1,48 +0,0 @@
-"use strict";
-
-var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
-var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
-exports.__esModule = true;
-exports.transclude = exports.toYAML = exports.toValue = exports.toString = exports.toJSON = exports.sexprs = exports.resolveSpecification = exports.refractorPluginSemanticElementIdentity = exports.refractorPluginElementIdentity = exports.mergeRight = exports.mergeLeft = exports.from = exports.fixedFields = exports.dispatchRefractorPlugins = exports.dehydrate = exports.defaultIdentityManager = exports.deepmerge = exports.createToolbox = exports.Transcluder = exports.MediaTypes = exports.IdentityManager = exports.ElementIdentityError = void 0;
-var _index = require("./refractor/plugins/dispatcher/index.cjs");
-exports.dispatchRefractorPlugins = _index.dispatchPluginsSync;
-var _toolbox = _interopRequireDefault(require("./refractor/toolbox.cjs"));
-exports.createToolbox = _toolbox.default;
-var _elementIdentity = _interopRequireDefault(require("./refractor/plugins/element-identity.cjs"));
-exports.refractorPluginElementIdentity = _elementIdentity.default;
-var _semanticElementIdentity = _interopRequireDefault(require("./refractor/plugins/semantic-element-identity.cjs"));
-exports.refractorPluginSemanticElementIdentity = _semanticElementIdentity.default;
-var _mediaTypes = _interopRequireDefault(require("./media-types.cjs"));
-exports.MediaTypes = _mediaTypes.default;
-var _index2 = _interopRequireWildcard(require("./transcluder/index.cjs"));
-exports.transclude = _index2.transclude;
-exports.Transcluder = _index2.default;
-var _specification = require("./specification.cjs");
-exports.resolveSpecification = _specification.resolveSpecification;
-var _index3 = require("./identity/index.cjs");
-exports.defaultIdentityManager = _index3.defaultIdentityManager;
-exports.IdentityManager = _index3.IdentityManager;
-var _ElementIdentityError = _interopRequireDefault(require("./identity/errors/ElementIdentityError.cjs"));
-exports.ElementIdentityError = _ElementIdentityError.default;
-var _from = _interopRequireDefault(require("./transformers/from.cjs"));
-exports.from = _from.default;
-var _value = _interopRequireDefault(require("./transformers/serializers/value.cjs"));
-exports.toValue = _value.default;
-var _json = _interopRequireDefault(require("./transformers/serializers/json.cjs"));
-exports.toJSON = _json.default;
-var _yaml = _interopRequireDefault(require("./transformers/serializers/yaml-1-2.cjs"));
-exports.toYAML = _yaml.default;
-var _dehydrate = _interopRequireDefault(require("./transformers/dehydrate.cjs"));
-exports.dehydrate = _dehydrate.default;
-var _toString = _interopRequireDefault(require("./transformers/to-string.cjs"));
-exports.toString = _toString.default;
-var _sexprs = _interopRequireDefault(require("./transformers/sexprs.cjs"));
-exports.sexprs = _sexprs.default;
-var _deepmerge = _interopRequireDefault(require("./merge/deepmerge.cjs"));
-exports.deepmerge = _deepmerge.default;
-var _mergeRight = _interopRequireDefault(require("./merge/merge-right.cjs"));
-exports.mergeRight = _mergeRight.default;
-var _mergeLeft = _interopRequireDefault(require("./merge/merge-left.cjs"));
-exports.mergeLeft = _mergeLeft.default;
-var _index4 = require("./fields/index.cjs");
-exports.fixedFields = _index4.fixedFields;

package/src/index.mjs

@@ -1,41 +0,0 @@
-export { dispatchPluginsSync as dispatchRefractorPlugins } from "./refractor/plugins/dispatcher/index.mjs";
-export { default as createToolbox } from "./refractor/toolbox.mjs";
-export { default as refractorPluginElementIdentity } from "./refractor/plugins/element-identity.mjs";
-export { default as refractorPluginSemanticElementIdentity } from "./refractor/plugins/semantic-element-identity.mjs";
-export { default as MediaTypes } from "./media-types.mjs";
-export { transclude, default as Transcluder } from "./transcluder/index.mjs";
-export { resolveSpecification } from "./specification.mjs";
-export { defaultIdentityManager, IdentityManager } from "./identity/index.mjs";
-export { default as ElementIdentityError } from "./identity/errors/ElementIdentityError.mjs";
-/**
- * Transforms data to an Element from a particular namespace.
- */
-export { default as from } from "./transformers/from.mjs";
-/**
- * Transforms the ApiDOM into JavaScript POJO.
- * This POJO would be the result of interpreting the ApiDOM
- * into JavaScript structure.
- */
-export { default as toValue } from "./transformers/serializers/value.mjs";
-/**
- * Transforms the ApiDOM into JSON string.
- */
-export { default as toJSON } from "./transformers/serializers/json.mjs";
-/**
- * Transforms the ApiDOM into YAML string.
- */
-export { default as toYAML } from "./transformers/serializers/yaml-1-2.mjs";
-/**
- * Creates a refract representation of an Element.
- * https://github.com/refractproject/refract-spec
- */
-export { default as dehydrate } from "./transformers/dehydrate.mjs";
-/**
- * Create a refracted string representation of an Element.
- */
-export { default as toString } from "./transformers/to-string.mjs";
-export { default as sexprs } from "./transformers/sexprs.mjs";
-export { default as deepmerge } from "./merge/deepmerge.mjs";
-export { default as mergeRight } from "./merge/merge-right.mjs";
-export { default as mergeLeft } from "./merge/merge-left.mjs";
-export { fixedFields } from "./fields/index.mjs";

package/src/media-types.cjs

@@ -1,21 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.default = void 0;
-var _apidomError = require("@speclynx/apidom-error");
-/**
- * @public
- */
-class MediaTypes extends Array {
-  unknownMediaType = 'application/octet-stream';
-  filterByFormat() {
-    throw new _apidomError.NotImplementedError('filterByFormat method in MediaTypes class is not yet implemented.');
-  }
-  findBy() {
-    throw new _apidomError.NotImplementedError('findBy method in MediaTypes class is not yet implemented.');
-  }
-  latest() {
-    throw new _apidomError.NotImplementedError('latest method in MediaTypes class is not yet implemented.');
-  }
-}
-var _default = exports.default = MediaTypes;

package/src/media-types.mjs

@@ -1,18 +0,0 @@
-import { NotImplementedError } from '@speclynx/apidom-error';
-
-/**
- * @public
- */
-class MediaTypes extends Array {
-  unknownMediaType = 'application/octet-stream';
-  filterByFormat() {
-    throw new NotImplementedError('filterByFormat method in MediaTypes class is not yet implemented.');
-  }
-  findBy() {
-    throw new NotImplementedError('findBy method in MediaTypes class is not yet implemented.');
-  }
-  latest() {
-    throw new NotImplementedError('latest method in MediaTypes class is not yet implemented.');
-  }
-}
-export default MediaTypes;