jg-rp / json-p3

JSONPath, JSON Patch and JSON Pointer for JavaScript

JSON P3

JSONPath, JSON Patch and JSON Pointer for JavaScript.
We follow RFC 9535 and test against the JSONPath Compliance Test Suite.

---

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[[email protected] < 100].name", data);
console.log(nodes.values()); // [ 'John', 'Sally', 'Jane' ]

Links

• Docs: https://jg-rp.github.io/json-p3/
• Install: https://jg-rp.github.io/json-p3/#install
• JSONPath playground: https://jg-rp.github.io/json-p3/playground
• JSONPath syntax: https://jg-rp.github.io/json-p3/guides/jsonpath-syntax
• API reference: https://jg-rp.github.io/json-p3/api
• Change log: https://github.com/jg-rp/json-p3/blob/main/CHANGELOG.md
• NPM: https://www.npmjs.com/package/json-p3
• Issue tracker: https://github.com/jg-rp/json-p3/issues

Bundles

JSON P3 is written in TypeScript, compiled to JavaScript using Babel, and bundled using Rollup. The following, included bundles target defaults, maintained node version, as defined by Browserslist.

JSON P3 has zero runtime dependencies.

Bundle	Description
json-p3.cjs.js	A CommonJS formatted bundle.
json-p3.esm.js	An ECMAScript module formatted bundle.
json-p3-iife.js	A bundle formatted as an Immediately Invoked Function Expression.
json-p3-iife.min.js	A minified bundle formatted as an Immediately Invoked Function Expression.

Compliance Environment Variables

These environment variables control the location of the compliance test suite under test and if nondeterministic object iteration is enabled for those tests.

Environment Variable	Description
JSONP3_CTS_PATH	The path to cts.json used by compliance.test.ts. Defaults to tests/path/cts/cts.json.
JSONP3_CTS_NONDETERMINISTIC	When set to true, enables nondeterministic iteration of JSON objects for compliance.test.ts. Defaults to false.

Contributing

Please see Contributing to JSON P3

License

json-p3 is distributed under the terms of the MIT license.

json-p3's Issues

Slice generator function

The *lazyResolve method of SliceSelector uses the non-lazy private slice method. We should add a generator version of slice, which should be more memory efficient when used on large arrays with large slice ranges.

json-p3/src/path/selectors.ts

Lines 212 to 217 in d0bd351

	private slice(
	arr: JSONValue[],
	start?: number,
	stop?: number,
	step?: number,
	): Array<[number, JSONValue]> {

Keys filter selector

To solve a problem with node locations generated when using the non-standard keys selector (~), we need a way to conditionally select an object's keys, which could also be useful aside from creating valid node locations.

Whereas the standard filter selector ([? <expression>]) selects values from an array or object when the expression evaluates to true, the keys filter selector would select keys instead of values. Syntax for this could be [?~ <expression>] or [~? <expression>].

Alternatively (or additionally), we could implement a key selector ("key" singular), which selects the key if it exists. Syntax could be $.obj.~name or $.obj[~'name'] or $.obj[~"name"]. Without this we could use the proposed keys filter selector like this:

[~? # == 'name']

But that would not be a singular query and the key selector would.

Model JSONPath segments explicitly

Considering our abstract class JSONPathSelector, and the absence of a JSONPathSegment class, we are currently blurring the lines between segments and selectors.

We should refactor to follow the JSONPath model described in RFC 9535 by implementing a JSONPathSegment class, where all JSONPathSelector instances belong to a segment, even shorthand selectors. In turn, a JSONPath expression (currently JSONPath and should be JSONPathQuery or JSONPathExpression to match terminology from RFC 9535) should be made up of segments only.

This diagram illustrates what we want.