From af91e945aca3552164ce8e5334244cd5ec756323 Mon Sep 17 00:00:00 2001 From: Oliwia Rogala Date: Wed, 19 Nov 2025 11:52:30 +0100 Subject: [PATCH 1/5] docs(json-pointer): provide documentation for modern version --- packages/apidom-json-pointer/README.md | 143 ++++++++++++++++++++++++- 1 file changed, 139 insertions(+), 4 deletions(-) diff --git a/packages/apidom-json-pointer/README.md b/packages/apidom-json-pointer/README.md index dd7a47d088..e467bd7cc5 100644 --- a/packages/apidom-json-pointer/README.md +++ b/packages/apidom-json-pointer/README.md @@ -22,7 +22,142 @@ 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 +``` + +### Errors + +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 +187,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 +197,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 +228,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 From 5d3c4b95b58474b764217c1f1311790f91d9b919 Mon Sep 17 00:00:00 2001 From: Oliwia Rogala Date: Wed, 19 Nov 2025 13:01:37 +0100 Subject: [PATCH 2/5] docs: mention underlying library documentation --- packages/apidom-json-pointer/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/apidom-json-pointer/README.md b/packages/apidom-json-pointer/README.md index e467bd7cc5..c56a6ffd87 100644 --- a/packages/apidom-json-pointer/README.md +++ b/packages/apidom-json-pointer/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, consult 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. @@ -111,7 +111,7 @@ testArrayIndex('0'); // => true testArrayDash('-'); // => true ``` -### Errors +### Invalid JSON Pointers JSONPointerError is the base class for all JSON Pointer errors. From 6fcb20db90e1b016bb058e48beca87a094a35b71 Mon Sep 17 00:00:00 2001 From: Oliwia Rogala Date: Wed, 19 Nov 2025 13:05:32 +0100 Subject: [PATCH 3/5] docs: phrasing --- packages/apidom-json-pointer/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/apidom-json-pointer/README.md b/packages/apidom-json-pointer/README.md index c56a6ffd87..0c7d799fc2 100644 --- a/packages/apidom-json-pointer/README.md +++ b/packages/apidom-json-pointer/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. For additional options, consult the `@swaggerexpert/json-pointer` [documentation](https://www.npmjs.com/package/@swaggerexpert/json-pointer#usage). +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. From 8828ea7a795af64057745ac66760b659319d5132 Mon Sep 17 00:00:00 2001 From: Oliwia Rogala Date: Wed, 19 Nov 2025 13:10:18 +0100 Subject: [PATCH 4/5] docs: spacing --- packages/apidom-json-pointer/README.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/packages/apidom-json-pointer/README.md b/packages/apidom-json-pointer/README.md index 0c7d799fc2..cd14a257c0 100644 --- a/packages/apidom-json-pointer/README.md +++ b/packages/apidom-json-pointer/README.md @@ -125,35 +125,31 @@ If an invalid list of tokens is supplied to `compile` function, `JSONPointerComp import { JSONPointerCompileError } from '@swagger-api/apidom-json-pointer/modern'; ``` -If an invalid JSON Pointer is supplied to `evaluate` function, `JSONPointerEvaluateError` -is thrown. +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. +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. +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. +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. +If an error occurs in `parse` function, `JSONPointerParseError` is thrown. ```js import { JSONPointerParseError } from '@swagger-api/apidom-json-pointer/modern'; From e74c9de12274d01e58de8fea7bd43e7f0d1dfa85 Mon Sep 17 00:00:00 2001 From: Oliwia Rogala Date: Wed, 19 Nov 2025 13:16:19 +0100 Subject: [PATCH 5/5] docs: quotes --- packages/apidom-json-pointer/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/apidom-json-pointer/README.md b/packages/apidom-json-pointer/README.md index cd14a257c0..fd429bb90d 100644 --- a/packages/apidom-json-pointer/README.md +++ b/packages/apidom-json-pointer/README.md @@ -113,7 +113,7 @@ testArrayDash('-'); // => true ### Invalid JSON Pointers -JSONPointerError is the base class for all JSON Pointer errors. +`JSONPointerError` is the base class for all JSON Pointer errors. ```js import { JSONPointerError } from '@swagger-api/apidom-json-pointer/modern';