@speclynx/apidom-json-pointer-relative 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-json-pointer-relative
+
 ## [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-json-pointer-relative

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-json-pointer-relative",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "description": "Evaluate Relative JSON Pointer expressions against ApiDOM.",
   "keywords": [
     "apidom",
@@ -54,16 +54,15 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-datamodel": "4.0.1",
-    "@speclynx/apidom-error": "4.0.1",
-    "@speclynx/apidom-json-pointer": "4.0.1",
-    "@speclynx/apidom-traverse": "4.0.1",
+    "@speclynx/apidom-datamodel": "4.0.3",
+    "@speclynx/apidom-error": "4.0.3",
+    "@speclynx/apidom-json-pointer": "4.0.3",
+    "@speclynx/apidom-traverse": "4.0.3",
     "ramda": "~0.32.0",
     "ramda-adjunct": "^6.0.0"
   },
   "files": [
-    "src/**/*.mjs",
-    "src/**/*.cjs",
+    "src/",
     "dist/",
     "types/apidom-json-pointer-relative.d.ts",
     "LICENSES",
@@ -71,5 +70,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "223132a9b00081ca04842efc2736a491f7876f44"
+  "gitHead": "6ccfa09c02232516215e7de3ead276641957e626"
 }

package/src/compile.cjs

@@ -0,0 +1,37 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var _CompilationRelativeJsonPointerError = _interopRequireDefault(require("./errors/CompilationRelativeJsonPointerError.cjs"));
+/**
+ * @public
+ */
+const compile = relativeJsonPointer => {
+  try {
+    let relativePointer = '';
+
+    // non-negative-integer
+    relativePointer += String(relativeJsonPointer.nonNegativeIntegerPrefix);
+
+    // index-manipulation
+    if (typeof relativeJsonPointer.indexManipulation === 'number') {
+      relativePointer += String(relativeJsonPointer.indexManipulation);
+    }
+    if (Array.isArray(relativeJsonPointer.jsonPointerTokens)) {
+      // <json-pointer>
+      relativePointer += (0, _apidomJsonPointer.compile)(relativeJsonPointer.jsonPointerTokens);
+    } else if (relativeJsonPointer.hashCharacter) {
+      // "#"
+      relativePointer += '#';
+    }
+    return relativePointer;
+  } catch (error) {
+    throw new _CompilationRelativeJsonPointerError.default('Relative JSON Pointer compilation encountered an error.', {
+      relativePointer: relativeJsonPointer,
+      cause: error
+    });
+  }
+};
+var _default = exports.default = compile;

package/src/compile.mjs

@@ -0,0 +1,32 @@
+import { compile as compileJsonPointer } from '@speclynx/apidom-json-pointer';
+import CompilationRelativeJsonPointerError from "./errors/CompilationRelativeJsonPointerError.mjs";
+/**
+ * @public
+ */
+const compile = relativeJsonPointer => {
+  try {
+    let relativePointer = '';
+
+    // non-negative-integer
+    relativePointer += String(relativeJsonPointer.nonNegativeIntegerPrefix);
+
+    // index-manipulation
+    if (typeof relativeJsonPointer.indexManipulation === 'number') {
+      relativePointer += String(relativeJsonPointer.indexManipulation);
+    }
+    if (Array.isArray(relativeJsonPointer.jsonPointerTokens)) {
+      // <json-pointer>
+      relativePointer += compileJsonPointer(relativeJsonPointer.jsonPointerTokens);
+    } else if (relativeJsonPointer.hashCharacter) {
+      // "#"
+      relativePointer += '#';
+    }
+    return relativePointer;
+  } catch (error) {
+    throw new CompilationRelativeJsonPointerError('Relative JSON Pointer compilation encountered an error.', {
+      relativePointer: relativeJsonPointer,
+      cause: error
+    });
+  }
+};
+export default compile;

package/src/compile.ts

@@ -0,0 +1,41 @@
+import { compile as compileJsonPointer } from '@speclynx/apidom-json-pointer';
+
+import { RelativeJsonPointer } from './types.ts';
+import CompilationRelativeJsonPointerError from './errors/CompilationRelativeJsonPointerError.ts';
+
+/**
+ * @public
+ */
+const compile = (relativeJsonPointer: RelativeJsonPointer): string => {
+  try {
+    let relativePointer = '';
+
+    // non-negative-integer
+    relativePointer += String(relativeJsonPointer.nonNegativeIntegerPrefix);
+
+    // index-manipulation
+    if (typeof relativeJsonPointer.indexManipulation === 'number') {
+      relativePointer += String(relativeJsonPointer.indexManipulation);
+    }
+
+    if (Array.isArray(relativeJsonPointer.jsonPointerTokens)) {
+      // <json-pointer>
+      relativePointer += compileJsonPointer(relativeJsonPointer.jsonPointerTokens);
+    } else if (relativeJsonPointer.hashCharacter) {
+      // "#"
+      relativePointer += '#';
+    }
+
+    return relativePointer;
+  } catch (error: unknown) {
+    throw new CompilationRelativeJsonPointerError(
+      'Relative JSON Pointer compilation encountered an error.',
+      {
+        relativePointer: relativeJsonPointer,
+        cause: error,
+      },
+    );
+  }
+};
+
+export default compile;

package/src/errors/CompilationRelativeJsonPointerError.cjs

