@niscorp/solid 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 CHANGED
@@ -1,5 +1,60 @@
1
1
  # @niscorp/solid
2
2
 
3
+ ## 0.2.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 4f89d7d: BREAKING — approved by moccadroid (owner), 2026-11-22: a strict stream given a non-string for a string-format field (`z.email()`, `z.url()`, `z.uuid()`, `z.iso.*`) now fails, where it resolved; nothing else unless an app relied on what is inside a field that takes any value being dropped.
8
+
9
+ What is inside a field whose schema takes any value is now kept, as DESIGN and README say. In `recover` and `strict`, everything below `z.any()`, `z.unknown()` or an intersection was refused as `<unknown path>`: `x: z.any()` given `{"x":{"b":[1,2]}}` ended `{ x: {} }` with an error. The fields of a `z.lazy()` or a pipe are now checked against the schema it stands for (the lazy's schema, the pipe's input side), so a recursive schema keeps every level instead of nothing.
10
+
11
+ A string-format field (`z.email()`, `z.url()`, `z.uuid()`, `z.iso.*`) is now kind-checked as a string, as `z.string()` is: `{"to":[1]}` for `to: z.email()` was taken in as a list. In `recover` such a value is skipped with an error; in `strict` it fails the stream.
12
+
13
+ - d951434: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on solid reading `Infinity`, hex (`0x1F`), a leading `+` or a leading `.` as numbers.
14
+
15
+ Only JSON numbers are read. `{"a":Infinity,"b":0x1F,"c":+5,"d":.5}` put `Infinity`, 1, 5 and 0.5 into `current()`; such text is now dropped, with no error, and each field keeps what it had. Valid JSON reads as before at every chunk boundary: `{"price":19.` then `99}` still shows 0, 19, 19.99.
16
+
17
+ - b210b56: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on a selection's `final()` resolving with the frozen value after a strict failure, or on a root key `""` ending the stream at its object's close.
18
+
19
+ A stream now ends once:
20
+ - After a strict failure, a selection's `final()` that had not resolved rejects with `[solid] stream failed validation`, as the root's does: `select('items').final()` awaited before the failure never settled, and `select('count').final()` asked after it resolved with the starting value. A selection that resolved before the failure keeps its value.
21
+ - A `final()` that resolved keeps its value: text after the root that fails a strict stream no longer makes a later `final()` reject.
22
+ - A root key `""` whose value is an object no longer ends the stream at that object's `}`: `{"":{"x":1},"b":2}` resolves `final()` at the last `}`, with `b` in it, and a key beside it finalizes with its value.
23
+
24
+ - c5aea8b: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on `createStream` throwing for such a schema, or on a cortex agent with such a data schema emitting no `output-partial` events.
25
+
26
+ `createStream` without `initial` no longer throws for a schema whose derived starting value only fails a constraint: `.min(1)`, `.positive()`, `array().min(1)`, an email, url or uuid format, a `z.record` or a `z.lazy`. The derived value is used when every value in it is of a kind (and, for a literal or enum, a value) the schema takes at its place; no constraint is asked of it. A `strict` stream started so checks the value `final()` would resolve with against the whole schema and fails when the schema refuses it: `{"t":""}` for `.min(1)`, `{"n":-1}` or a reply that leaves the starting `0` for `.positive()` reject `final()`, where construction threw before. Constraints (`.min(1)`, `.positive()`, a format, `.refine`) are checked in two places only. With `constraints: 'finalize'`, each field when it finishes. And in `strict` mode with no `initial`, when the derived starting value fails the schema: the value `final()` would resolve with (at the root's close or on `close()`) is checked whole, and one the schema refuses fails the stream. Otherwise they are not checked, and in `recover` mode `final()` can resolve with a value the schema refuses (`{"t":""}` for `t: z.string().min(1)`); under `constraints: 'finalize'` such a value is reported with `onError`, and it stays. A starting value that is no object or list (`z.any()`, a `.nullable()` object) no longer makes `write('{…')` throw a `TypeError`: the reply's root is kind-checked and becomes the value.
27
+
28
+ Through cortex, which makes its partial-output stream without `initial`, an agent whose data schema has such a field or is recursive now emits `output-partial` events, where it emitted none.
29
+
30
+ - 9899bd7: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on a union field's value being dropped, or a strict stream failing, when the value is of a kind only a later variant takes.
31
+
32
+ A field of a union (discriminated or not) is now kind-checked against every variant that has it, and passes the finalize check when any of them accepts its value. Before, only the first variant counted: with `w: z.discriminatedUnion('kind', [{ kind: 'text', value: z.string() }, { kind: 'count', value: z.number() }])`, `{"w":{"kind":"count","value":5}}` lost the 5 in `recover` and failed a valid reply in `strict`. A field typed alike in every variant behaves as before.
33
+
34
+ So that a field cannot take one variant's kind under another variant's discriminator, an object or list a union decides is checked when it closes: it must fit one variant by the kinds of its fields and the values of its literal and enum fields. `{"w":{"kind":"text","value":5}}`, or `{"a":1,"b":"x"}` against the union of `{ a: string, b: string }` and `{ a: number, c: number }`, fails a strict stream, as it did, and in `recover` is reported with `onError` (`expected: 'a variant of the union'`) while the value stays in `current()`; before, `recover` dropped the field's value silently.
35
+
36
+ ### Patch Changes
37
+
38
+ - f61ffdd: A key with a dot in it (`{"files":{"index.ts":…}}`) is kept and checked against the schema; before, it was dropped with an "expected <unknown path>" error, and strict mode failed the stream.
39
+
40
+ A listener that throws no longer cuts `write()` or `close()` short: the chunk is still parsed, every other listener and selection still hears of the change, and the call then throws that listener's error. Before, the rest of the chunk was lost and the stream could stop telling new listeners of changes.
41
+
42
+ - 88f93c0: A long reply no longer slows a stream down as it grows: a new key or a closing bracket now finalizes only the direct children of its container, where before it walked every container seen so far. 2,000 streamed rows took tens of seconds and now take tens of milliseconds, with the same events, values and order. DESIGN's "O(events)" for finalization is now true.
43
+
44
+ A write into a long list copies the list once and rebuilds only the elements it changed: 20,000 streamed numbers take about half the time.
45
+
46
+ README and DESIGN say that a number is shown as read so far, as a string is: `{"price":19` then `99}` shows 19, then 1999.
47
+
48
+ README and DESIGN say that a selection's `write()` and `close()` do nothing: the root is fed.
49
+
50
+ ## 0.1.3
51
+
52
+ ### Patch Changes
53
+
54
+ - a2d2df0: The README and DESIGN.md state the speed-up their own table shows (about 3x at 10 KB, growing with size) instead of 44x, and `current()` is described as kind-checked rather than always valid.
55
+
56
+ **What to change:** nothing. Documentation only.
57
+
3
58
  ## 0.1.2
4
59
 
5
60
  ### Patch Changes
package/DESIGN.md CHANGED
@@ -22,7 +22,7 @@ The streamed JSON is not the state. The state is a valid object that exists from
22
22
  const stream = createStream({ schema, initial });
23
23
  ```
24
24
 
25
- `initial` is validated against the Zod schema at construction. Every `current()` call returns an object — before, during, and after streaming — and a value of the wrong JSON kind is never written into it (see "The always-valid invariant" for where that check applies). The incoming JSON progressively overwrites fields in this object as they're parsed; an object the reply creates (a list row, an object where `initial` has `null` or nothing, a record entry) starts empty and fills in key by key.
25
+ `initial` is validated against the Zod schema at construction. Without it, the starting value is derived from the schema (`''`, `0`, `false`, `[]`, a default, or nothing for a field it cannot derive). It is used when it passes the schema, or when every value in it is of a kind the schema takes at its place: a constraint such as `.min(1)`, `.positive()` or an email format is not asked of the starting value. Otherwise construction throws. Constraints (`.min(1)`, `.positive()`, a format, `.refine`) are checked in two places only. With `constraints: 'finalize'`, each field when it finishes. And in `strict` mode with no `initial`, when the derived starting value fails the schema: the value `final()` would resolve with (at the root's close or on `close()`) is checked whole, and one the schema refuses fails the stream. Otherwise they are not checked, and in `recover` mode `final()` can resolve with a value the schema refuses (`{"t":""}` for `t: z.string().min(1)`); under `constraints: 'finalize'` such a value is reported with `onError`, and it stays. When the starting value is no object or list (`z.any()`, a `.nullable()` object), the reply's first `{` or `[` is kind-checked as the root and becomes it. Every `current()` call returns an object — before, during, and after streaming — and a value of the wrong JSON kind is never written into it (see "The always-valid invariant" for where that check applies). The incoming JSON progressively overwrites fields in this object as they're parsed; an object the reply creates (a list row, an object where `initial` has `null` or nothing, a record entry) starts empty and fills in key by key.
26
26
 
27
27
  This means consumers can render and act on the state immediately. There is no "waiting for valid JSON" phase.
28
28
 
@@ -98,9 +98,9 @@ write(chunk)
98
98
 
99
99
  **Why:** The repair+parse approach re-scans the entire accumulated buffer on every `write()`. Over N total characters in ~N/100 chunks, total work is O(N²). For a 20 KB response that's measurably slow (~38ms). The incremental parser maintains scanner state between calls and processes only new characters — O(N) total.
100
100
 
101
- **Trade-off:** We own the parser. If a JSON edge case breaks, it's our bug. We mitigate this with thorough tests (192 unit/integration tests + e2e streaming tests).
101
+ **Trade-off:** We own the parser. If a JSON edge case breaks, it's our bug. We mitigate this with thorough tests (unit, integration and e2e streaming, in `test/`).
102
102
 
103
- **Result:** 44x faster for character-by-character streaming of a 10 KB payload.
103
+ **Result:** about 3x faster than repair+parse on a 10 KB payload in 50-byte chunks (the README's table), and the gap grows with the payload: repair+parse is quadratic.
104
104
 
105
105
  ### 2. Structural sharing, not deep cloning
106
106
 
@@ -131,6 +131,8 @@ write(chunk)
131
131
 
132
132
  **How:** The parser calls `setValue(valueBuffer)` on every non-escape character while inside a string. The dirty tracking and snapshot machinery handle the rest.
133
133
 
134
+ A number is shown as read so far, as a string is: `{"price":19` then `99}` shows 19, then 1999. Text that a JSON number can still grow from (`19.`, `-`, `1e`) is read as `Number()` reads it; text that never can (`Infinity`, `0x1F`, `+5`, `.5`) is dropped, with no error, and the field keeps what it had.
135
+
134
136
  ### 5. Skip-if-unchanged for setValue
135
137
 
136
138
  **Decision:** The parser checks `value !== existing` before marking a path dirty.
@@ -149,7 +151,9 @@ write(chunk)
149
151
 
150
152
  **Assumption:** Producers emit keys in a deliberate order. LLM structured output does this naturally — the model writes fields left to right. Consumers should place immediately useful fields first (UI/render → text → reasoning → metadata).
151
153
 
152
- **Implementation:** The finalization tracker maintains a `keysPerContainer` map. When a new key enters, all previous sibling keys (and their descendants) are finalized. When a container closes, all its children are finalized.
154
+ **Implementation:** The finalization tracker keeps, for each container, its keys in order and how many leading keys are already final. When a new key enters or the container closes, the keys not yet final are finalized. Only that container's direct children are walked: a child container finalized its own children when it closed. The validator remembers how far it has checked each container's keys, so with `constraints: 'finalize'` each field is checked once.
155
+
156
+ The root is final when its count of open containers returns to 0. A key `""` gives its value the root's path, so a closing at path `""` is not enough: `{"":{"x":1},"b":2}` resolves `final()` at the last `}`, with `b` in it.
153
157
 
154
158
  ### 7. Events decouple parsing from finalization
155
159
 
@@ -167,6 +171,8 @@ write(chunk)
167
171
 
168
172
  **Caching:** `select('widget')` always returns the same stream instance. The cache is a `Map<string, Stream>` on the root.
169
173
 
174
+ A selection's `write()` and `close()` do nothing: feed the root.
175
+
170
176
  ### 9. Factory functions, not classes
171
177
 
172
178
  **Decision:** Follow the codebase style guide — factory functions returning explicit interfaces.
@@ -189,8 +195,8 @@ write(chunk)
189
195
  |-----------|-----------|
190
196
  | Parser scan | O(chunk_length) |
191
197
  | Dirty tracking | O(depth) per value set |
192
- | Snapshot | O(dirty_paths × depth) |
193
- | Finalization check | O(events) |
198
+ | Snapshot | O(dirty_paths × depth), plus the length of each list a write changes |
199
+ | Finalization check | O(events): each key is finalized once |
194
200
  | Selected stream notify | O(1) per selection (reference ===) |
195
201
 
196
202
  Total per-write: **O(chunk_length + dirty_count × depth)**
@@ -238,7 +244,7 @@ Three modes govern what happens on a kind violation:
238
244
 
239
245
  - **`trust`** — no validation. Today's pre-invariant behavior. Included as a debug escape hatch; discouraged in production.
240
246
  - **`recover`** (default) — the bad value is skipped, the prior valid value stays in place, an error is emitted via `onError`, and the stream continues. One hallucinated field doesn't tank the rest of the response.
241
- - **`strict`** — the bad value is skipped, an error is emitted once, the stream enters a terminal failed state. `current()` freezes at the last valid snapshot, further writes are no-ops, `final()` rejects. For when rendering wrong is worse than rendering nothing.
247
+ - **`strict`** — the bad value is skipped, an error is emitted once, the stream enters a terminal failed state. `current()` freezes at the last valid snapshot, further writes are no-ops, `final()` rejects, and so does every selection's `final()` not resolved yet, asked before or after the failure. A `final()` that resolved before the failure (the root closed, then text after it failed) keeps its value. For when rendering wrong is worse than rendering nothing.
242
248
 
243
249
  A constraint violation (phase 2) is found after the value has been written, so it is never skipped: in `recover` the value stays in `current()` and `final()` and the error is emitted; in `strict` the stream fails the same way, frozen with the violating value in it. `trust` runs neither phase.
244
250
 
@@ -247,7 +253,7 @@ A constraint violation (phase 2) is found after the value has been written, so i
247
253
  - A value of the wrong JSON kind is never written into `current()` (in `recover` and `strict`, for the schema kinds the walker checks — see Sub-schema walking), and every field `initial` holds keeps a value.
248
254
  - An object the reply creates starts empty and fills in key by key. Until it closes, `current()` can lack keys the schema requires, and no error is raised for that; a complete reply that never sends a required key of such an object leaves `final()` without it (reported only under `constraints: 'finalize'`).
249
255
  - `current()` is *not* always constraint-valid, mid-stream or at the end. `constraints: 'finalize'` reports a violation when the field closes; it does not take the value back.
250
- - No throwing from `write()`. All error surfaces go through `onError` + `final()` rejection. Signal adapters and other producer loops can write without try/catch.
256
+ - No validation error is thrown from `write()`: all of them go through `onError` + `final()` rejection, so signal adapters and other producer loops can write without try/catch. What `write()` and `close()` throw is a listener's own error: a listener that throws does not cut the call short, every other listener still hears of the change, and once the call has finished it throws the first such error.
251
257
  - Selected streams see only errors at-or-below their path. `select('widget').onError(...)` ignores errors on sibling fields.
252
258
 
253
259
  ### Sub-schema walking
@@ -258,11 +264,13 @@ A constraint violation (phase 2) is found after the value has been written, so i
258
264
  - `ZodArray` → `element`
259
265
  - `ZodTuple` → `items[idx]` or `rest`
260
266
  - `ZodRecord` → `valueType`
261
- - `ZodUnion` → first variant that accepts the segment
267
+ - `ZodUnion` (discriminated too) → every variant that has the segment: the field takes the kinds of all of them, and passes finalize if any of them accepts its value. So that a field cannot take one variant's kind under another variant's discriminator, an object or list a union decides is checked when it closes: it must fit one variant, by the kinds of its fields and the values of its literal and enum fields (constraints are left to `constraints: 'finalize'`, whose safeParse covers this). One that fits none is an `onError` (`phase: 'finalize'`, `expected: 'a variant of the union'`) in `recover`, where the value stays, and fails the stream in `strict`. `{"w":{"kind":"text","value":5}}` against the union of `{kind:'text', value: string}` and `{kind:'count', value: number}` is such an object.
262
268
  - `ZodOptional` / `ZodNullable` / `ZodDefault` → unwrap and recurse
263
269
  - `ZodLiteral`, `ZodEnum`, `ZodString/Number/Boolean/Null` → leaf kinds
264
270
  - Discriminated unions → object kind; full narrowing deferred to finalize
265
- - `ZodLazy` / `ZodIntersection` / `ZodPipeline` / `ZodAny` / `ZodUnknown` → accept-any (kind check skipped; finalize still runs if enabled)
271
+ - `ZodLazy` / `ZodPipe` → stepped through to reach a field: the lazy's own schema, the pipe's input side. A recursive schema is checked at every level.
272
+ - `ZodIntersection` / `ZodAny` / `ZodUnknown`, and a lazy or a pipe that is itself the value → accept-any (kind check skipped; finalize still runs if enabled). Every value below an accept-any schema is taken too.
273
+ - String formats (`z.email()`, `z.url()`, `z.uuid()`, `z.iso.*`) → string, as `z.string()`
266
274
 
267
275
  The walker caches nothing; the lookup is O(depth) per value. For typical schemas (depth 3–5), that's a few property accesses per write.
268
276
 
package/README.md CHANGED
@@ -11,9 +11,9 @@ Solid takes a different approach:
11
11
  - **Incremental parser** — processes only new characters. No re-scanning.
12
12
  - **Structural sharing** — snapshots reuse unchanged subtree references. No deep cloning.
13
13
  - **Reference equality** — change detection is `===`, not deep comparison. O(1).
14
- - **Always-valid invariant** — the parser kind-checks every value against the schema at the moment its type is known, so a value of the wrong JSON kind is never written into `current()`, whatever the LLM sends. (`trust` mode switches the check off, and a field whose schema is `z.lazy`, an intersection or a pipe is not kind-checked.)
14
+ - **Always-valid invariant** — the parser kind-checks every value against the schema at the moment its type is known, so a value of the wrong JSON kind is never written into `current()`, whatever the LLM sends. (`trust` mode switches the check off. A field whose schema takes any value — `z.any()`, `z.unknown()`, an intersection — is not kind-checked, and neither is anything inside it; the fields of a `z.lazy` or a pipe are checked against the schema it stands for. A string format such as `z.email()` takes only strings. A field of a union takes what any variant that has it takes; when the union's object closes it must fit one variant, or it is reported in `recover` and fails the stream in `strict`.)
15
15
 
16
- The result: linear scaling, 44x faster than naive repair+parse on a 10 KB payload, a clean subscription API that tells you exactly when each subtree finalizes, and a structural contract that holds even when the model hallucinates the wrong type for a field.
16
+ The result: linear scaling, about 3x faster than naive repair+parse on a 10 KB payload (table below), a clean subscription API that tells you exactly when each subtree finalizes, and a structural contract that holds even when the model hallucinates the wrong type for a field.
17
17
 
18
18
  ```
19
19
  Payload scaling (50-byte chunks):
@@ -114,6 +114,8 @@ This runs the sub-schema `safeParse` at the exact moment each field closes in th
114
114
 
115
115
  2. **Incremental parsing** — each `write(chunk)` feeds characters into a state machine that tracks JSON structure, extracts values, and emits structural events. No `JSON.parse`, no buffer re-scanning. What is written should be the JSON value and nothing else. A code fence around it is ignored, and so is text with no double quote, bracket or brace in it. A `"` in text before the JSON is read as a string where the root belongs: an `onError` (`[solid] <root>: expected object, got string`) in `recover`, a failed stream in `strict`. A bracket or brace in text before the JSON is read as the root itself: the stream ends there, on the initial value or, in `strict`, sometimes as a failure.
116
116
 
117
+ A string is shown as read so far, and a number is too: `{"price":19` then `99}` shows 19, then 1999. Only JSON numbers are read: `Infinity`, `0x1F`, `+5` and `.5` are dropped, and the field keeps what it had.
118
+
117
119
  3. **Value-open validation** — the moment the parser detects a value's JSON kind (`{`, `[`, `"`, digit, `t`/`f`/`n`), it checks it against the schema. If the kind doesn't match (string where number expected, array where object lives), the parser enters **skip-mode** — consuming the entire bad subtree without writing, dirtying, or emitting anything. The prior valid value stays in place.
118
120
 
119
121
  4. **Structural sharing** — the parser mutates an internal object, then produces an immutable snapshot where only the changed paths get new references. Unchanged subtrees keep the same object reference as the previous snapshot.
@@ -140,7 +142,9 @@ This runs the sub-schema `safeParse` at the exact moment each field closes in th
140
142
  ```typescript
141
143
  import { createStream } from '@niscorp/solid';
142
144
 
143
- // Create a stream with schema + optional initial value + validation opts
145
+ // Create a stream with schema + optional initial value + validation opts.
146
+ // Without initial, the starting value is derived from the schema; a constraint such as
147
+ // .min(1) is not asked of it. In strict mode, final() then rejects a value the schema refuses.
144
148
  const stream = createStream({
145
149
  schema,
146
150
  initial?,
@@ -154,14 +158,17 @@ stream.write(chunk: string): void
154
158
  // Signal end of stream (forces finalization)
155
159
  stream.close(): void
156
160
 
161
+ // A listener that throws does not cut write() or close() short: the call
162
+ // finishes, every other listener hears of the change, then it throws that error.
163
+
157
164
  // Tear down all listeners and reject pending promises
158
165
  stream.destroy(): void
159
166
 
160
- // Read current merged state (always structurally valid)
167
+ // Read current merged state (values kind-checked against the schema; see Validation modes)
161
168
  stream.current(): T
162
169
 
163
- // Promise that resolves when root JSON object closes.
164
- // Rejects if the stream entered strict failure.
170
+ // Promise that resolves when root JSON object closes, or on close().
171
+ // Rejects if the stream entered strict failure before that; once resolved, it keeps its value.
165
172
  stream.final(): Promise<T>
166
173
 
167
174
  // Subscribe — fires immediately with current value, then on each change
@@ -179,7 +186,9 @@ stream.onError(listener: (err: StreamError) => void): () => void
179
186
  stream.select<P>(path: string): Stream<P>
180
187
  ```
181
188
 
182
- `select()` streams are cached by path — `select('widget')` always returns the same instance. Selected streams use reference equality for change detection, so `select('widget.title').on(...)` only fires when the title actually changes, not when sibling fields update.
189
+ `select()` streams are cached by path — `select('widget')` always returns the same instance. A selection's `write()` and `close()` do nothing: feed the root. A selection's `final()` resolves when its path finishes; after a strict failure, one not yet resolved rejects with the root's error, unless the root had resolved first. Selected streams use reference equality for change detection, so `select('widget.title').on(...)` only fires when the title actually changes, not when sibling fields update.
190
+
191
+ A path separates keys with dots, so `select()` cannot reach a key that has a dot in it (`"index.ts"`). The stream itself keeps such a key and checks it against the schema; an error's `path` joins the keys with dots as given.
183
192
 
184
193
  ## License
185
194