@swagger-api/apidom-json-pointer 1.0.0-rc.2 → 1.0.0-rc.4

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.
 
+# [1.0.0-rc.4](https://github.com/swagger-api/apidom/compare/v1.0.0-rc.3...v1.0.0-rc.4) (2025-11-25)
+
+**Note:** Version bump only for package @swagger-api/apidom-json-pointer
+
+# [1.0.0-rc.3](https://github.com/swagger-api/apidom/compare/v1.0.0-rc.2...v1.0.0-rc.3) (2025-11-07)
+
+**Note:** Version bump only for package @swagger-api/apidom-json-pointer
+
 # [1.0.0-rc.2](https://github.com/swagger-api/apidom/compare/v1.0.0-rc.1...v1.0.0-rc.2) (2025-11-07)
 
 **Note:** Version bump only for package @swagger-api/apidom-json-pointer

package/README.md

@@ -13,7 +13,7 @@ You can install this package via [npm CLI](https://docs.npmjs.com/cli) by runnin
 ## 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.
+Uses [@swaggerexpert/json-pointer](https://www.npmjs.com/package/@swaggerexpert/json-pointer) under the hood and fully reflects its API. For additional options and details, refer to the `@swaggerexpert/json-pointer` [documentation](https://www.npmjs.com/package/@swaggerexpert/json-pointer#usage).
 
 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.
@@ -22,7 +22,138 @@ expects only ApiDOM as the first argument.
 import { evaluate } from '@swagger-api/apidom-json-pointer/modern';
 ```
 
+### Evaluating
+
+```js
+import { ObjectElement } from '@swagger-api/apidom-core';
+import { evaluate } from '@swagger-api/apidom-json-pointer/modern';
+
+const apidom = new ObjectElement({ a: { b: 'c' } });
+const result =  evaluate(apidom, '/a/b');
+// => StringElement('c')
+```
+
+### Parsing
+
+Parses JSON Pointer into a list of tokens, which can be accessed through the `tree` property of the parse result.
+
+```js
+import { parse } from '@swagger-api/apidom-json-pointer/modern';
+
+const parseResult = parse('/a/b');
+// =>
+// {
+//   result: {
+//     success: true,
+//     state: 101,
+//     stateName: 'MATCH',
+//     length: 4,
+//     matched: 4,
+//     maxMatched: 4,
+//     maxTreeDepth: 8,
+//     nodeHits: 31
+//   },
+//   tree: [ 'a', 'b' ],
+//   stats: undefined,
+//   trace: undefined
+// }
+```
+
+### Compiling
+
+Compiles a list of tokens into JSON Pointer.
+
+```js
+import { compile } from '@swagger-api/apidom-json-pointer/modern';
+
+const jsonPointer = compile(['a', 'b']); // => '/a/b'
+```
+
+### Escaping
+
+Escapes/unescapes tokens of JSON Pointer.
+
+```js
+import { escape, unescape } from '@swagger-api/apidom-json-pointer/modern';
 
+escape('~a/'); // => '~0a~1'
+unescape('~0a~1'); // => '~a/'
+```
+
+### Transforming URI to JSON Pointer
+
+Handles case of [URI Fragment Identifier Representation](https://datatracker.ietf.org/doc/html/rfc6901#section-6).
+
+```js
+import { URIFragmentIdentifier } from '@swagger-api/apidom-json-pointer/modern';
+
+URIFragmentIdentifier.fromURIReference('https://example.com/path/#/a/b'); // => '/a/b'
+```
+
+### Validating
+
+Validates a JSON Pointer and its tokens.
+
+```js
+import {
+  testJSONPointer,
+  testReferenceToken,
+  testArrayLocation,
+  testArrayIndex,
+  testArrayDash,
+} from '@swagger-api/apidom-json-pointer/modern';
+
+testJSONPointer('/a/b'); // => true
+testReferenceToken('a'); // => true
+testArrayLocation('0'); // => true
+testArrayLocation('-'); // => true
+testArrayIndex('0'); // => true
+testArrayDash('-'); // => true
+```
+
+### Invalid JSON Pointers
+
+`JSONPointerError` is the base class for all JSON Pointer errors.
+
+```js
+import { JSONPointerError } from '@swagger-api/apidom-json-pointer/modern';
+```
+
+If an invalid list of tokens is supplied to `compile` function, `JSONPointerCompileError` is thrown.
+
+```js
+import { JSONPointerCompileError } from '@swagger-api/apidom-json-pointer/modern';
+```
+
+If an invalid JSON Pointer is supplied to `evaluate` function, `JSONPointerEvaluateError` is thrown.
+
+```js
+import { JSONPointerEvaluateError } from '@swagger-api/apidom-json-pointer/modern';
+```
+
+If a valid JSON Pointer is supplied to `evaluate` function and the pointer cannot be evaluated against ApiDOM fragment because it is not an object or an array, `JSONPointerTypeError` is thrown.
+
+```js
+import { JSONPointerTypeError } from '@swagger-api/apidom-json-pointer/modern';
+```
+
+If a valid JSON Pointer is supplied to `evaluate` function and the pointer cannot be evaluated against ApiDOM fragment because the key does not exist in the object, `JSONPointerKeyError` is thrown.
+
+```js
+import { JSONPointerKeyError } from '@swagger-api/apidom-json-pointer/modern';
+```
+
+If a valid JSON Pointer is supplied to `evaluate` function and the pointer cannot be evaluated against ApiDOM fragment because the index does not exist in the array, `JSONPointerIndexError` is thrown. 
+
+```js
+import { JSONPointerIndexError } from '@swagger-api/apidom-json-pointer/modern';
+```
+
+If an error occurs in `parse` function, `JSONPointerParseError` is thrown.
+
+```js
+import { JSONPointerParseError } from '@swagger-api/apidom-json-pointer/modern';
+```
 
 ## Legacy API
 
@@ -52,7 +183,7 @@ const result =  evaluate('/a/b', apidom);
 
 ### Parsing
 
-Parses JSON Pointer into list of tokens.
+Parses JSON Pointer into a list of tokens.
 
 ```js
 import { parse } from '@swagger-api/apidom-json-pointer';
@@ -62,7 +193,7 @@ const tokens = parse('/a/b'); // => ['a', 'b']
 
 ### Compiling
 
-Compiles list of tokens into JSON Pointer.
+Compiles a list of tokens into JSON Pointer.
 
 ```js
 import { compile } from '@swagger-api/apidom-json-pointer';
@@ -93,14 +224,14 @@ uriToPointer('https://example.com/path/#/a/b'); // => '/a/b'
 
 ### Invalid JSON Pointers
 
-If invalid JSON Pointer is supplied to `parse` or `evaluate` functions, `InvalidJsonPointerError`
+If an invalid JSON Pointer is supplied to `parse` or `evaluate` functions, `InvalidJsonPointerError`
 is thrown.
 
 ```js
 import { InvalidJsonPointerError } from '@swagger-api/apidom-json-pointer';
 ```
 
-If valid JSON Pointer is supplied to `evaluate` function and the pointer cannot be evaluated against
+If a valid JSON Pointer is supplied to `evaluate` function and the pointer cannot be evaluated against
 ApiDOM fragment, `EvaluationJsonPointerError` is thrown.
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swagger-api/apidom-json-pointer",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.4",
   "description": "Evaluate JSON Pointer expressions against ApiDOM.",
   "publishConfig": {
     "access": "public",
@@ -50,8 +50,8 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.26.10",
-    "@swagger-api/apidom-core": "^1.0.0-rc.2",
-    "@swagger-api/apidom-error": "^1.0.0-rc.2",
+    "@swagger-api/apidom-core": "^1.0.0-rc.4",
+    "@swagger-api/apidom-error": "^1.0.0-rc.4",
     "@swaggerexpert/json-pointer": "^2.10.1"
   },
   "files": [
@@ -64,5 +64,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "3d141c924360d491cb6dfae1a14c3dcc6ffc708d"
+  "gitHead": "ee774281a884eedf1445699d8f2b0092e50db432"
 }