@@ -0,0 +1,31 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _RelativeJsonPointerError = _interopRequireDefault(require("./RelativeJsonPointerError.cjs"));
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class CompilationRelativeJsonPointerError extends _RelativeJsonPointerError.default {
+  nonNegativeIntegerPrefix;
+  indexManipulation;
+  jsonPointerTokens;
+  hashCharacter;
+  constructor(message, structuredOptions) {
+    super(message, structuredOptions);
+    if (typeof structuredOptions !== 'undefined') {
+      this.nonNegativeIntegerPrefix = structuredOptions.relativePointer.nonNegativeIntegerPrefix;
+      this.indexManipulation = structuredOptions.relativePointer.indexManipulation;
+      this.hashCharacter = structuredOptions.relativePointer.hashCharacter;
+      if (Array.isArray(structuredOptions.relativePointer.jsonPointerTokens)) {
+        this.jsonPointerTokens = [...structuredOptions.relativePointer.jsonPointerTokens];
+      }
+    }
+  }
+}
+var _default = exports.default = CompilationRelativeJsonPointerError;

package/src/errors/CompilationRelativeJsonPointerError.mjs

@@ -0,0 +1,25 @@
+import RelativeJsonPointerError from "./RelativeJsonPointerError.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+class CompilationRelativeJsonPointerError extends RelativeJsonPointerError {
+  nonNegativeIntegerPrefix;
+  indexManipulation;
+  jsonPointerTokens;
+  hashCharacter;
+  constructor(message, structuredOptions) {
+    super(message, structuredOptions);
+    if (typeof structuredOptions !== 'undefined') {
+      this.nonNegativeIntegerPrefix = structuredOptions.relativePointer.nonNegativeIntegerPrefix;
+      this.indexManipulation = structuredOptions.relativePointer.indexManipulation;
+      this.hashCharacter = structuredOptions.relativePointer.hashCharacter;
+      if (Array.isArray(structuredOptions.relativePointer.jsonPointerTokens)) {
+        this.jsonPointerTokens = [...structuredOptions.relativePointer.jsonPointerTokens];
+      }
+    }
+  }
+}
+export default CompilationRelativeJsonPointerError;

package/src/errors/CompilationRelativeJsonPointerError.ts

@@ -0,0 +1,39 @@
+import { ApiDOMErrorOptions } from '@speclynx/apidom-error';
+
+import { RelativeJsonPointer } from '../types.ts';
+import RelativeJsonPointerError from './RelativeJsonPointerError.ts';
+
+/**
+ * @public
+ */
+export interface CompilationRelativeJsonPointerErrorOptions extends ApiDOMErrorOptions {
+  readonly relativePointer: RelativeJsonPointer;
+}
+
+/**
+ * @public
+ */
+class CompilationRelativeJsonPointerError extends RelativeJsonPointerError {
+  public readonly nonNegativeIntegerPrefix!: number;
+
+  public readonly indexManipulation?: number;
+
+  public readonly jsonPointerTokens?: string[];
+
+  public readonly hashCharacter?: boolean;
+
+  constructor(message?: string, structuredOptions?: CompilationRelativeJsonPointerErrorOptions) {
+    super(message, structuredOptions);
+
+    if (typeof structuredOptions !== 'undefined') {
+      this.nonNegativeIntegerPrefix = structuredOptions.relativePointer.nonNegativeIntegerPrefix;
+      this.indexManipulation = structuredOptions.relativePointer.indexManipulation;
+      this.hashCharacter = structuredOptions.relativePointer.hashCharacter;
+      if (Array.isArray(structuredOptions.relativePointer.jsonPointerTokens)) {
+        this.jsonPointerTokens = [...structuredOptions.relativePointer.jsonPointerTokens];
+      }
+    }
+  }
+}
+
+export default CompilationRelativeJsonPointerError;

package/src/errors/EvaluationRelativeJsonPointerError.cjs

@@ -0,0 +1,29 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _RelativeJsonPointerError = _interopRequireDefault(require("./RelativeJsonPointerError.cjs"));
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class EvaluationRelativeJsonPointerError extends _RelativeJsonPointerError.default {
+  relativePointer;
+  currentElement;
+  rootElement;
+  cursorElement;
+  constructor(message, structuredOptions) {
+    super(message, structuredOptions);
+    if (typeof structuredOptions !== 'undefined') {
+      this.relativePointer = structuredOptions.relativePointer;
+      this.currentElement = structuredOptions.currentElement;
+      this.rootElement = structuredOptions.rootElement;
+      this.cursorElement = structuredOptions.cursorElement;
+    }
+  }
+}
+var _default = exports.default = EvaluationRelativeJsonPointerError;

package/src/errors/EvaluationRelativeJsonPointerError.mjs

@@ -0,0 +1,23 @@
+import RelativeJsonPointerError from "./RelativeJsonPointerError.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+class EvaluationRelativeJsonPointerError extends RelativeJsonPointerError {
+  relativePointer;
+  currentElement;
+  rootElement;
+  cursorElement;
+  constructor(message, structuredOptions) {
+    super(message, structuredOptions);
+    if (typeof structuredOptions !== 'undefined') {
+      this.relativePointer = structuredOptions.relativePointer;
+      this.currentElement = structuredOptions.currentElement;
+      this.rootElement = structuredOptions.rootElement;
+      this.cursorElement = structuredOptions.cursorElement;
+    }
+  }
+}
+export default EvaluationRelativeJsonPointerError;

package/src/errors/EvaluationRelativeJsonPointerError.ts

