@niscorp/solid 0.1.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/README.md ADDED
@@ -0,0 +1,184 @@
1
+ # @niscorp/solid
2
+
3
+ Structured Output Live Inference Decoding. Always-valid, schema-backed object streaming over partial JSON. Built for LLM structured output — see fields fill in as tokens arrive.
4
+
5
+ ## Why not just `JSON.parse`?
6
+
7
+ Every LLM streaming library does some version of "repair the partial JSON, parse it, diff it." That's O(n) per token on the **full buffer** — quadratic over a stream. At 20 KB it's already sluggish.
8
+
9
+ Solid takes a different approach:
10
+
11
+ - **Incremental parser** — processes only new characters. No re-scanning.
12
+ - **Structural sharing** — snapshots reuse unchanged subtree references. No deep cloning.
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. `current()` is guaranteed structurally valid, whatever the LLM sends.
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.
17
+
18
+ ```
19
+ Payload scaling (50-byte chunks):
20
+
21
+ Size(KB) | Naive | Solid
22
+ -----------|----------|--------
23
+ 1 KB | 0.15ms | 0.42ms
24
+ 5 KB | 2.3ms | 1.0ms
25
+ 10 KB | 9.3ms | 3.2ms
26
+ 20 KB | 38ms | 12ms
27
+
28
+ Scaling ratio (20KB/1KB ms/KB):
29
+ Naive: 12.7x (quadratic)
30
+ Solid: 1.4x (linear)
31
+ ```
32
+
33
+ ## Install
34
+
35
+ ```bash
36
+ pnpm add @niscorp/solid zod
37
+ ```
38
+
39
+ ## Quick Example
40
+
41
+ ```typescript
42
+ import { createStream } from '@niscorp/solid';
43
+ import { z } from 'zod';
44
+
45
+ const schema = z.object({
46
+ widget: z.object({ type: z.string(), title: z.string() }),
47
+ response: z.string(),
48
+ reasoning: z.string(),
49
+ });
50
+
51
+ const stream = createStream({
52
+ schema,
53
+ initial: { widget: { type: '', title: '' }, response: '', reasoning: '' },
54
+ });
55
+
56
+ // Subscribe to the full state
57
+ stream.on((value) => {
58
+ console.log(value.widget.type); // 'card' as soon as the token arrives
59
+ console.log(value.response); // grows character by character
60
+ });
61
+
62
+ // Subscribe to a subtree
63
+ stream.select('widget').onFinal((widget) => {
64
+ console.log('Widget is done:', widget);
65
+ // fires as soon as the parser moves past "widget" in the JSON
66
+ });
67
+
68
+ // Observe validation errors — fires when the LLM sends wrong types
69
+ stream.onError((err) => {
70
+ console.warn(`[${err.phase}] ${err.path}: expected ${err.expected}, got ${err.received}`);
71
+ });
72
+
73
+ // Feed tokens from your LLM stream
74
+ for await (const chunk of llmStream) {
75
+ stream.write(chunk);
76
+ }
77
+ stream.close();
78
+
79
+ // Or await the final result
80
+ const result = await stream.final();
81
+ ```
82
+
83
+ ## Validation modes
84
+
85
+ Every stream enforces the structural invariant: whatever `current()` returns conforms to the schema shape. When the LLM sends a value whose JSON kind doesn't match (a string where a number was expected, an array where an object lives, a field not in the schema), solid reacts based on `mode`:
86
+
87
+ ```typescript
88
+ createStream({ schema, initial, mode: 'recover' }) // default
89
+ createStream({ schema, initial, mode: 'strict' })
90
+ createStream({ schema, initial, mode: 'trust' })
91
+ ```
92
+
93
+ | Mode | Behavior |
94
+ |---|---|
95
+ | `recover` (default) | Reject the bad value, keep the prior valid one, emit `onError`, continue streaming. One hallucinated field doesn't kill rendering. |
96
+ | `strict` | Enter a terminal failed state on first violation. `current()` freezes, further writes are no-ops, `final()` rejects. |
97
+ | `trust` | No validation. Escape hatch for debugging or for producers you fully control. Discouraged. |
98
+
99
+ ### Constraint validation
100
+
101
+ Kind checks catch the structural foot-guns (map-over-a-string, add-to-a-string). For constraint checks — `.min`, `.max`, `.regex`, `.email`, `.int`, `.refine` — opt into `constraints: 'finalize'`:
102
+
103
+ ```typescript
104
+ createStream({ schema, initial, constraints: 'finalize' })
105
+ ```
106
+
107
+ This runs the sub-schema `safeParse` at the exact moment each field closes in the stream, so partial strings never trip constraints they'll eventually satisfy. Violations emit `onError` with `phase: 'finalize'`.
108
+
109
+ ## How it works
110
+
111
+ 1. **Base object** — validated against your Zod schema at construction. This is the starting state. Every field has a value from the start.
112
+
113
+ 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.
114
+
115
+ 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.
116
+
117
+ 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.
118
+
119
+ 5. **Subtree finalization** — JSON keys are written left-to-right. When the parser sees `"response":` after `"widget":{...}`, it knows widget is done. `select('widget').onFinal(...)` fires immediately, without waiting for the full stream to end.
120
+
121
+ 6. **Finalize-phase constraints** (opt-in) — when each field closes, the sub-schema `safeParse` runs once. Catches `.min`, `.regex`, `.email`, `.refine` — constraints that can't be checked mid-stream without false positives.
122
+
123
+ ## What others do
124
+
125
+ | Library | Partial validation | Constraint-at-finalize | Skip bad subtrees | Mode switching |
126
+ |---|---|---|---|---|
127
+ | **Solid** | Kind-check at value-open | Sub-schema safeParse at finalize | Skip-mode, keep prior value | trust / recover / strict |
128
+ | Vercel AI SDK (`streamObject`) | `DeepPartial<T>`, no runtime check | None — end-of-stream only | No — bad data lands in tree | No |
129
+ | Instructor | Explicitly unsupported during streaming | None | No | No |
130
+ | LangChain | End-of-stream only | End-of-stream only | No | No |
131
+
132
+ ## Documentation
133
+
134
+ - **[DESIGN.md](./DESIGN.md)** — Architecture, design decisions, and trade-offs
135
+
136
+ ## API
137
+
138
+ ```typescript
139
+ import { createStream } from '@niscorp/solid';
140
+
141
+ // Create a stream with schema + optional initial value + validation opts
142
+ const stream = createStream({
143
+ schema,
144
+ initial?,
145
+ mode?: 'trust' | 'recover' | 'strict', // default: 'recover'
146
+ constraints?: 'kind' | 'finalize', // default: 'kind'
147
+ });
148
+
149
+ // Feed streamed JSON chunks
150
+ stream.write(chunk: string): void
151
+
152
+ // Signal end of stream (forces finalization)
153
+ stream.close(): void
154
+
155
+ // Tear down all listeners and reject pending promises
156
+ stream.destroy(): void
157
+
158
+ // Read current merged state (always structurally valid)
159
+ stream.current(): T
160
+
161
+ // Promise that resolves when root JSON object closes.
162
+ // Rejects if the stream entered strict failure.
163
+ stream.final(): Promise<T>
164
+
165
+ // Subscribe — fires immediately with current value, then on each change
166
+ stream.on(listener: (value: T) => void): () => void
167
+
168
+ // Subscribe to finalization — fires once when stream ends
169
+ stream.onFinal(listener: (value: T) => void): () => void
170
+
171
+ // Subscribe to validation errors — kind-check failures at value-open,
172
+ // constraint failures at finalize (if constraints: 'finalize')
173
+ stream.onError(listener: (err: StreamError) => void): () => void
174
+
175
+ // Project into a subtree — returns a Stream<P> with its own on/onFinal/onError.
176
+ // Selected streams see only errors at-or-below their path.
177
+ stream.select<P>(path: string): Stream<P>
178
+ ```
179
+
180
+ `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.
181
+
182
+ ## License
183
+
184
+ Apache-2.0