json8-pointer

JSON Pointer toolkit for JavaScript

Usage no npm install needed!

<script type="module">
  import json8Pointer from 'https://cdn.skypack.dev/json8-pointer';
</script>

README

JSON8 Pointer

Introduction

JSON Pointer RFC 6901 toolkit for JavaScript.

See also JSON8 Patch for more methods to work with JSON pointers.


Getting started

npm install json8-pointer


const pointer = require("json8-pointer");

Methods

find

Use a JSON Pointer to find a value in a JSON document. Returns undefined if the value cannot be found.

var doc = { foo: { bar: "foobar" } };

pointer.find(doc, "/foo/bar");
// "foobar"

pointer.find(doc, "/bar/foo");
// undefined

context

Returns the target parent and target property of a pointer.

var doc = { foo: { bar: "foobar" } };

pointer.context(doc, "/foo/bar");
// ['bar', doc.foo]

encode

Takes an array of unescaped tokens (see decode) and return a JSON Pointer string.

pointer.encode(["foo", "bar", "hello"]);
// '/foo/bar/hello'

pointer.encode(["foo", "a/b"]);
// '/foo/a~1b'

You can specify a different separator than the default /.

pointer.encode(["foo", "bar", "hello"], ".");
// '.foo.bar.hello'

serialize

Alias for the encode method.

escape

Escape a single token for use in JSON Pointer.

pointer.escape("a/b");
// 'a~1b'

You can specify a different separator than the default /.

pointer.escape("a.b", ".");
// 'a~1b'

decode

Takes a JSON Pointer string and return an array of unescaped tokens.

pointer.decode("/foo/bar/hello");
// ['foo', 'bar', 'hello'];

pointer.decode("/foo/a~1b");
// ['foo', 'a/b']

You can specify a different separator than the default /.

pointer.decode(".foo.bar.hello", ".");
// ['foo', 'bar', 'hello'];

prototype pollution

decode will throw with an error if prototype pollution is attempted.

parse

Alias for the decode method.

unescape

Unescape a single token see escape.

pointer.unescape("a~1b");
// 'a/b'

You can specify a different separator than the default /.

pointer.unescape("a~1b", ".");
// 'a/b'

join

Join a base pointer and tokens;

pointer.join("/foo", ["bar"]);
pointer.join(["foo"], "bar");
pointer.join("", ["foo", "bar"]);
pointer.join([], ["foo", "bar"]);
// `/foo/bar`

You can specify a different separator than the default /.

pointer.join("/foo", ["bar"], ".");
// `.foo.bar`

index

demo/playground

The index method returns an object with all values indexed by pointers.

pointer.index("foo"); // {'': 'foo'}

pointer.index(["hello", "earth"]);
//  {
//    '': ['hello', 'earth'],
//    '/0': 'hello',
//    '/1': 'earth'
//  }

dict

demo/playground

Just like index but only indexes primitives.

pointer.dict(['hello', 'earth'])
//  {
//    '/0': 'hello',
//    '/1': 'earth'
//  }

pointer.dict({'foo', 'bar'})
//  {
//    '/foo': 'bar'
//  }

flatten

demo/playground

The flatten method works like a flat version of index.

pointer.flatten(["hello", "earth"]);
//  {
//    '': [],
//    '/0': 'hello',
//    '/1': 'earth'
//  }

unflatten

demo/playground

The unflatten method takes an flattened object and returns a deep JSON document.

pointer.unflatten({ "": "foo" }); // 'foo'

pointer.unflatten({
  "": [],
  "/0": "hello",
  "/1": "earth",
}); // ['hello', 'earth']

compile

The compile method takes a pointer and returns a function that accept a document and returns the value at the location of the pointer.

const getAge = pointer.compile("/age");

getAge({ age: 22 }); // 22