@niscorp/prism 0.1.2 → 0.2.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.
Files changed (38) hide show
  1. package/CHANGELOG.md +43 -0
  2. package/DESIGN.md +5 -2
  3. package/DOCS.md +35 -2
  4. package/README.md +49 -3
  5. package/dist/agent.cjs +6 -4
  6. package/dist/agent.cjs.map +1 -1
  7. package/dist/agent.js +2 -2
  8. package/dist/{chunk-HPUAEIWY.js → chunk-O3OJAQWA.js} +9 -7
  9. package/dist/chunk-O3OJAQWA.js.map +1 -0
  10. package/dist/{chunk-5ZHYURZO.js → chunk-VC4PRB4H.js} +21 -4
  11. package/dist/chunk-VC4PRB4H.js.map +1 -0
  12. package/dist/{chunk-XABNV76M.js → chunk-XRK55NPE.js} +3 -3
  13. package/dist/chunk-XRK55NPE.js.map +1 -0
  14. package/dist/examples/index.cjs +1543 -0
  15. package/dist/examples/index.cjs.map +1 -0
  16. package/dist/examples/index.d.cts +26 -0
  17. package/dist/examples/index.d.ts +26 -0
  18. package/dist/examples/index.js +1540 -0
  19. package/dist/examples/index.js.map +1 -0
  20. package/dist/index.cjs +25 -4
  21. package/dist/index.cjs.map +1 -1
  22. package/dist/index.d.cts +5 -82
  23. package/dist/index.d.ts +5 -82
  24. package/dist/index.js +5 -5
  25. package/dist/migrations/index.cjs +33 -19
  26. package/dist/migrations/index.cjs.map +1 -1
  27. package/dist/migrations/index.d.cts +3 -2
  28. package/dist/migrations/index.d.ts +3 -2
  29. package/dist/migrations/index.js +13 -18
  30. package/dist/migrations/index.js.map +1 -1
  31. package/dist/profiles-C6r-x-Vj.d.cts +83 -0
  32. package/dist/profiles-C6r-x-Vj.d.ts +83 -0
  33. package/dist/transform-DcVcOBzQ.d.cts +3 -0
  34. package/dist/transform-DcVcOBzQ.d.ts +3 -0
  35. package/package.json +19 -8
  36. package/dist/chunk-5ZHYURZO.js.map +0 -1
  37. package/dist/chunk-HPUAEIWY.js.map +0 -1
  38. package/dist/chunk-XABNV76M.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,48 @@
1
1
  # @niscorp/prism
2
2
 
3
+ ## 0.2.1
4
+
5
+ ### Patch Changes
6
+
7
+ - fe30458: Every package exports its `package.json`, so an app can say which version of a package it runs by reading it from the package:
8
+
9
+ ```ts
10
+ import prism from '@niscorp/prism/package.json' with { type: 'json' };
11
+ prism.version; // the version that is installed, not the range that asked for it
12
+ ```
13
+
14
+ Until now the `exports` map hid it, and the only way to the version was a path into `node_modules`. `check:packages` installs the tarballs and reads every package's version this way.
15
+
16
+ **What to change:** nothing. An app that read a version by path can read it by name.
17
+
18
+ - 259a6f7: `@niscorp/prism/examples` — the reference as data. `PRISM_EXAMPLES` is 82 examples (`{ id, group, title, description, op?, source, config, expected }`): one for each of the 73 operators, named by the operator, then nine configs of several operators working together. `PRISM_EXAMPLE_GROUPS` names the groups they come in — the reference's own (Core, Arrays, Math, …), in its order. The package's tests evaluate each example against its `expected`, and fail when an operator has no example of its own or has two, so whatever shows them shows what the installed version does. `OP_KEYS`, the grammar's operator names in its own order, is now exported from the main entry. STYLE_GUIDE.md gains "Examples": a change to what a package does changes its examples in the same commit.
19
+ - f801cc9: `prismTransform` is exported from the main entry: Prism in the shape a host's transform seam takes, `(config: unknown, source: unknown) => unknown` — what nova's shell, tide's engine and strata's upgrader are handed.
20
+
21
+ ```ts
22
+ import { prismTransform } from '@niscorp/prism';
23
+
24
+ createTide({ store, transform: prismTransform, effects });
25
+ ```
26
+
27
+ `evaluate` is typed for a `JsonValue` source, so a host could not hand it to a seam without a cast, a JSON round trip or a parse of its own. `prismTransform` parses the config against `ConfigSchema` and refuses a source that is not plain JSON. It is the function `@niscorp/prism/migrations` has exported all along, and that export stays. Its refusal now reads `The source of a transform must be plain JSON.`; it said `A document to migrate must be plain JSON.`
28
+
29
+ **What to change:** nothing. A host that wrote the join itself can pass `prismTransform` instead.
30
+
31
+ ## 0.2.0
32
+
33
+ ### Minor Changes
34
+
35
+ - 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").
36
+
37
+ 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.
38
+ - **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.
39
+ - **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.
40
+ - **create-nisc** — the templates' sources are recorded at `nisc.prism` 2.
41
+
42
+ **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.
43
+
44
+ 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).
45
+
3
46
  ## 0.1.2
