@briancray/belte 0.3.0 → 0.4.0

package/src/lib/shared/streamResponse.ts

@@ -0,0 +1,168 @@
+import { HttpError } from '../server/HttpError.ts'
+import { decodeResponse } from './decodeResponse.ts'
+import { jsonlErrorFrame } from './jsonlErrorFrame.ts'
+import { sseErrorFrame } from './sseErrorFrame.ts'
+import { STREAMING_CONTENT_TYPES } from './streamingContentTypes.ts'
+
+/*
+Turns a Response into an AsyncIterable of frames, regardless of the
+handler's chosen body format. Shared by `fn.stream(args)` (via
+subscribableFromResponse), the CLI's streaming print path, and the MCP
+tool dispatcher's stream drain — so every surface consumes sse/jsonl
+identically. Three shapes are handled:
+
+- text/event-stream (SSE): emits the JSON-parsed `data:` payload of
+  each event. The `event: error\ndata: {message}` frame the `sse()`
+  helper emits on generator throws is mapped back to a thrown Error so
+  consumers see the failure mid-iteration.
+- application/jsonl + application/x-ndjson: emits one JSON value per
+  line. The trailing `{"$error":"..."}` line the `jsonl()` helper
+  emits on generator throws is likewise re-thrown.
+- everything else: one-shot — yields the Content-Type-decoded body
+  once, then completes. Lets callers iterate uniformly on every rpc
+  handler, not just the streaming ones.
+
+Non-2xx responses surface as a thrown HttpError on the first pull,
+mirroring the plain `fn(args)` decode path.
+*/
+export function streamResponse<T>(response: Response): AsyncIterable<T> {
+    if (!response.ok) {
+        return errorIterable<T>(new HttpError(response))
+    }
+    const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
+    if (contentType.startsWith('text/event-stream')) {
+        return parseSse<T>(response)
+    }
+    if (STREAMING_CONTENT_TYPES.some((type) => contentType.startsWith(type))) {
+        return parseJsonLines<T>(response)
+    }
+    return oneShot<T>(response)
+}
+
+/* Surfaces a non-2xx response (or any pre-stream failure) as a thrown error on the first pull. */
+async function* errorIterable<T>(error: Error): AsyncGenerator<T> {
+    throw error
+}
+
+/*
+One-shot iterator over a non-streaming Response: decodes the body once
+via the same Content-Type sniffing the plain call uses, yields it, then
+completes. Makes streaming symmetrical across streaming and
+non-streaming handlers — callers can pick the iteration shape without
+worrying about which body the handler returned.
+*/
+async function* oneShot<T>(response: Response): AsyncGenerator<T> {
+    yield (await decodeResponse(response)) as T
+}
+
+/*
+Reads a streaming text Response and yields raw frame strings split on
+`delimiter` (`\n\n` for SSE events, `\n` for JSON lines). Owns the whole
+buffering lifecycle: incremental decode, amortised-O(n) compaction, a
+final flush of the trailing partial frame, and reader cancellation when
+the consumer stops iterating (the generator's `finally` runs on
+`return()`). The SSE and jsonl parsers layer their per-frame parsing on
+top of this single machine so the two can't drift.
+*/
+async function* frameReader(response: Response, delimiter: string): AsyncGenerator<string> {
+    const body = response.body
+    if (!body) {
+        return
+    }
+    const reader = body.pipeThrough(new TextDecoderStream()).getReader()
+    let buffer = ''
+    let bufferStart = 0
+    try {
+        while (true) {
+            const { value, done } = await reader.read()
+            if (done) {
+                if (bufferStart < buffer.length) {
+                    yield buffer.slice(bufferStart)
+                }
+                return
+            }
+            /*
+            Compact only when the unread region is small relative to the
+            consumed prefix — keeps amortised work O(n) instead of
+            quadratic slicing per frame boundary.
+            */
+            if (bufferStart > buffer.length / 2) {
+                buffer = buffer.slice(bufferStart) + value
+                bufferStart = 0
+            } else {
+                buffer += value
+            }
+            let boundary = buffer.indexOf(delimiter, bufferStart)
+            while (boundary !== -1) {
+                yield buffer.slice(bufferStart, boundary)
+                bufferStart = boundary + delimiter.length
+                boundary = buffer.indexOf(delimiter, bufferStart)
+            }
+        }
+    } finally {
+        await reader.cancel().catch(() => undefined)
+    }
+}
+
+/*
+SSE parser: yields the JSON-parsed `data` payload of each `event:`/`data:`
+frame. The error sentinel (`sseErrorFrame`) the `sse()` helper emits on a
+generator throw is surfaced as a thrown Error so consumer loops can react
+to mid-stream failure rather than silently stopping.
+*/
+async function* parseSse<T>(response: Response): AsyncGenerator<T> {
+    for await (const raw of frameReader(response, '\n\n')) {
+        const frame = parseFrame(raw)
+        if (!frame) {
+            continue
+        }
+        const errorMessage = sseErrorFrame.decode(frame.event, frame.data)
+        if (errorMessage !== undefined) {
+            throw new Error(errorMessage)
+        }
+        yield JSON.parse(frame.data) as T
+    }
+}
+
+function parseFrame(raw: string): { event: string; data: string } | undefined {
+    const lines = raw.split('\n').filter((line) => line.length > 0 && !line.startsWith(':'))
+    if (lines.length === 0) {
+        return undefined
+    }
+    let event = 'message'
+    const dataLines: string[] = []
+    for (const line of lines) {
+        const colon = line.indexOf(':')
+        const field = colon === -1 ? line : line.slice(0, colon)
+        const value = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '')
+        if (field === 'event') {
+            event = value
+        } else if (field === 'data') {
+            dataLines.push(value)
+        }
+    }
+    if (dataLines.length === 0) {
+        return undefined
+    }
+    return { event, data: dataLines.join('\n') }
+}
+
+/*
+JSONL/NDJSON parser: parses each non-empty line as JSON and yields the
+value. The error sentinel (`jsonlErrorFrame`) the `jsonl()` helper emits as
+a trailing line on a generator throw is surfaced here as a thrown Error so
+consumer loops can react to mid-stream failure.
+*/
+async function* parseJsonLines<T>(response: Response): AsyncGenerator<T> {
+    for await (const raw of frameReader(response, '\n')) {
+        if (raw.length === 0) {
+            continue
+        }
+        const parsed = JSON.parse(raw)
+        const errorMessage = jsonlErrorFrame.decode(parsed)
+        if (errorMessage !== undefined) {
+            throw new Error(errorMessage)
+        }
+        yield parsed as T
+    }
+}

