@loancrate/json-selector 4.0.0 → 5.1.0

package/README.md

@@ -1,31 +1,14 @@
 # LoanCrate JSON Selectors
 
-LoanCrate JSON Selectors are based on a subset of [JMESPath](https://jmespath.org)
-with the following additions:
+A TypeScript library for querying and mutating JSON documents using [JMESPath](https://jmespath.org)-style expressions. Fully implements both the original JMESPath specification and [JMESPath Community Edition](https://jmespath.site/main/), with two extensions for ID-based access and bare numeric literals.
 
-- A shorthand/extension for selecting an object from an array based on ID.
-- A root-node expression, as added in the [JMESPath Community Edition](https://jmespath.site/main/#spec-root-node).
+Key capabilities:
 
-Currently, the subset includes everything except [functions](https://jmespath.org/specification.html#functions-expressions),
-object projections ([`*` wildcard](https://jmespath.org/specification.html#wildcard-expressions) not within brackets),
-and multi-select [lists](https://jmespath.org/specification.html#multiselect-list) and [hashes](https://jmespath.org/specification.html#multiselect-hash).
-The library passes all of the [JMESPath compliance tests](https://github.com/jmespath/jmespath.test) not using those specific features.
-
-To allow for selection by ID, we extend index expressions to accept a
-[raw string literal](https://jmespath.org/specification.html#raw-string-literals)
-(as opposed to a numeric literal), which represents the value of the `id` property
-of the desired object from an array of objects.
-Formally, `x['y']` would be equivalent to `x[?id == 'y'] | [0]` in JMESPath.
-This should be unambiguous relative to the existing grammar and semantics.
-
-In addition to the extensions above, this library offers the following features compared to [jmespath.js](https://github.com/jmespath/jmespath.js):
-
-- Written using TypeScript with a hand-written Pratt parser
-- Type definitions for the abstract syntax tree (AST) produced by the parser
-- Typed visitor pattern for accessing AST nodes
-- Formatting of an AST back into an expression string
-- Read/write/delete accessors allow modification of the input data referenced by a selector
-- Detailed error reporting for syntax errors
+- **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
 
@@ -33,7 +16,7 @@ In addition to the extensions above, this library offers the following features
 npm add @loancrate/json-selector
 ```
 
-## Usage
+## Quick Start
 
 ```ts
 import {
@@ -61,69 +44,25 @@ accessor.delete();
 console.log(obj.foo.bar[0].value); // undefined
 ```
 
-## Operator Precedence
-
-As mentioned above, JSON Selectors are based on
-[JMESPath](https://jmespath.org). Although JMESPath claims to have an "ABNF
-grammar with a complete specification", the
-[specification](https://jmespath.org/specification.html) is not complete
-regarding operator precedence, since it only mentions the relative precedence of
-5 tokens (`|`, `||`, `&&`, `!`, and `]`). To discover the precedence of other
-operators, we must turn to the [JMESPath source
-code](https://github.com/jmespath/jmespath.js/blob/master/jmespath.js). It is
-implemented as a [Top-Down Operator Precedence (TDOP)
-parser](https://eli.thegreenplace.net/2010/01/02/top-down-operator-precedence-parsing),
-which is based on principles like "token binding power", "null denotation"
-(**nud**), and "left denotation" (**led**). Given knowledge of these principles
-and the [binding power
-table](https://github.com/jmespath/jmespath.js/blob/master/jmespath.js#L474-L501)
-from the source, we can reverse-engineer the operator precedence of JMESPath.
-
-The expression grammar has three categories of operators:
-
-**Logical and comparison operators** follow traditional precedence rules (from
-lowest to highest):
-
-- pipe: `|`
-- or: `||`
-- and: `&&`
-- compare: `<=`, `>=`, `<`, `>`, `==`, `!=`
-- not: `!` (prefix)
-
-Higher-precedence operators bind more tightly. For example, `a || b && c`
-parses as `a || (b && c)`, and `a || b.c` parses as `a || (b.c)` because
-access operators have higher precedence than `||`.
-
-**Access operators** chain left-to-right as postfix operators:
-
-- member access: `.field`
-- index access: `[0]`, `[n:m]` (slices)
-- ID access: `['id']` (shorthand for `[?id == 'id'] | [0]`)
-
-For example, `a[0].b.c['id'].d.e` parses as `(((((a[0]).b).c)['id']).d).e` -
-each operator applies to the complete expression on its left, building up the
-chain step by step.
-
-**Projection operators** create projections that map over collections:
-
-- flatten: `[]` (flatten arrays)
-- filter: `[?condition]` (filter by condition)
-- star: `[*]` (map over array values)
-
-Projections terminate before logical, comparison, and pipe operators, but
-continue with access operators and can chain with other projections. For
-example:
-
-- `items[*].name` - projects over items, accessing name from each
-- `items[*].tags[]` - projects over items, then flattens tags arrays
-- `items[*] || []` - projection completes before the `||`, result is `(items[*]) || []`
-
-**Note on chained flattens**: Multiple flattens compound to flatten deeper
-levels. For example, on data `[[[1,2]], [[3,4]]]`:
-
-- `[]` gives `[[1,2], [3,4]]` (one level)
-- `[][]` gives `[1,2,3,4]` (two levels)
-- `[*][]` gives `[[1,2], [3,4]]` (projects then flattens once - not the same as `[][]`)
+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**](docs/language.md) — Expression syntax, operators, precedence, projections, and extensions
+- [**Function Reference**](docs/functions.md) — All 43 built-in functions with signatures and behavior
+- [**API Reference**](docs/api.md) — TypeScript exports, accessors, visitor, function system, errors, and AST
+- [**Benchmarks**](docs/benchmark.md) — Parsing performance benchmarks and cross-library comparison
+
+## Standards and Extensions
+
+The library fully implements the original [JMESPath specification](https://jmespath.org) and [JMESPath Community Edition](https://jmespath.site/main/), including root-node expressions (`$`), arithmetic, ternary conditionals, and lexical-scope `let` expressions. Compliance is verified against both official [JMESPath test fixtures](https://github.com/jmespath/jmespath.test) 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](docs/language.md#legacy-compatibility) for details.
 
 ## License
 

package/dist/access-guards.d.ts

@@ -0,0 +1,16 @@
+import { JsonSelector } from "./ast";
+import { AccessorError } from "./errors";
+type ReadOnlySelectorType = "not" | "compare" | "arithmetic" | "unaryArithmetic" | "and" | "or" | "ternary" | "functionCall" | "expressionRef" | "variableRef" | "let" | "multiSelectList" | "multiSelectHash" | "literal" | "current" | "root";
+export type ReadOnlySelector = Extract<JsonSelector, {
+    type: ReadOnlySelectorType;
+}>;
+type AccessOperation = "get" | "set" | "delete";
+export declare function readOnlyError(selector: ReadOnlySelector, operation: "set" | "delete", construct?: string): AccessorError;
+export declare function requireObjectContext(value: unknown, selector: JsonSelector, operation: AccessOperation): Record<string, unknown>;
+export declare function requireObjectParent(value: unknown, selector: JsonSelector, operation: AccessOperation): Record<string, unknown>;
+export declare function requireArrayParent(value: unknown, selector: JsonSelector, operation: AccessOperation): unknown[];
+export declare function requireArrayOrStringParent(value: unknown, selector: JsonSelector, operation: AccessOperation): unknown[] | string;
+export declare function resolveInBoundsIndex(arr: unknown[], index: number, selector: JsonSelector, operation: AccessOperation): number;
+export declare function requireIdIndex(arr: unknown[], id: string | number, selector: JsonSelector, operation: AccessOperation): number;
+export {};
+//# sourceMappingURL=access-guards.d.ts.map

package/dist/access-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-guards.d.ts","sourceRoot":"","sources":["../src/access-guards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AACrC,OAAO,EAA0B,aAAa,EAAE,MAAM,UAAU,CAAC;AAIjE,KAAK,oBAAoB,GACrB,KAAK,GACL,SAAS,GACT,YAAY,GACZ,iBAAiB,GACjB,KAAK,GACL,IAAI,GACJ,SAAS,GACT,cAAc,GACd,eAAe,GACf,aAAa,GACb,KAAK,GACL,iBAAiB,GACjB,iBAAiB,GACjB,SAAS,GACT,SAAS,GACT,MAAM,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,OAAO,CACpC,YAAY,EACZ;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAC/B,CAAC;AAqBF,KAAK,eAAe,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,CAAC;AAmBhD,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,gBAAgB,EAC1B,SAAS,EAAE,KAAK,GAAG,QAAQ,EAC3B,SAAS,SAAsC,GAC9C,aAAa,CAOf;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,eAAe,GACzB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,eAAe,GACzB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,eAAe,GACzB,OAAO,EAAE,CAkBX;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,eAAe,GACzB,OAAO,EAAE,GAAG,MAAM,CAkBpB;AAED,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,EAAE,EACd,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,eAAe,GACzB,MAAM,CAWR;AAED,wBAAgB,cAAc,CAC5B,GAAG,EAAE,OAAO,EAAE,EACd,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,eAAe,GACzB,MAAM,CAWR"}

package/dist/access-util.d.ts

@@ -0,0 +1,7 @@
+import { JsonSelector } from "./ast";
+import type { EvaluationContext } from "./evaluation-context";
+export declare function replaceArray(target: unknown[], source: readonly unknown[]): unknown[];
+export declare function invertedFilter(value: unknown[], condition: JsonSelector, evalCtx: EvaluationContext): unknown[];
+/** Returns the complement of a slice: the elements that would NOT be selected by the given slice parameters. */
+export declare function invertedSlice(value: unknown[], start: number | undefined, end?: number, step?: number): unknown[];
+//# sourceMappingURL=access-util.d.ts.map

package/dist/access-util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-util.d.ts","sourceRoot":"","sources":["../src/access-util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAErC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG9D,wBAAgB,YAAY,CAC1B,MAAM,EAAE,OAAO,EAAE,EACjB,MAAM,EAAE,SAAS,OAAO,EAAE,GACzB,OAAO,EAAE,CAIX;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EAAE,EAChB,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,iBAAiB,GACzB,OAAO,EAAE,CAIX;AAED,gHAAgH;AAChH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EAAE,EAChB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,GAAG,CAAC,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,EAAE,CA6BX"}

package/dist/access.d.ts

@@ -1,21 +1,18 @@
 import { JsonSelector } from "./ast";
+import type { EvaluationContext } from "./evaluation-context";
+/** A selector-based accessor not yet bound to a specific context object, supporting get/set/delete operations. */
 export interface UnboundAccessor {
     readonly selector: JsonSelector;
     isValidContext(context: unknown, rootContext?: unknown): boolean;
     get(context: unknown, rootContext?: unknown): unknown;
+    getOrThrow(context: unknown, rootContext?: unknown): unknown;
     set(value: unknown, context: unknown, rootContext?: unknown): void;
+    setOrThrow(value: unknown, context: unknown, rootContext?: unknown): void;
     delete(context: unknown, rootContext?: unknown): void;
+    deleteOrThrow(context: unknown, rootContext?: unknown): void;
 }
-export declare function makeJsonSelectorAccessor(selector: JsonSelector): UnboundAccessor;
-export interface Accessor<T> {
-    readonly selector: JsonSelector;
-    readonly valid: boolean;
-    readonly path: string;
-    get(): T;
-    set(value: T): void;
-    delete(): void;
-}
-export declare function bindJsonSelectorAccessor(unbound: UnboundAccessor, context: unknown, rootContext?: unknown): Accessor<unknown>;
-export declare function accessWithJsonSelector(selector: JsonSelector, context: unknown, rootContext?: unknown): Accessor<unknown>;
-export declare function invertedSlice(value: unknown[], start: number | undefined, end?: number, step?: number): unknown[];
+/** Configuration for accessor creation, providing the function provider used during evaluation. */
+export type AccessorOptions = Omit<EvaluationContext, "rootContext">;
+/** Compiles a selector AST into an {@link UnboundAccessor} that can be repeatedly bound to different contexts. */
+export declare function makeJsonSelectorAccessor(selector: JsonSelector, options?: Partial<AccessorOptions>): UnboundAccessor;
 //# sourceMappingURL=access.d.ts.map

package/dist/access.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAuBrC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IACjE,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IACtD,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACnE,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACvD;AAyDD,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,YAAY,GACrB,eAAe,CA0VjB;AAED,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,GAAG,IAAI,CAAC,CAAC;IACT,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACpB,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,OAAO,EAChB,WAAW,UAAU,GACpB,QAAQ,CAAC,OAAO,CAAC,CAiBnB;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,OAAO,EAChB,WAAW,UAAU,GACpB,QAAQ,CAAC,OAAO,CAAC,CAMnB;AAqBD,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EAAE,EAChB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,GAAG,CAAC,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,EAAE,CA6BX"}
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,YAAY,EAQb,MAAM,OAAO,CAAC;AAaf,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAe9D,kHAAkH;AAClH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IACjE,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IACtD,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAC7D,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACnE,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1E,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACtD,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9D;AA2GD,mGAAmG;AACnG,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,iBAAiB,EAAE,aAAa,CAAC,CAAC;AAErE,kHAAkH;AAClH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,YAAY,EACtB,OAAO,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GACjC,eAAe,CAIjB"}

package/dist/ast.d.ts

@@ -1,44 +1,65 @@
 import { JsonValue } from "type-fest";
+/** Discriminator string for each AST node variant, used for exhaustive pattern matching. */
 export type JsonSelectorNodeType = JsonSelector["type"];
+/** The current context value (`@`), implicit when no explicit token is written. */
 export interface JsonSelectorCurrent {
     type: "current";
+    /** When true, the `@` token was explicitly written (not an implicit placeholder). */
+    explicit?: boolean;
 }
+/** Reference to the root document (`$`), enabling access to top-level data from nested contexts. */
 export interface JsonSelectorRoot {
     type: "root";
 }
+/** A constant JSON value embedded directly in the expression (e.g. `'hello'`, `` `42` ``, `true`). */
 export interface JsonSelectorLiteral {
     type: "literal";
     value: JsonValue;
+    /** When true, this literal was written with backtick syntax (e.g., `` `true` `` instead of bare `true`). */
+    backtickSyntax?: boolean;
 }
+/** A bare field name applied to the current context, e.g. `foo`. */
 export interface JsonSelectorIdentifier {
     type: "identifier";
     id: string;
 }
+/** Dot-notation property access on a sub-expression, e.g. `expr.field`. */
 export interface JsonSelectorFieldAccess {
     type: "fieldAccess";
     expression: JsonSelector;
     field: string;
 }
+/** Numeric array index access on a sub-expression, e.g. `expr[0]` or `expr[-1]`. */
 export interface JsonSelectorIndexAccess {
     type: "indexAccess";
     expression: JsonSelector;
     index: number;
 }
+/** LoanCrate extension: selects an array element by its `id` property, e.g. `expr['my-id']`. */
 export interface JsonSelectorIdAccess {
     type: "idAccess";
     expression: JsonSelector;
     id: string;
 }
+/** Array wildcard projection (`[*]`), applying an optional sub-expression to each element. */
 export interface JsonSelectorProject {
     type: "project";
     expression: JsonSelector;
     projection?: JsonSelector;
 }
+/** Wildcard projection over object values (`.*`), optionally applying a sub-expression to each value. */
+export interface JsonSelectorObjectProject {
+    type: "objectProject";
+    expression: JsonSelector;
+    projection?: JsonSelector;
+}
+/** Array filter that retains only elements where the condition is truthy, e.g. `expr[?age > 18]`. */
 export interface JsonSelectorFilter {
     type: "filter";
     expression: JsonSelector;
     condition: JsonSelector;
 }
+/** Python-style array slice with optional start, end, and step, e.g. `expr[0:5:2]`. */
 export interface JsonSelectorSlice {
     type: "slice";
     expression: JsonSelector;
@@ -46,35 +67,108 @@ export interface JsonSelectorSlice {
     end?: number;
     step?: number;
 }
+/** Flattens one level of nested arrays, e.g. `expr[]`. */
 export interface JsonSelectorFlatten {
     type: "flatten";
     expression: JsonSelector;
 }
+/** Logical negation: converts a truthy value to `false` and a falsy/empty value to `true`. */
 export interface JsonSelectorNot {
     type: "not";
     expression: JsonSelector;
 }
+/** The set of relational and equality operators supported in comparisons. */
 export type JsonSelectorCompareOperator = "<" | "<=" | "==" | ">=" | ">" | "!=";
+/** Binary comparison using a relational or equality operator, e.g. `a == b` or `age >= 18`. */
 export interface JsonSelectorCompare {
     type: "compare";
     operator: JsonSelectorCompareOperator;
     lhs: JsonSelector;
     rhs: JsonSelector;
 }
+/** The set of arithmetic operators supported in binary arithmetic expressions. */
+export type JsonSelectorArithmeticOperator = "+" | "-" | "*" | "/" | "%" | "//";
+/** Binary arithmetic operation, e.g. `a + b`, `price * quantity`, `x // 2`. */
+export interface JsonSelectorArithmetic {
+    type: "arithmetic";
+    operator: JsonSelectorArithmeticOperator;
+    lhs: JsonSelector;
+    rhs: JsonSelector;
+}
+/** The set of arithmetic operators supported in unary arithmetic expressions. */
+export type JsonSelectorUnaryArithmeticOperator = "+" | "-";
+/** Unary arithmetic operation, e.g. `-a` or `+value`. */
+export interface JsonSelectorUnaryArithmetic {
+    type: "unaryArithmetic";
+    operator: JsonSelectorUnaryArithmeticOperator;
+    expression: JsonSelector;
+}
+/** Short-circuit logical AND: returns the left operand if falsy, otherwise the right operand. */
 export interface JsonSelectorAnd {
     type: "and";
     lhs: JsonSelector;
     rhs: JsonSelector;
 }
+/** Short-circuit logical OR: returns the left operand if truthy, otherwise the right operand. */
 export interface JsonSelectorOr {
     type: "or";
     lhs: JsonSelector;
     rhs: JsonSelector;
 }
+/** Conditional expression (`condition ? consequent : alternate`) using JMESPath truthiness rules. */
+export interface JsonSelectorTernary {
+    type: "ternary";
+    condition: JsonSelector;
+    consequent: JsonSelector;
+    alternate: JsonSelector;
+}
+/** Pipe operator (`|`) that evaluates the right side against the result of the left side, resetting projections. */
 export interface JsonSelectorPipe {
     type: "pipe";
     lhs: JsonSelector;
     rhs: JsonSelector;
+    /** When true, this pipe originated from dot syntax (e.g., `foo.func()`, `foo.{...}`, `foo.[...]`). */
+    dotSyntax?: boolean;
+}
+/** Named function invocation with zero or more argument expressions, e.g. `length(foo)`. */
+export interface JsonSelectorFunctionCall {
+    type: "functionCall";
+    name: string;
+    args: JsonSelector[];
+}
+/** Unevaluated expression reference (`&expr`) passed to higher-order functions like `sort_by` and `map`. */
+export interface JsonSelectorExpressionRef {
+    type: "expressionRef";
+    expression: JsonSelector;
+}
+/** Reference to a lexical-scope variable (`$name`) bound by a `let` expression. */
+export interface JsonSelectorVariableRef {
+    type: "variableRef";
+    /** Variable name without the leading `$`. */
+    name: string;
+}
+/** Lexical-scope expression: binds variables for use within the `expression` body. */
+export interface JsonSelectorLet {
+    type: "let";
+    bindings: Array<{
+        name: string;
+        value: JsonSelector;
+    }>;
+    expression: JsonSelector;
 }
-export type JsonSelector = JsonSelectorCurrent | JsonSelectorRoot | JsonSelectorLiteral | JsonSelectorIdentifier | JsonSelectorFieldAccess | JsonSelectorIndexAccess | JsonSelectorIdAccess | JsonSelectorProject | JsonSelectorFilter | JsonSelectorSlice | JsonSelectorFlatten | JsonSelectorNot | JsonSelectorCompare | JsonSelectorAnd | JsonSelectorOr | JsonSelectorPipe;
+/** Evaluates multiple expressions in parallel and collects the results into an array, e.g. `[foo, bar]`. */
+export interface JsonSelectorMultiSelectList {
+    type: "multiSelectList";
+    expressions: JsonSelector[];
+}
+/** Evaluates named expressions and collects the results into a new object, e.g. `{a: foo, b: bar}`. */
+export interface JsonSelectorMultiSelectHash {
+    type: "multiSelectHash";
+    entries: Array<{
+        key: string;
+        value: JsonSelector;
+    }>;
+}
+/** Discriminated union of all AST node types produced by the selector parser. */
+export type JsonSelector = JsonSelectorCurrent | JsonSelectorRoot | JsonSelectorLiteral | JsonSelectorIdentifier | JsonSelectorFieldAccess | JsonSelectorIndexAccess | JsonSelectorIdAccess | JsonSelectorProject | JsonSelectorObjectProject | JsonSelectorFilter | JsonSelectorSlice | JsonSelectorFlatten | JsonSelectorNot | JsonSelectorCompare | JsonSelectorArithmetic | JsonSelectorUnaryArithmetic | JsonSelectorAnd | JsonSelectorOr | JsonSelectorTernary | JsonSelectorPipe | JsonSelectorFunctionCall | JsonSelectorExpressionRef | JsonSelectorVariableRef | JsonSelectorLet | JsonSelectorMultiSelectList | JsonSelectorMultiSelectHash;
 //# sourceMappingURL=ast.d.ts.map

package/dist/ast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,MAAM,oBAAoB,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,YAAY,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,YAAY,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,YAAY,CAAC;IACzB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,UAAU,EAAE,YAAY,CAAC;IACzB,UAAU,CAAC,EAAE,YAAY,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,YAAY,CAAC;IACzB,SAAS,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,YAAY,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,UAAU,EAAE,YAAY,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,KAAK,CAAC;IACZ,UAAU,EAAE,YAAY,CAAC;CAC1B;AAED,MAAM,MAAM,2BAA2B,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;AAEhF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,2BAA2B,CAAC;IACtC,GAAG,EAAE,YAAY,CAAC;IAClB,GAAG,EAAE,YAAY,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EAAE,YAAY,CAAC;IAClB,GAAG,EAAE,YAAY,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,YAAY,CAAC;IAClB,GAAG,EAAE,YAAY,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,YAAY,CAAC;IAClB,GAAG,EAAE,YAAY,CAAC;CACnB;AAED,MAAM,MAAM,YAAY,GACpB,mBAAmB,GACnB,gBAAgB,GAChB,mBAAmB,GACnB,sBAAsB,GACtB,uBAAuB,GACvB,uBAAuB,GACvB,oBAAoB,GACpB,mBAAmB,GACnB,kBAAkB,GAClB,iBAAiB,GACjB,mBAAmB,GACnB,eAAe,GACf,mBAAmB,GACnB,eAAe,GACf,cAAc,GACd,gBAAgB,CAAC"}
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"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"}

package/dist/bind.d.ts

@@ -0,0 +1,19 @@
+import { AccessorOptions, UnboundAccessor } from "./access";
+import { JsonSelector } from "./ast";
+/** A selector accessor bound to a specific context, providing typed get/set/delete and validity checking. */
+export interface Accessor<T> {
+    readonly selector: JsonSelector;
+    readonly valid: boolean;
+    readonly path: string;
+    get(): T;
+    getOrThrow(): T;
+    set(value: T): void;
+    setOrThrow(value: T): void;
+    delete(): void;
+    deleteOrThrow(): void;
+}
+/** Binds an {@link UnboundAccessor} to a specific context and root, producing a ready-to-use {@link Accessor}. */
+export declare function bindJsonSelectorAccessor(unbound: UnboundAccessor, context: unknown, rootContext?: unknown): Accessor<unknown>;
+/** One-step convenience: parses a selector into an accessor already bound to the given context. */
+export declare function accessWithJsonSelector(selector: JsonSelector, context: unknown, rootContext?: unknown, options?: Partial<AccessorOptions>): Accessor<unknown>;
+//# sourceMappingURL=bind.d.ts.map

package/dist/bind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind.d.ts","sourceRoot":"","sources":["../src/bind.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EAEf,eAAe,EAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAGrC,6GAA6G;AAC7G,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,GAAG,IAAI,CAAC,CAAC;IACT,UAAU,IAAI,CAAC,CAAC;IAChB,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACpB,UAAU,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAC3B,MAAM,IAAI,IAAI,CAAC;IACf,aAAa,IAAI,IAAI,CAAC;CACvB;AAED,kHAAkH;AAClH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,OAAO,EAChB,WAAW,UAAU,GACpB,QAAQ,CAAC,OAAO,CAAC,CA0BnB;AAED,mGAAmG;AACnG,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,OAAO,EAChB,WAAW,UAAU,EACrB,OAAO,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GACjC,QAAQ,CAAC,OAAO,CAAC,CAMnB"}

package/dist/errors.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Base class for all json-selector library errors.
+ */
+export declare class JsonSelectorError extends Error {
+    constructor(message: string);
+}
+/**
+ * Base class for parse-time errors.
+ */
+export declare class JsonSelectorSyntaxError extends JsonSelectorError {
+    readonly expression: string;
+    readonly offset: number;
+    constructor(message: string, expression: string, offset: number);
+}
+/**
+ * Lexer error for unknown/invalid characters.
+ */
+export declare class UnexpectedCharacterError extends JsonSelectorSyntaxError {
+    readonly character: string;
+    constructor(expression: string, offset: number, character: string);
+}
+/**
+ * Lexer error for missing closing delimiters.
+ */
+export declare class UnterminatedTokenError extends JsonSelectorSyntaxError {
+    readonly tokenKind: string;
+    readonly expectedDelimiter: string;
+    constructor(expression: string, offset: number, tokenKind: string, expectedDelimiter: string);
+}
+/**
+ * Lexer error for malformed token internals.
+ */
+export declare class InvalidTokenError extends JsonSelectorSyntaxError {
+    readonly tokenKind: string;
+    readonly detail: string;
+    constructor(expression: string, offset: number, tokenKind: string, detail: string);
+}
+/**
+ * Parser/lexer error for an unexpected token.
+ */
+export declare class UnexpectedTokenError extends JsonSelectorSyntaxError {
+    readonly token: string;
+    readonly expected?: string | undefined;
+    readonly context?: string | undefined;
+    constructor(expression: string, offset: number, token: string, expected?: string | undefined, context?: string | undefined);
+}
+/**
+ * Parser error for unexpected EOF.
+ */
+export declare class UnexpectedEndOfInputError extends JsonSelectorSyntaxError {
+    readonly expected?: string | undefined;
+    constructor(expression: string, expected?: string | undefined);
+}
+/**
+ * Base class for evaluation/runtime errors.
+ */
+export declare class JsonSelectorRuntimeError extends JsonSelectorError {
+}
+/**
+ * Base class for runtime type errors.
+ */
+export declare class JsonSelectorTypeError extends JsonSelectorRuntimeError {
+}
+export type AccessorErrorCode = "NOT_WRITABLE" | "MISSING_PARENT" | "TYPE_MISMATCH" | "INDEX_OUT_OF_BOUNDS" | "MISSING_ID";
+/**
+ * Error thrown when an accessor operation cannot be applied to the given context.
+ */
+export declare class AccessorError extends JsonSelectorRuntimeError {
+    readonly code: AccessorErrorCode;
+    readonly path: string;
+    readonly operation: "get" | "set" | "delete";
+    constructor(code: AccessorErrorCode, path: string, operation: "get" | "set" | "delete", message: string);
+}
+/**
+ * Error thrown when reading an unbound lexical-scope variable.
+ */
+export declare class UndefinedVariableError extends JsonSelectorRuntimeError {
+    readonly variableName: string;
+    constructor(variableName: string);
+}
+/**
+ * Error thrown when arithmetic requires a number but receives another type.
+ */
+export declare class NotANumberError extends JsonSelectorTypeError {
+    readonly operator: string;
+    readonly operandRole: string;
+    readonly actualType: string;
+    constructor(operator: string, operandRole: string, actualType: string, message?: string);
+}
+/**
+ * Error thrown when division or integer division has a zero divisor.
+ */
+export declare class DivideByZeroError extends NotANumberError {
+    readonly divisor: number;
+    constructor(operator: "/" | "//", divisor: number);
+}
+/**
+ * Base error class for all function-related errors.
+ */
+export declare class FunctionError extends JsonSelectorRuntimeError {
+    readonly functionName: string;
+    constructor(functionName: string, message: string);
+}
+/**
+ * Error thrown when an unknown function is called.
+ */
+export declare class UnknownFunctionError extends FunctionError {
+    constructor(functionName: string);
+}
+/**
+ * Error thrown when a function is called with the wrong number of arguments.
+ */
+export declare class InvalidArityError extends FunctionError {
+    constructor(functionName: string, message: string);
+}
+/** Base error for argument-level validation failures, carrying both the function and argument names. */
+export declare class InvalidArgumentError extends FunctionError {
+    readonly argumentName: string;
+    constructor(functionName: string, argumentName: string, message: string);
+}
+/**
+ * Error thrown when a function argument has the wrong type.
+ */
+export declare class InvalidArgumentTypeError extends InvalidArgumentError {
+    constructor(functionName: string, argumentName: string, message: string);
+}
+/**
+ * Error thrown when a function argument has a valid type but an invalid value
+ * (e.g. negative integer where non-negative is required, non-integer float, pad string length != 1).
+ */
+export declare class InvalidArgumentValueError extends InvalidArgumentError {
+    constructor(functionName: string, argumentName: string, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/evaluate.d.ts

@@ -1,18 +1,35 @@
-import { JsonSelector, JsonSelectorCompareOperator } from "./ast";
-export declare function evaluateJsonSelector(selector: JsonSelector, context: unknown, rootContext?: unknown): unknown;
-export declare function project(value: unknown[], projection: JsonSelector | undefined, rootContext: unknown): unknown[];
-export declare function project(value: unknown, projection: JsonSelector | undefined, rootContext: unknown): unknown[] | null;
-export declare function filter(value: unknown[], condition: JsonSelector, rootContext: unknown): unknown[];
-export declare function filter(value: unknown, condition: JsonSelector, rootContext: unknown): unknown[] | null;
+import { JsonSelector, JsonSelectorArithmeticOperator, JsonSelectorCompareOperator, JsonSelectorCurrent, JsonSelectorUnaryArithmeticOperator } from "./ast";
+import type { EvaluationContext } from "./evaluation-context";
+/** Evaluates a parsed selector AST against a JSON context value, returning the selected result. */
+export declare function evaluateJsonSelector(selector: JsonSelector, context: unknown, evalCtx?: Partial<EvaluationContext>): unknown;
+/** @deprecated Use the form with `Partial<EvaluationContext>` instead. */
+export declare function evaluateJsonSelector(selector: JsonSelector, context: unknown, rootContext?: unknown, options?: Omit<EvaluationContext, "rootContext">): unknown;
+export declare function performArithmetic(lv: unknown, rv: unknown, operator: JsonSelectorArithmeticOperator): number;
+export declare function performUnaryArithmetic(value: unknown, operator: JsonSelectorUnaryArithmeticOperator): number;
+/** Checks whether a projection is trivial (absent or `@`), meaning array elements pass through unchanged. */
+export declare function isIdentityProjection(selector: JsonSelector | undefined): selector is JsonSelectorCurrent | undefined;
+/** Applies a wildcard array projection (`[*]`), evaluating the optional sub-expression against each element. */
+export declare function project(value: unknown[], projection: JsonSelector | undefined, evalCtx: EvaluationContext): unknown[];
+export declare function project(value: unknown, projection: JsonSelector | undefined, evalCtx: EvaluationContext): unknown;
+/** Projects over an object's values (`.*`), optionally applying a sub-expression to each value and filtering out nulls. */
+export declare function objectProject(value: unknown, projection: JsonSelector | undefined, evalCtx: EvaluationContext): unknown[] | null;
+/** Filters array elements, keeping only those where the condition evaluates to a truthy value. */
+export declare function filter(value: unknown[], condition: JsonSelector, evalCtx: EvaluationContext): unknown[];
+export declare function filter(value: unknown, condition: JsonSelector, evalCtx: EvaluationContext): unknown[] | null;
+/** Extracts a sub-sequence from an array or string using Python-style slice semantics. */
 export declare function slice(value: unknown[], start: number | undefined, end?: number, step?: number): unknown[];
-export declare function slice(value: unknown, start: number | undefined, end?: number, step?: number): unknown[] | null;
+export declare function slice(value: string, start: number | undefined, end?: number, step?: number): string;
+export declare function slice(value: unknown, start: number | undefined, end?: number, step?: number): unknown[] | string | null;
+/** Resolves optional slice parameters against an array length, clamping negative indices and applying defaults. */
 export declare function normalizeSlice(length: number, start?: number, end?: number, step?: number): {
     start: number;
     end: number;
     step: number;
 };
+/** Flattens one level of nested arrays; returns `null` for non-array input. */
 export declare function flatten(value: unknown[]): unknown[];
 export declare function flatten(value: unknown): unknown[] | null;
+/** Applies a comparison operator to two values; ordering operators require both operands to be numbers. */
 export declare function compare(lv: number, rv: number, operator: JsonSelectorCompareOperator): boolean;
 export declare function compare(lv: unknown, rv: unknown, operator: JsonSelectorCompareOperator): boolean | null;
 //# sourceMappingURL=evaluate.d.ts.map