@niscorp/prism 0.3.3 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +113 -0
- package/DESIGN.md +24 -13
- package/DOCS.md +104 -15
- package/dist/agent.cjs +4 -4
- package/dist/agent.js +2 -2
- package/dist/{chunk-OL4CCYWX.js → chunk-E44DNCG3.js} +40 -23
- package/dist/chunk-E44DNCG3.js.map +1 -0
- package/dist/{chunk-ROYHYYIL.cjs → chunk-NBU7EBGN.cjs} +5 -5
- package/dist/{chunk-ROYHYYIL.cjs.map → chunk-NBU7EBGN.cjs.map} +1 -1
- package/dist/{chunk-QUI2X5JB.cjs → chunk-VXU22DMV.cjs} +41 -22
- package/dist/chunk-VXU22DMV.cjs.map +1 -0
- package/dist/{chunk-VNGBVDUM.js → chunk-ZMMUIMAK.js} +3 -3
- package/dist/{chunk-VNGBVDUM.js.map → chunk-ZMMUIMAK.js.map} +1 -1
- package/dist/examples/index.cjs +1 -1
- package/dist/examples/index.cjs.map +1 -1
- package/dist/examples/index.d.cts +1 -1
- package/dist/examples/index.d.ts +1 -1
- package/dist/examples/index.js +1 -1
- package/dist/examples/index.js.map +1 -1
- package/dist/index.cjs +417 -377
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +225 -185
- package/dist/index.js.map +1 -1
- package/dist/migrations/index.cjs +6 -2
- package/dist/migrations/index.cjs.map +1 -1
- package/dist/migrations/index.js +5 -1
- package/dist/migrations/index.js.map +1 -1
- package/dist/{profiles-CPVfysxC.d.cts → profiles-BhAR8Ti3.d.cts} +1 -0
- package/dist/{profiles-CPVfysxC.d.ts → profiles-BhAR8Ti3.d.ts} +1 -0
- package/package.json +7 -7
- package/dist/chunk-OL4CCYWX.js.map +0 -1
- package/dist/chunk-QUI2X5JB.cjs.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,118 @@
|
|
|
1
1
|
# @niscorp/prism
|
|
2
2
|
|
|
3
|
+
## 0.4.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- a41edf9: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app compares stored fingerprints or `constantsFolded` of a config whose date or locale op has only written inputs, or relies on an IR compiled on one machine answering in that machine's zone when executed on another.
|
|
8
|
+
|
|
9
|
+
`$date`, `$dateAdd`, `$dateDiff`, `$localeDate`, `$localeMoney` and `$localeNumber` are never worked out ahead of time, by `compile` or by a kept `evaluate`, even when every input is written in the config: they read the machine's clock zone or its `Intl` data. `{"$date":{"value":"2026-01-01T09:00:00Z","format":"HH:mm"}}` compiled in Vienna was stored as `{"$const":"10:00"}` and answered `10:00` from `execute` in Los Angeles, where `evaluate` answered `01:00`; the IR now keeps the op and answers `01:00` there. A `$localeDate` with a written `timeZone` is kept as an op too (main folded it); so are `$dateDiff` between bare dates, `$localeMoney` and `$localeNumber`, which do not read the zone but do read Intl data. They answer the same text, and each call spends one more step and one Intl format for each such op. On the machine that compiles, every answer is the same. The IR's `fingerprint` and `meta.stats.optimizations.constantsFolded` change for such configs; an IR stored before keeps its folded constant until it is compiled again. The exported `EvalContext` type gains an optional `folding?: boolean`, set while the optimizer works a subtree out ahead of time (additive).
|
|
10
|
+
|
|
11
|
+
- eb4ffb9: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a config near its `maxSteps` limit relied on passing from the second call; it is now refused on every call, as its first call already was.
|
|
12
|
+
|
|
13
|
+
A part of a config that `evaluate` works out ahead of time from the second call (when the config object is kept and its tree prepared) spends the steps working it out took, each time it is evaluated. A `$join` of 600 written parts under `maxSteps: 500` was refused on the first call and passed from the second; it is now refused on every call. `compile` and `execute` are unchanged: a compiled IR counts such a part as one step.
|
|
14
|
+
|
|
15
|
+
- ae647e8: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a template contains `{{…}}` with a name in a script other than ASCII and relied on the braces staying in the text.
|
|
16
|
+
|
|
17
|
+
`$interpolate` fills a placeholder whose name is letters, marks, digits and `_` in any script. `"Hallo {{straße}}"` with `{ straße: "A" }` gives `"Hallo A"`, and `""` in its place when `values` lacks the key, as an ASCII name always did; the braces used to stay in the text. A name with other characters (`{{first-name}}`, `{{ name }}`) is still left as written.
|
|
18
|
+
|
|
19
|
+
- 2effb54: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app caught a `RangeError` or `TypeError` by its class from `$localeDate` or `$localeNumber`; such a config always failed, and now fails with a `PrismError`.
|
|
20
|
+
|
|
21
|
+
`$localeDate` and `$localeNumber` options that pass the schema but that `Intl` refuses — `dateStyle` beside `weekday`, `minDigits` above `digits` — are a `PrismError` with code `E_SCHEMA`, the op and its place in the config ("$localeDate: Intl refused its options: …"), instead of a bare `TypeError` or `RangeError`. A zone or a locale `Intl` cannot read is still `E_TYPE`, as before.
|
|
22
|
+
|
|
23
|
+
- bd996ea: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a config handed `$localeMoney` or `$localeNumber` a list, a boolean, hex text or blank text as the amount (now `E_TYPE`), or relied on `$localeMoney` dividing by 100 for a locale `Intl` cannot read.
|
|
24
|
+
|
|
25
|
+
`$localeMoney` takes the minor-unit divisor from the currency alone, so a locale tag `Intl` cannot read no longer changes the amount: 1500 JPY with locale `en_US` prints `JPY 1500` (was `JPY 15.00`). `$localeMoney` and `$localeNumber` read `value` as `$toNumber` reads text: a number, or digits with spaces around them (`" 1999 "`). `[1999]`, `true`, `"0x10"` and `" "` are refused with `E_TYPE`; they used to print `19,99 €`, `0,01 €`, `0,16 €` and `0,00 €`.
|
|
26
|
+
|
|
27
|
+
- 180787b: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a config relied on an overflowing `$add`, `$sub`, `$mul`, `$div`, `$sum` or `$avg` giving `Infinity` (which JSON stores as `null`): it is now an `E_TYPE` error.
|
|
28
|
+
|
|
29
|
+
`$add`, `$sub`, `$mul` and `$div` refuse an answer that is not a JSON number. `{ "$mul": [1e308, 10] }` and `{ "$div": [1, 5e-324] }` are `E_TYPE` ("$mul gave Infinity, which is not a JSON number."), where they returned `Infinity`. `$sum`and`$avg` run as `$add`, so a sum past what a number can be is refused the same way: "$add gave Infinity, which is not a JSON number. At $sum, in the $add that $sum runs as."
|
|
30
|
+
|
|
31
|
+
- d53910e: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a config runs `$min` or `$max` over about 111,000 items or more under the default `maxSteps`, or relies on a stored compiled fingerprint of a config that uses them: each item now costs 9 steps instead of 8, and the desugared form, so the fingerprint, changes once.
|
|
32
|
+
|
|
33
|
+
`$min` and `$max` skip a `null` item wherever it is in the list. `[3, null, 1]` gave `E_TYPE` while `[null, 3, 1]` gave `1`; both now give `1`, and a list of nulls gives `null`. Every list that had an answer has the same answer.
|
|
34
|
+
|
|
35
|
+
- 276f457: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on the second and later calls of one config object losing a constant's `__proto__` key; they now answer as the first call does.
|
|
36
|
+
|
|
37
|
+
A `$const` whose value has a key `__proto__` keeps it as an own key on every call of a config object that is run again. From the second call (when the config's tree is kept and its constants handed out as copies), the key used to be dropped and its value became the copy's prototype, so `out.admin` read `true` through it.
|
|
38
|
+
|
|
39
|
+
- 413afbd: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a `$replace` replacement contains `$$`, `$&`, `` $` ``, `$'` or `$<name>` and relied on JavaScript reading it as a pattern (writing `$$` to get `$`).
|
|
40
|
+
|
|
41
|
+
`$replace` writes its `replacement` as given. `"US$$5"` writes `US$$5` (was `US$5`), and `"[$&]"` writes `[$&]` (was the matched text in brackets). DOCS already said `search` is plain text; the replacement now is too.
|
|
42
|
+
|
|
43
|
+
- 3f92c52: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a config relied on `$round` with `digits` above 0 giving the binary-product answer, or a stored number was rounded that way: the same input now rounds to a different number.
|
|
44
|
+
|
|
45
|
+
`$round` rounds a number at its decimals as they are written, not at `value × 10^digits`. With `digits: 2`: `1.1` with `"ceil"` is `1.1` (was `1.11`), `4.35` with `"floor"` is `4.35` (was `4.34`), `1.005` to the nearest is `1.01` (was `1`), `0.285` is `0.29` (was `0.28`). More digits than a number has give the number (was `NaN` for `digits: 400`, or `1e300` at 10 digits). With `digits: 0` every answer is the same as before.
|
|
46
|
+
|
|
47
|
+
- 841c010: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a config cut or split text with emoji or other characters outside the Basic Multilingual Plane and relied on getting half a character (which Postgres jsonb refuses and a browser shows as �).
|
|
48
|
+
|
|
49
|
+
`$slice`, `$take` and `$drop` never cut text between the two halves of one character: a cut there moves to the near side of it. `start` 0, `end` 5 of `"Hey 👍 there"` is `"Hey "` (was `"Hey \ud83d"`), and `$take 1` of `"👍"` is `""`. `$split` with `sep: ""` splits into characters: `"a👍"` → `["a", "👍"]` (was three items). Indexes stay UTF-16 units, so every result that was whole text is the same. `$length` still counts UTF-16 units, as zod does, and now says so.
|
|
50
|
+
|
|
51
|
+
- d93170b: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a config relied on `$update` turning a list or a scalar on its path into an object (also for digit text past the end of a list), or on `$has` answering `false` for digit text over a list.
|
|
52
|
+
|
|
53
|
+
`$update` and `$has` read a path as `$get` does: a number, or digit text such as `"0"` on a list, is an index. `$update` at `["items", "0", "qty"]` over a list now updates the first item; it used to replace the list with `{"0": {"qty": …}}` and lose the other items. Digit text past the end of a list (`["items", "5"]` over `[1, 2]`) is `E_MISSING_PATH`, as a number index there always was; it used to give `{"items": {"5": …}}`. `$has` with that path answers `true` where the item exists. A key on a list (`"x"`, and `"01"`, which is not index text) or on a string, number or boolean is now `E_TYPE`; it used to replace that value with a new object. A missing key or `null` on the path is still created as an object.
|
|
54
|
+
|
|
55
|
+
### Patch Changes
|
|
56
|
+
|
|
57
|
+
- 1f6d37d: `$fill` is measured at every level it fills: nested slots that use one slot twice are refused with `E_BUDGET` at the string limit, instead of first building text hundreds of megabytes long.
|
|
58
|
+
|
|
59
|
+
`__optional` leaves out a field whose `$get` runs into `null` or a missing key, as it already left out a `$ref` to a missing path. The error without `__optional` is unchanged (`E_TYPE`); it now carries `details.absent: true`.
|
|
60
|
+
|
|
61
|
+
The `Intl` formatter caches of `$localeDate`, `$localeMoney` and `$localeNumber` keep up to 1,000 formatters each and are emptied when full, as the path cache is; they grew with every distinct locale a process saw.
|
|
62
|
+
|
|
63
|
+
DOCS and `$walk`'s description say when a walk ends: `post` always ends; with `pre`, a walk whose every replacement again contains a node a rule matches runs until the budget stops it (`E_BUDGET`). They said it always ends.
|
|
64
|
+
|
|
65
|
+
`$reduce`'s DOCS and the descriptions of `as` and `acc` say that when the two are one name, the body sees the accumulator, not the item.
|
|
66
|
+
|
|
67
|
+
- d77baf9: Prism reads and writes only the data's own keys: `$.constructor` on `{}` is a missing path instead of a JavaScript function, `$groupBy` groups under `constructor` or `toString` instead of throwing, and a key called `__proto__` in the data stays a key of the result in `$merge`, `$omit`, `$pick`, `$keyBy`, `$fromEntries` and `$renameKeys`.
|
|
68
|
+
|
|
69
|
+
`$localeDate` and `$localeNumber` refuse a locale Intl does not read (`de_AT`) with a Prism type error (`E_TYPE`) instead of a bare `RangeError`.
|
|
70
|
+
|
|
71
|
+
A source nested deeper than the call stack reaches is stopped with `E_BUDGET` instead of a bare `RangeError`.
|
|
72
|
+
|
|
73
|
+
The cache of parsed `$ref` paths keeps at most 1,000 paths; it grew with every distinct path a process saw.
|
|
74
|
+
|
|
75
|
+
A config still cannot carry a key called `__proto__`: validation drops it from a plain object, a `$const` payload, a `$with` binding or a `$renameKeys` map while `validate` answers ok. DOCS.md says so; data with such a key comes in through the source.
|
|
76
|
+
|
|
77
|
+
With `check: 'always'`, a source that contains itself is refused as not JSON (`E_TYPE`, "source.self refers back to source").
|
|
78
|
+
|
|
79
|
+
- Updated dependencies [48138de]
|
|
80
|
+
- Updated dependencies [da3037e]
|
|
81
|
+
- Updated dependencies [e957628]
|
|
82
|
+
- Updated dependencies [c30562a]
|
|
83
|
+
- Updated dependencies [efd2368]
|
|
84
|
+
- Updated dependencies [ca26810]
|
|
85
|
+
- Updated dependencies [800a541]
|
|
86
|
+
- Updated dependencies [9c5367b]
|
|
87
|
+
- Updated dependencies [322f241]
|
|
88
|
+
- Updated dependencies [d85bab1]
|
|
89
|
+
- Updated dependencies [aeaf803]
|
|
90
|
+
- Updated dependencies [2b174f8]
|
|
91
|
+
- Updated dependencies [df79faf]
|
|
92
|
+
- Updated dependencies [133c0ee]
|
|
93
|
+
- Updated dependencies [543f79d]
|
|
94
|
+
- Updated dependencies [61b15e4]
|
|
95
|
+
- Updated dependencies [7e8f6d4]
|
|
96
|
+
- Updated dependencies [5c52ef5]
|
|
97
|
+
- Updated dependencies [66eb934]
|
|
98
|
+
- @niscorp/cortex@0.2.0
|
|
99
|
+
- @niscorp/signal@0.2.0
|
|
100
|
+
- @niscorp/strata@0.2.0
|
|
101
|
+
|
|
102
|
+
## 0.3.4
|
|
103
|
+
|
|
104
|
+
### Patch Changes
|
|
105
|
+
|
|
106
|
+
- 686e9c7: **`$localeDate` takes its zone from the source, and Prism's grammar is at version 4.** `options.timeZone` is a node, as `value` and `locale` already were: `{ "timeZone": { "$ref": "$.zone" } }` words a date where its reader is, so one mapping serves every zone instead of one config per zone. A written zone works as before and is still folded at compile time; a config with a bound zone compiles to one fingerprint, and `execute` reads the zone from each source.
|
|
107
|
+
|
|
108
|
+
A zone written in the program is still text or it is refused as the config is read, as before (`E_SCHEMA`, its message now naming both forms a zone may take); what is new is an op there that reads one. The JSON Schema (`getConfigJsonSchema`, a profile's) says only "a node" at `timeZone` and does not carry that rule, as it does not carry a `$ref` path's; `validate` and `compile` do. The form an error message shows for `$localeDate` reads `"timeZone"?: <node>`. A zone `Intl` does not know, written or read — or a bound one that is not text, `null` included — is refused with `E_TYPE` at `$localeDate.options.timeZone`, saying what it got. An unknown written zone used to escape as a bare `RangeError` from `Intl`; it is now a `PrismError`, which is still an `Error`. The zone is looked at after the date, so a bad date is still `E_DATE_INVALID` whatever the zone, and a written zone spends no step of the budget, as before.
|
|
109
|
+
|
|
110
|
+
**A locale tag `Intl` cannot read is refused the same way.** `$localeDate` and `$localeNumber` refuse text `Intl` cannot read as a locale tag (`"en_GB"`), written or read, with `E_TYPE` at `locale`, where it escaped as a bare `RangeError`. It is looked at after the date, so a bad date is still `E_DATE_INVALID`; where both the zone and the locale are bad, the zone is refused first. A well-formed tag `Intl` has no data for is read as before. `$localeMoney` is unchanged: it still prints the code beside the amount for a locale it cannot read, with a divisor of 100 whatever the currency, which DOCS.md now says.
|
|
111
|
+
|
|
112
|
+
**The grammar.** `nisc.prism` goes from 3 to 4 with one migration that rewrites nothing: this is an addition, and a reader at 3 must refuse a config with a bound zone.
|
|
113
|
+
|
|
114
|
+
**What to change:** an app that keeps Prism configs in its source moves its stamp: `npm run strata upgrade`, then `npm run strata verify`. There is nothing to edit; `strata.lock.json` goes to `nisc.prism 4`. A config written before parses to exactly what it did, so a compiled IR's fingerprint does not move. An app made by `create-nisc` from this release starts at `nisc.prism 4`.
|
|
115
|
+
|
|
3
116
|
## 0.3.3
|
|
4
117
|
|
|
5
118
|
### Patch Changes
|
package/DESIGN.md
CHANGED
|
@@ -47,10 +47,14 @@ type EvalContext = {
|
|
|
47
47
|
source: JsonValue; // Root source data (immutable)
|
|
48
48
|
vars: Record<string, JsonValue>; // Scoped variables (a loop writes to its own copy only)
|
|
49
49
|
budget?: Budget; // What this evaluation may still cost (engine/budget.ts)
|
|
50
|
+
kept?: boolean; // The tree is kept and run again: a `$const` is handed out as a copy
|
|
51
|
+
folding?: boolean; // The optimizer is working a literal subtree out ahead of time
|
|
50
52
|
};
|
|
51
53
|
```
|
|
52
54
|
|
|
53
|
-
|
|
55
|
+
An op whose answer depends on the machine it runs on — its clock zone or its `Intl` data: `$date`, `$dateAdd`, `$dateDiff`, `$localeDate`, `$localeMoney`, `$localeNumber` — throws in its first line when it sees `folding` (`notAheadOfTime`), and the optimizer keeps a node that throws as an op. The op says this about itself, so there is no list beside the schema.
|
|
56
|
+
|
|
57
|
+
The context an op is given is never written to. A `$with` binding makes a new context via spread. A loop (`$map`, `$filter`, `$reduce`, `$sortBy`, `$groupBy`, `$keyBy`) makes one context of its own for the whole loop and sets its variable in that for each item (`ops/scope.ts`), because a new one per item is a noticeable share of the time of a long map. Nothing keeps a scope past the evaluation of one body, so ops are still pure — same input always produces same output.
|
|
54
58
|
|
|
55
59
|
---
|
|
56
60
|
|
|
@@ -64,25 +68,25 @@ Ops receive the `evaluate` function as a parameter rather than importing it. Thi
|
|
|
64
68
|
|
|
65
69
|
### Dispatcher (if-chain, not Map)
|
|
66
70
|
|
|
67
|
-
|
|
71
|
+
One linear if-chain of type guards says which op a node is: `resolveHandler` in `engine/optimize.ts`.
|
|
68
72
|
|
|
69
73
|
```typescript
|
|
70
|
-
if (isRefNode(
|
|
71
|
-
if (isMapNode(
|
|
74
|
+
if (isRefNode(node)) return eraseOp(opRef);
|
|
75
|
+
if (isMapNode(node)) return eraseOp(opMap);
|
|
72
76
|
// ... 63 more
|
|
73
77
|
```
|
|
74
78
|
|
|
75
|
-
|
|
79
|
+
The interpreter asks it for every node it evaluates; the optimizer asks it once per node and attaches the answer to the node, so an optimized or compiled tree is dispatched without the chain. The handler comes back with its node type erased, which is safe because a node gets an op's handler only after it passed that op's guard. A Map from key to handler would answer a different op for a node with two `$` keys, which a tree that skipped the schema can have.
|
|
76
80
|
|
|
77
81
|
---
|
|
78
82
|
|
|
79
83
|
## Plain Objects and `__optional`
|
|
80
84
|
|
|
81
|
-
Objects without `$`-prefixed keys are output templates. Each value is recursively evaluated. The `__optional` metadata key lists fields that should be silently omitted when they evaluate to `null`/`undefined` or throw `
|
|
85
|
+
Objects without `$`-prefixed keys are output templates. Each value is recursively evaluated. The `__optional` metadata key lists fields that should be silently omitted when they evaluate to `null`/`undefined`, throw `E_MISSING_PATH`, or throw a `$get` error marked `details.absent` (its path ran into `null` or a missing key; the code stays `E_TYPE`).
|
|
82
86
|
|
|
83
87
|
This enables partial results from incomplete source data without try/catch wrapping every field.
|
|
84
88
|
|
|
85
|
-
The schema and the evaluator
|
|
89
|
+
The schema and the evaluator share one rule: a `$` name is an op's. The template branch's key pattern refuses every key that starts with `$`, which is exactly the evaluator's test for a plain object — so a `$` key that is not an op is `E_SCHEMA`, with the key's path, and not a config that validates, is stored, and fails each time it runs. Because the whole prefix is reserved, adding an op takes no name away from templates. Data that has `$` keys is a `$const` payload.
|
|
86
90
|
|
|
87
91
|
---
|
|
88
92
|
|
|
@@ -90,7 +94,9 @@ The schema and the evaluator hold one rule: a `$` name is an op's. The template
|
|
|
90
94
|
|
|
91
95
|
Prism supports `$.key.nested[0].deep` — dot notation for object keys, bracket notation for array indices. No filters, recursive descent, or unions. These omissions are intentional: `$filter`, `$map`, and `$merge` cover those use cases through the op system, which is composable and type-safe.
|
|
92
96
|
|
|
93
|
-
Parsed paths are cached
|
|
97
|
+
Parsed paths are cached by their text (`utils/jsonpath.ts`), up to 1,000 of them: a full cache is emptied and starts again, so a host that builds configs per request does not grow it without end. An optimized or compiled tree does not use it: `optimize` and `rehydrate` attach each `$ref`'s parsed path to the node.
|
|
98
|
+
|
|
99
|
+
A key is read from data only when the data has it as its own (`utils/own-keys.ts`): `$.constructor` on `{}` is a missing path, not `Object`. Only a value that could be inherited, a function or the value at `__proto__`, is asked about, so a read costs what a plain one does. A key is written the same way, so a `__proto__` key from `JSON.parse` stays a key of the result instead of replacing its prototype. zod drops a `__proto__` key while it parses a config, so a template or a `$const` cannot carry one.
|
|
94
100
|
|
|
95
101
|
---
|
|
96
102
|
|
|
@@ -118,6 +124,8 @@ type CompiledIr = {
|
|
|
118
124
|
|
|
119
125
|
`execute()` skips validation and desugaring — it restores each node's handler and each `$ref`'s parsed path once per IR, and evaluates `core` directly. How much that saves over `evaluate()` depends on the config: `pnpm bench` runs five against each other (`test/optimize.bench.ts`), from under 2x for a short map to over 50x where the constants fold.
|
|
120
126
|
|
|
127
|
+
A constant the optimizer works out for `evaluate`'s kept tree records, as a non-enumerable property beside its handler, the steps working it out took, and `$const` spends them each time it is evaluated: a kept config spends on every call what its first call spent. `compile` records nothing, as its IR is JSON, so `execute` counts such a constant as one step.
|
|
128
|
+
|
|
121
129
|
The fingerprint enables cache invalidation: store IRs by name, check the fingerprint to know if the config changed.
|
|
122
130
|
|
|
123
131
|
---
|
|
@@ -173,7 +181,7 @@ src/
|
|
|
173
181
|
│ ├── evaluate.ts # Dispatcher + evaluate / evaluateSafe (what a config object was found to be is kept here)
|
|
174
182
|
│ ├── compile.ts # Config → CompiledIr
|
|
175
183
|
│ ├── optimize.ts # Compile-time passes (ref segments, handlers, constant folding)
|
|
176
|
-
│ ├── budget.ts # Limits: steps, string length, result size
|
|
184
|
+
│ ├── budget.ts # Limits: steps, string length, result size; a value nested past the call stack
|
|
177
185
|
│ ├── execute.ts # CompiledIr + source → result
|
|
178
186
|
│ ├── place.ts # On the way out: an error's position, in the author's config, and the op's form
|
|
179
187
|
│ ├── validate.ts # Config validation
|
|
@@ -206,7 +214,8 @@ src/
|
|
|
206
214
|
│ ├── groups.ts # PRISM_EXAMPLE_GROUPS — id, title and description of each group
|
|
207
215
|
│ └── operators.ts, sugar.ts, composition.ts, real-world.ts # the examples
|
|
208
216
|
└── utils/
|
|
209
|
-
├── jsonpath.ts # JSONPath parser
|
|
217
|
+
├── jsonpath.ts # JSONPath parser
|
|
218
|
+
├── own-keys.ts # Reading and writing a data key as the data's own
|
|
210
219
|
├── compare.ts # Deep equality, ordered comparison
|
|
211
220
|
└── issues.ts # Zod issues → the branch the config meant
|
|
212
221
|
```
|
|
@@ -227,12 +236,14 @@ language into a package that has no business knowing which languages exist.
|
|
|
227
236
|
Formatter construction is cached per resolved argument tuple, because building
|
|
228
237
|
an `Intl` formatter costs roughly two orders of magnitude more than using one
|
|
229
238
|
and a mapping over a thousand rows would otherwise build a thousand of them.
|
|
239
|
+
Each cache keeps up to 1,000 formatters and is emptied when full, as the path
|
|
240
|
+
cache is: a locale read from data adds one per distinct tag.
|
|
230
241
|
|
|
231
242
|
---
|
|
232
243
|
|
|
233
244
|
## Design Decisions
|
|
234
245
|
|
|
235
|
-
1. **Linear if-chain over Map dispatch.**
|
|
246
|
+
1. **Linear if-chain over Map dispatch.** One chain for the interpreter and the optimizer, in the order the ops are listed; the first guard that matches answers. A Map keyed by op would answer differently for a node with two `$` keys.
|
|
236
247
|
|
|
237
248
|
2. **Desugar before execution, not during.** One canonical representation. Compiler stores desugared form. An error inside a sugar op names the core op that refused and the sugar op the author wrote: `engine/place.ts` follows the position back into the author's config, and where a sugar op's keys stop matching, rewrites a copy of it with a marker in each field to see where each field went. Nothing records the rewrite while it runs; the work is done only for an error.
|
|
238
249
|
|
|
@@ -240,7 +251,7 @@ and a mapping over a thousand rows would otherwise build a thousand of them.
|
|
|
240
251
|
|
|
241
252
|
4. **SHA256 fingerprint on IR.** Cache invalidation without version numbers. Same config = same fingerprint.
|
|
242
253
|
|
|
243
|
-
5. **`evaluate` + `evaluateSafe`.** Throwing for trusted code, Result type for untrusted input. Different call sites have different needs. Both keep what a config object was found to be, by the object: a host hands the same configs over on every request, and checking each again was the whole cost of a small transform. `check: 'always'` is the call that keeps nothing, for writing and testing a config.
|
|
254
|
+
5. **`evaluate` + `evaluateSafe`.** Throwing for trusted code, Result type for untrusted input. Different call sites have different needs. Both keep what a config object was found to be, by the object: a host hands the same configs over on every request, and checking each again was the whole cost of a small transform. `check: 'always'` is the call that keeps nothing, for writing and testing a config.
|
|
244
255
|
|
|
245
256
|
6. **Ops receive `evaluate` as a parameter.** Breaks the circular import between ops and the dispatcher. Also enables mock-based unit testing of individual ops.
|
|
246
257
|
|
|
@@ -252,4 +263,4 @@ and a mapping over a thousand rows would otherwise build a thousand of them.
|
|
|
252
263
|
|
|
253
264
|
10. **`compile()` is async.** Uses `crypto.subtle.digest` for SHA256, which is async in all runtimes. `evaluate()` stays sync because it doesn't need the fingerprint.
|
|
254
265
|
|
|
255
|
-
11. **The node union is tried by key before it is walked.** zod tries a union's 78 members (75 ops, then primitive, array and template) in order, and a plain object is the last. One `$` key and nothing else can only be that op, and no `$` key can only be a template, so that member is tried first and a valid config never walks the union. An invalid one is walked
|
|
266
|
+
11. **The node union is tried by key before it is walked.** zod tries a union's 78 members (75 ops, then primitive, array and template) in order, and a plain object is the last. One `$` key and nothing else can only be that op, and no `$` key can only be a template, so that member is tried first and a valid config never walks the union. An invalid one is walked from the top, so a refusal is the union's own. The union stays a union: the JSON Schema, the profiles and loom read it as one.
|
package/DOCS.md
CHANGED
|
@@ -20,6 +20,10 @@ A key that starts with `$` is an op's name. A plain object has none: `{ "$fetch"
|
|
|
20
20
|
|
|
21
21
|
Every evaluation takes a `source` — the data the transformation reads from via `$ref`. `evaluate` accepts any JSON value (object, array, or scalar); `"$"` is the whole of it.
|
|
22
22
|
|
|
23
|
+
Prism reads only the keys the data has: `$.constructor` on `{}` is a missing path, and `toString` is not a variable unless something binds it. A key called `__proto__` in the data (as `JSON.parse` makes it) is an ordinary key, read and written like any other.
|
|
24
|
+
|
|
25
|
+
A config cannot carry a key called `__proto__`. Validation drops it without a word, so `validate` answers ok and the key is gone: from a plain object, a `$const` payload, a `$with` binding or a `$renameKeys` map. Data with such a key comes in through the source.
|
|
26
|
+
|
|
23
27
|
### Bindings and Variables
|
|
24
28
|
|
|
25
29
|
`$ref` reads from source. `$var` reads from scoped variables created by `$with`, `$map`, `$filter`, `$reduce`, `$sortBy`, `$keyBy`, `$groupBy`, `$update`, and `$walk`.
|
|
@@ -38,6 +42,8 @@ Plain objects support an `__optional` metadata key that lists field names to sil
|
|
|
38
42
|
|
|
39
43
|
If `$.user.nickname` doesn't exist, the result is `{ "name": "Alice" }` — no error.
|
|
40
44
|
|
|
45
|
+
A `$get` whose path runs into `null` or a missing key is left out the same way. One that runs into a number, text or a boolean, reads a list by a key that is not an index, or reads an object by an index, is still an error (`E_TYPE`).
|
|
46
|
+
|
|
41
47
|
---
|
|
42
48
|
|
|
43
49
|
## Core Operations
|
|
@@ -174,7 +180,7 @@ Reduces an array to a single value. Binds each element as `as` and the running a
|
|
|
174
180
|
|
|
175
181
|
Source: `{ "numbers": [1, 2, 3] }` → `6`
|
|
176
182
|
|
|
177
|
-
The `acc` name defaults to `"acc"` if omitted.
|
|
183
|
+
The `acc` name defaults to `"acc"` if omitted. When `as` and `acc` are one name (`"as": "acc"` with no `acc`, for one), the body sees the accumulator, not the item.
|
|
178
184
|
|
|
179
185
|
### `$slice` — Slice array or string
|
|
180
186
|
|
|
@@ -183,7 +189,11 @@ The `acc` name defaults to `"acc"` if omitted.
|
|
|
183
189
|
{ "$slice": { "from": { "$ref": "$.text" }, "start": 0, "end": 5 } }
|
|
184
190
|
```
|
|
185
191
|
|
|
186
|
-
`start` defaults to 0, `end` defaults to length.
|
|
192
|
+
`start` defaults to 0, `end` defaults to length. A string is indexed in UTF-16
|
|
193
|
+
units, as `$length` counts it, and is never cut inside a character: a cut that
|
|
194
|
+
falls between the two halves of one (an emoji such as 👍 is two units) moves to
|
|
195
|
+
the near side of it, so that code point is left out. `start` 0 and `end` 5 of `"Hey 👍 there"` is `"Hey "`, and
|
|
196
|
+
`start` 5 is `" there"`. `$take` and `$drop` cut the same way.
|
|
187
197
|
|
|
188
198
|
### `$flatten` — Flatten one level
|
|
189
199
|
|
|
@@ -224,7 +234,7 @@ Source: `{ "tags": ["a", "b", "a", "c", "b"] }` → `["a", "b", "c"]`
|
|
|
224
234
|
|
|
225
235
|
## Math Operations
|
|
226
236
|
|
|
227
|
-
`$add`, `$sub`, `$mul`, `$div` and `$mod` take a `[left, right]` pair. Both operands are evaluated and must be numbers. `$round` and `$toNumber` take an object.
|
|
237
|
+
`$add`, `$sub`, `$mul`, `$div` and `$mod` take a `[left, right]` pair. Both operands are evaluated and must be numbers. An answer past what a JSON number can be (`{ "$mul": [1e308, 10] }`) is refused with `E_TYPE`, not handed out as `Infinity`. `$round` and `$toNumber` take an object.
|
|
228
238
|
|
|
229
239
|
### `$add`
|
|
230
240
|
```json
|
|
@@ -259,6 +269,8 @@ The remainder of the first number divided by the second. It takes the sign of th
|
|
|
259
269
|
```
|
|
260
270
|
Result: `3.14`. `digits` defaults to 0. `mode` is `"nearest"` unless given: `"floor"` rounds down (toward negative infinity) and `"ceil"` rounds up, at the same `digits`.
|
|
261
271
|
|
|
272
|
+
The number is rounded at its decimals as they are written: `1.1` with `"ceil"` at 2 digits is `1.1`, and `1.005` to the nearest at 2 digits is `1.01`. A half goes up, toward positive infinity (`-2.5` is `-2`). More digits than a number has give the number itself.
|
|
273
|
+
|
|
262
274
|
```json
|
|
263
275
|
{ "$round": { "value": { "$div": [{ "$ref": "$.minutes" }, 60] }, "mode": "floor" } }
|
|
264
276
|
```
|
|
@@ -299,7 +311,7 @@ Numbers → `"42"`, null → `"null"`, objects → JSON string.
|
|
|
299
311
|
}
|
|
300
312
|
}
|
|
301
313
|
```
|
|
302
|
-
Replaces `{{key}}` placeholders with values from the evaluated object. Missing keys become empty strings. A value that is an object or a list is refused (`E_TYPE`).
|
|
314
|
+
Replaces `{{key}}` placeholders with values from the evaluated object. A key is letters, marks, digits and `_` in any script (`{{straße}}`, `{{名前}}`); a placeholder with any other character (`{{first-name}}`, `{{ name }}`) is left as written. Missing keys become empty strings. A value that is an object or a list is refused (`E_TYPE`).
|
|
303
315
|
|
|
304
316
|
### `$fill` — Fill a counted phrase
|
|
305
317
|
```json
|
|
@@ -309,6 +321,8 @@ Source: `{ "progress": { "phrase": "{n} of {total}", "slots": { "n": 1, "total":
|
|
|
309
321
|
|
|
310
322
|
Takes a node that evaluates to a pattern value `{ phrase, slots }` and replaces each `{name}` hole with its slot, in the source language. A slot that is itself a pattern is filled recursively; a hole with no slot (or a null one) is left as written. Anything that is not a pattern passes through unchanged.
|
|
311
323
|
|
|
324
|
+
The text is measured at each level it fills, so a pattern whose text grows past `maxStringLength` is refused (`E_BUDGET`) as soon as it does. A slot used twice in its phrase still doubles the work at each level of nesting: when the text does not grow (the innermost slot is `""`), nothing is refused, and 24 such levels take seconds.
|
|
325
|
+
|
|
312
326
|
### `$trim`
|
|
313
327
|
```json
|
|
314
328
|
{ "$trim": { "$const": " hello " } }
|
|
@@ -329,14 +343,14 @@ Result: `"hello"`
|
|
|
329
343
|
```json
|
|
330
344
|
{ "$split": { "value": { "$const": "a,b,c" }, "sep": "," } }
|
|
331
345
|
```
|
|
332
|
-
Result: `["a", "b", "c"]`
|
|
346
|
+
Result: `["a", "b", "c"]`. With `"sep": ""` the text is split into code points: `"a👍"` → `["a", "👍"]`, and `"👍🏽"` gives two items.
|
|
333
347
|
|
|
334
348
|
### `$replace` — Replace a substring
|
|
335
349
|
```json
|
|
336
350
|
{ "$replace": { "value": { "$ref": "$.text" }, "search": "world", "replacement": "there" } }
|
|
337
351
|
{ "$replace": { "value": { "$ref": "$.phone" }, "search": " ", "replacement": "", "all": true } }
|
|
338
352
|
```
|
|
339
|
-
The first occurrence of `search`, or every occurrence with `all: true`. `search` is plain text, not a pattern
|
|
353
|
+
The first occurrence of `search`, or every occurrence with `all: true`. `search` is plain text, not a pattern, and `replacement` is written as given: `"US$$5"` writes `US$$5`, and `$&` is the two characters `$&`.
|
|
340
354
|
|
|
341
355
|
---
|
|
342
356
|
|
|
@@ -499,6 +513,7 @@ Returns one of: `"string"`, `"number"`, `"boolean"`, `"null"`, `"array"`, `"obje
|
|
|
499
513
|
{ "$length": { "$ref": "$.items" } }
|
|
500
514
|
{ "$length": { "$ref": "$.name" } }
|
|
501
515
|
```
|
|
516
|
+
A string's length counts UTF-16 units, not characters: `"👍🏽"` is 4.
|
|
502
517
|
|
|
503
518
|
---
|
|
504
519
|
|
|
@@ -513,7 +528,9 @@ precise edit.
|
|
|
513
528
|
{ "$has": { "from": { "$ref": "$.document" }, "path": ["props", "label"] } }
|
|
514
529
|
```
|
|
515
530
|
True when the whole path exists — a key present with `null` counts; a missing
|
|
516
|
-
one does not (which `$get` with a `fallback` cannot tell apart).
|
|
531
|
+
one does not (which `$get` with a `fallback` cannot tell apart). A path is read
|
|
532
|
+
as `$get` reads it: a number, or digit text such as `"0"` on a list, is an
|
|
533
|
+
index.
|
|
517
534
|
|
|
518
535
|
### `$renameKeys` — Rename in place
|
|
519
536
|
```json
|
|
@@ -527,8 +544,12 @@ existing key replaces that entry.
|
|
|
527
544
|
{ "$update": { "from": { "$ref": "$.document" }, "path": ["props", "count"], "value": { "$add": [{ "$var": "current" }, 1] } } }
|
|
528
545
|
```
|
|
529
546
|
The value currently at `path` (null when absent) is bound as `current` (rename
|
|
530
|
-
it with `"as"`).
|
|
531
|
-
|
|
547
|
+
it with `"as"`). The path is read as `$get` reads it: `["items", "0", "qty"]`
|
|
548
|
+
over a list updates its first item. Missing objects along a string path are
|
|
549
|
+
created, and so is an object where the path meets `null`; an array index that
|
|
550
|
+
does not exist is `E_MISSING_PATH`. A key on a list (`["items", "x"]`, and
|
|
551
|
+
`"01"`, which is not index text) or on a string, number or boolean is `E_TYPE`:
|
|
552
|
+
`$update` never replaces a value with an object.
|
|
532
553
|
|
|
533
554
|
### `$assert` — Refuse loudly
|
|
534
555
|
```json
|
|
@@ -555,7 +576,10 @@ Visits every node — objects, arrays and leaves, at any depth — and replaces
|
|
|
555
576
|
with the first rule whose `when` holds (bound to `as`); no rule, the node stays.
|
|
556
577
|
`"order": "post"` (default) rewrites children first, so a node's rules see them
|
|
557
578
|
rewritten; `"pre"` applies the rules first and descends into the result. A
|
|
558
|
-
replacement is never walked again at its own level
|
|
579
|
+
replacement is never walked again at its own level. With `post` the walk never
|
|
580
|
+
goes into a replacement, so it always ends. With `pre` it goes into each
|
|
581
|
+
replacement's children: if every replacement again contains a node a rule
|
|
582
|
+
matches, the walk does not end, and the run stops at the budget (`E_BUDGET`). A
|
|
559
583
|
walk visits objects too: guard a string op with a type check
|
|
560
584
|
(`{ "$and": [{ "$eq": [{ "$type": { "$var": "n" } }, "string"] }, …] }`).
|
|
561
585
|
|
|
@@ -576,6 +600,10 @@ removal. Changes to the grammar are strata migrations on `nisc.prism`
|
|
|
576
600
|
|
|
577
601
|
Powered by [dayjs](https://day.js.org/). Date values can be ISO 8601 strings or Unix timestamps (milliseconds). A date-only string (`YYYY-MM-DD`) is parsed and computed in UTC, so the calendar day survives the round trip.
|
|
578
602
|
|
|
603
|
+
**Worked out where it runs.** `$date`, `$dateAdd`, `$dateDiff`, `$localeDate`, `$localeMoney` and `$localeNumber` read the machine's clock zone or its `Intl` data, so neither `compile` nor a kept `evaluate` works them out ahead of time, even when every input is written in the config: a compiled IR keeps them as ops, and `execute` answers them on the machine it runs on, as `evaluate` there does.
|
|
604
|
+
|
|
605
|
+
A date and time with no zone (`2026-01-01T09:00`) is read in the time zone of the machine that runs Prism: `$date` answers `2026-01-01T08:00:00.000Z` on a server in Vienna and `2026-01-01T17:00:00.000Z` in Los Angeles. A `format` without `utc: true` prints in that zone too: `2026-01-01T09:00Z` with `"format": "HH:mm"` is `10:00` in Vienna and `01:00` in Los Angeles. For the same answer on every server, write the zone into the value (`Z` or `+01:00`) and pass `utc: true` when formatting.
|
|
606
|
+
|
|
579
607
|
### `$date` — Format a date
|
|
580
608
|
```json
|
|
581
609
|
{ "$date": { "value": { "$ref": "$.createdAt" } } }
|
|
@@ -616,6 +644,11 @@ discover it is a reader in Vienna being shown American dates.
|
|
|
616
644
|
All three take an optional `fallback` (default `""`), returned when `value` is
|
|
617
645
|
null or an empty string — before `locale` is even looked at.
|
|
618
646
|
|
|
647
|
+
Some option sets pass the schema and are still refused by `Intl` —
|
|
648
|
+
`dateStyle` beside `weekday`, `minDigits` above `digits`. `$localeDate` and
|
|
649
|
+
`$localeNumber` refuse them as a config Prism cannot run: a `PrismError` with
|
|
650
|
+
`E_SCHEMA`, the op and its place in the config, saying what `Intl` refused.
|
|
651
|
+
|
|
619
652
|
### `$localeMoney` — an amount as money
|
|
620
653
|
```json
|
|
621
654
|
{ "$localeMoney": { "value": { "$ref": "$.price_cents" }, "currency": { "$ref": "$.currency" }, "locale": "de-AT" } }
|
|
@@ -638,7 +671,14 @@ three countries:
|
|
|
638
671
|
- `digits` overrides the currency's own fraction digits.
|
|
639
672
|
- `fallback` (default `""`) is rendered for a null/absent amount, so an empty
|
|
640
673
|
SUM shows a dash rather than a confident `€0.00`.
|
|
641
|
-
-
|
|
674
|
+
- `value` is a number, or text that is a number written in digits (`"1999"`,
|
|
675
|
+
`" 1999 "`), as `$toNumber` reads it. Anything else — a list, `true`, `"0x10"`,
|
|
676
|
+
blank text — is refused with `E_TYPE`. `$localeNumber` reads its `value` the
|
|
677
|
+
same way.
|
|
678
|
+
- An ISO code `Intl` does not know prints beside the number instead of throwing,
|
|
679
|
+
with two fraction digits. So does a locale tag `Intl` cannot read (`"en_GB"`),
|
|
680
|
+
with the currency's own digits: the amount does not depend on the locale, so
|
|
681
|
+
1500 JPY prints `JPY 1500`.
|
|
642
682
|
|
|
643
683
|
### `$localeDate` — a date for a human
|
|
644
684
|
```json
|
|
@@ -650,10 +690,44 @@ three countries:
|
|
|
650
690
|
`timeStyle`, `weekday`, `year`, `month`, `day`, `hour`, `minute`, `second`,
|
|
651
691
|
`hour12`, `timeZone`). Defaults to `{ "dateStyle": "medium" }`.
|
|
652
692
|
|
|
693
|
+
**The zone and the locale may be read, not only written.** `locale` and
|
|
694
|
+
`options.timeZone` are nodes like `value`: a mapping words a date where its
|
|
695
|
+
reader is, from whatever the source carries.
|
|
696
|
+
|
|
697
|
+
```json
|
|
698
|
+
{ "$localeDate": { "value": { "$ref": "$.at" }, "locale": { "$ref": "$.locale" }, "options": { "timeStyle": "short", "timeZone": { "$ref": "$.zone" } } } }
|
|
699
|
+
```
|
|
700
|
+
|
|
701
|
+
A zone written in the program is text, or an op that reads one: anything else
|
|
702
|
+
there (a number, `null`, an object without a `$` key) is refused as the config
|
|
703
|
+
is read, as it always was. The JSON Schema (`getConfigJsonSchema`, a profile's)
|
|
704
|
+
says only "a node" there and does not carry this rule, as it does not carry a
|
|
705
|
+
`$ref` path's; `validate` and `compile` do. Where there is a date to word, the zone, written or
|
|
706
|
+
read, must be one `Intl` knows once it is evaluated — an IANA name such as
|
|
707
|
+
`"Europe/Vienna"`. Anything else — an unknown name, `""`, `null`, a number — is
|
|
708
|
+
refused with `E_TYPE` at `$localeDate.options.timeZone`, saying what it got. A
|
|
709
|
+
fallback is the author's to write: for a zone that may be `null`,
|
|
710
|
+
`{ "$coalesce": [{ "$ref": "$.zone" }, "UTC"] }` (an empty one is still
|
|
711
|
+
refused). A bad date is refused (`E_DATE_INVALID`) before the zone is looked
|
|
712
|
+
at. A config with a bound zone compiles once: its fingerprint does not depend
|
|
713
|
+
on the zone, and `execute` reads the zone from each source it is run on. A
|
|
714
|
+
written zone is kept for the run too, as every date and locale op is (see
|
|
715
|
+
"Worked out where it runs" under Time Operations).
|
|
716
|
+
|
|
717
|
+
**A locale, written or read, is a tag `Intl` can read.** One that is not text,
|
|
718
|
+
or text `Intl` cannot read as a locale tag (`"en_GB"`, `"not a locale!"`), is
|
|
719
|
+
refused with `E_TYPE` at `locale` by `$localeDate` and `$localeNumber`, saying
|
|
720
|
+
what it got. A well-formed tag `Intl` has no data for (`"xx-YY"`) is read as
|
|
721
|
+
`Intl` reads it, falling back to a locale it has. `$localeMoney` refuses a
|
|
722
|
+
locale that is not text and prints the code beside the amount for one `Intl`
|
|
723
|
+
cannot read, as it always did (see its caveat above). Where both the zone and
|
|
724
|
+
the locale are bad, the zone is refused first.
|
|
725
|
+
|
|
653
726
|
**DATE-only values are read as UTC.** `"2026-03-14"` is UTC midnight, and
|
|
654
727
|
formatting UTC midnight in any zone west of Greenwich prints the 13th. Every
|
|
655
728
|
date column in a schema has this shape, so the trap is handled once here rather
|
|
656
|
-
than rediscovered at each call site. An explicit `timeZone
|
|
729
|
+
than rediscovered at each call site. An explicit `timeZone`, written or read,
|
|
730
|
+
still wins.
|
|
657
731
|
|
|
658
732
|
### `$localeNumber` — a number
|
|
659
733
|
```json
|
|
@@ -661,7 +735,8 @@ than rediscovered at each call site. An explicit `timeZone` still wins.
|
|
|
661
735
|
{ "$localeNumber": { "value": { "$ref": "$.rate" }, "locale": "en-GB", "style": "percent" } }
|
|
662
736
|
```
|
|
663
737
|
|
|
664
|
-
`
|
|
738
|
+
`value` is a number or numeric text, as for `$localeMoney`. `style` is
|
|
739
|
+
`decimal` (default) or `percent` — percent multiplies by 100, so pass
|
|
665
740
|
`0.42`, not `42`. `digits`/`minDigits` cap and floor the fraction digits;
|
|
666
741
|
`compact` gives `1.2k`. Grouping and the decimal mark follow the locale
|
|
667
742
|
(`1.234,5` in Germany, `1 234,5` in Austria, `1,234.5` in Britain).
|
|
@@ -695,7 +770,7 @@ Empty array → `0`.
|
|
|
695
770
|
{ "$min": { "over": { "$ref": "$.prices" } } }
|
|
696
771
|
{ "$max": { "over": { "$ref": "$.scores" } } }
|
|
697
772
|
```
|
|
698
|
-
Empty array → `null`.
|
|
773
|
+
Empty array → `null`. A `null` item is skipped wherever it is: `[3, null, 1]` and `[null, 3, 1]` both give `1`, and a list of nulls gives `null`. Each item costs 9 steps of `maxSteps`.
|
|
699
774
|
|
|
700
775
|
### `$pluck` — Extract a field from each element
|
|
701
776
|
```json
|
|
@@ -748,6 +823,8 @@ const result2 = execute(ir, source2); // Each op's handler already attached
|
|
|
748
823
|
|
|
749
824
|
The IR is JSON-serializable — store it in a database, cache in Redis, send over a wire.
|
|
750
825
|
|
|
826
|
+
The date and locale ops stay ops in the IR, even on written values: an IR compiled in Vienna and executed in Los Angeles answers in Los Angeles's zone, as `evaluate` there does. An IR stored by an earlier release keeps whatever it worked out then until it is compiled again.
|
|
827
|
+
|
|
751
828
|
**A constant in an answer is frozen.** Every `execute` of an IR hands out the IR's own constants: a `$const` that is a list or an object, and anything the compiler worked out ahead of time because it did not depend on the source (`{ "$split": { "value": "a,b", "sep": "," } }` is a constant list). They are frozen, all the way down, so one caller cannot change what the next is given: `answer.tags.push(x)` on a list that came from `{ "$const": [] }` throws a `TypeError`. To change an answer, copy the part first (`[...answer.tags, x]`). Everything built for the call — a template's object, a `$map`'s list — is the caller's own. `evaluate` does not freeze: what it answers may be changed.
|
|
752
829
|
|
|
753
830
|
## evaluate
|
|
@@ -812,10 +889,22 @@ third argument: a `Partial<Limits>`, merged over `DEFAULT_LIMITS`:
|
|
|
812
889
|
| `maxStringLength` | `1_000_000` | Characters in any one string a node produces |
|
|
813
890
|
| `maxValues` | `1_000_000` | Values (scalars, array items, object fields) in a `$reduce` accumulator, a `$with` binding, or the result |
|
|
814
891
|
|
|
892
|
+
A config that `evaluate` keeps and runs again spends on every call the steps
|
|
893
|
+
its first call spent: a part worked out ahead of time from the second call
|
|
894
|
+
(a `$join` of 600 written parts) still costs the nodes it took. `execute` counts
|
|
895
|
+
such a part of a compiled IR as one step, since the IR is JSON and carries no
|
|
896
|
+
record of what working it out cost.
|
|
897
|
+
|
|
815
898
|
Past any of them the evaluation throws `E_BUDGET`. `maxValues` counts a value
|
|
816
899
|
each time it appears, as it would be serialized: a `$reduce` whose body is
|
|
817
900
|
`[{ "$var": "acc" }, { "$var": "acc" }]` doubles its count with every item.
|
|
818
901
|
|
|
902
|
+
A source nested deeper than the call stack reaches (tens of thousands of levels
|
|
903
|
+
in Node) also throws `E_BUDGET` once the evaluation walks it. That stack has no
|
|
904
|
+
limit to set; in Firefox the engine's own error comes through instead. A source that contains
|
|
905
|
+
itself is not JSON: with `check: 'always'` it is refused as `E_TYPE`, naming
|
|
906
|
+
where it refers back; unchecked, walking it stops with the same `E_BUDGET`.
|
|
907
|
+
|
|
819
908
|
## Error Codes
|
|
820
909
|
|
|
821
910
|
| Code | Meaning |
|
|
@@ -828,7 +917,7 @@ each time it appears, as it would be serialized: a `$reduce` whose body is
|
|
|
828
917
|
| `E_VAR_NOT_FOUND` | `$var` references undefined variable |
|
|
829
918
|
| `E_NODE_SHAPE` | A node no op answers to, in a tree that never went through the schema |
|
|
830
919
|
| `E_ASSERT` | A config's own `$assert` refused its input |
|
|
831
|
-
| `E_BUDGET` | Evaluation went past a limit (see Limits) |
|
|
920
|
+
| `E_BUDGET` | Evaluation went past a limit, or nested past the call stack (see Limits) |
|
|
832
921
|
|
|
833
922
|
All errors are instances of `PrismError` with `.code` and optional `.context`.
|
|
834
923
|
|
package/dist/agent.cjs
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
'use strict';
|
|
2
2
|
|
|
3
|
-
var
|
|
4
|
-
var
|
|
3
|
+
var chunkNBU7EBGN_cjs = require('./chunk-NBU7EBGN.cjs');
|
|
4
|
+
var chunkVXU22DMV_cjs = require('./chunk-VXU22DMV.cjs');
|
|
5
5
|
var zod = require('zod');
|
|
6
6
|
var cortex = require('@niscorp/cortex');
|
|
7
7
|
|
|
@@ -21,7 +21,7 @@ Worked example (illustrative only \u2014 read the schema for op details):
|
|
|
21
21
|
INPUT { "sampleInput": { "first": "Ada", "last": "Lovelace" }, "targetShape": { "fullName": "" } }
|
|
22
22
|
data { "fullName": { "$interpolate": { "template": "{{f}} {{l}}", "values": { "f": { "$ref": "$.first" }, "l": { "$ref": "$.last" } } } } }`;
|
|
23
23
|
var OUTPUT_DOC = `OUTPUT SCHEMA \u2014 your output MUST validate against this JSON Schema:
|
|
24
|
-
${JSON.stringify(
|
|
24
|
+
${JSON.stringify(chunkNBU7EBGN_cjs.getProfileJsonSchema(chunkNBU7EBGN_cjs.MAPPING_OPS, "draft-7"))}`;
|
|
25
25
|
var mappingAgent = cortex.defineAgent({
|
|
26
26
|
id: "prism.mapping",
|
|
27
27
|
description: "Generates a Prism transformation config from a sample input row and a target shape.",
|
|
@@ -29,7 +29,7 @@ var mappingAgent = cortex.defineAgent({
|
|
|
29
29
|
// Validated against the full grammar, documented with the mapping profile:
|
|
30
30
|
// a config using an op outside the profile is still accepted. The doc keeps
|
|
31
31
|
// cortex's own heading, "OUTPUT SCHEMA", which its finish protocol names.
|
|
32
|
-
output: { schema:
|
|
32
|
+
output: { schema: chunkVXU22DMV_cjs.ConfigSchema, doc: OUTPUT_DOC }
|
|
33
33
|
});
|
|
34
34
|
|
|
35
35
|
exports.MappingAgentInputSchema = MappingAgentInputSchema;
|
package/dist/agent.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { getProfileJsonSchema, MAPPING_OPS } from './chunk-
|
|
2
|
-
import { ConfigSchema } from './chunk-
|
|
1
|
+
import { getProfileJsonSchema, MAPPING_OPS } from './chunk-ZMMUIMAK.js';
|
|
2
|
+
import { ConfigSchema } from './chunk-E44DNCG3.js';
|
|
3
3
|
import { z } from 'zod';
|
|
4
4
|
import { defineAgent } from '@niscorp/cortex';
|
|
5
5
|
|