@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/DESIGN.md +320 -0
- package/LICENSE +202 -0
- package/README.md +184 -0
- package/dist/index.cjs +1269 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +34 -0
- package/dist/index.d.ts +34 -0
- package/dist/index.js +1267 -0
- package/dist/index.js.map +1 -0
- package/package.json +69 -0
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
|