json-ptr

What is json-ptr?

The json-ptr npm package provides utilities for working with JSON Pointers (RFC 6901) and JSON References (RFC 6901). It allows you to create, parse, and resolve JSON Pointers and References, making it easier to navigate and manipulate JSON data structures.

What are json-ptr's main functionalities?

Creating JSON Pointers

This feature allows you to create JSON Pointers from a string path. The example demonstrates creating a JSON Pointer for the path '/foo/bar'.

const ptr = require('json-ptr');
const pointer = ptr.create('/foo/bar');
console.log(pointer.toString()); // '/foo/bar'

Resolving JSON Pointers

This feature allows you to resolve a JSON Pointer against a JSON document to retrieve the value at the specified path. The example shows how to get the value 'baz' from the path '/foo/bar' in the given document.

const ptr = require('json-ptr');
const document = { foo: { bar: 'baz' } };
const value = ptr.get(document, '/foo/bar');
console.log(value); // 'baz'

Parsing JSON Pointers

This feature allows you to parse a JSON Pointer into its component parts. The example demonstrates parsing the pointer '/foo/bar' into an array of its segments.

const ptr = require('json-ptr');
const parsed = ptr.parse('/foo/bar');
console.log(parsed); // ['foo', 'bar']

Handling JSON References

This feature allows you to resolve JSON References within a document. The example shows how to resolve a reference to the path '#/foo/bar' and retrieve the value 'baz'.

const ptr = require('json-ptr');
const document = { foo: { bar: 'baz' }, ref: { '$ref': '#/foo/bar' } };
const value = ptr.resolve(document, document.ref);
console.log(value); // 'baz'

Other packages similar to json-ptr

jsonpointer

The jsonpointer package provides similar functionality for resolving JSON Pointers. It allows you to get and set values in a JSON document using JSON Pointers. Compared to json-ptr, jsonpointer is more focused on basic get and set operations and may not have as extensive support for JSON References.

json-ref

The json-ref package focuses on resolving JSON References within a document. It provides utilities for dereferencing JSON References and is useful for working with JSON schemas. Compared to json-ptr, json-ref is more specialized in handling JSON References and may not provide as much functionality for working with JSON Pointers.

jsonpath

The jsonpath package provides a way to query JSON documents using JSONPath expressions, which are more powerful and flexible than JSON Pointers. While jsonpath offers more advanced querying capabilities, it is not directly focused on JSON Pointers or References like json-ptr.

README

json-ptr

A complete implementation of JSON Pointer (RFC 6901) for nodejs and modern browsers.

Background

I wrote this module a couple of years ago when I was unable to find what I considered a complete implementation of RFC 6901. It turns out that I now use the hell out of it.

Since there are a few npm modules for you to choose from, see the section on performance later in this readme; you can use your own judgement as to which package you should employ.

Install

npm install json-ptr

Use

nodejs

import { JsonPointer, create } from 'json-ptr';

Module API

Classes

• JsonPointer : class – a convenience class for working with JSON pointers.
• JsonReference : class – a convenience class for working with JSON references.

Functions

• .create(pointer)
• .has(target,pointer)
• .get(target,pointer)
• .set(target,pointer,value,force)
• .unset(target,pointer,value,force)
• .flatten(target,fragmentId)
• .list(target,fragmentId)
• .map(target,fragmentId)

All example code assumes data has this structure:

const data = {
  legumes: [{
    name: 'pinto beans',
    unit: 'lbs',
    instock: 4
  }, {
    name: 'lima beans',
    unit: 'lbs',
    instock: 21
  }, {
    name: 'black eyed peas',
    unit: 'lbs',
    instock: 13
  }, {
    name: 'split peas',
    unit: 'lbs',
    instock: 8
  }]
}

.create(pointer: string | string[]): JsonPointer

Creates an instance of the JsonPointer class.

arguments:

• pointer : string, required – a JSON pointer in JSON string representation or URI fragment identifier representation

returns:

• a new JsonPointer instance

example:

const pointer = JsonPointer.create('/legumes/0');
// fragmentId: #/legumes/0

.has(target: unknown, pointer: string | string[] | JsonPointer): boolean

Determines whether the specified target has a value at the pointer's path.

