@jarenjs/json 0.9.2 → 0.34.0

package/README.md

@@ -8,9 +8,11 @@ None of it depends on JSON Schema: every module can be used standalone in any Ja
 
 | Import | Contents |
 |---|---|
-| `@jarenjs/json` | everything below |
+| `@jarenjs/json` | the addressing and query modules below (`jslt`/`jtlt`/`xquery` are subpath-only) |
 | `@jarenjs/json/basic` | JSON, JSON Pointer and JSONPath string validation |
 | `@jarenjs/json/pointer` | the JSON Pointer and Relative JSON Pointer compiler |
+| `@jarenjs/json/patch` | JSON Patch and JSON Merge Patch: compiled apply + structural diff |
+| `@jarenjs/json/write` | compiled write operations: set/insert/remove at pointers, normalized paths, or every JSONPath match |
 | `@jarenjs/json/path` | the JSONPath compiler |
 | `@jarenjs/json/query` | the Jaren JSON Query engine |
 | `@jarenjs/json/jslt` | the Jaren JSLT stylesheet compiler and dispatcher |
@@ -24,9 +26,14 @@ None of it depends on JSON Schema: every module can be used standalone in any Ja
 | Standard | Functions |
 |---|---|
 | JSON validation | `isValidJSON`, `isValidJSONCheap` (a fast "definitely not JSON" pre-test) |
-| JSON Pointer ([RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)) | `compileJSONPointer`, `parseJSONPointer`, `isValidJSONPointer`, `isValidJSONPointerUriFragment` |
+| JSON Pointer ([RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)) | `compileJSONPointer`, `parseJSONPointer`, `parseJSONPointerPath`, `isValidJSONPointer`, `isValidJSONPointerUriFragment` |
 | Relative JSON Pointer | `compileRelativeJSONPointer`, `parseRelativeJSONPointer`, `compileDataRef`, `isValidRelativeJSONPointer` |
