npm package: @jsonpathx/jsonpathx
Description: Modern, high-performance JSONPath library with RFC 9535 compliance and jsonpath-plus compatibility.
Author: Afzal Ahmad
Latest version: 0.1.6

# jsonpathx

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

[![Docs](https://img.shields.io/badge/Documentation-jsonpathx-blue?logo=github)](https://jsonpathx.github.io/jsonpathx/)
[![CI](https://github.com/jsonpathx/jsonpathx/actions/workflows/pages.yml/badge.svg)](https://github.com/jsonpathx/jsonpathx/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

# 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 📦

```bash
npm install @jsonpathx/jsonpathx
```

## Quick Start 🚀

### Basic Usage ✨

```typescript
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 🧩

```typescript
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 🧪

```typescript
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 🧱

```typescript
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 🎯

```typescript
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 🛠️

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

## Contributing 🤝

See `CONTRIBUTION.md` for contribution guidelines.

## License 📜

MIT License - see `LICENSE`.