@niscorp/prism 0.0.0-stage → 0.1.1

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 ADDED
@@ -0,0 +1,7 @@
1
+ # @niscorp/prism
2
+
3
+ ## 0.1.1
4
+
5
+ ### Patch Changes
6
+
7
+ - 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 ADDED
@@ -0,0 +1,223 @@
1
+ # Prism — Design Document
2
+
3
+ Architecture, design decisions, and trade-offs behind `@niscorp/prism`. For usage documentation, see [DOCS.md](./DOCS.md).
4
+
5
+ ---
6
+
7
+ ## Architecture
8
+
9
+ ```
10
+ Input Config (JSON)
11
+ ↓
12
+ ┌──────────────────┐
13
+ │ Schema Layer │ Zod 4 validation of all node shapes
14
+ └───────┬──────────┘
15
+ ↓
16
+ ┌──────────────────┐
17
+ │ Sugar Layer │ Desugar convenience ops → core ops (single pass)
18
+ └───────┬──────────┘
19
+ ↓
20
+ ┌──────────────────┐
21
+ │ Compile Layer │ Walk tree, extract tables, fingerprint → IR artifact
22
+ └───────┬──────────┘
23
+ ↓
24
+ ┌──────────────────┐
25
+ │ Execute Layer │ Evaluate nodes recursively against source data
26
+ └──────────────────┘
27
+ ↓
28
+ Output (JSON)
29
+ ```
30
+
31
+ ### Four Layers
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).
34
+
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
+
37
+ **Compile** — Walks the desugared tree, collecting stats (node count, op frequency, max depth), extracting tables (all JSONPaths, all string literals), and computing a SHA256 fingerprint. Produces a JSON-serializable IR artifact that can be stored and re-executed without re-validating or re-desugaring.
38
+
39
+ **Execute** — Recursive dispatcher using type guards. Each op is a pure function `(node, context, evaluate) => JsonValue`. The dispatcher walks the tree, matching op keys via type guards, and delegates to the appropriate handler. Plain objects without `$` keys are treated as output templates with recursive value evaluation.
40
+
41
+ ---
42
+
43
+ ## Evaluation Context
44
+
45
+ ```typescript
46
+ type EvalContext = {
47
+ source: JsonObject; // Root source data (immutable)
48
+ vars: Record<string, JsonValue>; // Scoped variables (immutable)
49
+ };
50
+ ```
51
+
52
+ Context is never mutated. Every scope change (loop variable, `$with` binding) creates a new context via spread. This means ops are pure — same input always produces same output.
53
+
54
+ ---
55
+
56
+ ## Op Handler Pattern
57
+
58
+ ```typescript
59
+ type OpHandler<TNode> = (node: TNode, context: EvalContext, evaluate: EvaluateFn) => JsonValue;
60
+ ```
61
+
62
+ Ops receive the `evaluate` function as a parameter rather than importing it. This avoids circular imports (ops need to evaluate sub-expressions, but the evaluator imports ops) and makes each op independently testable with a mock evaluator.
63
+
64
+ ### Dispatcher (if-chain, not Map)
65
+
66
+ The evaluator uses a linear if-chain with type guards:
67
+
68
+ ```typescript
69
+ if (isRefNode(obj)) return opRef(obj, context, evaluateNode);
70
+ if (isMapNode(obj)) return opMap(obj, context, evaluateNode);
71
+ // ... ~50 more
72
+ ```
73
+
74
+ 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.
75
+
76
+ ---
77
+
78
+ ## Plain Objects and `__optional`
79
+
80
+ 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 `E_MISSING_PATH`.
81
+
82
+ This enables partial results from incomplete source data without try/catch wrapping every field.
83
+
84
+ ---
85
+
86
+ ## JSONPath Subset
87
+
88
+ 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.
89
+
90
+ Parsed paths are cached in a `Map`. The compiled IR primes this cache.
91
+
92
+ ---
93
+
94
+ ## Compilation Model
95
+
96
+ `compile()` produces an IR that is JSON-serializable:
97
+
98
+ ```typescript
99
+ type CompiledIr = {
100
+ irVersion: 1;
101
+ compiler: { name: string; version: string };
102
+ meta: {
103
+ name?: string;
104
+ createdAt: string;
105
+ fingerprint: string; // SHA256 of desugared config
106
+ stats: { nodeCount, opCount, maxDepth };
107
+ };
108
+ tables: {
109
+ paths: string[]; // JSONPaths for cache priming
110
+ strings: string[]; // String literals
111
+ };
112
+ core: Config; // Desugared config
113
+ };
114
+ ```
115
+
116
+ `execute()` skips validation and desugaring — it primes the JSONPath cache from `tables.paths` and evaluates `core` directly. This is 2-5x faster than `evaluate()` for repeated configs.
117
+
118
+ The fingerprint enables cache invalidation: store IRs by name, check the fingerprint to know if the config changed.
119
+
120
+ ---
121
+
122
+ ## Error Model
123
+
124
+ All errors are `PrismError` instances with a `.code` string and optional `.context`:
125
+
126
+ | Code | When |
127
+ |------|------|
128
+ | `E_SCHEMA` | Config fails Zod validation |
129
+ | `E_MISSING_PATH` | `$ref` / `$get` path doesn't exist (no fallback) |
130
+ | `E_TYPE` | Wrong type for op (e.g. `$map.over` is not array) |
131
+ | `E_DIVISION_BY_ZERO` | `$div` with divisor 0 |
132
+ | `E_DATE_INVALID` | Unparseable date value |
133
+ | `E_VAR_NOT_FOUND` | `$var` references undefined variable |
134
+ | `E_NODE_SHAPE` | Unrecognized node structure |
135
+
136
+ ---
137
+
138
+ ## File Structure
139
+
140
+ ```
141
+ src/
142
+ ├── index.ts # Public API barrel
143
+ ├── errors.ts # PrismError + error codes
144
+ ├── types.ts # JsonValue, EvalContext, CompiledIr, etc.
145
+ ├── schemas/
146
+ │ ├── index.ts # Schema barrel
147
+ │ ├── json.schema.ts # JSON primitive/value/object schemas
148
+ │ ├── node.schema.ts # NodeSchema (recursive union of all ops)
149
+ │ ├── config.schema.ts # ConfigSchema
150
+ │ ├── guards.ts # Type guards (isRefNode, isMapNode, etc.)
151
+ │ └── ops/ # One schema file per category
152
+ │ ├── core.schema.ts
153
+ │ ├── array.schema.ts
154
+ │ ├── math.schema.ts
155
+ │ ├── string.schema.ts
156
+ │ ├── predicate.schema.ts
157
+ │ ├── logic.schema.ts
158
+ │ ├── structure.schema.ts
159
+ │ ├── object.schema.ts
160
+ │ ├── time.schema.ts
161
+ │ └── sugar.schema.ts
162
+ ├── engine/
163
+ │ ├── evaluate.ts # Dispatcher + evaluate / evaluateSafe
164
+ │ ├── compile.ts # Config → CompiledIr
165
+ │ ├── execute.ts # CompiledIr + source → result
166
+ │ ├── validate.ts # Config validation
167
+ │ └── documentation.ts # JSON Schema generation
168
+ ├── ops/ # One implementation file per category
169
+ │ ├── core.ops.ts
170
+ │ ├── array.ops.ts
171
+ │ ├── math.ops.ts
172
+ │ ├── string.ops.ts
173
+ │ ├── predicate.ops.ts
174
+ │ ├── logic.ops.ts
175
+ │ ├── structure.ops.ts
176
+ │ ├── object.ops.ts
177
+ │ └── time.ops.ts
178
+ ├── sugar/
179
+ │ ├── desugar.ts # Recursive desugaring pass
180
+ │ └── rewriters.ts # Sugar → core rewrite functions
181
+ └── utils/
182
+ ├── jsonpath.ts # JSONPath parser + cache
183
+ └── compare.ts # Deep equality, ordered comparison
184
+ ```
185
+
186
+ ---
187
+
188
+ ## Dependencies
189
+
190
+ - `zod` (peer, ^4.0.0) — Schema validation, JSON Schema generation via `z.toJSONSchema()`
191
+ - `dayjs` (^1.11.0) — Date operations (`$date`, `$dateAdd`, `$dateDiff`)
192
+
193
+ The locale-aware family (`$localeDate`, `$localeMoney`, `$localeNumber`) adds
194
+ **no** dependency: it delegates to the platform's `Intl`. That is why dayjs
195
+ stays locale-blind here — localising it would mean shipping a locale pack per
196
+ language into a package that has no business knowing which languages exist.
197
+ Formatter construction is cached per resolved argument tuple, because building
198
+ an `Intl` formatter costs roughly two orders of magnitude more than using one
199
+ and a mapping over a thousand rows would otherwise build a thousand of them.
200
+
201
+ ---
202
+
203
+ ## Design Decisions
204
+
205
+ 1. **Linear if-chain over Map dispatch.** Type narrowing. Each guard narrows the node type. A Map would need casts.
206
+
207
+ 2. **Desugar before execution, not during.** One canonical representation. Compiler stores desugared form. Error messages reference core ops only.
208
+
209
+ 3. **JSONPath subset, not full spec.** Filters, recursive descent, and unions overlap with `$filter`, `$map`, and `$merge`. The subset covers path access; ops cover everything else.
210
+
211
+ 4. **SHA256 fingerprint on IR.** Cache invalidation without version numbers. Same config = same fingerprint.
212
+
213
+ 5. **`evaluate` + `evaluateSafe`.** Throwing for trusted code, Result type for untrusted input. Different call sites have different needs.
214
+
215
+ 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.
216
+
217
+ 7. **`$with` uses `let`/`value`.** Reads like scoped bindings in most languages. `in` is a JS keyword.
218
+
219
+ 8. **Math ops take `[node, node]` arrays.** Less verbose than `{ a, b }` objects. Consistent with predicates.
220
+
221
+ 9. **`$case` uses `{ branches, else }`.** Clearer than a flat array mixing `{when,then}` and `{else}` objects. Simpler Zod schema.
222
+
223
+ 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.