-| JSONPath ([RFC 9535](https://www.rfc-editor.org/rfc/rfc9535.html)) | `compileJSONPath`, `queryJSONPath`, `parseJSONPath`, `isValidJSONPathStrict` |
+| JSON Patch ([RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902)) | `compileJSONPatch`, `applyJSONPatch`, `createJSONPatch`, `isValidJSONPatch`, `JsonPatchCompileError`, `JsonPatchRuntimeError` |
+| JSON Merge Patch ([RFC 7396](https://datatracker.ietf.org/doc/html/rfc7396)) | `compileMergePatch`, `applyMergePatch`, `createMergePatch` |
+| Write operations | `compileJSONPointerSetter`/`Inserter`/`Remover`, `compileJSONPathSetter`/`Inserter`/`Remover`, one-shot `setAtJSONPointer`, `removeAtJSONPath`, ..., `JsonWriteError` |
+| Addressing bridge | `jsonPointerFromJSONPath`, `jsonPathFromJSONPointer` |
+| JSONPath ([RFC 9535](https://www.rfc-editor.org/rfc/rfc9535.html)) | `compileJSONPath`, `queryJSONPath`, `parseJSONPath`, `isValidJSONPathStrict`, `isValidJSONPathSegments` |
+| Canonical JSON ([RFC 8785](https://www.rfc-editor.org/rfc/rfc8785.html)) | `canonicalizeJson`, `JsonCanonicalizeError` |
 | Jaren JSON Query | `compileJsonQuery`, `queryJson`, `JsonQueryCompileError`, `JsonQueryRuntimeError` |
 | Jaren JSLT | `compileJsltStylesheet`, `transformJson`, `JsltCompileError`, `JsltRuntimeError` |
 | Jaren JTLT | `compileJtltStylesheet`, `renderText`, `JtltCompileError`, `JtltRuntimeError` |
@@ -57,8 +64,118 @@ const getName = compileRelativeJSONPointer('0#');
 getName(doc, '/limits/min'); // 'min' (the member name of the location)
 ```
 
+The `#` form has two modes, chosen once at compile time, because the spec's
+answer and the fast answer are not the same thing. Relative JSON Pointer says
+`#` yields the member *name* for an object member and the *index* — a number —
+for an array element, and telling those apart means looking at the container:
+
+```javascript
+const asString = compileRelativeJSONPointer('0#');                        // default
+const asNumber = compileRelativeJSONPointer('0#', { hashIndex: 'number' });
+
+asString({ a: ['x', 'y'] }, '/a/1'); // '1'  — string, answered from the path alone
+asNumber({ a: ['x', 'y'] }, '/a/1'); // 1    — number, the draft's answer
+asNumber({ o: { 1: 'v' } }, '/o/1'); // '1'  — a member named "1" is still a name
+```
+
+`hashIndex: 'string'` is the default and never touches the document, which is
+what keeps it a string operation of tens of nanoseconds; it is also what the
+validator's `$data` keyword has always seen, so `{"$data": "0#"}` compared
+against a number-typed keyword gets a string. `hashIndex: 'number'` walks to the
+parent of the location to check whether it is an array, and falls back to the
+string when that parent cannot be reached — nothing proves a position is an
+index. An unknown mode is a `TypeError` at compile time rather than a silent
+fallback. `compileDataRef` forwards the option.
+
+Neither mode verifies the location itself exists: the caller passes a location
+it actually reached. The root has no name, so `0#` there is
+`JSONPOINTER_NOTHING` and stays distinguishable from the member a document can
+genuinely name `''`.
+
 `compileDataRef(ref)` compiles the union the validator accepts — `''` for the data root, a leading `/` for an absolute pointer, a leading digit for a relative one — deciding the dispatch once at compile time. On a realistic `$data` workload the compiled resolvers are 4–20x faster than the interpretive resolver they replaced, and beat the `jsonpointer` npm package on every scenario (`npm run benchmark:jsonpointer`, 2026-07-17: absolute pointers 12–16x, relative pointers 4–16x, `compileDataRef` dispatch 7–20x).
 
+The write-side encode is there too: `encodeJSONPointerSegment(key)` escapes one reference token (`~` → `~0`, `/` → `~1`), `decodeJSONPointerSegment(token)` is its inverse for one token (decoding `~1` before `~0`, so a member named `~1` survives the round trip), and `formatJSONPointer(segments)` is the inverse of `parseJSONPointer`.
+
+`parseJSONPointerPath(pointer)` is the typed variant: it returns
+`(string|number)[]`, narrowing canonical array indexes to numbers
+(`'/items/0/id'` → `['items', 0, 'id']`) while leaving anything RFC 6901 does
+not make an index — `01`, `1e0`, `-`, `1abc` — a string. RFC 6901 has no
+types, so the classification is lexical rather than resolved against a
+document, using the same index rule the pointer compiler uses. This is the
+path shape error reporters and diffing tools expect, so it pairs directly
+with a validation error's `instancePath`.
+
+### JSON Patch and JSON Merge Patch
+
+Partial updates follow the same compile-once discipline. `compileJSONPatch(patch)` validates an [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) patch document once (`JsonPatchCompileError`, `JP0xxx`, with a `docPath` pointing into the *patch* document), pre-parses every `path`/`from` through the RFC 6901 parser and specializes one closure per operation. Applying is **copy-on-write**: the input document is never mutated, untouched subtrees are shared by reference with the result, and application is atomic — a failing operation (`JsonPatchRuntimeError`, `JP2xxx`, carrying both the patch `docPath` and the target `dataPath`) leaves nothing behind, exactly as RFC 6902 section 5 requires. The engine passes the complete official [json-patch-tests](https://github.com/json-patch/json-patch-tests) suite:
+
+```javascript
+import { compileJSONPatch, applyJSONPatch, createJSONPatch } from '@jarenjs/json';
+
+// compile once, apply many times (hot path)
+const apply = compileJSONPatch([
+  { op: 'test', path: '/version', value: 5 },
+  { op: 'replace', path: '/user/name', value: 'Bob' },
+  { op: 'add', path: '/user/tags/-', value: 'admin' },
+]);
+const next = apply(doc); // doc is untouched; unchanged subtrees are shared
+
+// one-shot
+applyJSONPatch(doc, patch);
+
+// structural diff: a change feed for @jarenjs/forms and friends
+applyJSONPatch(a, createJSONPatch(a, b)); // deep-equals b
+```
+
+Because an application only clones the spine it writes through — and clones it once, no matter how many operations touch the same region — the compiled applier beats the usual clone-and-interpret shape by 5–170x depending on document size (`npm run benchmark:jsonpatch`). Two options tune the copy discipline, mirroring JSLT's `share`/`fresh` dispositions: `values: 'fresh'` deep-copies inserted operation values per application (the default `'share'` inserts them by reference, so treat results as immutable), and `mutate: true` patches in place for the last bit of speed at the cost of atomicity.
+
+`createJSONPatch(source, target)` trims each array's deep-equal common prefix and suffix and pairs the rest up index-wise, which is linear and already minimal for in-place edits and head/tail insertions — but turns a mid-array insertion into a run of per-index replaces. `createJSONPatch(source, target, { arrayDiff: 'minimal' })` aligns the changed middle instead, so the insertion is one `add`:
+
+```javascript
+const before = [{ id: 1 }, { id: 2 }, { id: 3, n: 0 }];
+const after = [{ id: 1 }, { id: 9 }, { id: 2 }, { id: 3, n: 1 }];
+
+createJSONPatch(before, after);
+// 4 ops: replace /1/id, replace /2/id, remove /2/n, add /3
+
+createJSONPatch(before, after, { arrayDiff: 'minimal' });
+// 2 ops: add /1 {id:9}, replace /3/n 1
+```
+
+The alignment minimizes the patch itself (edit distance with substitutions — *not* a longest common subsequence, which maximizes kept elements and so pays a delete plus an insert on a permutation where one rewrite would do), and therefore never takes more steps than the default. It stays opt-in because it is O(m·n) in the length of the changed middle; past a fixed budget a single array falls back to the linear diff, so the option can never make a large diff quadratic. Both modes reproduce `target` exactly.
+
+A third option makes the engine a **change feed**: `changes: true` specializes the applier to return `{ doc, changes }`, where `changes` holds one JSON Pointer per successful write, in application order. The reported pointers are *invalidation-sound* — object writes, array replaces and appends report the written location itself; shifting array inserts and removes report the parent array; a root write reports `''` — which is exactly the primitive dirty-path consumers (view re-rendering in `@jarenjs/app`, rule dependency memoization in `@jarenjs/forms`) need. `test` operations report nothing, and the option costs nothing when off: the tracking branch is compiled out of the applier.
+
+[RFC 7396](https://datatracker.ietf.org/doc/html/rfc7396) merge patches ride the same machinery: `compileMergePatch(patch)` pre-splits the patch into remove/set/merge plans, and applying is identity-preserving — a merge that changes nothing returns the target by reference, so it doubles as a cheap change detector. `createMergePatch(source, target)` emits the merge patch (with the RFC's documented `null`-member representability caveat), and `applyMergePatch(doc, patch)` is the one-shot form.
+
+### Write operations
+
+When a whole patch document is more ceremony than the job needs, the standalone write operations expose the same copy-on-write core directly — `set`, `insert` and `remove`, compiled once per target:
+
+```javascript
+import {
+  compileJSONPointerSetter, removeAtJSONPointer,
+  compileJSONPathSetter, removeAtJSONPath,
+} from '@jarenjs/json';
+
+// a target is an RFC 6901 pointer, a normalized path, or ANY singular
+// query — '/store/book/0/title', "$['store']['book'][0]['title']" and
+// '$.store.book[-1].title' (negative = from the end) all compile
+const setZip = compileJSONPointerSetter('/address/zip');
+const next = setZip(doc, '10999');   // doc untouched, spine cloned once
+
+setZip(doc, (old) => old ?? '10115'); // setters take updater functions
+
+// ...or write at EVERY node a JSONPath query selects
+const addVat = compileJSONPathSetter('$..price');
+addVat(doc, (price) => price * 1.21);
+removeAtJSONPath(doc, '$.store.book[?@.price > 20]');
+```
+
+Set replaces (creating a missing final member; `/arr/-` appends), insert has RFC 6902 `add` semantics (array elements shift right), remove deletes with shift. The query-selected writers apply matched locations in **reverse document order**, so multiple removals or inserts in one array — and nested matches — compose without index bookkeeping, and matching nothing is a no-op that returns the input. Everything is copy-on-write with an in-place `{ mutate: true }` escape hatch; failures (`JsonWriteError`, `JW0001`/`JW2xxx` with the target as `dataPath`) leave the input untouched.
+
+The addressing bridge rounds this out: `jsonPointerFromJSONPath(singularQuery)` and `jsonPathFromJSONPointer(pointer)` convert between the two location languages (digit tokens become index selectors — RFC 6901's one-token-two-forms ambiguity, resolved by convention), so pointers, normalized paths and query results compose freely.
+
 ## The JSONPath compiler
 
 JSONPath selects *many* locations: a query like `$.store.book[?@.price < 10].title` describes a whole nodelist. The `path.js` module implements the complete RFC 9535 specification as a two-stage compiler, mirroring the philosophy of the schema validator: **parse and decide everything once, then run a specialized function**.
@@ -81,6 +198,7 @@ query(other);  // compiled once, reusable on any document
 | `query(data)` / `query.values(data)` | array of matched values, in document order |
 | `query.first(data)` | the first matched value, or `undefined` |
 | `query.exists(data)` | `true` when at least one node matches |
+| `query.iterate(data)` | a generator yielding matched values on demand, in document order |
 | `query.nodes(data)` | array of `{ path, value }` pairs with normalized paths |
 | `query.paths(data)` | array of normalized paths (RFC 9535 §2.7), e.g. `$['store']['book'][0]['title']` |
 | `query.source` | the original query string |
@@ -88,6 +206,29 @@ query(other);  // compiled once, reusable on any document
 
 For one-off queries there is `queryJSONPath(source, data)`, which keeps a cache of compiled queries (512 entries, FIFO), and `isValidJSONPathStrict(source)` for a boolean grammar check — this is what the `json-path` format in [`@jarenjs/formats`](../formats) uses.
 
+`first`, `exists` and `iterate` are one lazy walk: they stop at the first node they need instead of building the whole nodelist, so `q.first(doc)` on `$.items[?@.price < 10].name` over 10 000 items costs about 2 µs where `q.values(doc)` costs about 240 µs. Nothing is buffered along the way — a filter evaluates its predicate only until one passes, and a descendant segment abandons the walk mid-subtree.
+
+#### Custom function extensions
+
+`compileJSONPath(source, { pathFunctions })` registers function extensions ([RFC 9535 §2.4](https://www.rfc-editor.org/rfc/rfc9535.html#name-function-extensions)) alongside the five built-ins. An entry declares its parameter and result types, which is what lets the parser type-check call sites the same way it checks `length()` or `match()`:
+
+```js
+const pathFunctions = {
+  is_even: {
+    params: ['value'],      // 'value' | 'nodes' | 'logical'
+    returns: 'logical',
+    evaluate: (v) => typeof v === 'number' && v % 2 === 0,
+  },
+};
+
+const q = compileJSONPath('$.items[?is_even(@.n)].n', { pathFunctions });
+q({ items: [{ n: 1 }, { n: 2 }, { n: 3 }, { n: 4 }] }); // [2, 4]
+```
+
+A `value` parameter arrives as a JSON value or `JSONPATH_NOTHING`, a `nodes` parameter as an array of the selected values, a `logical` parameter as a boolean — and a `logical` parameter accepts the full filter grammar at the call site, so `both(@.a > 1, !@.b)` parses. A name that would redefine a built-in is rejected (§2.4.1), and a malformed registry raises a `TypeError`.
+
+The same option reaches everywhere a path string is embedded: the JSONPath-addressed writers, `compileJsonQuery`, and JSLT match paths and rule bodies. The `json-path` and `json-path-segments` string formats deliberately do **not** see it — a format is a property of the string, so it has to mean the same thing in every schema regardless of which extensions a host installed.
+
 ### Supported syntax
 
 Everything in RFC 9535, with no extensions and no omissions:
@@ -211,17 +352,72 @@ One phrase carries the whole pipeline. Clauses apply in **fixed semantic order r
 
 | Key | Value | Presence |
 |---|---|---|
-| `$for` | iteration bindings `{ name: source, ... }`, positional form `{ "$in": expr, "$at": "i" }` | at least one of `$for`/`$let` |
-| `$let` | sequence bindings (no iteration) | at least one of `$for`/`$let` |
+| `$fold` | one accumulator binding `{ name: initExpr }` | at least one of `$fold`/`$for`/`$let` |
+| `$for` | iteration bindings `{ name: source, ... }`, extended form `{ "$in": expr, "$at": "i" }` | at least one of `$fold`/`$for`/`$let` |
+| `$let` | sequence bindings (no iteration) | at least one of `$fold`/`$for`/`$let` |
+| `$as` | schema assertions on this phrase's bindings | optional |
 | `$where` | tuple filter (effective boolean value) | optional |
 | `$groupby` | grouping-key bindings | optional |
 | `$orderby` | key spec or list: `{ "$key": e, "$dir": "desc", "$empty": "greatest" }` | optional |
 | `$count` | variable name for the 0-based tuple index | optional |
 | `$return` | the result expression per surviving tuple | required |
 
-Semantic order: `$for → $let → $where → $groupby → $orderby → $count → $return`. Quantifiers are their own two-key phrases: `{"$some": bindings, "$satisfies": expr}` / `{"$every": ...}`, with short-circuit evaluation.
+Semantic order: `$fold → $for → $let → $as → $where → $groupby → $orderby → $count → $return`. Quantifiers are their own two-key phrases: `{"$some": bindings, "$satisfies": expr}` / `{"$every": ...}`, with short-circuit evaluation.
+
+**`$fold` turns the phrase into a reduction.** The accumulator's initial value is evaluated once, `$return` names its next value per surviving tuple, and the phrase evaluates to the final accumulator instead of the collected sequence. This is how the language gets a general fold without the JSON encoding needing to spell a *function value* — the accumulator is a binding, not a lambda parameter. It composes with the rest, so `$orderby` folds over sorted tuples and `$groupby` updates once per group:
+
+```js
+queryJson({
+  $fold: { total: 0 },
+  $for: { b: '$.store.book[*]' },
+  $where: { $lt: ['$b.price', 10] },
+  $return: { $add: ['$total', '$b.price'] },
+}, bookstore); // 17.939999999999998 — every number is an IEEE double (D1)
+```
+
+Because `$get` is a real dynamic lookup, a fold over a runtime path is a pointer walk: `{"$fold": {"cur": "$.doc"}, "$for": {"seg": "$.path[*]"}, "$return": {"$get": ["$cur", "$seg"]}}`.
 
-The operator library (58 operators: comparisons, IEEE-double arithmetic, logic, strings with I-Regexp `$match`/`$search`/`$replace`, aggregates, sequence tools like `$distinct`/`$subsequence`/`$range`, type predicates and casts, `$coalesce`) is cataloged in [QUERY-FORMAT.md §8](./docs/QUERY-FORMAT.md#8-operators).
+**Extended `$for` bindings** cover the two remaining XQuery iteration shapes. `{"$in": e, "$allowing-empty": true}` is outer-join iteration: when the source yields no tuple, one tuple is emitted with the variable bound to the empty sequence (position `-1` if `$at` is present), so the enclosing row survives. `{"$in": e, "$window": "tumbling"|"sliding", "$size": n, "$step": m}` iterates runs instead of items — a tumbling window *partitions* the stream, so its short final window is kept; a sliding window is a fixed-width moving view, so only full windows are emitted.
+
+```js
+queryJson({
+  $for: { w: { $in: '$[*]', $window: 'sliding', $size: 3 } },
+  $return: { $avg: '$w' },
+}, [1, 2, 3, 4, 5]); // [2, 3, 4] — a 3-point moving average
+```
+
+The operator library (93 operators: comparisons, IEEE-double arithmetic, logic, strings with I-Regexp `$match`/`$search`/`$replace`, aggregates, sequence tools like `$distinct`/`$subsequence`/`$range`, type predicates and casts, `$coalesce`, the RFC 3339 date family, and the spatial family) is cataloged in [QUERY-FORMAT.md §8](./docs/QUERY-FORMAT.md#8-operators).
+
+**Extending the vocabulary (host opt-in).** The 93 are closed, but a host can add more the way `@jarenjs/validate` gains formats from `@jarenjs/formats`: `createJsltRegistry().use(mathPack).use(financePack)` composes packs of pure `@jarenjs/core` functions into a compiler, so `{ "$sqrt": "$.variance" }` and `{ "$npv": ["$.rate", "$.cashflows[*]"] }` work in a stylesheet, a bare query, and `@jarenjs/linq` — while a document compiled *without* the registry still rejects them. Aggregators fold a `seq` operand to an array before the pure call. See [JSLT-FORMAT.md §13](./docs/JSLT-FORMAT.md#13-registered-operators-host-opt-in-non-normative).
+
+**Dates are RFC 3339 strings** ([§8.13](./docs/QUERY-FORMAT.md#813-dates-and-times)): `$is-date`/`$is-time`/`$is-datetime`/`$is-duration` test the lexical forms, `$year`…`$seconds` and `$offset` read components *lexically, in the value's own offset* (so "group by month" means what you expect), `$week`/`$week-year`/`$quarter`/`$weekday` add the derived calendar fields, and `$epoch`/`$datetime` convert to and from epoch milliseconds — the one place a value is shifted to UTC, and therefore the way to compare instants across offsets. There is deliberately no `current-dateTime`: a compiled query is cached by document identity and saved as a rule, so it must answer the same for the same input forever.
+
+Dates also *move*. `$date-add`/`$date-sub` shift by an ISO 8601 duration or by an amount and a unit, `$start-of`/`$end-of` truncate to a calendar unit, `$date-diff` counts whole units, and `$date-format` renders through a Unicode LDML pattern compiled once with the query. Two rules keep it predictable: the **lexical form is preserved** (a date stays a date, and a date-time keeps its own offset instead of being normalized to UTC), and **month arithmetic clamps**, so 31 January plus a month is 28 February — with `$date-diff` counting to match, so adding its answer back never overshoots.
+
+```js
+queryJson({
+  $for: { e: '$[*]' },
+  $groupby: { w: { '$start-of': ['$e.on', 'week'] } },
+  $orderby: ['$w'],
+  $return: { week: '$w', count: { $count: '$e' } },
+}, [{ on: '2026-01-05' }, { on: '2026-01-08' }, { on: '2026-01-20' }]);
+// [{ week: '2026-01-05', count: 2 }, { week: '2026-01-19', count: 1 }]
+```
+
+Bucketing by week is the shape components alone cannot express, because a week boundary is arithmetic rather than a field. Patterns stay locale-independent — `MMMM` and `EEEE` are rejected rather than silently rendered in English — because localized text belongs to the presentation layer, not to a query.
+
+**Geography is GeoJSON** ([§8.14](./docs/QUERY-FORMAT.md#814-spatial)), for the same reason dates are RFC 3339 strings: it is what the document already holds. Operands are a bare `[longitude, latitude]` position, a geometry, a `Feature` or a `FeatureCollection`, and wrappers unwrap for you. `$distance`, `$area` and `$length` answer in metres on the WGS 84 sphere — never planar, because a Euclidean answer over raw degrees is wrong by two thirds over a kilometre at Dutch latitudes. `$within` tests containment, `$bbox`/`$centroid` measure, and `$bbox-intersects` is named for exactly what it tests, since an `$intersects` that compared only boxes would be a lie the first time two L-shapes shared one.
+
+```js
+queryJson({
+  $for: { c: '$.cities[*]' },
+  $where: { $within: ['$c.at', '$.region'] },
+  $orderby: [{ $key: { $distance: ['$c.at', '$.centre'] } }],
+  $return: '$c.name',
+}, data); // a spatial filter and a spatial sort, in the language's own clauses
+```
+
+A geohash needs no operator of its own to be useful: it is a string, so proximity is `$starts-with` on a prefix and spatial bucketing is `$groupby` over `$substring`. `$geohash` only produces it.
 
 ### External parameters
 
@@ -259,6 +455,28 @@ The complete structural grammar of the language is published as JSON Schema, twi
 
 Both exist because the schema is authored in a draft-neutral keyword subset (no `$ref` siblings, no `unevaluated*`, no tuples), so ecosystems pinned to draft-07 — several structured-output stacks among them — get an identical grammar for one `$defs`→`definitions` rename. Every fixture in the test suite validates under both drafts.
 
+### GeoJSON, fully validated
+
+The same machinery answers a problem the geospatial ecosystem has lived with for years. The [official GeoJSON JSON Schema](https://github.com/geojson/schema) states that it **cannot** express that a linear ring is closed, or that rings follow RFC 7946's right-hand rule — neither is a structural property — so every validator bolts on custom code, and unclosed rings and reversed winding (which makes a renderer fill the entire globe) remain among the commonest defects in real data.
+
+Three artifacts ship here:
+
+- [`schemas/geojson.schema.json`](./schemas/geojson.schema.json) — **portable**: plain draft-neutral JSON Schema, no Jaren extension, usable by any validator;
+- [`schemas/geojson.draft-07.schema.json`](./schemas/geojson.draft-07.schema.json) — its mechanically derived draft-07 twin;
+- [`schemas/geojson.jaren.schema.json`](./schemas/geojson.jaren.schema.json) — the same grammar plus the two missing invariants, expressed with [`$query`](../validate).
+
+The Jaren artifact is a mechanical *restriction* of the portable one — structurally identical, with a `$query` on the `polygon` and `multiPolygon` definitions — so the two cannot drift, and a consumer without `$query` support still gets the standard grammar. Ring closure is `$eq` of the first and last position; winding is the sign of the shoelace sum, computed with `$fold`:
+
+```javascript
+import { JarenValidator } from '@jarenjs/validate';
+
+const unclosed = { type: 'Polygon', coordinates: [[[0, 0], [1, 0], [1, 1], [0, 1]]] };
+new JarenValidator().compile(portableSchema)(unclosed);  // true  — structurally fine
+new JarenValidator().compile(jarenSchema)(unclosed);     // false — the ring never closes
+```
+
+The test suite pins six defect classes that slip past structural validation and are caught here, including one buried inside a `FeatureCollection`.
+
 ## Generating queries with LLMs
 
 A query language whose entire grammar is one JSON Schema is a natural fit for **constrained decoding** — the structured-output mode of every major LLM API. Hand the schema to the provider and the model cannot emit an unknown operator, a three-argument `$eq`, or a mixed `$`/plain-key object; what remains is validated and compiled in two lines, and every failure carries a `docPath` you can feed back to the model for repair:
@@ -279,7 +497,11 @@ const query = compileJsonQuery(doc);         // JsonQueryCompileError.docPath on
 query(data);                                 // JsonQueryRuntimeError.docPath at runtime
 ```
 
-The validate step is not redundant: provider structured-output implementations support varying JSON Schema subsets regardless of the draft they declare (`patternProperties` and `propertyNames`, which the schema uses for binding names and map constructors, are not universally enforced). Validating locally catches whatever the provider's subset let through. A simplified "LLM profile" of the schema — trading some precision for the lowest-common-denominator subset — is a possible follow-up; it does not exist today.
+The validate step is not redundant: provider structured-output implementations support varying JSON Schema subsets regardless of the draft they declare (`patternProperties` and `propertyNames`, which the schema uses for binding names and map constructors, are not universally enforced, and strict modes often reject `oneOf`). Validating locally catches whatever the provider's subset let through.
+
+For those strict subsets each grammar also ships an **LLM profile** — [`jaren-query.llm-profile.schema.json`](./schemas/jaren-query.llm-profile.schema.json) and [`jaren-jslt.llm-profile.schema.json`](./schemas/jaren-jslt.llm-profile.schema.json) — a mechanically derived, pure *relaxation* of the canonical artifact: `patternProperties`, `propertyNames` and asserted `format`s are removed (each restated in the nearest `description`, which the model still reads) and every `oneOf` becomes `anyOf`. That last swap costs no precision: the canonical grammar discriminates its branches by member name — a map constructor has no `$`-prefixed key, every phrase pins its own (`$const`, `$map`, `$call`, `$return`, …) or draws its single key from a disjoint operator enum — so at most one branch can ever match a document, and exactly-one and at-least-one accept the same language. It is also *required* once the name constraints are gone: `oneOf` would then reject `{"$eq": [1, 2]}` for matching two now-overlapping branches. Every canonical-valid document validates under the profile; the reverse is deliberately not guaranteed, which is exactly why the local validate-then-compile step above stays mandatory. Hand the profile to the provider's constrained decoder, validate locally against the canonical schema. (`@jarenjs/ai`'s `createStructuredOutput` packages this handshake.)
+
+A relaxation, though, is not a *shrink*: restating every removed constraint in a `description` means the JSLT profile is 19,158 characters against the canonical 18,736, and on a small model an oversized `response_format` is the difference between a document and an empty reply. So the JSLT grammar also ships an **authoring profile** — [`jaren-jslt.authoring.schema.json`](./schemas/jaren-jslt.authoring.schema.json), **3,491 characters** — the same mechanical derivation with one more step: the `queryDocument` `$ref` that pulls the entire expression language into the document grammar is left *open*. What survives is the document shape (envelope, rules, match specs, modes); what leaves is the ~16 kB of phrase shapes. It is a pure widening of the canonical language, so nothing the engine can run becomes inexpressible, and it is deliberately weaker — a body of pure nonsense decodes under it. That is the trade, and it is only safe because the two authorities after the decoder are unchanged: validate against the canonical schema, then compile. The vocabulary the cut removes belongs in the prompt instead, where `@jarenjs/ai`'s `operatorCrib` puts it (operator names grouped by arity, ~1.1 kB, read off the query artifact). `@jarenjs/ai`'s [`createStylesheetAuthor`](../ai/README.md#when-the-grammar-is-too-big-to-decode-measured) packages the whole handshake.
 
 Query documents are plain JSON, so they travel through the rest of an LLM toolchain as-is: function-call arguments, retrieval filters, audit logs, replay.
 
@@ -298,30 +520,31 @@ q(null, { doc: data }); // [ 'Sayings of the Century', 'Moby Dick' ]
 
 `npm run benchmark:jsonquery` runs the scenario matrix against [fontoxpath](https://www.npmjs.com/package/fontoxpath) (a real XQuery 3.1 engine in JavaScript — the closest honest comparison) and [jsonata](https://www.npmjs.com/package/jsonata) (the popular practical alternative), asserting result equivalence on every document before timing anything. Each engine runs the same scenario written idiomatically in its own language (`benchmark/adaptors/jsonquery/`).
 
-Measured with `npm run benchmark:jsonquery:profile` (2026-07-17, Node v24.14.0; ratios are that engine's time over Jaren's):
+Measured with `npm run benchmark:jsonquery:profile` (2026-07-27, Node v22.22.2; ratios are that engine's time over Jaren's):
 
 | Scenario | Jaren | fontoxpath 3.34 | jsonata 2.2 |
 |---|---|---|---|
 | **4-book bookstore** | | | |
-| singular access `$b.title` | 382 ns (2.6M/s) | 7.3 µs (19x) | 5.7 µs (15x) |
-| filter + project (spec A.2) | 1.9 µs (527k/s) | 36.1 µs (19x) | 27.0 µs (14x) |
-| join (spec A.3) | 5.6 µs (178k/s) | 77.5 µs (14x) | 111.7 µs (20x) |
-| group + aggregate (spec A.4) | 4.3 µs (234k/s) | n/a | 47.7 µs (11x) |
-| deep reshape | 2.6 µs (393k/s) | 190.5 µs (75x) | 82.9 µs (33x) |
+| singular access `$b.title` | 451 ns (2.2M/s) | 12.0 µs (27x) | 7.3 µs (16x) |
+| filter + project (spec A.2) | 3.6 µs (281k/s) | 60.6 µs (17x) | 26.2 µs (7.4x) |
+| join (spec A.3) | 3.4 µs (291k/s) | 102.0 µs (30x) | 96.6 µs (28x) |
+| group + aggregate (spec A.4) | 4.4 µs (229k/s) | n/a | 52.6 µs (12x) |
+| deep reshape | 2.4 µs (426k/s) | 173.1 µs (74x) | 55.8 µs (24x) |
 | **10,000-book bookstore** | | | |
-| singular access | 299 ns (3.3M/s) | 16.6 µs (56x) | 4.2 µs (14x) |
-| filter + project | 1.5 ms | 328.3 ms (215x) | 68.0 ms (45x) |
-| join (measured at 1,000 books) | 27.8 ms | 1.57 s (57x) | 1.75 s (63x) |
-| group + aggregate | 2.5 ms | n/a | 39.9 ms (16x) |
-| deep reshape | 3.6 ms | 422.0 ms (118x) | 119.0 ms (33x) |
-| **compile, µs per query** | 24.3 µs | 460.7 µs (19x) | 66.1 µs (2.7x) |
+| singular access | 324 ns (3.1M/s) | 9.0 µs (28x) | 4.6 µs (14x) |
+| filter + project | 1.33 ms | 343.2 ms (259x) | 70.4 ms (53x) |
+| join (measured at 1,000 books) | 331 µs | 1.64 s (4952x) | 1.71 s (5175x) |
+| group + aggregate | 2.47 ms | n/a | 37.9 ms (15x) |
+| deep reshape | 3.51 ms | 452.0 ms (129x) | 117.0 ms (33x) |
+| **compile, µs per query** | 37.4 µs | 562.5 µs (15x) | 118.3 µs (3.2x) |
 
 Honest caveats — what each competitor is optimized for:
 
 - **fontoxpath** is an XML-first XPath/XQuery engine; JSON rides on XDM maps and arrays. The benchmark pre-converts each document to XDM *once, outside the timed loop* (per-call conversion would cost ~12 ms alone at 10k books), and fontoxpath has no public compile-only API, so its compile number is fresh-source evaluation minus cached re-evaluation. It does not implement `group by`. Its engineering effort goes into DOM navigation, buckets and XQuery Update — not JSON throughput.
 - **jsonata** is a tree-walking interpreter whose `evaluate()` is async since 2.x; its numbers include that promise overhead because its API imposes it. It is optimized for expressiveness and embeddability, not raw speed.
 - **Jaren**'s compile number includes `JSON.parse` of the query text, since the competitors parse text too.
-- The join is a naive O(books × ratings) nested loop in **all three** engines (Jaren's hash-join optimizer is roadmap); it is measured at 1,000 books.
+- The join row is the one place these engines are not doing the same work, and the four-digit ratio says so rather than hiding it. fontoxpath and jsonata run it as a naive O(books × ratings) nested loop; Jaren's planner recognizes the uncorrelated equijoin and answers it from a hash table, which is O(books + ratings). At four books that is worth nothing (3.4 µs against 96–102 µs, the same 28–30x as every other small-document row); at 1,000 books it is the whole difference. Read the 4,952x as "different algorithm", not "faster engine" — and note the rewrite is declined whenever it would be observable (a `$as`, a `$let`, a correlated probe side), in which case Jaren runs the same nested loop they do. The row stays capped at 1,000 books because raising it would grow their cost quadratically and Jaren's linearly, measuring the cap instead of the engines.
+- The 4-book `singular` cell reads slower than the 1,000-book one (451 ns vs 335 ns) run to run. That is JIT/IC noise across the cell sequence, not a real cost curve; pinning it down is a `--cell-order` shuffle on the roadmap.
 
 ## JSLT — declarative JSON transformation
 
@@ -400,6 +623,8 @@ const annotateBooks = compileJsltStylesheet([
 ], { compileTypeTest: createTypeTestCompiler() });
 ```
 
+For render-loop consumers there is one more lever: `compileJsltStylesheet(doc, { memo: true })` memoizes rule outputs by (location, value reference). A compile-time analysis marks every rule whose output provably depends on nothing but the matched value (no `$root`/`$path`/user externals, transitively through `$apply`, and no root references inside match-path filters); those rules return their previous output **by reference** when the same subtree reference shows up at the same location. Across copy-on-write updates an unchanged document transforms in O(1) and a one-field change re-evaluates one spine — the fuel for the `@jarenjs/view` patcher's reference-equality fast path, which is why `@jarenjs/app` compiles every view with it. The cache is two-generational (entries unused for one transform retire), and memoized outputs must be treated as immutable.
+
 The complete stylesheet grammar is published for validators and LLM constrained decoding as [`jaren-jslt.schema.json`](./schemas/jaren-jslt.schema.json) (draft 2020-12) and its mechanically derived [`jaren-jslt.draft-07.schema.json`](./schemas/jaren-jslt.draft-07.schema.json) twin. Rule-body definitions are mechanically copied from the query artifact and extended only with `$apply`, so the query vocabulary stays closed. Provider structured-output implementations still support uneven schema subsets; validate the generated document locally before compiling it, as described in [JSLT-FORMAT Appendix B](./docs/JSLT-FORMAT.md#appendix-b-llm-structured-output-non-normative).
 
 ### JSLT benchmark
@@ -464,8 +689,8 @@ Unmatched nodes follow the XSLT built-in template rules, restated for JSON: cont
 
 ## Roadmap
 
-This package's roadmap lives in the repository-wide [ROADMAP](../../ROADMAP.md), under its `@jarenjs/json` sections: the query filter optimizer and hash joins, lazy sequences, the JSLT single-walk matcher, write operations and JSON Patch, custom JSONPath function extensions, canonical JSON, XQuery front-end `xs:*` casts, and more. Recently landed from that list: JSON Schema as the query type system (`$valid`/`$assert`/`$as`), the inverse [`$query` keyword](../validate/README.md) in the validator, compiled JSON Pointers, and the complete JSLT template layer.
+This package's roadmap lives in the repository-wide [ROADMAP](../../docs/ROADMAP.md), under its `@jarenjs/json` sections: hoisting `$`-absolute comparables out of filter loops, first-class function values, the JSLT single-walk matcher, XQuery front-end `xs:*` casts, and more. Recently landed from that list: hash-joined equijoins and counting-loop `$range` iteration, the `$fold` accumulator clause, `$allowing-empty` and window bindings, the RFC 3339 date operators, closed-world compilation and the `steps`/`depth` execution limits.
 
 ## Development
 
-Unit tests live in `test/json/` at the repository root (`npm run test:json`); the JSONPath tests are built from the RFC's own examples, the query and JSLT tests from their normative fixtures (each schema corpus validates against both artifact drafts), and every example in this README runs in `test/json/readme-examples.test.js`. This package's internals are described in its own [ARCHITECTURE](./ARCHITECTURE.md) document. Benchmarks (all documented in the [benchmark workspace README](../../benchmark/README.md)): `benchmark/jsonpath.js` (JSONPath compliance + performance), `benchmark/jsonpointer.js` (compiled pointers vs the interpretive resolver and the `jsonpointer` npm package), `benchmark/jsonquery.js` (query engine vs fontoxpath/jsonata), `benchmark/jslt.js` (stylesheet engine vs native JS/JSONata), `benchmark/qt3-runner.js` (W3C QT3 scorecard through the XQuery front-end). See the repository [README](../../README.md) and [ARCHITECTURE](../../ARCHITECTURE.md) for the monorepo picture.
+Unit tests live in `test/json/` at the repository root (`npm run test:json`); the JSONPath tests are built from the RFC's own examples, the query and JSLT tests from their normative fixtures (each schema corpus validates against both artifact drafts), and every example in this README runs in `test/json/readme-examples.test.js`. This package's internals are described in its own [ARCHITECTURE](./ARCHITECTURE.md) document. Benchmarks (all documented in the [benchmark workspace README](../../benchmark/README.md)): `benchmark/jsonpath.js` (JSONPath compliance + performance), `benchmark/jsonpointer.js` (compiled pointers vs the interpretive resolver and the `jsonpointer` npm package), `benchmark/jsonquery.js` (query engine vs fontoxpath/jsonata), `benchmark/jslt.js` (stylesheet engine vs native JS/JSONata), `benchmark/qt3-runner.js` (W3C QT3 scorecard through the XQuery front-end). See the repository [README](../../README.md) and [ARCHITECTURE](../../docs/ARCHITECTURE.md) for the monorepo picture.

package/dist/types/canonical.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Error thrown when a value cannot be canonicalized because it is not
+ * JSON data (RFC 8785 section 3.2.1). `dataPath` is an RFC 6901 JSON
+ * Pointer to the offending value, so a rejected document says which
+ * member was at fault rather than only that one was.
+ *
+ * Extends `TypeError`: passing a non-JSON value to a canonicalizer is a
+ * programming error, the same class `JSON.stringify` raises for a
+ * BigInt or a cycle.
+ */
+export declare class JsonCanonicalizeError extends TypeError {
+    dataPath: any;
+    constructor(message: any, dataPath: any);
+}
+/**
+ * Serialize a JSON value to its canonical form (RFC 8785 / JCS): object
+ * members sorted by the UTF-16 code units of their names, numbers in
+ * the ECMAScript `Number::toString` form, strings with the shortest
+ * JSON escapes and no escaping of non-ASCII, and no insignificant
+ * whitespace. Two structurally equal values always produce identical
+ * text, which is what makes the result safe to hash or sign.
+ *
+ * Unlike `JSON.stringify`, nothing is dropped or coerced: `undefined`,
+ * a function, a symbol, a BigInt, `NaN`, `Infinity`, an unpaired
+ * surrogate, a circular reference and a class instance are all errors,
+ * because a canonicalizer that quietly rewrote its input would produce
+ * a signature over a document nobody sent.
+ *
+ * @param {any} value - The JSON value to canonicalize
+ * @returns {string} The canonical JSON text
+ * @throws {JsonCanonicalizeError} When the value is not JSON data
+ * @example
+ * canonicalizeJson({ b: 1, a: [2, 3] }); // '{"a":[2,3],"b":1}'
+ * canonicalizeJson({ 'ä': 1, 'a': 2 }); // '{"a":2,"ä":1}'
+ * canonicalizeJson(1e21); // '1e+21'
+ */
+export declare function canonicalizeJson(value: any): string;

package/dist/types/cow.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The mutable state of one write application. `owned` is the set of
+ * nodes this application created and may mutate freely; `null` means
+ * in-place mode (every node is owned).
+ */
+export declare function makeState(root: any, owned: any): {
+    root: any;
+    owned: any;
+};
+/** Ensure the root is owned before the first write into it. */
+export declare function ownedRoot(state: any): any;
+/**
+ * Return an owned version of `child`, writing the clone back into the
+ * (already owned) parent slot when one is taken.
+ */
+export declare function ownedChild(state: any, parent: any, child: any, key: any): any;
+/**
+ * The concrete array index a step addresses in `parent`, or -1 when the
+ * step cannot address an array element. Typed index steps resolve
+ * negative indexes from the end; the RFC 6901 form never does.
+ */
+export declare function stepArrayIndex(parent: any, name: any, index: any): any;
+/**
+ * Read the location `steps[0..len)` in `root` without cloning anything.
+ * Returns the shared NOTHING-style `miss` sentinel value passed in when
+ * the location does not exist (callers pick their own sentinel).
+ */
+export declare function readSteps(root: any, names: any, indexes: any, len: any, miss: any): any;

package/dist/types/errors.d.ts

@@ -0,0 +1,45 @@
+import { CodedError } from '@jarenjs/core/errors';
+/**
+ * Base for errors that carry a stable `code` and a `docPath`, an RFC
+ * 6901 JSON Pointer into the offending document. A wrapped error is
+ * exposed through the native `cause` option when one is given. This is
+ * the positional adapter over `@jarenjs/core`'s {@link CodedError}: a
+ * trailing `undefined` cause means "no cause" (no own property), per
+ * the base's contract.
+ */
+export declare class CodedDocPathError extends CodedError {
+    /**
+     * @param {string} name - The public class name for `error.name`
+     * @param {string} code - Stable diagnosis code
+     * @param {string} reason - What is wrong (bare; the message is composed)
+     * @param {string} docPath - JSON Pointer into the offending document
+     * @param {unknown} [cause] - Wrapped error, when there is one
+     */
+    constructor(name: string, code: string, reason: string, docPath: string, cause?: unknown);
+}
+/**
+ * Base for syntax errors over a source string: `source` and `position`
+ * locate the offending token, and the message is prefixed with a
+ * human-readable language label. Deliberately NOT a {@link CodedError}:
+ * this family carries no stable code and locates by source offset, not
+ * by document pointer.
+ */
+export declare class LabeledSyntaxError extends SyntaxError {
+    source: string;
+    position: number;
+    /**
+     * @param {string} name - The public class name for `error.name`
+     * @param {string} label - Language label for the message prefix
+     * @param {string} message - What is wrong
+     * @param {string} source - The offending source text
+     * @param {number} position - 0-based index of the offending token
+     */
+    constructor(name: string, label: string, message: string, source: string, position: number);
+}
+/**
+ * Build a `fail(code, message, docPath)` throw-adapter for a coded
+ * error class; compilers use it to keep rejection one-liners readable.
+ * @param {new (code: string, message: string, docPath: string) => Error} ErrorClass
+ * @returns {(code: string, message: string, docPath: string) => never}
+ */
+export declare function failerFor(ErrorClass: new (code: string, message: string, docPath: string) => Error): (code: string, message: string, docPath: string) => never;

package/dist/types/index.d.ts

@@ -1,4 +1,7 @@
 export * from './basic.js';
+export * from './canonical.js';
 export * from './pointer.js';
+export * from './patch.js';
 export * from './path.js';
+export * from './write.js';
 export * from './query/index.js';

package/dist/types/jslt/errors.d.ts

@@ -1,18 +1,25 @@
+import { CodedError } from '@jarenjs/core/errors';
+import { CodedDocPathError } from '../errors.js';
 /**
  * Error thrown when a JSLT stylesheet is rejected at compile time
  * (`JT0xxx` codes).
  */
-export declare class JsltCompileError extends Error {
-    code: any;
-    docPath: any;
-    constructor(code: any, message: any, docPath: any, cause?: undefined);
+export declare class JsltCompileError extends CodedError {
+    /**
+     * @param {string} code
+     * @param {string} reason
+     * @param {string} docPath
+     * @param {...unknown} cause - When a fourth argument is passed AT
+     *   ALL, it is retained as an own `cause` — even `undefined`, so a
+     *   host hook that threw `undefined` stays distinguishable from "no
+     *   cause".
+     */
+    constructor(code: string, reason: string, docPath: string, ...cause: unknown[]);
 }
 /**
  * Error thrown when evaluating a compiled JSLT stylesheet fails
  * (`JT2xxx` codes).
  */
-export declare class JsltRuntimeError extends Error {
-    code: any;
-    docPath: any;
-    constructor(code: any, message: any, docPath: any, cause?: undefined);
+export declare class JsltRuntimeError extends CodedDocPathError {
+    constructor(code: any, reason: any, docPath: any, cause?: undefined);
 }

package/dist/types/jslt/index.d.ts

@@ -1,4 +1,6 @@
 export { JsltCompileError, JsltRuntimeError } from './errors.js';
+export { createJsltRegistry } from './registry.js';
+export { mathPack, financePack, statsPack, allPacks } from './packs/index.js';
 /**
  * Compile a Jaren JSLT 0.1 stylesheet into a reusable transformation.
  *
@@ -17,6 +19,20 @@ export { JsltCompileError, JsltRuntimeError } from './errors.js';
  *   [options.compileTypeTest] - validator-agnostic hook compiling schema
  *   match conditions and schema literals inside query bodies
  * @param {number} [options.maxDepth=1024] - maximum dispatch nesting depth
+ * @param {boolean} [options.memo=false] - memoize rule outputs by
+ *   (location, value reference): across repeated transforms of
+ *   copy-on-write-updated documents, unchanged subtrees return the
+ *   PREVIOUS output by reference — the fuel for reference-equality
+ *   fast paths downstream (the @jarenjs/view patcher). Only rules whose
+ *   output provably depends on nothing but the matched value are cached
+ *   (no $root/$path/user externals, transitively through $apply, and no
+ *   root references inside match-path filters); everything else runs
+ *   normally. Memoized outputs MUST be treated as immutable, and the
+ *   cache retains the previous transform's outputs (two generations).
+ * @param {Record<string, import('../path.js').JSONPathFunction>}
+ *   [options.pathFunctions] - custom JSONPath function extensions (RFC
+ *   9535 section 2.4), available in rule match paths and in the path
+ *   strings inside rule bodies
  * @returns {function} reusable `transform(data, externals?)` function
  * @throws {import('./errors.js').JsltCompileError} when compilation fails
  * @example
@@ -29,6 +45,7 @@ export { JsltCompileError, JsltRuntimeError } from './errors.js';
 export declare function compileJsltStylesheet(doc: any, options?: {
     compileTypeTest?: (schemaJson: any, docPath: string) => ((value: any) => boolean);
     maxDepth?: number;
+    memo?: boolean;
 }): Function;
 /**
  * Transform a JSON value with a JSLT stylesheet in one call.
@@ -41,6 +58,9 @@ export declare function compileJsltStylesheet(doc: any, options?: {
  * @param {(schemaJson: any, docPath: string) => ((value: any) => boolean)}
  *   [options.compileTypeTest] - schema type-test compiler
  * @param {number} [options.maxDepth=1024] - maximum dispatch nesting depth
+ * @param {boolean} [options.memo=false] - memoize rule outputs
+ * @param {Record<string, import('../path.js').JSONPathFunction>}
+ *   [options.pathFunctions] - custom JSONPath function extensions
  * @returns {any} `undefined`, one JSON item, or an array of result items
  * @throws {import('./errors.js').JsltCompileError} when compilation fails
  * @throws {import('./errors.js').JsltRuntimeError} when dispatch fails
@@ -50,4 +70,6 @@ export declare function compileJsltStylesheet(doc: any, options?: {
 export declare function transformJson(stylesheet: any, data: any, externals?: object, options?: {
     compileTypeTest?: (schemaJson: any, docPath: string) => ((value: any) => boolean);
     maxDepth?: number;
+    memo?: boolean;
+    pathFunctions?: Record<string, import('../path.js').JSONPathFunction>;
 }): any;