@niscorp/prism 0.1.0 → 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 +13 -0
- package/DESIGN.md +28 -10
- package/DOCS.md +33 -7
- package/README.md +8 -4
- package/package.json +7 -10
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# @niscorp/prism
|
|
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
|
+
|
|
9
|
+
## 0.1.1
|
|
10
|
+
|
|
11
|
+
### Patch Changes
|
|
12
|
+
|
|
13
|
+
- 534eb4b: `@niscorp/strata` is a required peer: nova's shell and layout store and Prism's engine import its document-depth limit at load time, and with strata declared optional an app installing nova or Prism without it crashed on import. `check:packages` now follows every built entry's imports and refuses an undeclared one, or an optional peer loaded by a main entry.
|
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 ~
|
|
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:
|
|
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
|
-
// ... ~
|
|
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
|
|
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:
|
|
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
|
-
│
|
|
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
|
-
|
|
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.
|
|
191
|
-
- `
|
|
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`
|
|
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 `$
|
|
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
|
|
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.
|
|
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/
|
|
81
|
-
"@niscorp/
|
|
82
|
-
"@niscorp/strata": "^0.1.
|
|
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": {
|
|
@@ -87,18 +87,15 @@
|
|
|
87
87
|
},
|
|
88
88
|
"@niscorp/signal": {
|
|
89
89
|
"optional": true
|
|
90
|
-
},
|
|
91
|
-
"@niscorp/strata": {
|
|
92
|
-
"optional": true
|
|
93
90
|
}
|
|
94
91
|
},
|
|
95
92
|
"devDependencies": {
|
|
96
93
|
"tsup": "^8.5.1",
|
|
97
94
|
"vitest": "^4.1.2",
|
|
98
95
|
"zod": "^4.6.5",
|
|
99
|
-
"@niscorp/
|
|
100
|
-
"@niscorp/
|
|
101
|
-
"@niscorp/
|
|
96
|
+
"@niscorp/signal": "^0.1.1",
|
|
97
|
+
"@niscorp/strata": "^0.1.1",
|
|
98
|
+
"@niscorp/cortex": "^0.1.1"
|
|
102
99
|
},
|
|
103
100
|
"scripts": {
|
|
104
101
|
"build": "tsup",
|