@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.
Files changed (43) hide show
  1. package/CHANGELOG.md +41 -0
  2. package/DESIGN.md +2 -1
  3. package/DOCS.md +29 -0
  4. package/README.md +49 -3
  5. package/dist/agent.cjs +4 -756
  6. package/dist/agent.cjs.map +1 -1
  7. package/dist/agent.js +2 -2
  8. package/dist/chunk-26VYDHHC.cjs +784 -0
  9. package/dist/chunk-26VYDHHC.cjs.map +1 -0
  10. package/dist/{chunk-BRIXDNJQ.js → chunk-O3OJAQWA.js} +3 -3
  11. package/dist/chunk-O3OJAQWA.js.map +1 -0
  12. package/dist/chunk-V426VIRI.cjs +1168 -0
  13. package/dist/chunk-V426VIRI.cjs.map +1 -0
  14. package/dist/{chunk-3GAYBBNH.js → chunk-VC4PRB4H.js} +21 -4
  15. package/dist/chunk-VC4PRB4H.js.map +1 -0
  16. package/dist/chunk-W32JXP33.cjs +147 -0
  17. package/dist/chunk-W32JXP33.cjs.map +1 -0
  18. package/dist/{chunk-3PYQITGE.js → chunk-XRK55NPE.js} +3 -3
  19. package/dist/{chunk-3PYQITGE.js.map → chunk-XRK55NPE.js.map} +1 -1
  20. package/dist/examples/index.cjs +1543 -0
  21. package/dist/examples/index.cjs.map +1 -0
  22. package/dist/examples/index.d.cts +26 -0
  23. package/dist/examples/index.d.ts +26 -0
  24. package/dist/examples/index.js +1540 -0
  25. package/dist/examples/index.js.map +1 -0
  26. package/dist/index.cjs +190 -2048
  27. package/dist/index.cjs.map +1 -1
  28. package/dist/index.d.cts +5 -82
  29. package/dist/index.d.ts +5 -82
  30. package/dist/index.js +5 -5
  31. package/dist/migrations/index.cjs +7 -1775
  32. package/dist/migrations/index.cjs.map +1 -1
  33. package/dist/migrations/index.d.cts +3 -2
  34. package/dist/migrations/index.d.ts +3 -2
  35. package/dist/migrations/index.js +3 -18
  36. package/dist/migrations/index.js.map +1 -1
  37. package/dist/profiles-C6r-x-Vj.d.cts +83 -0
  38. package/dist/profiles-C6r-x-Vj.d.ts +83 -0
  39. package/dist/transform-DcVcOBzQ.d.cts +3 -0
  40. package/dist/transform-DcVcOBzQ.d.ts +3 -0
  41. package/package.json +19 -8
  42. package/dist/chunk-3GAYBBNH.js.map +0 -1
  43. 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`, 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