@@ -0,0 +1,51 @@
+import { Element } from '@speclynx/apidom-datamodel';
+import { ApiDOMErrorOptions } from '@speclynx/apidom-error';
+
+import RelativeJsonPointerError from './RelativeJsonPointerError.ts';
+
+/**
+ * @public
+ */
+export interface EvaluationRelativeJsonPointerErrorOptions<
+  T extends Element,
+  U extends Element,
+  V extends Element,
+> extends ApiDOMErrorOptions {
+  readonly relativePointer: string;
+  readonly currentElement: T;
+  readonly rootElement: U;
+  readonly cursorElement?: V;
+}
+
+/**
+ * @public
+ */
+class EvaluationRelativeJsonPointerError<
+  T extends Element,
+  U extends Element,
+  V extends Element,
+> extends RelativeJsonPointerError {
+  public readonly relativePointer!: string;
+
+  public readonly currentElement!: T;
+
+  public readonly rootElement!: U;
+
+  public readonly cursorElement?: V;
+
+  constructor(
+    message?: string,
+    structuredOptions?: EvaluationRelativeJsonPointerErrorOptions<T, U, V>,
+  ) {
+    super(message, structuredOptions);
+
+    if (typeof structuredOptions !== 'undefined') {
+      this.relativePointer = structuredOptions.relativePointer;
+      this.currentElement = structuredOptions.currentElement;
+      this.rootElement = structuredOptions.rootElement;
+      this.cursorElement = structuredOptions.cursorElement;
+    }
+  }
+}
+
+export default EvaluationRelativeJsonPointerError;

package/src/errors/InvalidRelativeJsonPointerError.cjs

@@ -0,0 +1,23 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _RelativeJsonPointerError = _interopRequireDefault(require("./RelativeJsonPointerError.cjs"));
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class InvalidRelativeJsonPointerError extends _RelativeJsonPointerError.default {
+  relativePointer;
+  constructor(message, structuredOptions) {
+    super(message, structuredOptions);
+    if (typeof structuredOptions !== 'undefined') {
+      this.relativePointer = structuredOptions.relativePointer;
+    }
+  }
+}
+exports.default = InvalidRelativeJsonPointerError;

package/src/errors/InvalidRelativeJsonPointerError.mjs

@@ -0,0 +1,16 @@
+import RelativeJsonPointerError from "./RelativeJsonPointerError.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+export default class InvalidRelativeJsonPointerError extends RelativeJsonPointerError {
+  relativePointer;
+  constructor(message, structuredOptions) {
+    super(message, structuredOptions);
+    if (typeof structuredOptions !== 'undefined') {
+      this.relativePointer = structuredOptions.relativePointer;
+    }
+  }
+}

package/src/errors/InvalidRelativeJsonPointerError.ts

@@ -0,0 +1,25 @@
+import { ApiDOMErrorOptions } from '@speclynx/apidom-error';
+
+import RelativeJsonPointerError from './RelativeJsonPointerError.ts';
+
+/**
+ * @public
+ */
+export interface InvalidRelativeJsonPointerErrorOptions extends ApiDOMErrorOptions {
+  readonly relativePointer: string;
+}
+
+/**
+ * @public
+ */
+export default class InvalidRelativeJsonPointerError extends RelativeJsonPointerError {
+  public readonly relativePointer!: string;
+
+  constructor(message?: string, structuredOptions?: InvalidRelativeJsonPointerErrorOptions) {
+    super(message, structuredOptions);
+
+    if (typeof structuredOptions !== 'undefined') {
+      this.relativePointer = structuredOptions.relativePointer;
+    }
+  }
+}

package/src/errors/RelativeJsonPointerError.cjs

@@ -0,0 +1,10 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomError = require("@speclynx/apidom-error");
+/**
+ * @public
+ */
+class RelativeJsonPointerError extends _apidomError.ApiDOMStructuredError {}
+var _default = exports.default = RelativeJsonPointerError;

package/src/errors/RelativeJsonPointerError.mjs

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

package/src/errors/RelativeJsonPointerError.ts

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

package/src/evaluate.cjs