4
47
 
5
48
  ### Patch Changes
package/DESIGN.md CHANGED
@@ -82,6 +82,8 @@ Objects without `$`-prefixed keys are output templates. Each value is recursivel
82
82
 
83
83
  This enables partial results from incomplete source data without try/catch wrapping every field.
84
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
+
85
87
  ---
86
88
 
87
89
  ## JSONPath Subset
@@ -132,7 +134,7 @@ All errors are `PrismError` instances with a `.code` string and optional `.conte
132
134
  | `E_DIVISION_BY_ZERO` | `$div` with divisor 0 |
133
135
  | `E_DATE_INVALID` | Unparseable date value |
134
136
  | `E_VAR_NOT_FOUND` | `$var` references undefined variable |
135
- | `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`) |
136
138
  | `E_ASSERT` | A config's own `$assert` refused its input |
137
139
  | `E_BUDGET` | An evaluation went past its budget (`engine/budget.ts`) |
138
140
 
@@ -167,6 +169,7 @@ src/
167
169
  │ └── sugar.schema.ts
168
170
  ├── engine/
169
171
  │ ├── evaluate.ts # Dispatcher + evaluate / evaluateSafe
172
+ │ ├── transform.ts # prismTransform — Prism in the shape a host's transform seam takes
170
173
  │ ├── compile.ts # Config → CompiledIr
171
174
  │ ├── optimize.ts # Compile-time passes (ref segments, handlers, constant folding)
172
175
  │ ├── budget.ts # Limits: steps, string length, result size
@@ -192,7 +195,7 @@ src/
192
195
  │ ├── index.ts
193
196
  │ └── mapping-agent.ts # mappingAgent (Cortex agent definition)
194
197
  ├── migrations/
195
- │ └── index.ts # @niscorp/prism/migrations — PRISM_SEQUENCE, prismTransform
198
+ │ └── index.ts # @niscorp/prism/migrations — PRISM_SEQUENCE, and prismTransform again
196
199
  └── utils/
197
200
  ├── jsonpath.ts # JSONPath parser + cache
198
201
  ├── compare.ts # Deep equality, ordered comparison
package/DOCS.md CHANGED
@@ -14,6 +14,8 @@ 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
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.
@@ -727,6 +729,35 @@ const result2 = execute(ir, source2); // 2-5x faster than evaluate()
727
729
 
728
730
  The IR is JSON-serializable — store it in a database, cache in Redis, send over a wire.
729
731
 
732
+ ## As a host's transform
733
+
734
+ ```typescript
735
+ prismTransform(config: unknown, source: unknown): unknown
736
+ ```
737
+
738
+ Prism in the shape a host's transform seam takes. nova's shell (`transform`),
739
+ tide's engine (`transform`) and strata's upgrader (`{ transform }`) each run a
740
+ config through a function they are handed and know nothing of Prism; this is the
741
+ function to hand them.
742
+
743
+ ```typescript
744
+ import { prismTransform } from '@niscorp/prism';
745
+
746
+ const tide = createTide({ store, transform: prismTransform, effects });
747
+ ```
748
+
749
+ - **The config** is parsed against `ConfigSchema` where it comes in — once for
750
+ each config object, so a config a host keeps and passes again is not parsed
751
+ again.
752
+ - **The source** must be plain JSON: `null`, strings, booleans, finite numbers,
753
+ and arrays and objects of those. One that holds `undefined`, a function or a
754
+ non-finite number is refused — `The source of a transform must be plain JSON.`
755
+ - **The result** is what `evaluate` answers.
756
+
757
+ `evaluate` itself is typed for a `JsonValue` source and checks none, so it does
758
+ not fit a seam that hands over `unknown`. `@niscorp/prism/migrations` exports the
759
+ same function.
760
+
730
761
  ## Limits
731
762
 
732
763
  `evaluate`, `evaluateSafe` and `execute` take an optional third argument, a
@@ -744,14 +775,16 @@ Past any of them the evaluation throws `E_BUDGET`.
744
775
 
745
776
  | Code | Meaning |
746
777
  |------|---------|
747
- | `E_SCHEMA` | Config failed Zod validation |
778
+ | `E_SCHEMA` | Config failed Zod validation — a malformed op, or a `$` key that is not an op |
748
779
  | `E_MISSING_PATH` | `$ref` or `$get` path doesn't exist (and no fallback) |
749
780
  | `E_TYPE` | Wrong type for operation (e.g. `$map.over` is not an array) |
750
781
  | `E_DIVISION_BY_ZERO` | `$div` with divisor 0 |
751
782
  | `E_DATE_INVALID` | Invalid date value |
752
783
  | `E_VAR_NOT_FOUND` | `$var` references undefined variable |
753
- | `E_NODE_SHAPE` | Unrecognized node structure |
784
+ | `E_NODE_SHAPE` | A node no op answers to, in a tree that never went through the schema |
754
785
  | `E_ASSERT` | A config's own `$assert` refused its input |
755
786
  | `E_BUDGET` | Evaluation went past a limit (see Limits) |
756
787
 
757
788
  All errors are instances of `PrismError` with `.code` and optional `.context`.
789
+
790
+ **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
@@ -53,6 +53,9 @@ const result = evaluate(
53
53
  evaluate(config, source, limits?) → JsonValue
54
54
  evaluateSafe(config, source, limits?) → { ok: true, data } | { ok: false, error }
55
55
 
56
+ // The same, in the shape a host's transform seam takes
57
+ prismTransform(config: unknown, source: unknown) → unknown
58
+
56
59
  // Compile once, execute many (2-5x faster for repeated configs)
57
60
  compile(config, options?) → Promise<CompiledIr>
58
61
  execute(ir, source, limits?) → JsonValue
@@ -65,6 +68,49 @@ getNodeJsonSchema(target?) → object
65
68
  getConfigJsonSchema(target?) → object
66
69
  ```