package/src/lib/shared/subscribableFromResponse.ts

@@ -1,177 +1,6 @@
-import { HttpError } from '../server/HttpError.ts'
-import { decodeResponse } from './decodeResponse.ts'
-import { STREAMING_CONTENT_TYPES } from './streamingContentTypes.ts'
+import { streamResponse } from './streamResponse.ts'
 import type { Subscribable } from './types/Subscribable.ts'
 
-/*
-Turns a Response into an AsyncIterable of frames. Used by
-`fn.stream(args)` to give callers a uniform iterator regardless of the
-handler's chosen body format. Three shapes are handled:
-
-- text/event-stream (SSE): emits the JSON-parsed `data:` payload of
-  each event. The `event: error\ndata: {message}` frame the `sse()`
-  helper emits on generator throws is mapped back to a thrown Error so
-  consumers see the failure mid-iteration.
-- application/jsonl + application/x-ndjson: emits one JSON value per
-  line. The trailing `{"$error":"..."}` line the `jsonl()` helper
-  emits on generator throws is likewise re-thrown.
-- everything else: one-shot — yields the Content-Type-decoded body
-  once, then completes. Lets `fn.stream(args)` work uniformly on every
-  rpc handler, not just the streaming ones.
-
-Non-2xx responses surface as a thrown HttpError on the first pull,
-mirroring the plain `fn(args)` decode path.
-*/
-function streamResponse<T>(response: Response): AsyncIterable<T> {
-    if (!response.ok) {
-        return errorIterable<T>(new HttpError(response))
-    }
-    const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
-    if (contentType.startsWith('text/event-stream')) {
-        return parseSse<T>(response)
-    }
-    if (STREAMING_CONTENT_TYPES.some((type) => contentType.startsWith(type))) {
-        return parseJsonLines<T>(response)
-    }
-    return oneShot<T>(response)
-}
-
-/* Surfaces a non-2xx response (or any pre-stream failure) as a thrown error on the first pull. */
-async function* errorIterable<T>(error: Error): AsyncGenerator<T> {
-    throw error
-}
-
-/*
-One-shot iterator over a non-streaming Response: decodes the body once
-via the same Content-Type sniffing the plain call uses, yields it, then
-completes. Makes `fn.stream(args)` symmetrical across streaming and
-non-streaming handlers — callers can pick the iteration shape without
-worrying about which body the handler returned.
-*/
-async function* oneShot<T>(response: Response): AsyncGenerator<T> {
-    yield (await decodeResponse(response)) as T
-}
-
-/*
-Reads a streaming text Response and yields raw frame strings split on
-`delimiter` (`\n\n` for SSE events, `\n` for JSON lines). Owns the whole
-buffering lifecycle: incremental decode, amortised-O(n) compaction, a
-final flush of the trailing partial frame, and reader cancellation when
-the consumer stops iterating (the generator's `finally` runs on
-`return()`). The SSE and jsonl parsers layer their per-frame parsing on
-top of this single machine so the two can't drift.
-*/
-async function* frameReader(response: Response, delimiter: string): AsyncGenerator<string> {
-    const body = response.body
-    if (!body) {
-        return
-    }
-    const reader = body.pipeThrough(new TextDecoderStream()).getReader()
-    let buffer = ''
-    let bufferStart = 0
-    try {
-        while (true) {
-            const { value, done } = await reader.read()
-            if (done) {
-                if (bufferStart < buffer.length) {
-                    yield buffer.slice(bufferStart)
-                }
-                return
-            }
-            /*
-            Compact only when the unread region is small relative to the
-            consumed prefix — keeps amortised work O(n) instead of
-            quadratic slicing per frame boundary.
-            */
-            if (bufferStart > buffer.length / 2) {
-                buffer = buffer.slice(bufferStart) + value
-                bufferStart = 0
-            } else {
-                buffer += value
-            }
-            let boundary = buffer.indexOf(delimiter, bufferStart)
-            while (boundary !== -1) {
-                yield buffer.slice(bufferStart, boundary)
-                bufferStart = boundary + delimiter.length
-                boundary = buffer.indexOf(delimiter, bufferStart)
-            }
-        }
-    } finally {
-        await reader.cancel().catch(() => undefined)
-    }
-}
-
-/*
-SSE parser: yields the JSON-parsed `data` payload of each `event:`/`data:`
-frame. The `sse()` respond helper emits an `event: error\ndata:
-{"message":...}` frame when the source generator throws, which we surface
-as a thrown Error so consumer loops can react to mid-stream failure
-rather than silently stopping.
-*/
-async function* parseSse<T>(response: Response): AsyncGenerator<T> {
-    for await (const raw of frameReader(response, '\n\n')) {
-        const frame = parseFrame(raw)
-        if (!frame) {
-            continue
-        }
-        if (frame.event === 'error') {
-            try {
-                const decoded = JSON.parse(frame.data) as { message?: string }
-                throw new Error(decoded?.message ?? 'sse stream error')
-            } catch (err) {
-                if (err instanceof SyntaxError) {
-                    throw new Error(frame.data || 'sse stream error')
-                }
-                throw err
-            }
-        }
-        yield JSON.parse(frame.data) as T
-    }
-}
-
-function parseFrame(raw: string): { event: string; data: string } | undefined {
-    const lines = raw.split('\n').filter((line) => line.length > 0 && !line.startsWith(':'))
-    if (lines.length === 0) {
-        return undefined
-    }
-    let event = 'message'
-    const dataLines: string[] = []
-    for (const line of lines) {
-        const colon = line.indexOf(':')
-        const field = colon === -1 ? line : line.slice(0, colon)
-        const value = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '')
-        if (field === 'event') {
-            event = value
-        } else if (field === 'data') {
-            dataLines.push(value)
-        }
-    }
-    if (dataLines.length === 0) {
-        return undefined
-    }
-    return { event, data: dataLines.join('\n') }
-}
-
-/*
-JSONL/NDJSON parser: parses each non-empty line as JSON and yields the
-value. The `jsonl()` respond helper emits a trailing
-`{"$error":"<message>"}` line when the source generator throws — that's
-surfaced here as a thrown Error so consumer loops can react to mid-stream
-failure.
-*/
-async function* parseJsonLines<T>(response: Response): AsyncGenerator<T> {
-    for await (const raw of frameReader(response, '\n')) {
-        if (raw.length === 0) {
-            continue
-        }
-        const parsed = JSON.parse(raw) as Record<string, unknown> & { $error?: string }
-        if (parsed && typeof parsed === 'object' && typeof parsed.$error === 'string') {
-            throw new Error(parsed.$error)
-        }
-        yield parsed as T
-    }
-}
-
 /*
 Builds the Subscribable returned by `fn.stream(args)`. The carried
 `name` is the cache-style key for (method, url, args) so subscribe()

package/src/lib/shared/types/CacheEntry.ts

@@ -6,6 +6,11 @@ the function. `ttl`/`expiresAt` drive eviction: expiresAt = undefined means
 soon as the promise settles). The stored promise resolves to the raw
 Response so the snapshot can read its status/headers/body; the cache
 layer hands callers a decoded view derived from this same promise.
+
+`value` is set only for entries hydrated from the SSR snapshot: the
+snapshot body is pre-decoded synchronously so the first client render can
+read it without a microtask hop and byte-match the SSR DOM. Live fetches
+leave it undefined and take the async decode path.
 */
 export type CacheEntry = {
     key: string
@@ -13,4 +18,5 @@ export type CacheEntry = {
     request: Request
     ttl: number | undefined
     expiresAt: number | undefined
+    value?: unknown
 }

package/template/src/server/rpc/getHello.ts

@@ -12,9 +12,11 @@ decoding) is inferred from the handler's return type via the
 `TypedResponse<T>` brand on `json`/`error`/`redirect`/`jsonl`/`sse`, so
 plain `GET(() => json({...}))` already types end-to-end.
 
