@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.
- package/CHANGELOG.md +43 -0
- package/DESIGN.md +5 -2
- package/DOCS.md +35 -2
- package/README.md +49 -3
- package/dist/agent.cjs +6 -4
- package/dist/agent.cjs.map +1 -1
- package/dist/agent.js +2 -2
- package/dist/{chunk-HPUAEIWY.js → chunk-O3OJAQWA.js} +9 -7
- package/dist/chunk-O3OJAQWA.js.map +1 -0
- package/dist/{chunk-5ZHYURZO.js → chunk-VC4PRB4H.js} +21 -4
- package/dist/chunk-VC4PRB4H.js.map +1 -0
- package/dist/{chunk-XABNV76M.js → chunk-XRK55NPE.js} +3 -3
- package/dist/chunk-XRK55NPE.js.map +1 -0
- package/dist/examples/index.cjs +1543 -0
- package/dist/examples/index.cjs.map +1 -0
- package/dist/examples/index.d.cts +26 -0
- package/dist/examples/index.d.ts +26 -0
- package/dist/examples/index.js +1540 -0
- package/dist/examples/index.js.map +1 -0
- package/dist/index.cjs +25 -4
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +5 -82
- package/dist/index.d.ts +5 -82
- package/dist/index.js +5 -5
- package/dist/migrations/index.cjs +33 -19
- package/dist/migrations/index.cjs.map +1 -1
- package/dist/migrations/index.d.cts +3 -2
- package/dist/migrations/index.d.ts +3 -2
- package/dist/migrations/index.js +13 -18
- package/dist/migrations/index.js.map +1 -1
- package/dist/profiles-C6r-x-Vj.d.cts +83 -0
- package/dist/profiles-C6r-x-Vj.d.ts +83 -0
- package/dist/transform-DcVcOBzQ.d.cts +3 -0
- package/dist/transform-DcVcOBzQ.d.ts +3 -0
- package/package.json +19 -8
- package/dist/chunk-5ZHYURZO.js.map +0 -1
- package/dist/chunk-HPUAEIWY.js.map +0 -1
- 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` |
|
|
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` |
|
|
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
|
|
87
|
-
the
|
|
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
|
|
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
|
|
598
|
-
//
|
|
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(
|
|
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);
|