jsonpathx

Modern, high-performance JSONPath library with RFC 9535 compliance and jsonpath-plus compatibility

Interactive JSONPath Playground 🛝

Try out JSONPath queries in your browser with the interactive playground: https://jsonpathx-playground.vercel.app/

Why jsonpathx? ⚡

jsonpathx is a next-generation JSONPath library that combines standards compliance with a practical, developer-friendly API. It is actively maintained and focused on real-world performance.

The motivation is driven by jsonpath and jsonpath-plus. Both libraries are no longer maintained, so jsonpathx exists to keep development alive, add new features, and make JSONPath tooling more robust.

RFC 9535 compliant - implements the official JSONPath standard
jsonpath-plus compatible - supports jsonpath-plus extensions and options
TypeScript-first - comprehensive type safety
Fluent builder API - chainable query composition
Multiple result formats - values, paths, pointers, parents, and more
Caching built in - LRU with TTL support

Installation 📦

npm install @jsonpathx/jsonpathx

Quick Start 🚀

Basic Usage ✨

import { JSONPath } from '@jsonpathx/jsonpathx';

const data = {
  store: {
    book: [
      { title: 'Sayings of the Century', price: 8.95 },
      { title: 'Moby Dick', price: 8.99 },
      { title: 'The Lord of the Rings', price: 22.99 }
    ],
    bicycle: { color: 'red', price: 19.95 }
  }
};

const titles = await JSONPath.query('$.store.book[*].title', data);
// ['Sayings of the Century', 'Moby Dick', 'The Lord of the Rings']

const cheapBooks = await JSONPath.query('$.store.book[?(@.price < 10)]', data);
// [{ title: 'Sayings of the Century', price: 8.95 }, { title: 'Moby Dick', price: 8.99 }]

const paths = await JSONPath.paths('$.store.book[*].title', data);
// ['$.store.book[0].title', '$.store.book[1].title', '$.store.book[2].title']

Fluent Builder API 🧩

import { JSONPath } from '@jsonpathx/jsonpathx';

const result = await JSONPath.create(data)
  .query('$.store.book[*]')
  .filter(book => book.price < 10)
  .sort((a, b) => a.price - b.price)
  .map(book => book.title)
  .take(5)
  .execute();
// ['Sayings of the Century', 'Moby Dick']

Type Selectors 🧪

const mixedData = {
  items: [1, "two", 3, "four", null, true, { key: "value" }, [1, 2]]
};

await JSONPath.query('$.items[?(@number())]', mixedData);
await JSONPath.query('$.items[?(@string())]', mixedData);
await JSONPath.query('$.items[?(@scalar())]', mixedData);

Extended Syntax ➕

jsonpathx implements all RFC 9535 features plus jsonpath-plus extensions like:

OR operator: $.store.book | $.store.bicycle
Grouping: $.store.(book, bicycle)
XPath-style filters: $..book[?~@.price<10].author

Performance 🏎️

See the benchmark results generated by the repo scripts (current suite shows jsonpathx leading most queries):

bench/results.md
apps/docs/bench.md

API Overview 🧭

JSONPath Class 🧱

await JSONPath.query(path, data, options)
await JSONPath.paths(path, data)
await JSONPath.pointers(path, data)
await JSONPath.parents(path, data)

JSONPath.create(data).query(path).filter(...).execute()

JSONPath.enableCache({ maxSize: 100, ttl: 60000 })
JSONPath.clearCache()
JSONPath.getCacheStats()

Result Types 🎯

resultType: 'value'
resultType: 'path'
resultType: 'pointer'
resultType: 'parent'
resultType: 'parentProperty'
resultType: 'all'

Documentation 📚

Guide and API docs are in apps/docs
Benchmarks: bench/results.md
Migration from jsonpath-plus: apps/docs/migration/from-jsonpath-plus.md

Development 🛠️

npm install
npm test
npm run bench
npm run docs:build

Contributing 🤝

See CONTRIBUTION.md for contribution guidelines.

License 📜

MIT License - see LICENSE.