67
70
 
71
+ ## As a host's transform
72
+
73
+ nova's shell, tide's engine and strata's upgrader each run a config through a
74
+ transform they are handed, `(config, source) => unknown`, and know nothing of
75
+ Prism. `prismTransform` is Prism in that shape:
76
+
77
+ ```typescript
78
+ import { prismTransform } from '@niscorp/prism';
79
+
80
+ createTide({ store, transform: prismTransform, effects }); // @niscorp/tide
81
+ createUpgrader(grammars, { transform: prismTransform }); // @niscorp/strata
82
+ ```
83
+
84
+ Both sides arrive untyped, so both are checked: the config is parsed against
85
+ `ConfigSchema` (once for each config object), and the source must be plain JSON
86
+ — a source holding `undefined`, a function or a non-finite number is refused.
87
+ `evaluate` is typed for a `JsonValue` and checks no source, which is why it
88
+ cannot be handed to a seam as it is. A host that adds values of its own to the
89
+ source first (the app's "today", the session's principal) wraps it.
90
+
91
+ ## Examples
92
+
93
+ `@niscorp/prism/examples` is the reference as data: one example for each
94
+ operator, named by the operator — a config, the source it is given, and what
95
+ comes out — then a few configs of several operators working together.
96
+
97
+ ```typescript
98
+ import { evaluate } from '@niscorp/prism';
99
+ import { PRISM_EXAMPLES, PRISM_EXAMPLE_GROUPS } from '@niscorp/prism/examples';
100
+
101
+ const map = PRISM_EXAMPLES.find((example) => example.op === '$map');
102
+ // → { id: 'map', group: 'arrays', title: '$map', description, op: '$map', source, config, expected }
103
+ evaluate(map.config, map.source); // → map.expected
104
+
105
+ // PRISM_EXAMPLE_GROUPS → [{ id: 'arrays', title: 'Arrays', description }, …]
106
+ // the groups the reference puts the operators in, in the same order
107
+ ```
108
+
109
+ They are tested with the package (`test/examples.test.ts`): each one evaluates to
110
+ its `expected`, and every operator in `OP_KEYS` has exactly one example of its
111
+ own. So whatever shows them — a documentation page, an agent reading
112
+ `node_modules` — is showing what the installed version does.
113
+
68
114
  ## Profiles
69
115
 
70
116
  `getProfileJsonSchema(ops, target?)` is the config JSON Schema documenting only
@@ -82,9 +128,9 @@ rules) — see [DOCS.md § Transform Operations](./DOCS.md#transform-operations)
82
128
  They are what strata's document migrations are written in.
83
129
 
84
130
  **`@niscorp/prism/migrations`** publishes Prism's own grammar — `PRISM_SEQUENCE`
85
- (`nisc.prism`, kind `nisc.prism/config`), `PRISM_SCHEMAS` — and
86
- `prismTransform`, the evaluator a migration runs through (strata injects it;
87
- the config is parsed once, the source must be plain JSON).
131
+ (`nisc.prism`, kind `nisc.prism/config`), `PRISM_SCHEMAS` — and exports
132
+ `prismTransform` as well, the evaluator a migration runs through (strata injects
133
+ it): the same function as the main entry's.
88
134
 
89
135
  **The op set only ever grows.** Configs are stored — endpoint requests, vex
90
136
  mappings, migrations — and a migration cannot be migrated by the language it is
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);