arguments:

• target : object, required – the target object
• pointer : string, required – a JSON pointer in JSON string representation or URI fragment identifier representation

returns:

• the dereferenced value or undefined if nonexistent

.get(target,pointer)

Gets a value from the specified target object at the pointer's path

arguments:

• target : object, required – the target object
• pointer : string, required – a JSON pointer in JSON string representation or URI fragment identifier representation

returns:

• the dereferenced value or undefined if nonexistent

example:

let value = JsonPointer.get(data, '/legumes/1');
// fragmentId: #/legumes/1

.set(target, pointer, value, force)

Sets the value at the specified pointer on the target. The default behavior is to do nothing if pointer is nonexistent.

arguments:

• target : object, required – the target object
• pointer : string, required – a JSON pointer in JSON string representation or URI fragment identifier representation
• value : any – the value to be set at the specified pointer's path
• force : boolean, optional – indicates whether nonexistent paths are created during the call

returns:

• The prior value at the pointer's path — therefore, undefined means the pointer's path was nonexistent.

example:

let prior = JsonPointer.set(data, '#/legumes/1/instock', 50);

example force:

let data = {};

JsonPointer.set(data, '#/peter/piper', 'man', true);
JsonPointer.set(data, '#/peter/pan', 'boy', true);
JsonPointer.set(data, '#/peter/pickle', 'dunno', true);

console.log(JSON.stringify(data, null, '  '));

{
  "peter": {
    "piper": "man",
    "pan": "boy",
    "pickle": "dunno"
  }
}

.unset(target, pointer)

Unsets the value at the specified pointer on the target and returns the value. The default behavior is to do nothing if pointer is nonexistent.

arguments:

• target : object, required – the target object
• pointer : string, required – a JSON pointer in JSON string representation or URI fragment identifier representation

returns:

• The dereferenced value or undefined if nonexistent

example:

var prior = ptr.unset(data, '#/legumes/1/instock');

example force:

var data = {};

ptr.unset(data, '#/peter/piper');
ptr.unset(data, '#/peter/pan');

console.log(JSON.stringify(data, null, '  '));

{
  "peter": {
    "pickle": "dunno"
  }
}

.list(target, fragmentId)

Lists all of the pointers available on the specified target.

See a discussion about cycles in the object graph later in this document if you have interest in how such is dealt with.

arguments:

• target : object, required – the target object
• fragmentId : boolean, optional – indicates whether fragment identifiers should be listed instead of pointers

returns:

• an array of pointer-value pairs

example:

let list = JsonPointer.list(data);

[ ...
  {
    "pointer": "/legumes/2/unit",
    "value": "ea"
  },
  {
    "pointer": "/legumes/2/instock",
    "value": 9340
  },
  {
    "pointer": "/legumes/3/name",
    "value": "plit peas"
  },
  {
    "pointer": "/legumes/3/unit",
    "value": "lbs"
  },
  {
    "pointer": "/legumes/3/instock",
    "value": 8
  }
]

fragmentId example:

let list = JsonPointer.list(data, true);

[ ...
  {
    "fragmentId": "#/legumes/2/unit",
    "value": "ea"
  },
  {
    "fragmentId": "#/legumes/2/instock",
    "value": 9340
  },
  {
    "fragmentId": "#/legumes/3/name",
    "value": "plit peas"
  },
  {
    "fragmentId": "#/legumes/3/unit",
    "value": "lbs"
  },
  {
    "fragmentId": "#/legumes/3/instock",
    "value": 8
  }
]

.flatten(target, fragmentId)

Flattens an object graph (the target) into a single-level object of pointer-value pairs.

arguments:

• target : object, required – the target object
• fragmentId : boolean, optional – indicates whether fragment identifiers should be listed instead of pointers

returns:

• a flattened object of property-value pairs as properties.

example:

let obj = JsonPointer.flatten(data, true);

{ ...
  "#/legumes/1/name": "lima beans",
  "#/legumes/1/unit": "lbs",
  "#/legumes/1/instock": 21,
  "#/legumes/2/name": "black eyed peas",
  "#/legumes/2/unit": "ea",
  "#/legumes/2/instock": 9340,
  "#/legumes/3/name": "plit peas",
  "#/legumes/3/unit": "lbs",
  "#/legumes/3/instock": 8
}

