@niscorp/prism 0.1.1 → 0.2.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 CHANGED
@@ -1,5 +1,26 @@
1
1
  # @niscorp/prism
2
2
 
3
+ ## 0.2.0
4
+
5
+ ### Minor Changes
6
+
7
+ - f1cec45: A Prism config that validates no longer names an op Prism does not have. `validate` accepted `{ card: { $fetch: … } }` and `{ $eval: "…" }`: the plain-object branch refused only the names of ops that exist, so any other `$` key passed as a template key. Such a config could be stored — an endpoint request, a vex mapping, a strata migration — and then failed every time it was evaluated (`E_NODE_SHAPE`, "Unsupported node shape").
8
+
9
+ A key that starts with `$` is now an op's name and nothing else. The template branch refuses every `$` key — the rule the evaluator already held — so `validate` reports it with the key and where it is (`card.$fetch: Not a Prism op. A key that starts with "$" names an op; data with such a key goes in $const.`), and `evaluate` and `compile` fail with `E_SCHEMA` before anything runs. An op's name used as a template key keeps its own message. `E_NODE_SHAPE` is left for a tree that never went through the schema: an IR handed to `execute`. Adding an op no longer takes a key away from templates.
10
+ - **prism** — the change, and a grammar narrowing: `nisc.prism` 2, a marker with no document step (a key that never evaluated has nothing to be rewritten to). `$` keys that are data are untouched: a `$const` payload, `$with` names, `$renameKeys` and `$fromEntries` keys. The JSON Schema's template key pattern is `^(?!\$)` instead of a list of every op.
11
+ - **nova, vex, moss, loom, cli, nisc** — no change of their own. They depend on prism and are released with it, so the set installs together; the configs they hand to prism (endpoint `request` and `response`, `$prism` bindings, vex mappings) are held to the same rule.
12
+ - **create-nisc** — the templates' sources are recorded at `nisc.prism` 2.
13
+
14
+ **What to change:** in a config with a `$`-prefixed key that is not a Prism op, remove the key — or put the object in `$const` if it is literal data. An app that keeps a `strata.lock.json` runs `pnpm strata upgrade`, then `pnpm strata verify`; there is nothing to edit unless it has such a config. Everything else: nothing.
15
+
16
+ BREAKING — approved by moccadroid, 2026-10-04: a config with a `$`-prefixed key that is not a Prism op no longer validates, compiles or evaluates — also where evaluation never reached the key (an untaken `$case` branch, a short-circuited `$or`, a `$map` body over an empty array), which used to work. A vex seed mapping with one fails when it is seeded, at boot, instead of on each replay. Code that matched `E_NODE_SHAPE` from `evaluate` gets `E_SCHEMA`. The `@niscorp` packages that depend on prism move with it, so an app moves them together (`@niscorp/nisc` 0.3.0).
17
+
18
+ ## 0.1.2
19
+
20
+ ### Patch Changes
21
+
22
+ - b67a125: Documentation only: each package's README, reference and design docs checked against its source and corrected — install lines and peers, signatures, defaults, status codes, licenses (loom, signal: Apache-2.0), and API that existed but was not documented.
23
+
3
24
  ## 0.1.1
4
25
 
5
26
  ### Patch Changes
package/DESIGN.md CHANGED
@@ -30,7 +30,7 @@ Input Config (JSON)
30
30
 
31
31
  ### Four Layers
32
32
 
33
- **Schema** — Every op is a Zod schema with `.strict()` and `.describe()`. The top-level `NodeSchema` is a recursive union of ~50 op schemas plus primitives, arrays, and plain objects. Schemas are the source of truth for validation and JSON Schema generation (for LLM consumption).
33
+ **Schema** — Every op is a Zod schema with `.strict()` and `.describe()`. The top-level `NodeSchema` is a recursive union of ~70 op schemas plus primitives, arrays, and plain objects. Schemas are the source of truth for validation and JSON Schema generation (for LLM consumption).
34
34
 
