@niscorp/prism 0.1.1 → 0.1.2

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,11 @@
1
1
  # @niscorp/prism
2
2
 
3
+ ## 0.1.2
4
+
5
+ ### Patch Changes
6
+
7
+ - 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.
8
+
3
9
  ## 0.1.1
4
10
 
5
11
  ### 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.
@@ -102,14 +103,14 @@ type CompiledIr = {
102
103
  meta: {
103
104
  name?: string;
104
105
  createdAt: string;
105
- fingerprint: string; // SHA256 of desugared config
106
- stats: { nodeCount, opCount, maxDepth };
106
+ fingerprint: string; // SHA256 of the desugared, optimized core
107
+ stats: { nodeCount, opCount, maxDepth, optimizations };
107
108
  };
108
109
  tables: {
109
110
  paths: string[]; // JSONPaths for cache priming
110
111
  strings: string[]; // String literals
111
112
  };
112
- core: Config; // Desugared config
113
+ core: unknown; // Desugared, optimized config
113
114
  };
114
115
  ```
115
116
 
@@ -132,6 +133,8 @@ All errors are `PrismError` instances with a `.code` string and optional `.conte
132
133
  | `E_DATE_INVALID` | Unparseable date value |
133
134
  | `E_VAR_NOT_FOUND` | `$var` references undefined variable |
134
135
  | `E_NODE_SHAPE` | Unrecognized node structure |
136
+ | `E_ASSERT` | A config's own `$assert` refused its input |
137
+ | `E_BUDGET` | An evaluation went past its budget (`engine/budget.ts`) |
135
138
 
136
139
  ---
137
140
 
@@ -148,6 +151,7 @@ src/
148
151
  │ ├── node.schema.ts # NodeSchema (recursive union of all ops)
149
152
  │ ├── config.schema.ts # ConfigSchema
150
153
  │ ├── guards.ts # Type guards (isRefNode, isMapNode, etc.)
154
+ │ ├── profiles.ts # Named op subsets for documentation (MAPPING_OPS)
151
155
  │ └── ops/ # One schema file per category
152
156
  │ ├── core.schema.ts
153
157
  │ ├── array.schema.ts
@@ -158,10 +162,14 @@ src/
158
162
  │ ├── structure.schema.ts
159
163
  │ ├── object.schema.ts
160
164
  │ ├── time.schema.ts
165
+ │ ├── intl.schema.ts
166
+ │ ├── transform.schema.ts
161
167
  │ └── sugar.schema.ts
162
168
  ├── engine/
163
169
  │ ├── evaluate.ts # Dispatcher + evaluate / evaluateSafe
164
170
  │ ├── compile.ts # Config → CompiledIr
171
+ │ ├── optimize.ts # Compile-time passes (ref segments, handlers, constant folding)
172
+ │ ├── budget.ts # Limits: steps, string length, result size
165
173
  │ ├── execute.ts # CompiledIr + source → result
166
174
  │ ├── validate.ts # Config validation
167
175
  │ └── documentation.ts # JSON Schema generation
@@ -174,21 +182,31 @@ src/
174
182
  │ ├── logic.ops.ts
175
183
  │ ├── structure.ops.ts
176
184
  │ ├── object.ops.ts
177
- │ └── time.ops.ts
185
+ │ ├── time.ops.ts
186
+ │ ├── intl.ops.ts
187
+ │ └── transform.ops.ts
178
188
  ├── sugar/
179
189
  │ ├── desugar.ts # Recursive desugaring pass
180
190
  │ └── rewriters.ts # Sugar → core rewrite functions
191
+ ├── agent/ # @niscorp/prism/agent
192
+ │ ├── index.ts
193
+ │ └── mapping-agent.ts # mappingAgent (Cortex agent definition)
194
+ ├── migrations/
195
+ │ └── index.ts # @niscorp/prism/migrations — PRISM_SEQUENCE, prismTransform
181
196
  └── utils/
182
197
  ├── jsonpath.ts # JSONPath parser + cache
