@jarenjs/json 0.9.2 → 0.34.2

package/dist/types/write.d.ts

@@ -0,0 +1,204 @@
+import { CodedError } from '@jarenjs/core/errors';
+/**
+ * Error thrown when a write target is malformed (`JW0001`) or a write
+ * fails to apply (`JW2xxx`). `dataPath` is the write target as given
+ * (a JSON Pointer or JSONPath), or the normalized path of the failing
+ * location for query-selected writes — rendered `in data <path>` per
+ * the `@jarenjs/core` coded contract, because it locates *data*, not a
+ * document.
+ */
+export declare class JsonWriteError extends CodedError {
+    constructor(code: any, reason: any, dataPath: any);
+}
+export type JsonWriteOptions = {
+    /**
+     * - Apply in place instead of copy-on-write.
+     */
+    mutate?: boolean;
+    /**
+     * - What a missing spine means
+     * for setters and inserters: `'reject'` (default) raises `JW2001`;
+     * `'create'` grows fresh containers along the way — an array when the
+     * following step is index-shaped (`-`, a typed index, or a numeric
+     * token), an object otherwise — and REPLACES a scalar or `null` found
+     * on the spine. The schema-less form-data discipline (@jarenjs/forms
+     * `setValueAtPointer` is this option plus undefined-deletes).
+     */
+    parents?: 'reject' | 'create';
+    /**
+     * Custom JSONPath function extensions, for the JSONPath-addressed
+     * writers only. A pointer-addressed target is a singular query, which
+     * has no filters and so no function calls.
+     */
+    pathFunctions?: Record<string, import('./path.js').JSONPathFunction>;
+};
+export type JsonWriter = (root: any, value: any) => any;
+export type JsonRemover = (root: any) => any;
+/**
+ * Options for the compiled write operations.
+ * @typedef {Object} JsonWriteOptions
+ * @property {boolean} [mutate] - Apply in place instead of copy-on-write.
+ * @property {'reject'|'create'} [parents] - What a missing spine means
+ *   for setters and inserters: `'reject'` (default) raises `JW2001`;
+ *   `'create'` grows fresh containers along the way — an array when the
+ *   following step is index-shaped (`-`, a typed index, or a numeric
+ *   token), an object otherwise — and REPLACES a scalar or `null` found
+ *   on the spine. The schema-less form-data discipline (@jarenjs/forms
+ *   `setValueAtPointer` is this option plus undefined-deletes).
+ * @property {Record<string, import('./path.js').JSONPathFunction>} [pathFunctions]
+ *   Custom JSONPath function extensions, for the JSONPath-addressed
+ *   writers only. A pointer-addressed target is a singular query, which
+ *   has no filters and so no function calls.
+ */
+/**
+ * A compiled setter/inserter: applies the write and returns the new
+ * document. `value` may be an updater function `(oldValue, location) =>
+ * next` for setters.
+ * @typedef {(root: any, value: any) => any} JsonWriter
+ */
+/**
+ * A compiled remover: removes the location and returns the new document.
+ * @typedef {(root: any) => any} JsonRemover
+ */
+/**
+ * Compile a `set` at a JSON Pointer, a normalized path, or any singular
+ * JSONPath query. Set replaces the addressed element or member, creates
+ * the member when absent (parents must exist), and extends an array by
+ * one at index == length (`/arr/-` appends). `value` may be an updater
+ * function `(oldValue, location) => next`.
+ *
+ * Application is copy-on-write: the input is never mutated and
+ * untouched subtrees are shared with the result.
+ *
+ * @param {string} target - The write target (e.g. `/user/name`, `$['user']['name']`)
+ * @param {JsonWriteOptions} [options] - Write options
+ * @returns {JsonWriter} `(root, value) => newRoot`
+ * @throws {JsonWriteError} `JW0001` when the target is not a pointer or
+ *   singular query
+ * @example
+ * const setZip = compileJSONPointerSetter('/address/zip');
+ * setZip(doc, '10999'); // doc untouched, spine cloned once
+ */
+export declare function compileJSONPointerSetter(target: string, options?: JsonWriteOptions): JsonWriter;
+/**
+ * Compile an `insert` at a JSON Pointer, a normalized path, or any
+ * singular JSONPath query - RFC 6902 `add` semantics: array elements
+ * shift right (`/arr/-` appends), object members are set-or-created.
+ *
+ * @param {string} target - The write target
+ * @param {JsonWriteOptions} [options] - Write options
+ * @returns {JsonWriter} `(root, value) => newRoot`
+ * @throws {JsonWriteError} `JW0001` when the target is not a pointer or
+ *   singular query
+ */
+export declare function compileJSONPointerInserter(target: string, options?: JsonWriteOptions): JsonWriter;
+/**
+ * Compile a `remove` at a JSON Pointer, a normalized path, or any
+ * singular JSONPath query. The location must exist (`JW2001`); array
+ * elements shift left.
+ *
+ * @param {string} target - The write target
+ * @param {JsonWriteOptions} [options] - Write options
+ * @returns {JsonRemover} `(root) => newRoot`
+ * @throws {JsonWriteError} `JW0001` when the target is not a pointer or
+ *   singular query
+ */
+export declare function compileJSONPointerRemover(target: string, options?: JsonWriteOptions): JsonRemover;
+/**
+ * One-shot `set` at a pointer / normalized path / singular query. On hot
+ * paths prefer `compileJSONPointerSetter` and reuse the writer.
+ * @param {any} root - The document (never mutated unless `options.mutate`)
+ * @param {string} target - The write target
+ * @param {any} value - The value, or an updater `(oldValue, location) => next`
+ * @param {JsonWriteOptions} [options] - Write options
+ * @returns {any} The new document
+ */
+export declare function setAtJSONPointer(root: any, target: string, value: any, options?: JsonWriteOptions): any;
+/**
+ * One-shot `insert` at a pointer / normalized path / singular query.
+ * @param {any} root - The document (never mutated unless `options.mutate`)
+ * @param {string} target - The write target
+ * @param {any} value - The value to insert
+ * @param {JsonWriteOptions} [options] - Write options
+ * @returns {any} The new document
+ */
+export declare function insertAtJSONPointer(root: any, target: string, value: any, options?: JsonWriteOptions): any;
+/**
+ * One-shot `remove` at a pointer / normalized path / singular query.
+ * @param {any} root - The document (never mutated unless `options.mutate`)
+ * @param {string} target - The write target
+ * @param {JsonWriteOptions} [options] - Write options
+ * @returns {any} The new document
+ */
+export declare function removeAtJSONPointer(root: any, target: string, options?: JsonWriteOptions): any;
+/**
+ * Compile a `set` at every node a JSONPath query selects. Applying runs
+ * the query against the document and replaces each matched node; `value`
+ * may be an updater function `(oldValue, normalizedPath) => next`.
+ * Matching nothing is a no-op. Locations are rewritten in reverse
+ * document order, so when matches nest, the ancestor's rewrite wins.
+ *
+ * @param {string} path - The JSONPath query (e.g. `$..price`)
+ * @param {JsonWriteOptions} [options] - Write options
+ * @returns {JsonWriter} `(root, value) => newRoot`
+ * @throws {JSONPathSyntaxError} When the query is not valid RFC 9535
+ * @example
+ * const addVat = compileJSONPathSetter('$..price');
+ * addVat(doc, (price) => price * 1.21);
+ */
+export declare function compileJSONPathSetter(path: string, options?: JsonWriteOptions): JsonWriter;
+/**
+ * Compile an `insert` at every node a JSONPath query selects - RFC 6902
+ * `add` semantics per location: the value is inserted *before* each
+ * matched array element (later siblings shift right), and replaces
+ * matched object members. Matching nothing is a no-op.
+ *
+ * @param {string} path - The JSONPath query (e.g. `$.list[0]`)
+ * @param {JsonWriteOptions} [options] - Write options
+ * @returns {JsonWriter} `(root, value) => newRoot`
+ * @throws {JSONPathSyntaxError} When the query is not valid RFC 9535
+ */
+export declare function compileJSONPathInserter(path: string, options?: JsonWriteOptions): JsonWriter;
+/**
+ * Compile a `remove` of every node a JSONPath query selects. Array
+ * elements are removed with shift; removals apply in reverse document
+ * order, so multiple removals from one array (and nested removals)
+ * compose correctly. Matching nothing is a no-op; selecting the root
+ * raises `JW2003`.
+ *
+ * @param {string} path - The JSONPath query (e.g. `$.store.book[?@.price > 20]`)
+ * @param {JsonWriteOptions} [options] - Write options
+ * @returns {JsonRemover} `(root) => newRoot`
+ * @throws {JSONPathSyntaxError} When the query is not valid RFC 9535
+ * @example
+ * const dropExpensive = compileJSONPathRemover('$.store.book[?@.price > 20]');
+ * dropExpensive(doc); // matched books removed, everything else shared
+ */
+export declare function compileJSONPathRemover(path: string, options?: JsonWriteOptions): JsonRemover;
+/**
+ * One-shot `set` at every node a JSONPath query selects. On hot paths
+ * prefer `compileJSONPathSetter` and reuse the writer.
+ * @param {any} root - The document (never mutated unless `options.mutate`)
+ * @param {string} path - The JSONPath query
+ * @param {any} value - The value, or an updater `(oldValue, normalizedPath) => next`
+ * @param {JsonWriteOptions} [options] - Write options
+ * @returns {any} The new document
+ */
+export declare function setAtJSONPath(root: any, path: string, value: any, options?: JsonWriteOptions): any;
+/**
+ * One-shot `insert` at every node a JSONPath query selects.
+ * @param {any} root - The document (never mutated unless `options.mutate`)
+ * @param {string} path - The JSONPath query
+ * @param {any} value - The value to insert
+ * @param {JsonWriteOptions} [options] - Write options
+ * @returns {any} The new document
+ */
+export declare function insertAtJSONPath(root: any, path: string, value: any, options?: JsonWriteOptions): any;
+/**
+ * One-shot `remove` of every node a JSONPath query selects.
+ * @param {any} root - The document (never mutated unless `options.mutate`)
+ * @param {string} path - The JSONPath query
+ * @param {JsonWriteOptions} [options] - Write options
+ * @returns {any} The new document
+ */
+export declare function removeAtJSONPath(root: any, path: string, options?: JsonWriteOptions): any;

