nish/json-pointer
RFC 6901 JSON Pointers: parsed into their tokens, escaped, resolved against a JsonDocument, and checked, with JSON Schema's relative JSON Pointer beside them.
import {
JSON_POINTER_ERR_SYNTAX,
JSON_POINTER_NONE,
isJsonPointer,
isRelativeJsonPointer,
jsonPointerEscape,
jsonPointerParse,
jsonPointerResolve,
} from "nish/json-pointer";
import { jsonPointerParse, jsonPointerResolve, isRelativeJsonPointer } from "nish/json-pointer"
const doc = new JsonDocument(new JsonLimits())
const root = doc.parseText('{"a/b":[10,20],"~":true}')
jsonPointerParse("/a~1b/1") // ["a/b", "1"]
doc.i64(jsonPointerResolve(doc, root, "/a~1b/1")) // 20
jsonPointerResolve(doc, root, "/a~1b/-") // JSON_POINTER_NONE
jsonPointerResolve(doc, root, "a") // JSON_POINTER_ERR_SYNTAX
isRelativeJsonPointer("1/a~1b") // true
isJsonPointer
Whether s is an RFC 6901 JSON Pointer (the module header's grammar).
isRelativeJsonPointer
Whether s is a relative JSON Pointer: a non-negative integer with no leading zero (0, 12, not 01, +1 or -1), then #, or an optional + or - and another such integer and then a JSON Pointer, which may be empty.
jsonPointerEscape
token written as one token of a JSON Pointer: ~ as ~0 and / as ~1, so "a/b" is a~1b.
jsonPointerParse
The reference tokens of JSON Pointer p, decoded: [] for "", ["a/b", "", "~"] for /a~1b//~0.
jsonPointerResolve
The value JSON Pointer p names in root of doc: root itself for "", else each token taken in turn, as the module header says.
The grammar
A pointer is empty, naming the whole document, or a run
of /-led tokens, each any bytes but /, with ~0 for ~ and ~1 for
/ and no other ~. A token names an object's member by its key, bytes
for bytes, and an array's element by an index written 0 or without a
leading zero; -, the place after the last element, names nothing, as
does an index past the end, a token on a scalar, and a key not there. The
pointer is the decoded string, not a URI fragment: #/a is not one.
A relative JSON Pointer (draft-bhutton-relative-json-pointer-00, which
JSON Schema 2020-12's relative-json-pointer format names) is a
non-negative integer written without a leading zero, then either #, or
an optional index manipulation (+ or - and another such integer) and
a JSON Pointer: 0#, 1/a, 0+1/a, 2-1, not 0+1#. Only its form is
checked here: resolving one needs the place it is relative to, which a
validator walking an instance holds.
What a call costs
isJsonPointer and isRelativeJsonPointer read
the text once and allocate nothing. jsonPointerParse allocates each
token and the array. jsonPointerResolve reads the pointer once and
allocates each token it decodes; a member is found by JsonDocument.get,
which steps through the object's members, so a step costs the object's
size.
Functions
isJsonPointer
Whether s is an RFC 6901 JSON Pointer (the module header's grammar).
Allocates nothing.
const isJsonPointer: (s: string) => boolean
sstringrequiredthe text to check.
returnsbooleantrue when s is a JSON Pointer, the empty one included.
isRelativeJsonPointer
Whether s is a relative JSON Pointer: a non-negative integer with no
leading zero (0, 12, not 01, +1 or -1), then #, or an optional
+ or - and another such integer and then a JSON Pointer, which may be
empty. Allocates nothing.
const isRelativeJsonPointer: (s: string) => boolean
sstringrequiredthe text to check.
returnsbooleantrue when s is a relative JSON Pointer.
jsonPointerEscape
token written as one token of a JSON Pointer: ~ as ~0 and / as
~1, so "a/b" is a~1b. Everything else is copied whole.
const jsonPointerEscape: (token: string) => string
tokenstringrequiredone reference token, as it reads in an object key.
returnsstringthe token as it is written inside a pointer.
jsonPointerParse
The reference tokens of JSON Pointer p, decoded: [] for "",
["a/b", "", "~"] for /a~1b//~0. null when p is not a JSON Pointer.
const jsonPointerParse: (p: string) => string[] | null
pstringrequiredthe pointer text.
returnsstring[] | null
the decoded reference tokens, in order, or null when p is not a
JSON Pointer.
jsonPointerResolve
The value JSON Pointer p names in root of doc: root itself for
"", else each token taken in turn, as the module header says.
JSON_POINTER_NONE when the pointer names nothing there (or root names
no value), and JSON_POINTER_ERR_SYNTAX when p is not a JSON Pointer.
const jsonPointerResolve: (
doc: JsonDocument,
root: i32,
p: string,
) => i32
docJsonDocumentrequiredthe document to look in.
rooti32requiredthe value the pointer starts from.
pstringrequiredthe pointer text.
returnsi32
the handle of the value named, JSON_POINTER_NONE, or
JSON_POINTER_ERR_SYNTAX.
Constants
-2
JSON_POINTER_ERR_SYNTAX: i32
jsonPointerResolve: the text is not a JSON Pointer.
-1
JSON_POINTER_NONE: i32
jsonPointerResolve: the pointer is well formed and names nothing in the document.