35
35
  **Sugar** — Convenience ops (`$sum`, `$avg`, `$pluck`, etc.) are rewritten to core ops in a single recursive pass before evaluation or compilation. This means the evaluator and compiler only need to handle core ops. Sugar rewriters receive a `recurse` function to transform their sub-expressions.
36
36
 
@@ -44,8 +44,9 @@ Input Config (JSON)
44
44
 
45
45
  ```typescript
46
46
  type EvalContext = {
47
- source: JsonObject; // Root source data (immutable)
47
+ source: JsonValue; // Root source data (immutable)
48
48
  vars: Record<string, JsonValue>; // Scoped variables (immutable)
49
+ budget?: Budget; // What this evaluation may still cost (engine/budget.ts)
49
50
  };
50
51
  ```
51
52
 
@@ -68,7 +69,7 @@ The evaluator uses a linear if-chain with type guards:
68
69
  ```typescript
69
70
  if (isRefNode(obj)) return opRef(obj, context, evaluateNode);
70
71
  if (isMapNode(obj)) return opMap(obj, context, evaluateNode);
71
- // ... ~50 more
72
+ // ... ~60 more
72
73
  ```
73
74
 
74
75
  A Map-based dispatch would be shorter but loses type narrowing — each guard narrows the node to its specific type, so the handler receives a correctly typed argument without casts.
@@ -81,6 +82,8 @@ Objects without `$`-prefixed keys are output templates. Each value is recursivel
81
82
 
82
83
  This enables partial results from incomplete source data without try/catch wrapping every field.
83
84
 
85
+ The schema and the evaluator hold 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. Until `nisc.prism` 2 the pattern refused only the names of ops that existed, and each new op took a name away from templates; reserving the prefix means adding an op narrows nothing. Data that has `$` keys is a `$const` payload.
86
+
84
87
  ---
85
88
 
86
89
  ## JSONPath Subset
@@ -102,14 +105,14 @@ type CompiledIr = {
102
105
  meta: {
103
106
  name?: string;
104
107
  createdAt: string;
105
- fingerprint: string; // SHA256 of desugared config
106
- stats: { nodeCount, opCount, maxDepth };
108
+ fingerprint: string; // SHA256 of the desugared, optimized core
109
+ stats: { nodeCount, opCount, maxDepth, optimizations };
107
110
  };
108
111
  tables: {
109
112
  paths: string[]; // JSONPaths for cache priming
110
113
  strings: string[]; // String literals
111
114
  };
112
- core: Config; // Desugared config
115
+ core: unknown; // Desugared, optimized config
113
116
  };
114
117
  ```
115
118
 
@@ -131,7 +134,9 @@ All errors are `PrismError` instances with a `.code` string and optional `.conte
131
134
  | `E_DIVISION_BY_ZERO` | `$div` with divisor 0 |
132
135
  | `E_DATE_INVALID` | Unparseable date value |
133
136
  | `E_VAR_NOT_FOUND` | `$var` references undefined variable |
134
- | `E_NODE_SHAPE` | Unrecognized node structure |
137
+ | `E_NODE_SHAPE` | A node no op answers to, in a tree that skipped the schema (an IR given to `execute`) |
138
+ | `E_ASSERT` | A config's own `$assert` refused its input |
139
+ | `E_BUDGET` | An evaluation went past its budget (`engine/budget.ts`) |
135
140
 
136
141
  ---
137
142
 
@@ -148,6 +153,7 @@ src/
148
153
  │ ├── node.schema.ts # NodeSchema (recursive union of all ops)
149
154
  │ ├── config.schema.ts # ConfigSchema
150
155
  │ ├── guards.ts # Type guards (isRefNode, isMapNode, etc.)
156
+ │ ├── profiles.ts # Named op subsets for documentation (MAPPING_OPS)
151
157
  │ └── ops/ # One schema file per category