package/dist/types/xquery/parse.d.ts

@@ -1,12 +1,11 @@
+import { LabeledSyntaxError } from '../errors.js';
 /**
  * Error thrown when XQuery text is not valid for the supported subset -
  * either invalid XQuery 3.1 syntax or a recognized construct outside the
  * subset (mirrors JSONPathSyntaxError: `source` and `position` locate the
  * offending token).
  */
-export declare class XQuerySyntaxError extends SyntaxError {
-    source: any;
-    position: any;
+export declare class XQuerySyntaxError extends LabeledSyntaxError {
     constructor(message: any, source: any, position: any);
 }
 /**

package/docs/JSLT-FORMAT.md

@@ -601,6 +601,67 @@ for a singleton, an array of items for a longer sequence. `options` carries
 caching compiled stylesheets by document identity and compile-option
 values in a WeakMap.
 
+## 13. Registered operators (host opt-in, non-normative)
+
+The operator vocabulary (QUERY-FORMAT §8) is **closed** — a document
+using `$npv` fails `JQ0002` exactly as one using `$frobnicate` does. A
+host can EXTEND it, the way `@jarenjs/validate` gains formats from
+`@jarenjs/formats`: compose packs of pure functions into a registry and
+compile against it. The published format is unchanged; the extension
+lives entirely in the caller's compile options.
+
+```js
+import { createJsltRegistry, mathPack, financePack, statsPack }
+  from '@jarenjs/json/jslt';
+
+const jslt = createJsltRegistry().use(mathPack).use(financePack).use(statsPack);
+const transform = jslt.compile(stylesheet);   // bound compileJsltStylesheet
+const q = jslt.compileQuery(queryDocument);    // bound compileJsonQuery
+jslt.names();                                  // every registered name
+jslt.toOptions();                              // { extensions, functions }
+```
+
+`createJsltRegistry()` is **immutable-by-copy**: `.use(pack)` returns a
+new registry (a value, not a mutable singleton), and a name that collides
+with the core vocabulary or a name already registered throws a
+`TypeError` at `.use()` — a host programming error, never a `JQ`
+document error.
+
+A **pack** is plain data — `{ name, entries }` — wrapping pure functions,
+free of the operator internals. Each entry declares a **kind**:
+
+- **`op`** — a scalar `$`-operator over scalar operands (`$sqrt`,
+  `$pow`). An empty operand propagates to an empty result.
+- **`agg`** — an operator whose declared `seq` operands are FOLDED to
+  arrays before the call, then the pure function runs and its result is
+  wrapped: a number as one item, an array under a `seq<number>` result as
+  a SEQUENCE (which packs into a JSON array with `[...]`, the same rule
+  `$range` follows). This is core `$sum`'s fold generalized, so
+  `{ "$npv": ["$.rate", "$.cashflows[*]"] }` computes the present value
+  of a filtered cashflow series. `sum`/`min`/`max`/`avg`/`count` are
+  already core operators and are NOT re-registered.
+- **`fn`** — a bare `$call` function, the low-level escape.
+
+**Purity is required.** A pack function must be a pure deterministic
+function of its arguments (no clock, randomness, or changing closure) —
+the same discipline `$call` and `$orderby`'s collations demand. A
+throwing function surfaces as the coded runtime error `JQ2010`, never a
+crash; a function returning `NaN`/`null` is the caller's data problem.
+
+The built-in packs wrap `@jarenjs/core`: `mathPack` (`$sqrt`, `$pow`,
+`$hypot`, trigonometry, logs — scalar ops), `financePack` (`$npv`,
+`$irr`, `$mirr`, `$fv`/`$pv`/`$pmt`, `$sma`/`$ema`/`$wma`/`$rsi`,
+`$volatility`/`$sharpe`/`$maxDrawdown` — aggregators over a series), and
+`statsPack` (`$mean`, `$median`, `$variance`, `$stddev`, `$percentile`).
+Because a registry compiles both stylesheets and bare query documents,
+registered operators also work through `@jarenjs/linq` over an in-memory
+source. Against `@jarenjs/db` a store opens with `openStore(model, {
+operators })`: every registered operator runs **correctly** in the query
+residual (JS over the fetched rows, named by `explain()`), and the
+`pushable:'scalar'` subset (the math ops) is additionally pushed into
+SQLite as deterministic UDFs where the driver allows (`node:sqlite` yes;
+`bun:sqlite` stays the residual). See MODEL-FORMAT §8.1–8.2.
+
 ---
 
 ## Appendix A. Worked examples (normative fixtures)
@@ -852,9 +913,19 @@ Schema subsets regardless of the draft they advertise. In particular,
 recursive references, `patternProperties`, `propertyNames`, `format`, and
 some composition keywords may be restricted or treated as annotations.
 Always validate a generated stylesheet locally against the full artifact
-before calling `compileJsltStylesheet`. A simplified lowest-common-
-denominator LLM profile could trade precision for broader provider support,
-but no such third artifact is defined in version 0.1.
+before calling `compileJsltStylesheet`.
+
+For those strict subsets a third artifact ships,
+[`../schemas/jaren-jslt.llm-profile.schema.json`](../schemas/jaren-jslt.llm-profile.schema.json)
+(`$id` `https://jarenjs.dev/schemas/jaren-jslt/0.1/llm-profile`): 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`. The guarantee runs one way only: every
+canonical-valid stylesheet validates under the profile, the reverse is
+deliberately *not* guaranteed. The profile is what you hand the provider's
+constrained decoder; the canonical artifact remains the authority, so the
+local validate-then-compile step above stays mandatory.
 
 Stylesheets remain ordinary JSON throughout the toolchain: they can be
 function-call arguments, retrieved rule sets, reviewed diffs, audit-log

package/docs/JSLT-PRELUDE.md

@@ -155,5 +155,5 @@ The intended consumers, in order:
 
 The groundwork this prelude assumed — schema literals inside query
 documents, the compile-time `compileTypeTest` hook, per-item validation
-semantics — shipped with the type-system work order; the next concrete step
+semantics — has since shipped in the query engine; the next concrete step
 is the `$apply` dispatch prototype behind a `jslt` module boundary.