@hkk12369/jsonpath-lite

Lightweight, performance-focused JSONPath subset for Node.js with full TypeScript support.

~11× faster than jsonpath on typical queries. Zero dependencies.

Installation

npm install @hkk12369/jsonpath-lite

Quick start

import { query, compile } from '@hkk12369/jsonpath-lite';

const data = {
    store: {
        books: [
            { title: 'A', price: 8.95 },
            { title: 'B', price: 12.99 },
        ],
    },
};

// String path — convenient for one-off calls
query(data, '$.store.books[?(@.price > 10)]');
// → [{ title: 'B', price: 12.99 }]

// Pre-compiled path — parse once, reuse many times
const path = compile('$..books[?(@.price > 10)].title');
for (const record of records) {
    query(record, path);
}

Supported syntax

| Syntax | Description | |---|---| | $ | Root element | | .key | Child key access | | ..key | Recursive descent by key | | [n] | Array index | | ['key'] | Bracket key (allows special characters) | | [*] | Wildcard — all direct children | | .key* | Glob key — matches key, keyA, keyFoo, … | | .*key | Glob key — matches any key ending with key | | [?(...)] | Filter expression |

Filter operators

| Operator | Example | |---|---| | == === | [?(@.x == 1)] | | != !== | [?(@.x != null)] | | > >= < <= | [?(@.price >= 10)] | | like_regex | [?(@.name like_regex "^Jo")] | | like_regex with flags | [?(@.name like_regex "^jo" flag "i")] | | starts_with | [?(@.id starts_with "usr_")] | | ends_with | [?(@.file ends_with ".ts")] | | includes / contains | [?(@.tags contains "admin")] | | truthy (no operator) | [?(@.enabled)] | | ! && \|\| () | [?(@.a && (@.b > 1 \|\| [email protected]))] | | @key | Key of the element — use after [*] or ..* |

Path in filter (@. and @..)

• @.field — direct child lookup
• @..field — recursive lookup anywhere inside the node
• @.a.b.c — chained path steps
• @.a* — glob inside filter path

// Recursive lookup inside filter
query(data, '$..items[?(@..status == "active")]');

// @key — filter by key name
query(data, '$.*[?(@key starts_with "usr_")]');

Pre-compiling paths

Call compile() once and pass the result to query() to avoid re-parsing on every call:

import { compile, query, type CompiledPath } from '@hkk12369/jsonpath-lite';

const activePath: CompiledPath = compile('$..items[?(@.active)].name');

// Zero parsing overhead on each iteration
for (const record of largeDataset) {
    const names = query(record, activePath);
}

TypeScript

All exports are fully typed. query() returns unknown[]

const prices = query(data, '$..price') as number[];

The CompiledPath type is exported for storing pre-compiled paths in class fields or module-level constants.

License

MIT