@@ -0,0 +1,127 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomTraverse = require("@speclynx/apidom-traverse");
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var _ramda = require("ramda");
+var _EvaluationRelativeJsonPointerError = _interopRequireDefault(require("./errors/EvaluationRelativeJsonPointerError.cjs"));
+var _parse = _interopRequireDefault(require("./parse.cjs"));
+/**
+ * Evaluates Relative JSON Pointer against ApiDOM fragment.
+ * @public
+ */
+const evaluate = (relativePointer, currentElement, rootElement) => {
+  let ancestorLineage = [];
+  let cursor = currentElement;
+  (0, _apidomTraverse.traverse)(rootElement, {
+    enter(path) {
+      if (path.node === currentElement) {
+        ancestorLineage = path.getAncestorNodes().reverse().filter(_apidomDatamodel.isElement);
+        path.stop();
+      }
+    }
+  });
+  if (ancestorLineage.length === 0) {
+    throw new _EvaluationRelativeJsonPointerError.default('Relative JSON Pointer evaluation failed. Current element not found inside the root element', {
+      relativePointer,
+      currentElement: (0, _apidomDatamodel.cloneDeep)(currentElement),
+      rootElement: (0, _apidomDatamodel.cloneDeep)(rootElement),
+      cursorElement: _apidomDatamodel.cloneDeep.safe(cursor)
+    });
+  }
+  if ((0, _ramda.last)(ancestorLineage) === rootElement) {
+    throw new _EvaluationRelativeJsonPointerError.default('Relative JSON Pointer evaluation failed. Current element cannot be the root element', {
+      relativePointer,
+      currentElement,
+      rootElement,
+      cursorElement: cursor
+    });
+  }
+  let relativeJsonPointer;
+  try {
+    relativeJsonPointer = (0, _parse.default)(relativePointer);
+  } catch (error) {
+    throw new _EvaluationRelativeJsonPointerError.default('Relative JSON Pointer evaluation failed while parsing the pointer.', {
+      relativePointer,
+      currentElement: (0, _apidomDatamodel.cloneDeep)(currentElement),
+      rootElement: (0, _apidomDatamodel.cloneDeep)(currentElement),
+      cursorElement: _apidomDatamodel.cloneDeep.safe(cursor),
+      cause: error
+    });
+  }
+
+  // non-negative-integer
+  if (relativeJsonPointer.nonNegativeIntegerPrefix > 0) {
+    const ancestorLineageCopy = [...ancestorLineage];
+    for (let {
+      nonNegativeIntegerPrefix
+    } = relativeJsonPointer; nonNegativeIntegerPrefix > 0; nonNegativeIntegerPrefix -= 1) {
+      cursor = ancestorLineageCopy.pop();
+      if ((0, _apidomDatamodel.isMemberElement)(cursor)) {
+        cursor = ancestorLineageCopy.pop();
+      }
+    }
+    if (typeof cursor === 'undefined') {
+      throw new _EvaluationRelativeJsonPointerError.default(`Relative JSON Pointer evaluation failed on non-negative-integer prefix of "${relativeJsonPointer.nonNegativeIntegerPrefix}"`, {
+        relativePointer,
+        currentElement: (0, _apidomDatamodel.cloneDeep)(currentElement),
+        rootElement: (0, _apidomDatamodel.cloneDeep)(rootElement),
+        cursorElement: _apidomDatamodel.cloneDeep.safe(cursor)
+      });
+    }
+    ancestorLineage = ancestorLineageCopy;
+  }
+
+  // index-manipulation
+  if (typeof relativeJsonPointer.indexManipulation === 'number') {
+    const containedArray = (0, _ramda.last)(ancestorLineage);
+    if (typeof containedArray === 'undefined' || !(0, _apidomDatamodel.isArrayElement)(containedArray)) {
+      throw new _EvaluationRelativeJsonPointerError.default(`Relative JSON Pointer evaluation failed failed on index-manipulation "${relativeJsonPointer.indexManipulation}"`, {
+        relativePointer,
+        currentElement: (0, _apidomDatamodel.cloneDeep)(currentElement),
+        rootElement: (0, _apidomDatamodel.cloneDeep)(rootElement),
+        cursorElement: _apidomDatamodel.cloneDeep.safe(cursor)
+      });
+    }
+    const arrayContent = containedArray.content;
+    const currentCursorIndex = arrayContent.indexOf(cursor);
+    const newCursorIndex = currentCursorIndex + relativeJsonPointer.indexManipulation;
+    cursor = arrayContent[newCursorIndex];
+    if (typeof cursor === 'undefined') {
+      throw new _EvaluationRelativeJsonPointerError.default(`Relative JSON Pointer evaluation failed on index-manipulation "${relativeJsonPointer.indexManipulation}"`, {
+        relativePointer,
+        currentElement: (0, _apidomDatamodel.cloneDeep)(currentElement),
+        rootElement: (0, _apidomDatamodel.cloneDeep)(rootElement),
+        cursorElement: _apidomDatamodel.cloneDeep.safe(cursor)
+      });
+    }
+  }
+  if (Array.isArray(relativeJsonPointer.jsonPointerTokens)) {
+    // <json-pointer>
+    const jsonPointer = (0, _apidomJsonPointer.compile)(relativeJsonPointer.jsonPointerTokens);
+    cursor = (0, _apidomJsonPointer.evaluate)(cursor, jsonPointer);
+  } else if (relativeJsonPointer.hashCharacter) {
+    // "#"
+    if (cursor === rootElement) {
+      throw new _EvaluationRelativeJsonPointerError.default('Relative JSON Pointer evaluation failed. Current element cannot be the root element to apply "#"', {
+        relativePointer,
+        currentElement: (0, _apidomDatamodel.cloneDeep)(currentElement),
+        rootElement: (0, _apidomDatamodel.cloneDeep)(rootElement),
+        cursorElement: _apidomDatamodel.cloneDeep.safe(cursor)
+      });
+    }
+    const parentElement = (0, _ramda.last)(ancestorLineage);
+    if (typeof parentElement !== 'undefined') {
+      if ((0, _apidomDatamodel.isMemberElement)(parentElement)) {
+        cursor = parentElement.key;
+      } else if ((0, _apidomDatamodel.isArrayElement)(parentElement)) {
+        cursor = new _apidomDatamodel.NumberElement(parentElement.content.indexOf(cursor));
+      }
+    }
+  }
+  return cursor;
+};
+var _default = exports.default = evaluate;

package/src/evaluate.mjs