152
158
  │ ├── core.schema.ts
153
159
  │ ├── array.schema.ts
@@ -158,10 +164,14 @@ src/
158
164
  │ ├── structure.schema.ts
159
165
  │ ├── object.schema.ts
160
166
  │ ├── time.schema.ts
167
+ │ ├── intl.schema.ts
168
+ │ ├── transform.schema.ts
161
169
  │ └── sugar.schema.ts
162
170
  ├── engine/
163
171
  │ ├── evaluate.ts # Dispatcher + evaluate / evaluateSafe
164
172
  │ ├── compile.ts # Config → CompiledIr
173
+ │ ├── optimize.ts # Compile-time passes (ref segments, handlers, constant folding)
174
+ │ ├── budget.ts # Limits: steps, string length, result size
165
175
  │ ├── execute.ts # CompiledIr + source → result
166
176
  │ ├── validate.ts # Config validation
167
177
  │ └── documentation.ts # JSON Schema generation
@@ -174,21 +184,31 @@ src/
174
184
  │ ├── logic.ops.ts
175
185
  │ ├── structure.ops.ts
176
186
  │ ├── object.ops.ts
177
- │ └── time.ops.ts
187
+ │ ├── time.ops.ts
188
+ │ ├── intl.ops.ts
189
+ │ └── transform.ops.ts
178
190
  ├── sugar/
179
191
  │ ├── desugar.ts # Recursive desugaring pass
180
192
  │ └── rewriters.ts # Sugar → core rewrite functions
193
+ ├── agent/ # @niscorp/prism/agent
194
+ │ ├── index.ts
195
+ │ └── mapping-agent.ts # mappingAgent (Cortex agent definition)
196
+ ├── migrations/
197
+ │ └── index.ts # @niscorp/prism/migrations — PRISM_SEQUENCE, prismTransform
181
198
  └── utils/
182
199
  ├── jsonpath.ts # JSONPath parser + cache
183
- └── compare.ts # Deep equality, ordered comparison
200
+ ├── compare.ts # Deep equality, ordered comparison
201
+ └── issues.ts # Zod issues → the branch the config meant
184
202
  ```
185
203
 
186
204
  ---
187
205
 
188
206
  ## Dependencies
189
207
 
190
- - `zod` (peer, ^4.0.0) — Schema validation, JSON Schema generation via `z.toJSONSchema()`
191
- - `dayjs` (^1.11.0) — Date operations (`$date`, `$dateAdd`, `$dateDiff`)
208
+ - `zod` (peer, ^4.2.0) — Schema validation, JSON Schema generation via `z.toJSONSchema()`
209
+ - `@niscorp/strata` (peer) — the depth guard on configs, and the sequence type behind `@niscorp/prism/migrations`
210
+ - `@niscorp/cortex`, `@niscorp/signal` (optional peers) — only for `@niscorp/prism/agent`
211
+ - `dayjs` (^1.11.20) — Date operations (`$date`, `$dateAdd`, `$dateDiff`)
192
212
 
193
213
  The locale-aware family (`$localeDate`, `$localeMoney`, `$localeNumber`) adds
194
214
  **no** dependency: it delegates to the platform's `Intl`. That is why dayjs
package/DOCS.md CHANGED
@@ -14,13 +14,15 @@ A Prism config is a JSON structure that describes a transformation. It can be:
14
14
  - A **plain object** (`{ name: { $ref: "$.user.name" } }`) — each value evaluated recursively
15
15
  - An **array** (`[{ $const: 1 }, { $ref: "$.x" }]`) — each element evaluated
16
16
 
17
+ A key that starts with `$` is an op's name. A plain object has none: `{ "$fetch": … }` is not a config, because Prism has no `$fetch` — `validate` refuses it with the key's path (`card.$fetch`), and `evaluate` and `compile` fail with `E_SCHEMA` before anything runs. Data that has such keys goes in `$const`, which returns its value untouched; `$fromEntries` builds one from computed values.
18
+
17
19
  ### Source Data
18
20
 
19
- Every evaluation takes a `source` object — the data the transformation reads from via `$ref`.
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.
20
22
 
21
23
  ### Bindings and Variables
22
24
 
23
- `$ref` reads from source. `$var` reads from scoped variables created by `$with`, `$map`, `$filter`, `$reduce`, and `$sortBy`.
25
+ `$ref` reads from source. `$var` reads from scoped variables created by `$with`, `$map`, `$filter`, `$reduce`, `$sortBy`, `$keyBy`, `$groupBy`, `$update`, and `$walk`.
24
26
 
25
27
  ### Optional Fields
26
28
 
@@ -87,7 +89,7 @@ Navigates into a value using an array of path segments. Segments can be strings
87
89
  { "$get": { "from": { "$ref": "$.data" }, "path": ["missing"], "fallback": { "$const": "N/A" } } }
88
90
  ```