183
- └── compare.ts # Deep equality, ordered comparison
198
+ ├── compare.ts # Deep equality, ordered comparison
199
+ └── issues.ts # Zod issues → the branch the config meant
184
200
  ```
185
201
 
186
202
  ---
187
203
 
188
204
  ## Dependencies
189
205
 
190
- - `zod` (peer, ^4.0.0) — Schema validation, JSON Schema generation via `z.toJSONSchema()`
191
- - `dayjs` (^1.11.0) — Date operations (`$date`, `$dateAdd`, `$dateDiff`)
206
+ - `zod` (peer, ^4.2.0) — Schema validation, JSON Schema generation via `z.toJSONSchema()`
207
+ - `@niscorp/strata` (peer) — the depth guard on configs, and the sequence type behind `@niscorp/prism/migrations`
208
+ - `@niscorp/cortex`, `@niscorp/signal` (optional peers) — only for `@niscorp/prism/agent`
209
+ - `dayjs` (^1.11.20) — Date operations (`$date`, `$dateAdd`, `$dateDiff`)
192
210
 
193
211
  The locale-aware family (`$localeDate`, `$localeMoney`, `$localeNumber`) adds
194
212
  **no** dependency: it delegates to the platform's `Intl`. That is why dayjs
package/DOCS.md CHANGED
@@ -16,11 +16,11 @@ A Prism config is a JSON structure that describes a transformation. It can be:
16
16
 
17
17
  ### Source Data
18
18
 
19
- Every evaluation takes a `source` object — the data the transformation reads from via `$ref`.
19
+ 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
20
 
21
21
  ### Bindings and Variables
22
22
 
23
- `$ref` reads from source. `$var` reads from scoped variables created by `$with`, `$map`, `$filter`, `$reduce`, and `$sortBy`.
23
+ `$ref` reads from source. `$var` reads from scoped variables created by `$with`, `$map`, `$filter`, `$reduce`, `$sortBy`, `$keyBy`, `$groupBy`, `$update`, and `$walk`.
24
24
 
25
25
  ### Optional Fields
26
26
 
@@ -87,7 +87,7 @@ Navigates into a value using an array of path segments. Segments can be strings
87
87
  { "$get": { "from": { "$ref": "$.data" }, "path": ["missing"], "fallback": { "$const": "N/A" } } }
88
88
  ```
89
89
 
90
- Without `fallback`, throws `E_MISSING_PATH`. With `fallback`, returns the fallback value instead.
90
+ 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
91
 
92
92
  Dynamic segments:
93
93
  ```json
@@ -282,6 +282,14 @@ Numbers → `"42"`, null → `"null"`, objects → JSON string.
282
282
  ```
283
283
  Replaces `{{key}}` placeholders with values from the evaluated object. Missing keys become empty strings.
284
284
 
285
+ ### `$fill` — Fill a counted phrase
286
+ ```json
287
+ { "$fill": { "$ref": "$.progress" } }
288
+ ```
289
+ Source: `{ "progress": { "phrase": "{n} of {total}", "slots": { "n": 1, "total": 12 } } }` → `"1 of 12"`
290
+
291
+ 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.
292
+
285
293
  ### `$trim`
286
294
  ```json
287
295
  { "$trim": { "$const": " hello " } }
@@ -545,7 +553,7 @@ removal. Changes to the grammar are strata migrations on `nisc.prism`
545
553
 
546
554
  ## Time Operations
547
555
 
548
- Powered by [dayjs](https://day.js.org/). Date values can be ISO 8601 strings or Unix timestamps (milliseconds).
556
+ 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
557
 
550
558
  ### `$date` — Format a date
551
559
  ```json
@@ -564,7 +572,7 @@ reads: for that, use `$localeDate` below.
564
572
  { "$dateAdd": { "date": { "$ref": "$.startDate" }, "amount": 30, "unit": "day" } }
565
573
  { "$dateAdd": { "date": { "$ref": "$.now" }, "amount": -1, "unit": "hour" } }
566
574
  ```
567
- Returns ISO 8601 string. Units: `year`, `month`, `day`, `hour`, `minute`, `second`.
575
+ 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
576
 
569
577
  ### `$dateDiff` — Date difference
570
578
  ```json
@@ -584,6 +592,9 @@ CLDR rather than from a table in this package.
584
592
  renders something plausible for everybody it is wrong for, and the only way to
585
593
  discover it is a reader in Vienna being shown American dates.
586
594
 
595
+ All three take an optional `fallback` (default `""`), returned when `value` is
596
+ null or an empty string — before `locale` is even looked at.
597
+
587
598
  ### `$localeMoney` — an amount as money