@@ -0,0 +1,122 @@
+import { isElement, isMemberElement, isArrayElement, NumberElement, cloneDeep } from '@speclynx/apidom-datamodel';
+import { traverse } from '@speclynx/apidom-traverse';
+import { compile as compileJsonPointer, evaluate as evaluateJsonPointer } from '@speclynx/apidom-json-pointer';
+import { last } from 'ramda';
+import EvaluationRelativeJsonPointerError from "./errors/EvaluationRelativeJsonPointerError.mjs";
+import parse from "./parse.mjs";
+/**
+ * Evaluates Relative JSON Pointer against ApiDOM fragment.
+ * @public
+ */
+const evaluate = (relativePointer, currentElement, rootElement) => {
+  let ancestorLineage = [];
+  let cursor = currentElement;
+  traverse(rootElement, {
+    enter(path) {
+      if (path.node === currentElement) {
+        ancestorLineage = path.getAncestorNodes().reverse().filter(isElement);
+        path.stop();
+      }
+    }
+  });
+  if (ancestorLineage.length === 0) {
+    throw new EvaluationRelativeJsonPointerError('Relative JSON Pointer evaluation failed. Current element not found inside the root element', {
+      relativePointer,
+      currentElement: cloneDeep(currentElement),
+      rootElement: cloneDeep(rootElement),
+      cursorElement: cloneDeep.safe(cursor)
+    });
+  }
+  if (last(ancestorLineage) === rootElement) {
+    throw new EvaluationRelativeJsonPointerError('Relative JSON Pointer evaluation failed. Current element cannot be the root element', {
+      relativePointer,
+      currentElement,
+      rootElement,
+      cursorElement: cursor
+    });
+  }
+  let relativeJsonPointer;
+  try {
+    relativeJsonPointer = parse(relativePointer);
+  } catch (error) {
+    throw new EvaluationRelativeJsonPointerError('Relative JSON Pointer evaluation failed while parsing the pointer.', {
+      relativePointer,
+      currentElement: cloneDeep(currentElement),
+      rootElement: cloneDeep(currentElement),
+      cursorElement: cloneDeep.safe(cursor),
+      cause: error
+    });
+  }
+
+  // non-negative-integer
+  if (relativeJsonPointer.nonNegativeIntegerPrefix > 0) {
+    const ancestorLineageCopy = [...ancestorLineage];
+    for (let {
+      nonNegativeIntegerPrefix
+    } = relativeJsonPointer; nonNegativeIntegerPrefix > 0; nonNegativeIntegerPrefix -= 1) {
+      cursor = ancestorLineageCopy.pop();
+      if (isMemberElement(cursor)) {
+        cursor = ancestorLineageCopy.pop();
+      }
+    }
+    if (typeof cursor === 'undefined') {
+      throw new EvaluationRelativeJsonPointerError(`Relative JSON Pointer evaluation failed on non-negative-integer prefix of "${relativeJsonPointer.nonNegativeIntegerPrefix}"`, {
+        relativePointer,
+        currentElement: cloneDeep(currentElement),
+        rootElement: cloneDeep(rootElement),
+        cursorElement: cloneDeep.safe(cursor)
+      });
+    }
+    ancestorLineage = ancestorLineageCopy;
+  }
+
+  // index-manipulation
+  if (typeof relativeJsonPointer.indexManipulation === 'number') {
+    const containedArray = last(ancestorLineage);
+    if (typeof containedArray === 'undefined' || !isArrayElement(containedArray)) {
+      throw new EvaluationRelativeJsonPointerError(`Relative JSON Pointer evaluation failed failed on index-manipulation "${relativeJsonPointer.indexManipulation}"`, {
+        relativePointer,
+        currentElement: cloneDeep(currentElement),
+        rootElement: cloneDeep(rootElement),
+        cursorElement: cloneDeep.safe(cursor)
+      });
+    }
+    const arrayContent = containedArray.content;
+    const currentCursorIndex = arrayContent.indexOf(cursor);
+    const newCursorIndex = currentCursorIndex + relativeJsonPointer.indexManipulation;
+    cursor = arrayContent[newCursorIndex];
+    if (typeof cursor === 'undefined') {
+      throw new EvaluationRelativeJsonPointerError(`Relative JSON Pointer evaluation failed on index-manipulation "${relativeJsonPointer.indexManipulation}"`, {
+        relativePointer,
+        currentElement: cloneDeep(currentElement),
+        rootElement: cloneDeep(rootElement),
+        cursorElement: cloneDeep.safe(cursor)
+      });
+    }
+  }
+  if (Array.isArray(relativeJsonPointer.jsonPointerTokens)) {
+    // <json-pointer>
+    const jsonPointer = compileJsonPointer(relativeJsonPointer.jsonPointerTokens);
+    cursor = evaluateJsonPointer(cursor, jsonPointer);
+  } else if (relativeJsonPointer.hashCharacter) {
+    // "#"
+    if (cursor === rootElement) {
+      throw new EvaluationRelativeJsonPointerError('Relative JSON Pointer evaluation failed. Current element cannot be the root element to apply "#"', {
+        relativePointer,
+        currentElement: cloneDeep(currentElement),
+        rootElement: cloneDeep(rootElement),
+        cursorElement: cloneDeep.safe(cursor)
+      });
+    }
+    const parentElement = last(ancestorLineage);
+    if (typeof parentElement !== 'undefined') {
+      if (isMemberElement(parentElement)) {
+        cursor = parentElement.key;
+      } else if (isArrayElement(parentElement)) {
+        cursor = new NumberElement(parentElement.content.indexOf(cursor));
+      }
+    }
+  }
+  return cursor;
+};
+export default evaluate;

package/src/evaluate.ts

