@niscorp/prism 0.2.0 → 0.2.2
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 +41 -0
- package/DESIGN.md +2 -1
- package/DOCS.md +29 -0
- package/README.md +49 -3
- package/dist/agent.cjs +4 -756
- package/dist/agent.cjs.map +1 -1
- package/dist/agent.js +2 -2
- package/dist/chunk-26VYDHHC.cjs +784 -0
- package/dist/chunk-26VYDHHC.cjs.map +1 -0
- package/dist/{chunk-BRIXDNJQ.js → chunk-O3OJAQWA.js} +3 -3
- package/dist/chunk-O3OJAQWA.js.map +1 -0
- package/dist/chunk-V426VIRI.cjs +1168 -0
- package/dist/chunk-V426VIRI.cjs.map +1 -0
- package/dist/{chunk-3GAYBBNH.js → chunk-VC4PRB4H.js} +21 -4
- package/dist/chunk-VC4PRB4H.js.map +1 -0
- package/dist/chunk-W32JXP33.cjs +147 -0
- package/dist/chunk-W32JXP33.cjs.map +1 -0
- package/dist/{chunk-3PYQITGE.js → chunk-XRK55NPE.js} +3 -3
- package/dist/{chunk-3PYQITGE.js.map → chunk-XRK55NPE.js.map} +1 -1
- 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 +190 -2048
- 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 +7 -1775
- 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 +3 -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-3GAYBBNH.js.map +0 -1
- package/dist/chunk-BRIXDNJQ.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,46 @@
|
|
|
1
1
|
# @niscorp/prism
|
|
2
2
|
|
|
3
|
+
## 0.2.2
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- 7f8d202: Under `require`, the entry points of nova, prism and strata share one copy of their code, as they always have under `import`.
|
|
8
|
+
|
|
9
|
+
The CommonJS build was not split, so every entry point carried its own copy of each class and of each React context. The ESM build is byte for byte what it was. Under `require`:
|
|
10
|
+
- an error from `@niscorp/strata/postgres`, `/check`, `/upgrade` or `/node` is an `instanceof` the `StrataError` that `@niscorp/strata` exports; one from `prismTransform` of `@niscorp/prism/migrations` is an `instanceof PrismError`; one from `<Nova.Layout>` is an `instanceof NovaError` and of its own class. None of them was.
|
|
11
|
+
- `upgradeStore` names the row it refused — `integration_actions (integration_id="…", action_id="…"): …`, with the upgrader's error as its `cause` — and so does a moss boot that meets a stored row it cannot read. Both gave the upgrader's sentence alone.
|
|
12
|
+
- a kit registered from `@niscorp/nova/adapters/react/components` renders under `<Nova.Shell>`. It threw `useShell must be used inside <NovaShellProvider>`.
|
|
13
|
+
|
|
14
|
+
**What to change:** nothing in an ESM app. A CommonJS app that had built on any of the above — a branch that ran because `instanceof` failed, a match on the whole text of an `upgradeStore` refusal — now sees what an ESM app sees. An app that loads both builds of one package in one process still has two copies of it.
|
|
15
|
+
|
|
16
|
+
## 0.2.1
|
|
17
|
+
|
|
18
|
+
### Patch Changes
|
|
19
|
+
|
|
20
|
+
- 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:
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
import prism from '@niscorp/prism/package.json' with { type: 'json' };
|
|
24
|
+
prism.version; // the version that is installed, not the range that asked for it
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
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.
|
|
28
|
+
|
|
29
|
+
**What to change:** nothing. An app that read a version by path can read it by name.
|
|
30
|
+
|
|
31
|
+
- 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.
|
|
32
|
+
- 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.
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
import { prismTransform } from '@niscorp/prism';
|
|
36
|
+
|
|
37
|
+
createTide({ store, transform: prismTransform, effects });
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
`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.`
|
|
41
|
+
|
|
42
|
+
**What to change:** nothing. A host that wrote the join itself can pass `prismTransform` instead.
|
|
43
|
+
|
|
3
44
|
## 0.2.0
|
|
4
45
|
|
|
5
46
|
### Minor Changes
|
package/DESIGN.md
CHANGED
|
@@ -169,6 +169,7 @@ src/
|
|
|
169
169
|
│ └── sugar.schema.ts
|
|
170
170
|
├── engine/
|
|
171
171
|
│ ├── evaluate.ts # Dispatcher + evaluate / evaluateSafe
|
|
172
|
+
│ ├── transform.ts # prismTransform — Prism in the shape a host's transform seam takes
|
|
172
173
|
│ ├── compile.ts # Config → CompiledIr
|
|
173
174
|
│ ├── optimize.ts # Compile-time passes (ref segments, handlers, constant folding)
|
|
174
175
|
│ ├── budget.ts # Limits: steps, string length, result size
|
|
@@ -194,7 +195,7 @@ src/
|
|
|
194
195
|
│ ├── index.ts
|
|
195
196
|
│ └── mapping-agent.ts # mappingAgent (Cortex agent definition)
|
|
196
197
|
├── migrations/
|
|
197
|
-
│ └── index.ts # @niscorp/prism/migrations — PRISM_SEQUENCE, prismTransform
|
|
198
|
+
│ └── index.ts # @niscorp/prism/migrations — PRISM_SEQUENCE, and prismTransform again
|
|
198
199
|
└── utils/
|
|
199
200
|
├── jsonpath.ts # JSONPath parser + cache
|
|
200
201
|
├── compare.ts # Deep equality, ordered comparison
|
package/DOCS.md
CHANGED
|
@@ -729,6 +729,35 @@ const result2 = execute(ir, source2); // 2-5x faster than evaluate()
|
|
|
729
729
|
|
|
730
730
|
The IR is JSON-serializable — store it in a database, cache in Redis, send over a wire.
|
|
731
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
|
+
|
|
732
761
|
## Limits
|
|
733
762
|
|
|
734
763
|
`evaluate`, `evaluateSafe` and `execute` take an optional third argument, a
|
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
|