588
599
  ```json
589
600
  { "$localeMoney": { "value": { "$ref": "$.price_cents" }, "currency": { "$ref": "$.currency" }, "locale": "de-AT" } }
@@ -650,7 +661,7 @@ Desugars to `$reduce` + `$add`. Empty array → `0`.
650
661
  ```json
651
662
  { "$avg": { "over": { "$ref": "$.scores" } } }
652
663
  ```
653
- Desugars to `$div($sum, $count)`.
664
+ Desugars to `$div($sum, $count)`. Empty array → `E_DIVISION_BY_ZERO`.
654
665
 
655
666
  ### `$count` — Count elements
656
667
  ```json
@@ -707,7 +718,7 @@ const ir = await compile(config, { name: 'user-transform', version: '1.0.0' });
707
718
  // ir contains:
708
719
  // - Desugared config (sugar ops already resolved)
709
720
  // - SHA256 fingerprint (for cache invalidation)
710
- // - Stats (node count, op frequency, max depth)
721
+ // - Stats (node count, op frequency, max depth, optimizations applied)
711
722
  // - Tables (all JSONPaths and string literals for cache priming)
712
723
 
713
724
  const result1 = execute(ir, source1); // No validation, no desugaring
@@ -716,6 +727,19 @@ const result2 = execute(ir, source2); // 2-5x faster than evaluate()
716
727
 
717
728
  The IR is JSON-serializable — store it in a database, cache in Redis, send over a wire.
718
729
 
730
+ ## Limits
731
+
732
+ `evaluate`, `evaluateSafe` and `execute` take an optional third argument, a
733
+ `Partial<Limits>`, merged over `DEFAULT_LIMITS`:
734
+
735
+ | Limit | Default | Counts |
736
+ |-------|---------|--------|
737
+ | `maxSteps` | `1_000_000` | Nodes evaluated in one evaluation |
738
+ | `maxStringLength` | `1_000_000` | Characters in any one string a node produces |
739
+ | `maxValues` | `1_000_000` | Values (scalars, array items, object fields) in a `$reduce` accumulator, a `$with` binding, or the result |
740
+
741
+ Past any of them the evaluation throws `E_BUDGET`.
742
+
719
743
  ## Error Codes
720
744
 
721
745
  | Code | Meaning |
@@ -727,5 +751,7 @@ The IR is JSON-serializable — store it in a database, cache in Redis, send ove
727
751
  | `E_DATE_INVALID` | Invalid date value |
728
752
  | `E_VAR_NOT_FOUND` | `$var` references undefined variable |
729
753
  | `E_NODE_SHAPE` | Unrecognized node structure |
754
+ | `E_ASSERT` | A config's own `$assert` refused its input |
755
+ | `E_BUDGET` | Evaluation went past a limit (see Limits) |
730
756
 
731
757
  All errors are instances of `PrismError` with `.code` and optional `.context`.
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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@niscorp/prism",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Pure JSON transformation DSL with compilation and zero code execution",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",
@@ -77,9 +77,9 @@
77
77
  },
78
78
  "peerDependencies": {
79
79
  "zod": "^4.2.0",
80
- "@niscorp/cortex": "^0.1.0",
81
- "@niscorp/signal": "^0.1.0",
82
- "@niscorp/strata": "^0.1.0"
80
+ "@niscorp/cortex": "^0.1.1",
81
+ "@niscorp/signal": "^0.1.1",
82
+ "@niscorp/strata": "^0.1.1"
83
83
  },
84
84
  "peerDependenciesMeta": {
85
85
  "@niscorp/cortex": {
@@ -93,9 +93,9 @@
93
93
  "tsup": "^8.5.1",
94
94
  "vitest": "^4.1.2",
95
95
  "zod": "^4.6.5",
96
- "@niscorp/signal": "^0.1.0",
97
- "@niscorp/strata": "^0.1.0",
98
- "@niscorp/cortex": "^0.1.0"
96
+ "@niscorp/signal": "^0.1.1",
97
+ "@niscorp/strata": "^0.1.1",
98
+ "@niscorp/cortex": "^0.1.1"
99
99
  },
100
100
  "scripts": {
101
101
  "build": "tsup",