89
91
 
90
- Without `fallback`, throws `E_MISSING_PATH`. With `fallback`, returns the fallback value instead.
92
+ Without `fallback`, throws `E_MISSING_PATH` when the path is missing, and `E_TYPE` when a key is asked of a non-object or an index of a non-array. With `fallback`, returns the fallback value in either case.
91
93
 
92
94
  Dynamic segments:
93
95
  ```json
@@ -282,6 +284,14 @@ Numbers → `"42"`, null → `"null"`, objects → JSON string.
282
284
  ```
283
285
  Replaces `{{key}}` placeholders with values from the evaluated object. Missing keys become empty strings.
284
286
 
287
+ ### `$fill` — Fill a counted phrase
288
+ ```json
289
+ { "$fill": { "$ref": "$.progress" } }
290
+ ```
291
+ Source: `{ "progress": { "phrase": "{n} of {total}", "slots": { "n": 1, "total": 12 } } }` → `"1 of 12"`
292
+
293
+ 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.
294
+
285
295
  ### `$trim`
286
296
  ```json
287
297
  { "$trim": { "$const": " hello " } }
@@ -545,7 +555,7 @@ removal. Changes to the grammar are strata migrations on `nisc.prism`
545
555
 
546
556
  ## Time Operations
547
557
 
548
- Powered by [dayjs](https://day.js.org/). Date values can be ISO 8601 strings or Unix timestamps (milliseconds).
558
+ 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.
549
559
 
550
560
  ### `$date` — Format a date
551
561
  ```json
@@ -564,7 +574,7 @@ reads: for that, use `$localeDate` below.
564
574
  { "$dateAdd": { "date": { "$ref": "$.startDate" }, "amount": 30, "unit": "day" } }
565
575
  { "$dateAdd": { "date": { "$ref": "$.now" }, "amount": -1, "unit": "hour" } }
566
576
  ```
567
- Returns ISO 8601 string. Units: `year`, `month`, `day`, `hour`, `minute`, `second`.
577
+ Returns ISO 8601 string — or, when the input is a date-only string (`"2026-06-01"`), a date-only string (`"2026-07-01"`). Units: `year`, `month`, `day`, `hour`, `minute`, `second`.
568
578
 
569
579
  ### `$dateDiff` — Date difference
570
580
  ```json
@@ -584,6 +594,9 @@ CLDR rather than from a table in this package.
584
594
  renders something plausible for everybody it is wrong for, and the only way to
585
595
  discover it is a reader in Vienna being shown American dates.
586
596
 
597
+ All three take an optional `fallback` (default `""`), returned when `value` is
598
+ null or an empty string — before `locale` is even looked at.
599
+
587
600
  ### `$localeMoney` — an amount as money
588
601
  ```json
589
602
  { "$localeMoney": { "value": { "$ref": "$.price_cents" }, "currency": { "$ref": "$.currency" }, "locale": "de-AT" } }
@@ -650,7 +663,7 @@ Desugars to `$reduce` + `$add`. Empty array → `0`.
650
663
  ```json
