@niscorp/prism 0.1.2 → 0.2.0
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 +15 -0
- package/DESIGN.md +3 -1
- package/DOCS.md +6 -2
- package/dist/agent.cjs +6 -4
- package/dist/agent.cjs.map +1 -1
- package/dist/agent.js +2 -2
- package/dist/{chunk-5ZHYURZO.js → chunk-3GAYBBNH.js} +3 -3
- package/dist/{chunk-5ZHYURZO.js.map → chunk-3GAYBBNH.js.map} +1 -1
- package/dist/{chunk-XABNV76M.js → chunk-3PYQITGE.js} +3 -3
- package/dist/chunk-3PYQITGE.js.map +1 -0
- package/dist/{chunk-HPUAEIWY.js → chunk-BRIXDNJQ.js} +8 -6
- package/dist/chunk-BRIXDNJQ.js.map +1 -0
- package/dist/index.cjs +6 -4
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +5 -5
- package/dist/migrations/index.cjs +16 -4
- package/dist/migrations/index.cjs.map +1 -1
- package/dist/migrations/index.js +12 -2
- package/dist/migrations/index.js.map +1 -1
- package/package.json +3 -3
- package/dist/chunk-HPUAEIWY.js.map +0 -1
- package/dist/chunk-XABNV76M.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,20 @@
|
|
|
1
1
|
# @niscorp/prism
|
|
2
2
|
|
|
3
|
+
## 0.2.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 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").
|
|
8
|
+
|
|
9
|
+
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.
|
|
10
|
+
- **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.
|
|
11
|
+
- **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.
|
|
12
|
+
- **create-nisc** — the templates' sources are recorded at `nisc.prism` 2.
|
|
13
|
+
|
|
14
|
+
**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.
|
|
15
|
+
|
|
16
|
+
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).
|
|
17
|
+
|
|
3
18
|
## 0.1.2
|
|
4
19
|
|
|
5
20
|
### 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
|
|
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.
|
|
@@ -744,14 +746,16 @@ Past any of them the evaluation throws `E_BUDGET`.
|
|
|
744
746
|
|
|
745
747
|
| Code | Meaning |
|
|
746
748
|
|------|---------|
|
|
747
|
-
| `E_SCHEMA` | Config failed Zod validation |
|
|
749
|
+
| `E_SCHEMA` | Config failed Zod validation — a malformed op, or a `$` key that is not an op |
|
|
748
750
|
| `E_MISSING_PATH` | `$ref` or `$get` path doesn't exist (and no fallback) |
|
|
749
751
|
| `E_TYPE` | Wrong type for operation (e.g. `$map.over` is not an array) |
|
|
750
752
|
| `E_DIVISION_BY_ZERO` | `$div` with divisor 0 |
|
|
751
753
|
| `E_DATE_INVALID` | Invalid date value |
|
|
752
754
|
| `E_VAR_NOT_FOUND` | `$var` references undefined variable |
|
|
753
|
-
| `E_NODE_SHAPE` |
|
|
755
|
+
| `E_NODE_SHAPE` | A node no op answers to, in a tree that never went through the schema |
|
|
754
756
|
| `E_ASSERT` | A config's own `$assert` refused its input |
|
|
755
757
|
| `E_BUDGET` | Evaluation went past a limit (see Limits) |
|
|
756
758
|
|
|
757
759
|
All errors are instances of `PrismError` with `.code` and optional `.context`.
|
|
760
|
+
|
|
761
|
+
**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/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);
|