@speclynx/apidom-json-pointer-relative 1.12.1

package/src/evaluate.cjs

@@ -0,0 +1,126 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomCore = require("@speclynx/apidom-core");
+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, _apidomCore.visit)(rootElement, {
+    enter(element, key, parent, path, ancestors) {
+      if (element === currentElement) {
+        ancestorLineage = [...ancestors, parent].filter(_apidomCore.isElement);
+        return _apidomCore.BREAK;
+      }
+      return undefined;
+    }
+  });
+  if (ancestorLineage.length === 0) {
+    throw new _EvaluationRelativeJsonPointerError.default('Relative JSON Pointer evaluation failed. Current element not found inside the root element', {
+      relativePointer,
+      currentElement: (0, _apidomCore.cloneDeep)(currentElement),
+      rootElement: (0, _apidomCore.cloneDeep)(rootElement),
+      cursorElement: _apidomCore.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, _apidomCore.cloneDeep)(currentElement),
+      rootElement: (0, _apidomCore.cloneDeep)(currentElement),
+      cursorElement: _apidomCore.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, _apidomCore.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, _apidomCore.cloneDeep)(currentElement),
+        rootElement: (0, _apidomCore.cloneDeep)(rootElement),
+        cursorElement: _apidomCore.cloneDeep.safe(cursor)
+      });
+    }
+    ancestorLineage = ancestorLineageCopy;
+  }
+
+  // index-manipulation
+  if (typeof relativeJsonPointer.indexManipulation === 'number') {
+    const containedArray = (0, _ramda.last)(ancestorLineage);
+    if (typeof containedArray === 'undefined' || !(0, _apidomCore.isArrayElement)(containedArray)) {
+      throw new _EvaluationRelativeJsonPointerError.default(`Relative JSON Pointer evaluation failed failed on index-manipulation "${relativeJsonPointer.indexManipulation}"`, {
+        relativePointer,
+        currentElement: (0, _apidomCore.cloneDeep)(currentElement),
+        rootElement: (0, _apidomCore.cloneDeep)(rootElement),
+        cursorElement: _apidomCore.cloneDeep.safe(cursor)
+      });
+    }
+    const currentCursorIndex = containedArray.content.indexOf(cursor);
+    const newCursorIndex = currentCursorIndex + relativeJsonPointer.indexManipulation;
+    cursor = containedArray.content[newCursorIndex];
+    if (typeof cursor === 'undefined') {
+      throw new _EvaluationRelativeJsonPointerError.default(`Relative JSON Pointer evaluation failed on index-manipulation "${relativeJsonPointer.indexManipulation}"`, {
+        relativePointer,
+        currentElement: (0, _apidomCore.cloneDeep)(currentElement),
+        rootElement: (0, _apidomCore.cloneDeep)(rootElement),
+        cursorElement: _apidomCore.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, _apidomCore.cloneDeep)(currentElement),
+        rootElement: (0, _apidomCore.cloneDeep)(rootElement),
+        cursorElement: _apidomCore.cloneDeep.safe(cursor)
+      });
+    }
+    const parentElement = (0, _ramda.last)(ancestorLineage);
+    if (typeof parentElement !== 'undefined') {
+      if ((0, _apidomCore.isMemberElement)(parentElement)) {
+        cursor = parentElement.key;
+      } else if ((0, _apidomCore.isArrayElement)(parentElement)) {
+        cursor = new _apidomCore.NumberElement(parentElement.content.indexOf(cursor));
+      }
+    }
+  }
+  return cursor;
+};
+var _default = exports.default = evaluate;

package/src/evaluate.mjs

@@ -0,0 +1,121 @@
+import { visit, cloneDeep, BREAK, isElement, isMemberElement, isArrayElement, NumberElement } from '@speclynx/apidom-core';
+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;
+  visit(rootElement, {
+    enter(element, key, parent, path, ancestors) {
+      if (element === currentElement) {
+        ancestorLineage = [...ancestors, parent].filter(isElement);
+        return BREAK;
+      }
+      return undefined;
+    }
+  });
+  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 currentCursorIndex = containedArray.content.indexOf(cursor);
+    const newCursorIndex = currentCursorIndex + relativeJsonPointer.indexManipulation;
+    cursor = containedArray.content[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/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/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/types.cjs

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

package/src/types.mjs

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

package/types/apidom-json-pointer-relative.d.ts

@@ -0,0 +1,96 @@
+import { ApiDOMErrorOptions } from '@speclynx/apidom-error';
+import { ApiDOMStructuredError } from '@speclynx/apidom-error';
+import { Element as Element_2 } from '@speclynx/apidom-core';
+
+/**
+ * @public
+ */
+export declare class CompilationRelativeJsonPointerError extends RelativeJsonPointerError {
+    readonly nonNegativeIntegerPrefix: number;
+    readonly indexManipulation?: number;
+    readonly jsonPointerTokens?: string[];
+    readonly hashCharacter?: boolean;
+    constructor(message?: string, structuredOptions?: CompilationRelativeJsonPointerErrorOptions);
+}
+
+/**
+ * @public
+ */
+export declare interface CompilationRelativeJsonPointerErrorOptions extends ApiDOMErrorOptions {
+    readonly relativePointer: RelativeJsonPointer;
+}
+
+/**
+ * @public
+ */
+export declare const compile: (relativeJsonPointer: RelativeJsonPointer) => string;
+
+/**
+ * Evaluates Relative JSON Pointer against ApiDOM fragment.
+ * @public
+ */
+export declare const evaluate: <T extends Element_2, U extends Element_2>(relativePointer: string, currentElement: T, rootElement: U) => Element_2 | undefined;
+
+/**
+ * @public
+ */
+export declare class EvaluationRelativeJsonPointerError<T extends Element_2, U extends Element_2, V extends Element_2> extends RelativeJsonPointerError {
+    readonly relativePointer: string;
+    readonly currentElement: T;
+    readonly rootElement: U;
+    readonly cursorElement?: V;
+    constructor(message?: string, structuredOptions?: EvaluationRelativeJsonPointerErrorOptions<T, U, V>);
+}
+
+/**
+ * @public
+ */
+export declare interface EvaluationRelativeJsonPointerErrorOptions<T extends Element_2, U extends Element_2, V extends Element_2> extends ApiDOMErrorOptions {
+    readonly relativePointer: string;
+    readonly currentElement: T;
+    readonly rootElement: U;
+    readonly cursorElement?: V;
+}
+
+/**
+ * @public
+ */
+export declare class InvalidRelativeJsonPointerError extends RelativeJsonPointerError {
+    readonly relativePointer: string;
+    constructor(message?: string, structuredOptions?: InvalidRelativeJsonPointerErrorOptions);
+}
+
+/**
+ * @public
+ */
+export declare interface InvalidRelativeJsonPointerErrorOptions extends ApiDOMErrorOptions {
+    readonly relativePointer: string;
+}
+
+/**
+ * @public
+ */
+export declare const isRelativeJsonPointer: (value: any) => boolean;
+
+/**
+ * @public
+ */
+export declare const parse: (relativePointer: string) => RelativeJsonPointer;
+
+/**
+ * @public
+ */
+export declare type RelativeJsonPointer = {
+    readonly nonNegativeIntegerPrefix: number;
+    readonly indexManipulation?: number;
+    readonly jsonPointerTokens?: string[];
+    readonly hashCharacter?: boolean;
+};
+
+/**
+ * @public
+ */
+export declare class RelativeJsonPointerError extends ApiDOMStructuredError {
+}
+
+export { }