.map(target, fragmentId)

Flattens an object graph (the target) into a Map object.

arguments:

• target : object, required – the target object
• fragmentId : boolean, optional – indicates whether fragment identifiers should be listed instead of pointers

returns:

• a Map object containing key-value pairs where keys are pointers.

example:

let map = JsonPointer.map(data, true);

for (let it of map) {
  console.log(JSON.stringify(it, null, '  '));
}

...
["#/legumes/0/name", "pinto beans"]
["#/legumes/0/unit", "lbs"]
["#/legumes/0/instock", 4 ]
["#/legumes/1/name", "lima beans"]
["#/legumes/1/unit", "lbs"]
["#/legumes/1/instock", 21 ]
["#/legumes/2/name", "black eyed peas"]
["#/legumes/2/unit", "ea"]
["#/legumes/2/instock", 9340 ]
["#/legumes/3/name", "plit peas"]
["#/legumes/3/unit", "lbs"]
["#/legumes/3/instock", 8 ]

.decode(pointer)

Decodes the specified pointer.

arguments:

• pointer : string, required – a JSON pointer in JSON string representation or URI fragment identifier representation.

returns:

• An array of path segments used as indexers to descend from a root/target object to a referenced value.

example:

let path = JsonPointer.decode('#/legumes/1/instock');

[ "legumes", "1", "instock" ]

decodePointer(pointer)

Decodes the specified pointer.

arguments:

• pointer : string, required – a JSON pointer in JSON string representation.

returns:

• An array of path segments used as indexers to descend from a root/target object to a referenced value.

example:

let path = decodePointer('/people/wilbur dongleworth/age');

[ "people", "wilbur dongleworth", "age" ]

encodePointer(path)

Encodes the specified path as a JSON pointer in JSON string representation.

arguments:

• path : Array, required – an array of path segments

returns:

• A JSON pointer in JSON string representation.

example:

let path = encodePointer(['people', 'wilbur dongleworth', 'age']);

"/people/wilbur dongleworth/age"

decodeUriFragmentIdentifier(pointer)

Decodes the specified pointer.

arguments:

• pointer : string, required – a JSON pointer in URI fragment identifier representation.

returns:

• An array of path segments used as indexers to descend from a root/target object to a referenced value.

example:

let path = decodePointer('#/people/wilbur%20dongleworth/age');

[ "people", "wilbur dongleworth", "age" ]

encodeUriFragmentIdentifier(path)

Encodes the specified path as a JSON pointer in URI fragment identifier representation.

arguments:

• path : Array, required - an array of path segments

returns:

• A JSON pointer in URI fragment identifier representation.

example:

let path = ptr.encodePointer(['people', 'wilbur dongleworth', 'age']);

"#/people/wilbur%20dongleworth/age"

JsonPointer Class

Encapsulates pointer related operations for a specified pointer.

properties:

• .path : array – contains the pointer's path segements.
• .pointer : string – the pointer's JSON string representation
• .uriFragmentIdentifier : string – the pointer's URI fragment identifier representation

methods:

.has(target)

Determins whether the specified target has a value at the pointer's path.

.get(target)

Looks up the specified target's value at the pointer's path if such exists; otherwise undefined.

.set(target, value, force)

Sets the specified target's value at the pointer's path, if such exists.If force is specified (truthy), missing path segments are created and the value is always set at the pointer's path.

arguments:

• target : object, required – the target object
• value : any – the value to be set at the specified pointer's path
• force : boolean, optional – indicates whether nonexistent paths are created during the call

result:

• The prior value at the pointer's path — therefore, undefined means the pointer's path was nonexistent.

.concat(target)

Creates new pointer appending target to the current pointer's path

arguments:

• target : JsonPointer, array or string, required – the path to be appended to the current path

Performance

This repository has a companion repository that makes some performance comparisons between json-ptr, jsonpointer and json-pointer.

All timings are expressed as nanoseconds:

.flatten(obj)
...
MODULE       | METHOD  | COMPILED | SAMPLES |       AVG | SLOWER
json-pointer | dict    |          | 10      | 464455181 |
json-ptr     | flatten |          | 10      | 770424039 | 65.88%
jsonpointer  | n/a     |          | -       |         - |