-For inbound validation pass a Standard Schema-compatible schema as the
-second argument: `GET(fn, { schema })`. Args then infers from the schema's
-output type and the server replies with 422 on validation failure.
+For inbound validation pass a Standard Schema as `inputSchema` in the
+second argument: `GET(fn, { inputSchema })`. Args then infers from the
+schema's output type and the server replies with 422 on validation
+failure. An optional `outputSchema` describes the success body for the
+OpenAPI 200 response and the MCP tool output.
 
 `json(...)` from `belte/server/json` is a thin wrapper over `Response.json`
 that defaults `Cache-Control: no-store`, since intermediary caches shouldn't

package/src/lib/shared/belteImportName.test.ts

@@ -1,58 +0,0 @@
-import { afterAll, expect, test } from 'bun:test'
-import { mkdtempSync, rmSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { belteImportName } from './belteImportName.ts'
-
-const roots: string[] = []
-afterAll(() => roots.forEach((root) => rmSync(root, { recursive: true, force: true })))
-
-// Writes a package.json into a fresh temp dir and returns the dir.
-async function projectWith(packageJson: unknown): Promise<string> {
-    const root = mkdtempSync(`${tmpdir()}/belte-import-name-`)
-    roots.push(root)
-    await Bun.write(`${root}/package.json`, JSON.stringify(packageJson))
-    return root
-}
-
-test('uses the canonical name for a direct dependency', async () => {
-    const cwd = await projectWith({ dependencies: { '@briancray/belte': '^0.2.0' } })
-    expect(await belteImportName(cwd)).toBe('@briancray/belte')
-})
-
-test('uses the `belte` alias key for an npm alias', async () => {
-    const cwd = await projectWith({ dependencies: { belte: 'npm:@briancray/belte@^0.2.0' } })
-    expect(await belteImportName(cwd)).toBe('belte')
-})
-
-test('uses the `belte` alias key for a workspace alias', async () => {
-    const cwd = await projectWith({ dependencies: { belte: 'workspace:@briancray/belte@*' } })
-    expect(await belteImportName(cwd)).toBe('belte')
-})
-
-test('uses a non-`belte` alias key when that is how belte is declared', async () => {
-    const cwd = await projectWith({ dependencies: { framework: 'npm:@briancray/belte' } })
-    expect(await belteImportName(cwd)).toBe('framework')
-})
-
-test('prefers the `belte` alias over a direct canonical dependency', async () => {
-    const cwd = await projectWith({
-        dependencies: { '@briancray/belte': '^0.2.0', belte: 'npm:@briancray/belte@^0.2.0' },
-    })
-    expect(await belteImportName(cwd)).toBe('belte')
-})
-
-test('finds the alias in devDependencies', async () => {
-    const cwd = await projectWith({ devDependencies: { belte: 'npm:@briancray/belte@^0.2.0' } })
-    expect(await belteImportName(cwd)).toBe('belte')
-})
-
-test('falls back to the canonical name when belte is absent', async () => {
-    const cwd = await projectWith({ dependencies: { svelte: '^5.0.0' } })
-    expect(await belteImportName(cwd)).toBe('@briancray/belte')
-})
-
-test('falls back to the canonical name when package.json is missing', async () => {
-    const root = mkdtempSync(`${tmpdir()}/belte-import-name-`)
-    roots.push(root)
-    expect(await belteImportName(root)).toBe('@briancray/belte')
-})