651
664
  { "$avg": { "over": { "$ref": "$.scores" } } }
652
665
  ```
653
- Desugars to `$div($sum, $count)`.
666
+ Desugars to `$div($sum, $count)`. Empty array → `E_DIVISION_BY_ZERO`.
654
667
 
655
668
  ### `$count` — Count elements
656
669
  ```json
@@ -707,7 +720,7 @@ const ir = await compile(config, { name: 'user-transform', version: '1.0.0' });
707
720
  // ir contains:
708
721
  // - Desugared config (sugar ops already resolved)
709
722
  // - SHA256 fingerprint (for cache invalidation)
710
- // - Stats (node count, op frequency, max depth)
723
+ // - Stats (node count, op frequency, max depth, optimizations applied)
711
724
  // - Tables (all JSONPaths and string literals for cache priming)
712
725
 
713
726
  const result1 = execute(ir, source1); // No validation, no desugaring
@@ -716,16 +729,33 @@ const result2 = execute(ir, source2); // 2-5x faster than evaluate()
716
729
 
717
730
  The IR is JSON-serializable — store it in a database, cache in Redis, send over a wire.
718
731
 
732
+ ## Limits
733
+
734
+ `evaluate`, `evaluateSafe` and `execute` take an optional third argument, a
735
+ `Partial<Limits>`, merged over `DEFAULT_LIMITS`:
736
+
737
+ | Limit | Default | Counts |
738
+ |-------|---------|--------|
739
+ | `maxSteps` | `1_000_000` | Nodes evaluated in one evaluation |
740
+ | `maxStringLength` | `1_000_000` | Characters in any one string a node produces |
741
+ | `maxValues` | `1_000_000` | Values (scalars, array items, object fields) in a `$reduce` accumulator, a `$with` binding, or the result |
742
+
743
+ Past any of them the evaluation throws `E_BUDGET`.
744
+
719
745
  ## Error Codes
720
746
 
721
747
  | Code | Meaning |
722
748
  |------|---------|
723
- | `E_SCHEMA` | Config failed Zod validation |
749
+ | `E_SCHEMA` | Config failed Zod validation — a malformed op, or a `$` key that is not an op |
724
750
  | `E_MISSING_PATH` | `$ref` or `$get` path doesn't exist (and no fallback) |
725
751
  | `E_TYPE` | Wrong type for operation (e.g. `$map.over` is not an array) |
726
752
  | `E_DIVISION_BY_ZERO` | `$div` with divisor 0 |
727
753
  | `E_DATE_INVALID` | Invalid date value |
728
754
  | `E_VAR_NOT_FOUND` | `$var` references undefined variable |
729
- | `E_NODE_SHAPE` | Unrecognized node structure |
755
+ | `E_NODE_SHAPE` | A node no op answers to, in a tree that never went through the schema |
756
+ | `E_ASSERT` | A config's own `$assert` refused its input |
757
+ | `E_BUDGET` | Evaluation went past a limit (see Limits) |
730
758
 
731
759
  All errors are instances of `PrismError` with `.code` and optional `.context`.
760
+
761
+ **Valid, and what it does not promise.** `validate`, `evaluate` and `compile` hold a config to the same schema, so a config that validates has no node the evaluator cannot dispatch: every object in it is an op Prism has or a plain object with no `$` key. It can still fail on the data it is given — a missing path, a wrong type, a budget. `E_NODE_SHAPE` is what is left for a tree the schema never saw: an IR handed to `execute`, which does not validate.
package/README.md CHANGED
@@ -7,9 +7,13 @@ Transformations are JSON objects — no code strings, no `eval`, no security ris
7
7
  ## Install
8
8
 
9
9
  ```bash
10
- pnpm add @niscorp/prism zod
10
+ pnpm add @niscorp/prism @niscorp/strata zod
11
11
  ```