@@ -0,0 +1,178 @@
+import {
+  Element,
+  isElement,
+  isMemberElement,
+  isArrayElement,
+  MemberElement,
+  ArrayElement,
+  NumberElement,
+  cloneDeep,
+} from '@speclynx/apidom-datamodel';
+import { traverse, Path } from '@speclynx/apidom-traverse';
+import {
+  compile as compileJsonPointer,
+  evaluate as evaluateJsonPointer,
+} from '@speclynx/apidom-json-pointer';
+import { last } from 'ramda';
+
+import EvaluationRelativeJsonPointerError from './errors/EvaluationRelativeJsonPointerError.ts';
+import parse from './parse.ts';
+import { RelativeJsonPointer } from './types.ts';
+
+/**
+ * Evaluates Relative JSON Pointer against ApiDOM fragment.
+ * @public
+ */
+const evaluate = <T extends Element, U extends Element>(
+  relativePointer: string,
+  currentElement: T,
+  rootElement: U,
+): Element | undefined => {
+  let ancestorLineage: Element[] = [];
+  let cursor: Element | undefined = currentElement;
+
+  traverse(rootElement, {
+    enter(path: Path<Element>) {
+      if (path.node === currentElement) {
+        ancestorLineage = path.getAncestorNodes().reverse().filter(isElement);
+        path.stop();
+      }
+    },
+  });
+
+  if (ancestorLineage.length === 0) {
+    throw new EvaluationRelativeJsonPointerError(
+      'Relative JSON Pointer evaluation failed. Current element not found inside the root element',
+      {
+        relativePointer,
+        currentElement: cloneDeep(currentElement),
+        rootElement: cloneDeep(rootElement),
+        cursorElement: cloneDeep.safe(cursor),
+      },
+    );
+  }
+
+  if (last(ancestorLineage) === rootElement) {
+    throw new EvaluationRelativeJsonPointerError(
+      'Relative JSON Pointer evaluation failed. Current element cannot be the root element',
+      {
+        relativePointer,
+        currentElement,
+        rootElement,
+        cursorElement: cursor,
+      },
+    );
+  }
+
+  let relativeJsonPointer: RelativeJsonPointer;
+  try {
+    relativeJsonPointer = parse(relativePointer);
+  } catch (error: unknown) {
+    throw new EvaluationRelativeJsonPointerError(
+      'Relative JSON Pointer evaluation failed while parsing the pointer.',
+      {
+        relativePointer,
+        currentElement: cloneDeep(currentElement),
+        rootElement: cloneDeep(currentElement),
+        cursorElement: cloneDeep.safe(cursor),
+        cause: error,
+      },
+    );
+  }
+
+  // non-negative-integer
+  if (relativeJsonPointer.nonNegativeIntegerPrefix > 0) {
+    const ancestorLineageCopy = [...ancestorLineage];
+
+    for (
+      let { nonNegativeIntegerPrefix } = relativeJsonPointer;
+      nonNegativeIntegerPrefix > 0;
+      nonNegativeIntegerPrefix -= 1
+    ) {
+      cursor = ancestorLineageCopy.pop();
+      if (isMemberElement(cursor)) {
+        cursor = ancestorLineageCopy.pop();
+      }
+    }
+
+    if (typeof cursor === 'undefined') {
+      throw new EvaluationRelativeJsonPointerError(
+        `Relative JSON Pointer evaluation failed on non-negative-integer prefix of "${relativeJsonPointer.nonNegativeIntegerPrefix}"`,
+        {
+          relativePointer,
+          currentElement: cloneDeep(currentElement),
+          rootElement: cloneDeep(rootElement),
+          cursorElement: cloneDeep.safe(cursor),
+        },
+      );
+    }
+
+    ancestorLineage = ancestorLineageCopy;
+  }
+
+  // index-manipulation
+  if (typeof relativeJsonPointer.indexManipulation === 'number') {
+    const containedArray = last(ancestorLineage);
+
+    if (typeof containedArray === 'undefined' || !isArrayElement(containedArray)) {
+      throw new EvaluationRelativeJsonPointerError(
+        `Relative JSON Pointer evaluation failed failed on index-manipulation "${relativeJsonPointer.indexManipulation}"`,
+        {
+          relativePointer,
+          currentElement: cloneDeep(currentElement),
+          rootElement: cloneDeep(rootElement),
+          cursorElement: cloneDeep.safe(cursor),
+        },
+      );
+    }
+
+    const arrayContent = containedArray.content as Element[];
+    const currentCursorIndex = arrayContent.indexOf(cursor!);
+    const newCursorIndex = currentCursorIndex + relativeJsonPointer.indexManipulation;
+    cursor = arrayContent[newCursorIndex] as Element | undefined;
+
+    if (typeof cursor === 'undefined') {
+      throw new EvaluationRelativeJsonPointerError(
+        `Relative JSON Pointer evaluation failed on index-manipulation "${relativeJsonPointer.indexManipulation}"`,
+        {
+          relativePointer,
+          currentElement: cloneDeep(currentElement),
+          rootElement: cloneDeep(rootElement),
+          cursorElement: cloneDeep.safe(cursor),
+        },
+      );
+    }
+  }
+
+  if (Array.isArray(relativeJsonPointer.jsonPointerTokens)) {
+    // <json-pointer>
+    const jsonPointer = compileJsonPointer(relativeJsonPointer.jsonPointerTokens);
+    cursor = evaluateJsonPointer(cursor, jsonPointer);
+  } else if (relativeJsonPointer.hashCharacter) {
+    // "#"
+    if (cursor === rootElement) {
+      throw new EvaluationRelativeJsonPointerError(
+        'Relative JSON Pointer evaluation failed. Current element cannot be the root element to apply "#"',
+        {
+          relativePointer,
+          currentElement: cloneDeep(currentElement),
+          rootElement: cloneDeep(rootElement),
+          cursorElement: cloneDeep.safe(cursor),
+        },
+      );
+    }
+
+    const parentElement = last(ancestorLineage) as ArrayElement | MemberElement | undefined;
+    if (typeof parentElement !== 'undefined') {
+      if (isMemberElement(parentElement)) {
+        cursor = (parentElement as MemberElement).key as Element;
+      } else if (isArrayElement(parentElement)) {
+        cursor = new NumberElement((parentElement.content as Element[]).indexOf(cursor!));
+      }
+    }
+  }
+
+  return cursor;
+};
+
+export default evaluate;

package/src/index.cjs

