fix(ns-openapi-3-1): use spec compliant JSON Pointer implementation (#4880)

char0n · web-flow · commit 9499aa873344 · 2025-05-02T07:27:02.000+02:00
Refs #4870
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/apidom-json-path/package.json b/packages/apidom-json-path/package.json
@@ -40,7 +40,7 @@
     "@babel/runtime-corejs3": "^7.26.10",
     "@swagger-api/apidom-core": "^1.0.0-beta.33",
     "@swagger-api/apidom-error": "^1.0.0-beta.33",
-    "@swaggerexpert/json-pointer": "^2.9.0",
+    "@swagger-api/apidom-json-pointer": "^1.0.0-beta.33",
     "jsonpath-plus": "^10.0.6"
   },
   "files": [
diff --git a/packages/apidom-json-path/src/evaluate-multi.ts b/packages/apidom-json-path/src/evaluate-multi.ts
@@ -1,5 +1,5 @@
 import { JSONPath } from 'jsonpath-plus';
-import { evaluate as jsonPointerEvaluate } from '@swaggerexpert/json-pointer/evaluate/realms/apidom';
+import { evaluate as jsonPointerEvaluate } from '@swagger-api/apidom-json-pointer/modern';
 import { Element, toValue, cloneDeep } from '@swagger-api/apidom-core';
 
 import MultiEvaluationJsonPathError from './errors/MultiEvaluationJsonPathError.ts';
diff --git a/packages/apidom-json-path/src/evaluate.ts b/packages/apidom-json-path/src/evaluate.ts
@@ -1,5 +1,5 @@
 import { JSONPath } from 'jsonpath-plus';
-import { evaluate as jsonPointerEvaluate } from '@swaggerexpert/json-pointer/evaluate/realms/apidom';
+import { evaluate as jsonPointerEvaluate } from '@swagger-api/apidom-json-pointer/modern';
 import { Element, toValue, cloneDeep } from '@swagger-api/apidom-core';
 
 import EvaluationJsonPathError from './errors/EvaluationJsonPathError.ts';
diff --git a/packages/apidom-json-pointer/README.md b/packages/apidom-json-pointer/README.md
@@ -9,7 +9,37 @@ You can install this package via [npm CLI](https://docs.npmjs.com/cli) by runnin
 ```sh
  $ npm install @swagger-api/apidom-json-pointer
 ```
-## Evaluating
+
+## Modern API
+
+This is the recommended API for use in new projects. It is fully compliant with [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901) and supports all aspects of JSON Pointer.
+Uses [@swaggerexpert/json-pointer](https://www.npmjs.com/package/@swaggerexpert/json-pointer) under the hood and fully reflects its API.
+
+Evaluation is contextual to [ApiDOM realm](https://github.com/swaggerexpert/json-pointer?tab=readme-ov-file#apidom-evaluation-realm) - meaning `evaluate` function
+expects only ApiDOM as the first argument.
+
+```js
+import { evaluate } from '@swagger-api/apidom-json-pointer/modern';
+```
+
+
+
+## Legacy API
+
+This is a legacy API not recommended for use in new projects. It is provided for backward compatibility only.
+The legacy API implementation is not RFC 6901 compliant, nor does it support all features of JSON Pointer.
+
+Importing legacy API from `@swagger-api/apidom-json-pointer` is equivalent to importing from `@swagger-api/apidom-json-pointer/legacy`.
+
+```js
+import { evaluate } from '@swagger-api/apidom-json-pointer';
+```
+or
+```js
+import { evaluate } from '@swagger-api/apidom-json-pointer/legacy';
+```
+
+### Evaluating
 
 ```js
 import { ObjectElement } from '@swagger-api/apidom-core';
@@ -20,7 +50,7 @@ const result =  evaluate('/a/b', apidom);
 // => StringElement('c')
 ```
 
-## Parsing
+### Parsing
 
 Parses JSON Pointer into list of tokens.
 
@@ -30,7 +60,7 @@ import { parse } from '@swagger-api/apidom-json-pointer';
 const tokens = parse('/a/b'); // => ['a', 'b']
 ```
 
-## Compiling
+### Compiling
 
 Compiles list of tokens into JSON Pointer.
 
@@ -40,7 +70,7 @@ import { compile } from '@swagger-api/apidom-json-pointer';
 const jsonPointer = compile(['a', 'b']); // => '/a/b'
 ```
 
-## Escaping
+### Escaping
 
 Escapes/unescapes tokens of JSON Pointer.
 
@@ -51,7 +81,7 @@ escape('~a/'); // => '~0a~1'
 unescape('~0a~1'); // => '~a/'
 ```
 
-## Transforming URI to JSON Pointer
+### Transforming URI to JSON Pointer
 
 Handles case of [URI Fragment Identifier Representation](https://datatracker.ietf.org/doc/html/rfc6901#section-6).
 
@@ -61,7 +91,7 @@ import { uriToPointer } from '@swagger-api/apidom-json-pointer';
 uriToPointer('https://example.com/path/#/a/b'); // => '/a/b'
 ```
 
-## Invalid JSON Pointers
+### Invalid JSON Pointers
 
 If invalid JSON Pointer is supplied to `parse` or `evaluate` functions, `InvalidJsonPointerError`
 is thrown.
@@ -76,3 +106,4 @@ ApiDOM fragment, `EvaluationJsonPointerError` is thrown.
 ```js
 import { EvaluationJsonPointerError } from '@swagger-api/apidom-json-pointer';
 ```
+
diff --git a/packages/apidom-json-pointer/package.json b/packages/apidom-json-pointer/package.json
@@ -9,13 +9,25 @@
   "type": "module",
   "sideEffects": false,
   "unpkg": "./dist/apidom-json-pointer.browser.min.js",
-  "main": "./src/index.cjs",
+  "main": "./src/legacy/index.cjs",
   "exports": {
-    "types": "./types/apidom-json-pointer.d.ts",
-    "import": "./src/index.mjs",
-    "require": "./src/index.cjs"
+    ".": {
+      "types": "./types/legacy/index.d.ts",
+      "import": "./src/legacy/index.mjs",
+      "require": "./src/legacy/index.cjs"
+    },
+    "./legacy": {
+      "types": "./types/legacy/index.d.ts",
+      "import": "./src/legacy/index.mjs",
+      "require": "./src/legacy/index.cjs"
+    },
+    "./modern": {
+      "types": "./types/apidom-json-pointer.d.ts",
+      "import": "./src/index.mjs",
+      "require": "./src/index.cjs"
+    }
   },
-  "types": "./types/apidom-json-pointer.d.ts",
+  "types": "./types/legacy/index.d.ts",
   "scripts": {
     "build": "npm run clean && run-p --max-parallel ${CPU_CORES:-2} typescript:declaration build:es build:cjs build:umd:browser",
     "build:es": "cross-env BABEL_ENV=es babel src --out-dir src --extensions '.ts' --out-file-extension '.mjs' --root-mode 'upward'",
@@ -40,7 +52,7 @@
     "@babel/runtime-corejs3": "^7.26.10",
     "@swagger-api/apidom-core": "^1.0.0-beta.33",
     "@swagger-api/apidom-error": "^1.0.0-beta.33",
-    "@swaggerexpert/json-pointer": "^2.9.0"
+    "@swaggerexpert/json-pointer": "^2.10.1"
   },
   "files": [
     "src/**/*.mjs",
diff --git a/packages/apidom-json-pointer/src/index.ts b/packages/apidom-json-pointer/src/index.ts
@@ -1,12 +1,38 @@
-export { default as JsonPointerError } from './errors/JsonPointerError.ts';
-export { default as InvalidJsonPointerError } from './errors/InvalidJsonPointerError.ts';
-export type { InvalidJsonPointerErrorOptions } from './errors/InvalidJsonPointerError.ts';
-export { default as CompilationJsonPointerError } from './errors/CompilationJsonPointerError.ts';
-export type { CompilationJsonPointerErrorOptions } from './errors/CompilationJsonPointerError.ts';
-export { default as EvaluationJsonPointerError } from './errors/EvaluationJsonPointerError.ts';
-export type { EvaluationJsonPointerErrorOptions } from './errors/EvaluationJsonPointerError.ts';
-export { default as parse, uriToPointer } from './parse.ts';
-export { default as evaluate } from './evaluate.ts';
-export { default as escape } from './escape.ts';
-export { default as unescape } from './unescape.ts';
-export { default as compile } from './compile.ts';
+export {
+  /**
+   * Representation
+   */
+  JSONString,
+  URIFragmentIdentifier,
+  /**
+   * Parsing
+   */
+  parse,
+  CSTTranslator,
+  ASTTranslator,
+  XMLTranslator,
+  /**
+   * Compiling
+   */
+  compile,
+  /**
+   * Escaping
+   */
+  escape,
+  unescape,
+  /**
+   * Errors
+   */
+  JSONPointerError,
+  JSONPointerParseError,
+  JSONPointerCompileError,
+  JSONPointerEvaluateError,
+  JSONPointerTypeError,
+  JSONPointerKeyError,
+  JSONPointerIndexError,
+} from '@swaggerexpert/json-pointer';
+/**
+ * Evaluation
+ */
+export { evaluate } from '@swaggerexpert/json-pointer/evaluate/realms/apidom';
+export type * from '@swaggerexpert/json-pointer';
diff --git a/packages/apidom-json-pointer/src/legacy/compile.ts b/packages/apidom-json-pointer/src/legacy/compile.ts
@@ -8,6 +8,7 @@ import CompilationJsonPointerError from './errors/CompilationJsonPointerError.ts
 
 /**
  * @public
+ * @deprecated
  */
 const compile = (tokens: string[]): string => {
   try {
diff --git a/packages/apidom-json-pointer/src/legacy/errors/CompilationJsonPointerError.ts b/packages/apidom-json-pointer/src/legacy/errors/CompilationJsonPointerError.ts
@@ -4,13 +4,15 @@ import JsonPointerError from './JsonPointerError.ts';
 
 /**
  * @public
+ * @deprecated
  */
 export interface CompilationJsonPointerErrorOptions extends ApiDOMErrorOptions {
   readonly tokens: string[];
 }
 
 /**
  * @public
+ * @deprecated
  */
 class CompilationJsonPointerError extends JsonPointerError {
   public readonly tokens!: string[];
diff --git a/packages/apidom-json-pointer/src/legacy/errors/EvaluationJsonPointerError.ts b/packages/apidom-json-pointer/src/legacy/errors/EvaluationJsonPointerError.ts
@@ -5,6 +5,7 @@ import JsonPointerError from './JsonPointerError.ts';
 
 /**
  * @public
+ * @deprecated
  */
 export interface EvaluationJsonPointerErrorOptions<T extends Element> extends ApiDOMErrorOptions {
   readonly pointer: string;
@@ -16,6 +17,7 @@ export interface EvaluationJsonPointerErrorOptions<T extends Element> extends Ap
 
 /**
  * @public
+ * @deprecated
  */
 class EvaluationJsonPointerError<T extends Element> extends JsonPointerError {
   public readonly pointer!: string;
diff --git a/packages/apidom-json-pointer/src/legacy/errors/InvalidJsonPointerError.ts b/packages/apidom-json-pointer/src/legacy/errors/InvalidJsonPointerError.ts
@@ -4,13 +4,15 @@ import JsonPointerError from './JsonPointerError.ts';
 
 /**
  * @public
+ * @deprecated
  */
 export interface InvalidJsonPointerErrorOptions extends ApiDOMErrorOptions {
   readonly pointer: string;
 }
 
 /**
  * @public
+ * @deprecated
  */
 class InvalidJsonPointerError extends JsonPointerError {
   public readonly pointer!: string;
diff --git a/packages/apidom-json-pointer/src/legacy/errors/JsonPointerError.ts b/packages/apidom-json-pointer/src/legacy/errors/JsonPointerError.ts
@@ -2,6 +2,7 @@ import { ApiDOMStructuredError } from '@swagger-api/apidom-error';
 
 /**
  * @public
+ * @deprecated
  */
 class JsonPointerError extends ApiDOMStructuredError {}
 
diff --git a/packages/apidom-json-pointer/src/legacy/escape.ts b/packages/apidom-json-pointer/src/legacy/escape.ts
@@ -2,6 +2,7 @@ import { escape as baseEscape, URIFragmentIdentifier } from '@swaggerexpert/json
 
 /**
  * @public
+ * @deprecated
  */
 const escape = (referenceToken: string): string => {
   return URIFragmentIdentifier.to(baseEscape(referenceToken)).slice(1);
diff --git a/packages/apidom-json-pointer/src/legacy/evaluate.ts b/packages/apidom-json-pointer/src/legacy/evaluate.ts
@@ -7,6 +7,7 @@ import EvaluationJsonPointerError from './errors/EvaluationJsonPointerError.ts';
 /**
  * Evaluates JSON Pointer against ApiDOM fragment.
  * @public
+ * @deprecated
  */
 const evaluate = <T extends Element>(pointer: string, element: T): Element => {
   try {
diff --git a/packages/apidom-json-pointer/src/legacy/index.ts b/packages/apidom-json-pointer/src/legacy/index.ts
@@ -0,0 +1,12 @@
+export { default as JsonPointerError } from './errors/JsonPointerError.ts';
+export { default as InvalidJsonPointerError } from './errors/InvalidJsonPointerError.ts';
+export type { InvalidJsonPointerErrorOptions } from './errors/InvalidJsonPointerError.ts';
+export { default as CompilationJsonPointerError } from './errors/CompilationJsonPointerError.ts';
+export type { CompilationJsonPointerErrorOptions } from './errors/CompilationJsonPointerError.ts';
+export { default as EvaluationJsonPointerError } from './errors/EvaluationJsonPointerError.ts';
+export type { EvaluationJsonPointerErrorOptions } from './errors/EvaluationJsonPointerError.ts';
+export { default as parse, uriToPointer } from './parse.ts';
+export { default as evaluate } from './evaluate.ts';
+export { default as escape } from './escape.ts';
+export { default as unescape } from './unescape.ts';
+export { default as compile } from './compile.ts';
diff --git a/packages/apidom-json-pointer/src/legacy/parse.ts b/packages/apidom-json-pointer/src/legacy/parse.ts
@@ -6,6 +6,7 @@ import {
 
 /**
  * @public
+ * @deprecated
  */
 const parse = (pointer: string, options?: ParseOptions): string[] => {
   const { tree } = jsonPointerParse(URIFragmentIdentifier.from(pointer), options);
@@ -26,6 +27,7 @@ const getHash = (uri: string): string => {
 
 /**
  * @public
+ * @deprecated
  */
 export const uriToPointer = (uri: string): string => {
   const hash = getHash(uri);
diff --git a/packages/apidom-json-pointer/src/legacy/unescape.ts b/packages/apidom-json-pointer/src/legacy/unescape.ts
@@ -2,6 +2,7 @@ import { unescape as baseUnescape, URIFragmentIdentifier } from '@swaggerexpert/
 
 /**
  * @public
+ * @deprecated
  */
 const unescape = (referenceToken: string): string => {
   return URIFragmentIdentifier.from(baseUnescape(referenceToken));
diff --git a/packages/apidom-json-pointer/test/evaluate.ts b/packages/apidom-json-pointer/test/evaluate.ts
@@ -1,7 +1,7 @@
 import { assert } from 'chai';
 import { ObjectElement, ArrayElement, StringElement } from '@swagger-api/apidom-core';
 
-import { evaluate, uriToPointer, EvaluationJsonPointerError } from '../src/index.ts';
+import { evaluate, uriToPointer, EvaluationJsonPointerError } from '../src/legacy/index.ts';
 
 describe('apidom-json-pointer', function () {
   context('RFC 6901 test', function () {
diff --git a/packages/apidom-ns-openapi-3-1/src/refractor/toolbox.ts b/packages/apidom-ns-openapi-3-1/src/refractor/toolbox.ts
@@ -12,7 +12,7 @@ import {
   includesClasses,
   hasElementSourceMap,
 } from '@swagger-api/apidom-core';
-import { compile as compileJSONPointerTokens } from '@swagger-api/apidom-json-pointer';
+import { compile as compileJSONPointerTokens } from '@swagger-api/apidom-json-pointer/modern';
 import { isServersElement } from '@swagger-api/apidom-ns-openapi-3-0';
 
 import * as openApi3_1Predicates from '../predicates.ts';
diff --git a/packages/apidom-ns-openapi-3-1/test/refractor/plugins/normalize-parameters/callbacks/__snapshots__/index.mjs.snap b/packages/apidom-ns-openapi-3-1/test/refractor/plugins/normalize-parameters/callbacks/__snapshots__/index.mjs.snap
@@ -1014,7 +1014,7 @@ exports[`refractor plugins normalize-parameters given parameters are defined in
                   "content": [
                     {
                       "element": "string",
-                      "content": "/paths/~1/get/callbacks/myCallback/%7B$url%7D/get"
+                      "content": "/paths/~1/get/callbacks/myCallback/{$url}/get"
                     },
                     {
                       "element": "string",
diff --git a/packages/apidom-ns-openapi-3-1/test/tsconfig.json b/packages/apidom-ns-openapi-3-1/test/tsconfig.json
@@ -1,8 +1,9 @@
 {
   "extends": "../tsconfig.json",
   "compilerOptions": {
-    "module": "esnext",
-    "moduleResolution": "node"
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "skipLibCheck": true
   },
   "include": [
     "."