.has(obj, pointer)
...
MODULE       | METHOD | COMPILED | SAMPLES | AVG  | SLOWER
json-ptr     | has    | compiled | 1000000 | 822  |
json-ptr     | has    |          | 1000000 | 1747 | 112.53%
json-pointer | has    |          | 1000000 | 2683 | 226.4%
jsonpointer  | n/a    |          | -       | -    |

.has(obj, fragmentId)
...
MODULE       | METHOD | COMPILED | SAMPLES | AVG  | SLOWER
json-ptr     | has    | compiled | 1000000 | 602  |
json-ptr     | has    |          | 1000000 | 1664 | 176.41%
json-pointer | has    |          | 1000000 | 2569 | 326.74%
jsonpointer  | n/a    |          | -       | -    |

.get(obj, pointer)
...
MODULE       | METHOD | COMPILED | SAMPLES | AVG  | SLOWER
json-ptr     | get    | compiled | 1000000 | 590  |
json-ptr     | get    |          | 1000000 | 1676 | 184.07%
jsonpointer  | get    | compiled | 1000000 | 2102 | 256.27%
jsonpointer  | get    |          | 1000000 | 2377 | 302.88%
json-pointer | get    |          | 1000000 | 2585 | 338.14%

.get(obj, fragmentId)
...
MODULE       | METHOD | COMPILED | SAMPLES | AVG  | SLOWER
json-ptr     | get    | compiled | 1000000 | 587  |
json-ptr     | get    |          | 1000000 | 1673 | 185.01%
jsonpointer  | get    | compiled | 1000000 | 2105 | 258.6%
jsonpointer  | get    |          | 1000000 | 2451 | 317.55%
json-pointer | get    |          | 1000000 | 2619 | 346.17%

These results have been elided because there is too much detail in the actual. Your results will vary slightly depending on the resources available where you run it.

It is important to recognize in the performance results that compiled options are faster. As a general rule, you should compile any pointers you'll be using repeatedly.

Consider this example code that queries the flickr API and prints results to the console:

'use strict';

let ptr = require('..'),
  http = require('http'),
  util = require('util');

// A flickr feed, tags surf,pipeline
let feed = 'http://api.flickr.com/services/feeds/photos_public.gne?tags=surf,pipeline&tagmode=all&format=json&jsoncallback=processResponse';

// Compile/prepare the pointers...
let items = ptr.create('#/items');
let author = ptr.create('#/author');
let media = ptr.create('#/media/m');

function processResponse(json) {
  let data = items.get(json);

  if (data && Array.isArray(data)) {
    let images = data.reduce((acc, it) => {
      // Using the prepared pointers to select parts...
      acc.push({
        author: author.get(it),
        media: media.get(it)
      });
      return acc;
    }, []);
    console.log(util.inspect(images, false, 9));
  }
}

http.get(feed, function(res) {
  let data = '';

  res.on('data', function(chunk) {
    data += chunk;
  });

  res.on('end', function() {
    // result is formatted as jsonp... this is for illustration only.
    data = eval(data); // eslint-disable-line no-eval
    processResponse(data);
  });
}).on('error', function(e) {
  console.log('Got error: ' + e.message);
});

[example/real-world.js]

Tests

Tests are written using mocha and expect.js.

npm test

... or ...

mocha

Releases

• 2019-09-14 — 1.2.0

  • Merged new .concat function contributed by @vuwuv, updated dependencies.

• 2019-03-10 — 1.1.2

  • Updated packages to remove critical security concern among dev dependencies'

• 2016-07-26 — 1.0.1

  • Fixed a problem with the Babel configuration

• 2016-01-12 — 1.0.0

  • Rolled major version to 1 to reflect breaking change in .list(obj, fragmentId).

• 2016-01-02 — 0.3.0

  • Retooled for node 4+
  • Better compiled pointers
  • Unrolled recursive .list function
  • Added .map function
  • Fully linted
  • Lots more tests and examples.
  • Documented many previously undocumented features.

• 2014-10-21 — 0.2.0 Added #list function to enumerate all properties in a graph, producing fragmentId/value pairs.

License

MIT