@niscorp/prism 0.3.2 → 0.3.3

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,13 @@
1
1
  # @niscorp/prism
2
2
 
3
+ ## 0.3.3
4
+
5
+ ### Patch Changes
6
+
7
+ - e4dfb25: The docs give the op count (75; 78 union members), say `$mod` also throws `E_DIVISION_BY_ZERO`, that only the binary math ops take a pair, that compiled IR does not use the path cache, and list `ops/scope.ts` and `examples/`.
8
+
9
+ **What to change:** nothing. Documentation only.
10
+
3
11
  ## 0.3.2
4
12
 
5
13
  ### 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 ~70 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 75 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
 
@@ -69,7 +69,7 @@ The evaluator uses a linear if-chain with type guards:
69
69
  ```typescript
70
70
  if (isRefNode(obj)) return opRef(obj, context, evaluateNode);
71
71
  if (isMapNode(obj)) return opMap(obj, context, evaluateNode);
72
- // ... ~60 more
72
+ // ... 63 more
73
73
  ```
74
74
 
75
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.
@@ -90,7 +90,7 @@ The schema and the evaluator hold one rule: a `$` name is an op's. The template
90
90
 
91
91
  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
92
 
93
- Parsed paths are cached in a `Map`. The compiled IR primes this cache.
93
+ Parsed paths are cached in a `Map`. Compiled IR does not use it: `rehydrate` attaches each `$ref` node's parsed path to the node.
94
94
 
95
95
  ---
96
96
 
@@ -131,7 +131,7 @@ All errors are `PrismError` instances with a `.code` string and optional `.conte
131
131
  | `E_SCHEMA` | Config fails Zod validation |
132
132
  | `E_MISSING_PATH` | `$ref` / `$get` path doesn't exist (no fallback) |
133
133
  | `E_TYPE` | Wrong type for op (e.g. `$map.over` is not array) |
134
- | `E_DIVISION_BY_ZERO` | `$div` with divisor 0 |
134
+ | `E_DIVISION_BY_ZERO` | `$div` or `$mod` with divisor 0 |
135
135
  | `E_DATE_INVALID` | Unparseable date value |
136
136
  | `E_VAR_NOT_FOUND` | `$var` references undefined variable |
137
137
  | `E_NODE_SHAPE` | A node no op answers to, in a tree that skipped the schema (an IR given to `execute`) |
@@ -180,6 +180,7 @@ src/
180
180
  │ └── documentation.ts # JSON Schema generation
181
181
  ├── ops/ # One implementation file per category
182
182
  │ ├── refuse.ts # The sentence for an op given the wrong kind of value
183
+ │ ├── scope.ts # loopScope — one scope for a whole loop
183
184
  │ ├── core.ops.ts
184
185
  │ ├── array.ops.ts
185
186
  │ ├── math.ops.ts
@@ -199,6 +200,11 @@ src/
199
200
  │ └── mapping-agent.ts # mappingAgent (Cortex agent definition)
200
201
  ├── migrations/
201
202
  │ └── index.ts # @niscorp/prism/migrations — PRISM_SEQUENCE, PRISM_SCHEMAS
203
+ ├── examples/ # @niscorp/prism/examples
204
+ │ ├── index.ts # PRISM_EXAMPLES, PRISM_EXAMPLE_GROUPS
205
+ │ ├── example.types.ts # PrismExample, PrismExampleGroup
206
+ │ ├── groups.ts # PRISM_EXAMPLE_GROUPS — id, title and description of each group
207
+ │ └── operators.ts, sugar.ts, composition.ts, real-world.ts # the examples
202
208
  └── utils/
203
209
  ├── jsonpath.ts # JSONPath parser + cache
204
210
  ├── compare.ts # Deep equality, ordered comparison
@@ -240,10 +246,10 @@ and a mapping over a thousand rows would otherwise build a thousand of them.
240
246
 
241
247
  7. **`$with` uses `let`/`value`.** Reads like scoped bindings in most languages. `in` is a JS keyword.
242
248
 
243
- 8. **Math ops take `[node, node]` arrays.** Less verbose than `{ a, b }` objects. Consistent with predicates.
249
+ 8. **Binary math ops take `[node, node]` arrays.** Less verbose than `{ a, b }` objects. Consistent with predicates.
244
250
 
245
251
  9. **`$case` uses `{ branches, else }`.** Clearer than a flat array mixing `{when,then}` and `{else}` objects. Simpler Zod schema.
246
252
 
247
253
  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.
248
254
 
249
- 11. **The node union is tried by key before it is walked.** zod tries a union's 76 members 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 as before, 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.
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 as before, 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
@@ -224,7 +224,7 @@ Source: `{ "tags": ["a", "b", "a", "c", "b"] }` → `["a", "b", "c"]`
224
224
 
225
225
  ## Math Operations
226
226
 
227
- All math ops take a `[left, right]` pair. Both operands are evaluated and must be numbers.
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.
228
228
 
229
229
  ### `$add`
230
230
  ```json
@@ -823,7 +823,7 @@ each time it appears, as it would be serialized: a `$reduce` whose body is
823
823
  | `E_SCHEMA` | Config failed Zod validation — a malformed op, or a `$` key that is not an op |
824
824
  | `E_MISSING_PATH` | `$ref` or `$get` path doesn't exist (and no fallback) |
825
825
  | `E_TYPE` | Wrong type for operation (e.g. `$map.over` is not an array) |
826
- | `E_DIVISION_BY_ZERO` | `$div` with divisor 0 |
826
+ | `E_DIVISION_BY_ZERO` | `$div` or `$mod` with divisor 0 |
827
827
  | `E_DATE_INVALID` | Invalid date value |
828
828
  | `E_VAR_NOT_FOUND` | `$var` references undefined variable |
829
829
  | `E_NODE_SHAPE` | A node no op answers to, in a tree that never went through the schema |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@niscorp/prism",
3
- "version": "0.3.2",
3
+ "version": "0.3.3",
4
4
  "description": "Pure JSON transformation DSL with compilation and zero code execution",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",
@@ -88,9 +88,9 @@
88
88
  },
89
89
  "peerDependencies": {
90
90
  "zod": "^4.2.0",
91
- "@niscorp/cortex": "^0.1.5",
92
- "@niscorp/signal": "^0.1.7",
93
- "@niscorp/strata": "^0.1.7"
91
+ "@niscorp/cortex": "^0.1.6",
92
+ "@niscorp/signal": "^0.1.9",
93
+ "@niscorp/strata": "^0.1.9"
94
94
  },
95
95
  "peerDependenciesMeta": {
96
96
  "@niscorp/cortex": {
@@ -104,9 +104,9 @@
104
104
  "tsup": "^8.5.1",
105
105
  "vitest": "^4.1.2",
106
106
  "zod": "^4.6.5",
107
- "@niscorp/signal": "^0.1.7",
108
- "@niscorp/strata": "^0.1.7",
109
- "@niscorp/cortex": "^0.1.5"
107
+ "@niscorp/cortex": "^0.1.6",
108
+ "@niscorp/signal": "^0.1.9",
109
+ "@niscorp/strata": "^0.1.9"
110
110
  },
111
111
  "scripts": {
112
112
  "build": "tsup",