12
12
 
13
+ `@niscorp/strata` and `zod` are required peers. `@niscorp/cortex` and
14
+ `@niscorp/signal` are optional — only the mapping agent at
15
+ `@niscorp/prism/agent` (`mappingAgent`) needs them.
16
+
13
17
  ## Quick Example
14
18
 
15
19
  ```typescript
@@ -46,12 +50,12 @@ const result = evaluate(
46
50
 
47
51
  ```typescript
48
52
  // One-shot evaluation
49
- evaluate(config, source) → JsonValue
50
- evaluateSafe(config, source) → { ok: true, data } | { ok: false, error }
53
+ evaluate(config, source, limits?) → JsonValue
54
+ evaluateSafe(config, source, limits?) → { ok: true, data } | { ok: false, error }
51
55
 
52
56
  // Compile once, execute many (2-5x faster for repeated configs)
53
57
  compile(config, options?) → Promise<CompiledIr>
54
- execute(ir, source) → JsonValue
58
+ execute(ir, source, limits?) → JsonValue
55
59
 
56
60
  // Validation
57
61
  validate(config) → { ok: true, data } | { ok: false, issues }
package/dist/agent.cjs CHANGED
@@ -496,7 +496,9 @@ var OP_KEYS = [
496
496
  "$walk"
497
497
  ];
498
498
  var OPTIONAL_FIELDS_KEY = "__optional";
499
- var NOT_AN_OP_KEY = new RegExp(`^(?!(?:${OP_KEYS.map((k) => k.replace(/\$/g, "\\$")).join("|")})$)`);
499
+ var TEMPLATE_KEY = /^(?!\$)/;
500
+ var isOpKey = (key) => OP_KEYS.some((op) => op === key);
501
+ var templateKeyRefusal = (key) => isOpKey(key) ? "An op name cannot be a plain object key. Use the op itself." : 'Not a Prism op. A key that starts with "$" names an op; data with such a key goes in $const.';
500
502
  var hasValidOptionalMeta = (obj) => {
501
503
  const meta = obj[OPTIONAL_FIELDS_KEY];
502
504
  if (meta === void 0) return true;
@@ -594,14 +596,14 @@ var NodeSchema = zod.z.lazy(
594
596
  JsonPrimitiveSchema,
595
597
  // Arrays of nodes
596
598
  zod.z.array(zod.z.lazy(() => NodeSchema)),
597
- // Plain objects (no op keys, recursive values)
598
- // An op's name is not a template key. Said in the KEY schema, not a
599
+ // Plain objects (no `$` keys, recursive values)
600
+ // A `$` key is not a template key. Said in the KEY schema, not a
599
601
  // refinement: a refinement leaves this branch structurally matched, and
600
602
  // zod then reports its complaint instead of the union's — so a typo inside
601
603
  // a real op (`{ $get: { pathh } }`) read as "plain object must not contain
602
604
  // $ op keys" at the root. As a key pattern it is also plain JSON Schema
603
605
  // (`propertyNames`), which the grammar snapshot and agent prompts read.
604
- zod.z.record(zod.z.string().regex(NOT_AN_OP_KEY, { message: "An op name cannot be a plain object key. Use the op itself." }), zod.z.lazy(() => NodeSchema)).refine((o) => hasValidOptionalMeta(o), { message: "__optional must be an array of non-empty field name strings." })
606
+ zod.z.record(zod.z.string().regex(TEMPLATE_KEY, { error: (issue) => templateKeyRefusal(issue.input) }), zod.z.lazy(() => NodeSchema)).refine((o) => hasValidOptionalMeta(o), { message: "__optional must be an array of non-empty field name strings." })
605
607
  ]).describe("A Prism node: an op, a plain JSON value, an array of nodes, or a plain object template.")
606
608
  );
607
609
  setNodeSchema(NodeSchema);