@@ -0,0 +1,21 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.parse = exports.isRelativeJsonPointer = exports.evaluate = exports.compile = exports.RelativeJsonPointerError = exports.InvalidRelativeJsonPointerError = exports.EvaluationRelativeJsonPointerError = exports.CompilationRelativeJsonPointerError = void 0;
+var _RelativeJsonPointerError = _interopRequireDefault(require("./errors/RelativeJsonPointerError.cjs"));
+exports.RelativeJsonPointerError = _RelativeJsonPointerError.default;
+var _InvalidRelativeJsonPointerError = _interopRequireDefault(require("./errors/InvalidRelativeJsonPointerError.cjs"));
+exports.InvalidRelativeJsonPointerError = _InvalidRelativeJsonPointerError.default;
+var _EvaluationRelativeJsonPointerError = _interopRequireDefault(require("./errors/EvaluationRelativeJsonPointerError.cjs"));
+exports.EvaluationRelativeJsonPointerError = _EvaluationRelativeJsonPointerError.default;
+var _CompilationRelativeJsonPointerError = _interopRequireDefault(require("./errors/CompilationRelativeJsonPointerError.cjs"));
+exports.CompilationRelativeJsonPointerError = _CompilationRelativeJsonPointerError.default;
+var _parse = _interopRequireWildcard(require("./parse.cjs"));
+exports.parse = _parse.default;
+exports.isRelativeJsonPointer = _parse.isRelativeJsonPointer;
+var _compile = _interopRequireDefault(require("./compile.cjs"));
+exports.compile = _compile.default;
+var _evaluate = _interopRequireDefault(require("./evaluate.cjs"));
+exports.evaluate = _evaluate.default;

package/src/index.mjs

@@ -0,0 +1,7 @@
+export { default as RelativeJsonPointerError } from "./errors/RelativeJsonPointerError.mjs";
+export { default as InvalidRelativeJsonPointerError } from "./errors/InvalidRelativeJsonPointerError.mjs";
+export { default as EvaluationRelativeJsonPointerError } from "./errors/EvaluationRelativeJsonPointerError.mjs";
+export { default as CompilationRelativeJsonPointerError } from "./errors/CompilationRelativeJsonPointerError.mjs";
+export { default as parse, isRelativeJsonPointer } from "./parse.mjs";
+export { default as compile } from "./compile.mjs";
+export { default as evaluate } from "./evaluate.mjs";

package/src/index.ts

@@ -0,0 +1,11 @@
+export { default as RelativeJsonPointerError } from './errors/RelativeJsonPointerError.ts';
+export { default as InvalidRelativeJsonPointerError } from './errors/InvalidRelativeJsonPointerError.ts';
+export type { InvalidRelativeJsonPointerErrorOptions } from './errors/InvalidRelativeJsonPointerError.ts';
+export { default as EvaluationRelativeJsonPointerError } from './errors/EvaluationRelativeJsonPointerError.ts';
+export type { EvaluationRelativeJsonPointerErrorOptions } from './errors/EvaluationRelativeJsonPointerError.ts';
+export { default as CompilationRelativeJsonPointerError } from './errors/CompilationRelativeJsonPointerError.ts';
+export type { CompilationRelativeJsonPointerErrorOptions } from './errors/CompilationRelativeJsonPointerError.ts';
+export { default as parse, isRelativeJsonPointer } from './parse.ts';
+export { default as compile } from './compile.ts';
+export { default as evaluate } from './evaluate.ts';
+export type { RelativeJsonPointer } from './types.ts';

package/src/parse.cjs

@@ -0,0 +1,54 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.isRelativeJsonPointer = exports.default = void 0;
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var _InvalidRelativeJsonPointerError = _interopRequireDefault(require("./errors/InvalidRelativeJsonPointerError.cjs"));
+const nonNegativeIntegerPrefixRegExp = '(?<nonNegativeIntegerPrefix>[1-9]\\d*|0)';
+const indexManipulationRegExp = '(?<indexManipulation>[+-][1-9]\\d*|0)';
+const hashCharacterRegExp = '(?<hashCharacter>#)';
+const jsonPointerRegExp = '(?<jsonPointer>\\/.*)';
+const relativeJsonPointerRegExp = new RegExp(`^${nonNegativeIntegerPrefixRegExp}${indexManipulationRegExp}?(${hashCharacterRegExp}|${jsonPointerRegExp})?$`);
+
+/**
+ * @public
+ */
+const isRelativeJsonPointer = value => {
+  return typeof value === 'string' && relativeJsonPointerRegExp.test(value);
+};
+
+/**
+ * @public
+ */
+exports.isRelativeJsonPointer = isRelativeJsonPointer;
+const parse = relativePointer => {
+  const match = relativePointer.match(relativeJsonPointerRegExp);
+  if (match === null || typeof match.groups === 'undefined') {
+    throw new _InvalidRelativeJsonPointerError.default(`Invalid Relative JSON Pointer "${relativePointer}".`, {
+      relativePointer
+    });
+  }
+  try {
+    // non-negative-integer
+    const nonNegativeIntegerPrefix = parseInt(match.groups.nonNegativeIntegerPrefix, 10);
+    // index-manipulation
+    const indexManipulation = typeof match.groups.indexManipulation === 'string' ? parseInt(match.groups.indexManipulation, 10) : undefined;
+    // <json-pointer>
+    const jsonPointerTokens = typeof match.groups.jsonPointer === 'string' ? (0, _apidomJsonPointer.parse)(match.groups.jsonPointer).tree : undefined;
+    // "#"
+    const hashCharacter = typeof match.groups.hashCharacter === 'string';
+    return {
+      nonNegativeIntegerPrefix,
+      indexManipulation,
+      jsonPointerTokens,
+      hashCharacter
+    };
+  } catch (error) {
+    throw new _InvalidRelativeJsonPointerError.default(`Relative JSON Pointer parsing of "${relativePointer}" encountered an error.`, {
+      relativePointer,
+      cause: error
+    });
+  }
+};
+var _default = exports.default = parse;

