Package Exports

json-p3
json-p3/dist/json-p3.cjs.js
json-p3/dist/json-p3.esm.js
json-p3/dist/json-p3.iife.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (json-p3) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

JSON P3

JSONPath, JSON Patch and JSON Pointer for JavaScript.

Install

Node.js

Use npm:

npm install --save json-p3

Or yarn:

yarn add json-p3

Or pnpm:

pnpm add json-p3

And use ES module imports:

import { query } from "json-p3";

const data = {
  players: [{ name: "Sue" }, { name: "John" }, { name: "Sally" }],
  visitors: [{ name: "Brian" }, { name: "Roy" }],
};

const nodes = query("$..name", data);
console.log(nodes.values());
// [ 'Sue', 'John', 'Sally', 'Brian', 'Roy' ]

Or CommonJS modules:

const { query } = require("json-p3");

const data = {
  players: [{ name: "Sue" }, { name: "John" }, { name: "Sally" }],
  visitors: [{ name: "Brian" }, { name: "Roy" }],
};

const nodes = query("$..name", data);
console.log(nodes.values());
// [ 'Sue', 'John', 'Sally', 'Brian', 'Roy' ]

Browser

TODO:

JSONPath

Retrieve values from JSON-like data using JSONPath query expressions. We strictly follow standards described in the IETF JSONPath draft.

import { jsonpath } from "json-p3";

const data = {
  users: [
    { name: "Sue", score: 100 },
    { name: "John", score: 86 },
    { name: "Sally", score: 84 },
    { name: "Jane", score: 55 },
  ],
};

const nodes = jsonpath.query("$.users[?@.score < 100].name", data);
console.log(nodes.values()); // [ 'John', 'Sally', 'Jane' ]

The result of jsonpath.query() is an instance of JSONPathNodeList. That is a list of JSONPathNode objects, one node for each value in the target JSON document matching the query. Each node has a:

value - The value found in the target JSON value. This could be an array, object or primitive value.
location - An array of property names and array indices that were required to reach the node's value in the target JSON value.
path - The normalized JSONPath to this node in the target JSON document.

Use JSONPathNodeList.paths() to retrieve all node paths.

// .. continued from above
console.log(nodes.paths());

Output:

[
  "$['users']['1']['name']",
  "$['users']['2']['name']",
  "$['users']['3']['name']"
]

And JSONPathNodeList.locations() to get an array of node locations.

// .. continued from above
console.log(nodes.locations());

Output:

[
  [ 'users', 1, 'name' ],
  [ 'users', 2, 'name' ],
  [ 'users', 3, 'name' ]
]

TODO: node lists are iterable

You can also compile a JSONPath query for repeated use against different data.

import { jsonpath } from "json-p3";

const data = {
  users: [
    { name: "Sue", score: 100 },
    { name: "John", score: 86 },
    { name: "Sally", score: 84 },
    { name: "Jane", score: 55 },
  ],
};

const path = jsonpath.compile("$.users[?@.score < 100].name");
const nodes = path.query(data);
console.log(nodes.values()); // [ 'John', 'Sally', 'Jane' ]

JSON Pointer

Identify a single value in JSON-like data, as per RFC 6901. Use jsonpointer.resolve() to retrieve the value.

import { jsonpointer } from "json-p3";

const data = {
  users: [
    { name: "Sue", score: 100 },
    { name: "John", score: 86 },
    { name: "Sally", score: 84 },
    { name: "Jane", score: 55 },
  ],
};

const rv = jsonpointer.resolve("/users/1", data);
console.log(rv); // { name: 'John', score: 86 }

If the pointer can't be resolved against the argument JSON value, one of JSONPointerIndexError, JSONPointerKeyError or JSONPointerTypeError is thrown. All three exceptions inherit from JSONPointerResolutionError.

import { jsonpointer } from "json-p3";

const data = {
  users: [
    { name: "Sue", score: 100 },
    { name: "John", score: 86 },
    { name: "Sally", score: 84 },
    { name: "Jane", score: 55 },
  ],
};

const rv = jsonpointer.resolve("/users/1/age", data);
// JSONPointerKeyError: no such property ("/users/1/age")

A fallback value can be given as a third argument, which will be returned in the event of a JSONPointerResolutionError.

import { jsonpointer } from "json-p3";

const data = {
  users: [
    { name: "Sue", score: 100 },
    { name: "John", score: 86 },
    { name: "Sally", score: 84 },
    { name: "Jane", score: 55 },
  ],
};

const rv = jsonpointer.resolve("/users/1/age", data, -1);
console.log(rv); // -1

TODO: "compile" a pointer for later use

JSON Patch

Apply a JSON Patch (RFC 6902) to some data. A JSON Patch defines update operation to perform on a JSON document. Data is modified in place..

import { jsonpatch } from "json-p3";

const ops = [
  { op: "add", path: "/some/foo", value: { foo: {} } },
  { op: "add", path: "/some/foo", value: { bar: [] } },
  { op: "copy", from: "/some/other", path: "/some/foo/else" },
  { op: "add", path: "/some/foo/bar/-", value: 1 },
];

const data = { some: { other: "thing" } };
jsonpatch.apply(ops, data);
console.log(data);
// { some: { other: 'thing', foo: { bar: [Array], else: 'thing' } } }

Use the JSONPatch class to create a patch for repeated application.

import { JSONPatch } from "json-p3";

const patch = new JSONPatch([
  { op: "add", path: "/some/foo", value: { foo: {} } },
  { op: "add", path: "/some/foo", value: { bar: [] } },
  { op: "copy", from: "/some/other", path: "/some/foo/else" },
  { op: "add", path: "/some/foo/bar/-", value: 1 },
]);

const data = { some: { other: "thing" } };
patch.apply(data);
console.log(data);
// { some: { other: 'thing', foo: { bar: [Array], else: 'thing' } } }

TODO: patch builder api