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
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
sstringrequired

the text to check.

returnsboolean

true 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
sstringrequired

the text to check.

returnsboolean

true 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
tokenstringrequired

one reference token, as it reads in an object key.

returnsstring

the 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
pstringrequired

the 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
docJsonDocumentrequired

the document to look in.

rooti32required

the value the pointer starts from.

pstringrequired

the 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.