package/src/parse.mjs

@@ -0,0 +1,48 @@
+import { parse as parseJsonPointer } from '@speclynx/apidom-json-pointer';
+import InvalidRelativeJsonPointerError from "./errors/InvalidRelativeJsonPointerError.mjs";
+const nonNegativeIntegerPrefixRegExp = '(?<nonNegativeIntegerPrefix>[1-9]\\d*|0)';
+const indexManipulationRegExp = '(?<indexManipulation>[+-][1-9]\\d*|0)';
+const hashCharacterRegExp = '(?<hashCharacter>#)';
+const jsonPointerRegExp = '(?<jsonPointer>\\/.*)';
+const relativeJsonPointerRegExp = new RegExp(`^${nonNegativeIntegerPrefixRegExp}${indexManipulationRegExp}?(${hashCharacterRegExp}|${jsonPointerRegExp})?$`);
+
+/**
+ * @public
+ */
+export const isRelativeJsonPointer = value => {
+  return typeof value === 'string' && relativeJsonPointerRegExp.test(value);
+};
+
+/**
+ * @public
+ */
+const parse = relativePointer => {
+  const match = relativePointer.match(relativeJsonPointerRegExp);
+  if (match === null || typeof match.groups === 'undefined') {
+    throw new InvalidRelativeJsonPointerError(`Invalid Relative JSON Pointer "${relativePointer}".`, {
+      relativePointer
+    });
+  }
+  try {
+    // non-negative-integer
+    const nonNegativeIntegerPrefix = parseInt(match.groups.nonNegativeIntegerPrefix, 10);
+    // index-manipulation
+    const indexManipulation = typeof match.groups.indexManipulation === 'string' ? parseInt(match.groups.indexManipulation, 10) : undefined;
+    // <json-pointer>
+    const jsonPointerTokens = typeof match.groups.jsonPointer === 'string' ? parseJsonPointer(match.groups.jsonPointer).tree : undefined;
+    // "#"
+    const hashCharacter = typeof match.groups.hashCharacter === 'string';
+    return {
+      nonNegativeIntegerPrefix,
+      indexManipulation,
+      jsonPointerTokens,
+      hashCharacter
+    };
+  } catch (error) {
+    throw new InvalidRelativeJsonPointerError(`Relative JSON Pointer parsing of "${relativePointer}" encountered an error.`, {
+      relativePointer,
+      cause: error
+    });
+  }
+};
+export default parse;

package/src/parse.ts

@@ -0,0 +1,66 @@
+import { parse as parseJsonPointer } from '@speclynx/apidom-json-pointer';
+
+import InvalidRelativeJsonPointerError from './errors/InvalidRelativeJsonPointerError.ts';
+import { RelativeJsonPointer } from './types.ts';
+
+const nonNegativeIntegerPrefixRegExp = '(?<nonNegativeIntegerPrefix>[1-9]\\d*|0)';
+const indexManipulationRegExp = '(?<indexManipulation>[+-][1-9]\\d*|0)';
+const hashCharacterRegExp = '(?<hashCharacter>#)';
+const jsonPointerRegExp = '(?<jsonPointer>\\/.*)';
+const relativeJsonPointerRegExp = new RegExp(
+  `^${nonNegativeIntegerPrefixRegExp}${indexManipulationRegExp}?(${hashCharacterRegExp}|${jsonPointerRegExp})?$`,
+);
+
+/**
+ * @public
+ */
+export const isRelativeJsonPointer = (value: any) => {
+  return typeof value === 'string' && relativeJsonPointerRegExp.test(value);
+};
+
+/**
+ * @public
+ */
+const parse = (relativePointer: string): RelativeJsonPointer => {
+  const match = relativePointer.match(relativeJsonPointerRegExp);
+  if (match === null || typeof match.groups === 'undefined') {
+    throw new InvalidRelativeJsonPointerError(
+      `Invalid Relative JSON Pointer "${relativePointer}".`,
+      { relativePointer },
+    );
+  }
+
+  try {
+    // non-negative-integer
+    const nonNegativeIntegerPrefix = parseInt(match.groups.nonNegativeIntegerPrefix, 10);
+    // index-manipulation
+    const indexManipulation =
+      typeof match.groups.indexManipulation === 'string'
+        ? parseInt(match.groups.indexManipulation, 10)
+        : undefined;
+    // <json-pointer>
+    const jsonPointerTokens =
+      typeof match.groups.jsonPointer === 'string'
+        ? parseJsonPointer(match.groups.jsonPointer).tree
+        : undefined;
+    // "#"
+    const hashCharacter = typeof match.groups.hashCharacter === 'string';
+
+    return {
+      nonNegativeIntegerPrefix,
+      indexManipulation,
+      jsonPointerTokens,
+      hashCharacter,
+    };
+  } catch (error: unknown) {
+    throw new InvalidRelativeJsonPointerError(
+      `Relative JSON Pointer parsing of "${relativePointer}" encountered an error.`,
+      {
+        relativePointer,
+        cause: error,
+      },
+    );
+  }
+};
+
+export default parse;

package/src/types.cjs

@@ -0,0 +1,3 @@
+"use strict";
+
+exports.__esModule = true;

package/src/types.mjs

@@ -0,0 +1 @@
+export {};

package/src/types.ts

@@ -0,0 +1,9 @@
+/**
+ * @public
+ */
+export type RelativeJsonPointer = {
+  readonly nonNegativeIntegerPrefix: number;
+  readonly indexManipulation?: number;
+  readonly jsonPointerTokens?: string[];
+  readonly hashCharacter?: boolean;
+};