JSONPath

jsonpath-plus (published on npm as jsonpath-plus, developed under the JSONPath-Plus org on GitHub) is a JavaScript implementation of JSONPath that extends Stefan Goessner’s original specification with additional operators and clearer semantics. Beyond standard path matching, it adds parent (^) and property-name (~) selectors, a full set of typed selectors (@string(), @number(), @scalar(), and more), and shorthand selectors like @path/@parent usable inside filter expressions.

Queries can return matched values, their absolute paths, JSON Pointers, parent objects, or parent property names, and filter expressions are evaluated through a sandboxed, jsep-based scripting layer that blocks prototype-pollution and Function-constructor escapes by default. The package ships ESM, CommonJS, and browser UMD builds along with a small CLI, and while actively used, the maintainers note in the README that the project is no longer under active feature development — only well-documented PRs and simple maintenance updates are considered.

What You Get

• A single JSONPath() function (or instantiable class) implementing the original Goessner JSONPath spec plus extensions (^, ~, typed selectors, escaping)
• Five result-type modes (value, path, pointer, parent, parentProperty, or all of them at once) selectable per query
• A safety-conscious filter-expression evaluator (jsep-based SafeScript) with configurable eval modes, avoiding raw eval/Function by default
• Prebuilt ESM/CJS/browser-UMD bundles plus a CLI binary for shell-based querying

Common Use Cases

• Extracting nested values from JSON API responses
• Querying JSON files from the command line via the bundled CLI
• Locating and rewriting matched paths in JSON documents for transformation pipelines
• Converting between JSONPath strings, path arrays, and JSON Pointers

Under The Hood

Architecture

The library splits its entry points by platform: src/jsonpath.js holds the core JSONPathClass evaluator with a shared parsing/caching layer (pathCache, scriptCache), src/jsonpath-node.js attaches Node’s vm.Script to the class for native filter-expression evaluation, and src/jsonpath-browser.js binds a browser-safe scripting engine instead, with per-target ESM/CJS/browser-UMD bundles produced under dist/ via Rollup. Filter expressions (?()) are parsed and evaluated through Safe-Script.js, a jsep-based AST evaluator that blocks access to Function constructors and prototype-polluting properties before executing dynamic script fragments — a compiled, sandboxed scripting layer sitting behind the core path-matching engine. bin/jsonpath-cli.js is a thin CLI wrapper reusing the same Node evaluator. Changing the core recursive-descent matching algorithm in jsonpath.js would ripple into every entry point since they all wrap the same class.

Tech Stack

JavaScript (ESM-first, "type": "module"), targeting Node >=18. Runtime dependency on jsep (a lightweight expression parser) plus its @jsep-plugin/assignment and @jsep-plugin/regex plugins for filter-expression syntax. Build tooling is Rollup 4 with plugin-babel/node-resolve/terser producing ESM, CommonJS, and browser UMD bundles; TypeScript (tsc) is used only to emit .d.ts declaration files from JSDoc-typed source rather than as the primary source language. Testing uses Mocha + Chai with c8 coverage, linting via ESLint (eslint-config-ash-nazg), and CI runs through GitHub Actions.

Code Quality

Extensive dedicated Mocha test files cover path expressions, escaping, callbacks, safe-eval sandboxing, type operators, and CLI behavior, run through c8 for coverage with a generated coverage badge, plus a tsc pass and an “Are The Types Wrong” check to validate published type definitions. Errors are handled explicitly — Safe-Script.js throws on blocked constructs rather than silently ignoring them, and the CLI wraps JSON parsing in try/catch with clear usage output. Code is authored as plain JavaScript with abundant JSDoc type annotations feeding the declaration-file generation, rather than native TypeScript. ESLint and CI enforce style and run the full suite on every change.

API Design The public API is a single JSONPath({path, json, ...}) call (or a positional shorthand) that returns matches directly — no class instantiation required for the common case — while still exposing an instantiable class (autostart: false) for repeated evaluations with cached parsed paths/scripts. Options like resultType, wrap, and eval give fine-grained control over output shape and script-evaluation safety without extra dependencies, and static helpers (toPathArray, toPathString, toPointer) cover common path-format conversions. Getting started requires only an import plus one function call, though the breadth of options (five eval modes, meta-selector operators like ^/~) adds a documentation surface a newcomer must skim before using advanced filters.