LoanCrate JSON Selectors

A TypeScript library for querying and mutating JSON documents using JMESPath-style expressions. Fully implements both the original JMESPath specification and JMESPath Community Edition, with two extensions for ID-based access and bare numeric literals.

Key capabilities:

• Parse expression strings into a typed AST
• Evaluate selectors against JSON data
• Format ASTs back into expression strings (round-trip safe)
• Read/write/delete values via selector-based accessors, including strict *OrThrow variants
• Extend with custom functions via a pluggable registry

Installation

npm add @loancrate/json-selector

Quick Start

import {
  accessWithJsonSelector,
  parseJsonSelector,
} from "@loancrate/json-selector";

const obj = {
  foo: {
    bar: [
      {
        id: "x",
        value: 1,
      },
    ],
  },
};
const selector = parseJsonSelector("foo.bar['x'].value");
const accessor = accessWithJsonSelector(selector, obj);
console.log(accessor.get()); // 1
console.log(obj.foo.bar[0].value); // 1
accessor.set(2);
console.log(obj.foo.bar[0].value); // 2
accessor.delete();
console.log(obj.foo.bar[0].value); // undefined

Use getOrThrow(), setOrThrow(), and deleteOrThrow() when you want accessor failures surfaced as AccessorError (instead of null reads or no-op writes/deletes).

Documentation

• Language Reference — Expression syntax, operators, precedence, projections, and extensions
• Function Reference — All 43 built-in functions with signatures and behavior
• API Reference — TypeScript exports, accessors, visitor, function system, errors, and AST
• Benchmarks — Parsing performance benchmarks and cross-library comparison

Standards and Extensions

The library fully implements the original JMESPath specification and JMESPath Community Edition, including root-node expressions ($), arithmetic, ternary conditionals, and lexical-scope let expressions. Compliance is verified against both official JMESPath test fixtures and JMESPath Community Edition fixtures.

Two extensions are added:

• ID-based access: x['id'] selects the first array element whose id property matches — equivalent to x[?id == 'id'] | [0] in standard JMESPath.
• Bare numeric literals: Numbers like 0, -1, 3.14 can appear directly in expressions without backtick delimiters, enabling natural syntax like foo[?price > 0] and a - 1.

Compatibility options (strictJsonLiterals, rawStringBackslashEscape, evaluateNullMultiSelect) control standards-compliance behavior. See the Language Reference for details.

License

This library is available under the ISC license.