@briancray/belte 0.1.0

package/src/lib/shared/subscribableFromResponse.ts

@@ -0,0 +1,333 @@
+import { HttpError } from '../server/HttpError.ts'
+import { decodeResponse } from './decodeResponse.ts'
+import { STREAMING_CONTENT_TYPES } from './streamingContentTypes.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(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)
+}
+
+function errorIterable<T>(error: Error): AsyncIterable<T> {
+    return {
+        [Symbol.asyncIterator](): AsyncIterator<T, void, undefined> {
+            let done = false
+            return {
+                async next() {
+                    if (done) {
+                        return { value: undefined, done: true }
+                    }
+                    done = true
+                    throw error
+                },
+                async return() {
+                    done = true
+                    return { value: undefined, done: true }
+                },
+            }
+        },
+    }
+}
+
+/*
+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.
+*/
+function oneShot<T>(response: Response): AsyncIterable<T> {
+    return {
+        [Symbol.asyncIterator](): AsyncIterator<T, void, undefined> {
+            let yielded = false
+            return {
+                async next() {
+                    if (yielded) {
+                        return { value: undefined, done: true }
+                    }
+                    yielded = true
+                    const value = (await decodeResponse(response)) as T
+                    return { value, done: false }
+                },
+                async return() {
+                    yielded = true
+                    return { value: undefined, done: true }
+                },
+            }
+        },
+    }
+}
+
+/*
+SSE parser: reads the response body as text frames separated by blank
+lines, splits each frame into `event:` / `data:` lines, and yields the
+JSON-parsed data payload. 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
+surface mid-stream failure rather than silently stopping.
+*/
+function parseSse<T>(response: Response): AsyncIterable<T> {
+    return {
+        [Symbol.asyncIterator](): AsyncIterator<T, void, undefined> {
+            const body = response.body
+            if (!body) {
+                return emptyIterator<T>()
+            }
+            const reader = body.pipeThrough(new TextDecoderStream()).getReader()
+            let buffer = ''
+            let bufferStart = 0
+            const pending: Array<{ event: string; data: string }> = []
+            let done = false
+
+            async function pullFrames(): Promise<void> {
+                while (pending.length === 0 && !done) {
+                    const { value, done: streamDone } = await reader.read()
+                    if (streamDone) {
+                        done = true
+                        if (bufferStart < buffer.length) {
+                            const frame = parseFrame(buffer.slice(bufferStart))
+                            if (frame) {
+                                pending.push(frame)
+                            }
+                            buffer = ''
+                            bufferStart = 0
+                        }
+                        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('\n\n', bufferStart)
+                    while (boundary !== -1) {
+                        const raw = buffer.slice(bufferStart, boundary)
+                        bufferStart = boundary + 2
+                        const frame = parseFrame(raw)
+                        if (frame) {
+                            pending.push(frame)
+                        }
+                        boundary = buffer.indexOf('\n\n', bufferStart)
+                    }
+                }
+            }
+
+            return {
+                async next() {
+                    while (true) {
+                        if (pending.length > 0) {
+                            const next = pending.shift() as { event: string; data: string }
+                            if (next.event === 'error') {
+                                try {
+                                    const decoded = JSON.parse(next.data) as { message?: string }
+                                    throw new Error(decoded?.message ?? 'sse stream error')
+                                } catch (err) {
+                                    if (err instanceof SyntaxError) {
+                                        throw new Error(next.data || 'sse stream error')
+                                    }
+                                    throw err
+                                }
+                            }
+                            const value = JSON.parse(next.data) as T
+                            return { value, done: false }
+                        }
+                        if (done) {
+                            return { value: undefined, done: true }
+                        }
+                        await pullFrames()
+                    }
+                },
+                async return() {
+                    done = true
+                    await reader.cancel().catch(() => undefined)
+                    return { value: undefined, done: true }
+                },
+            }
+        },
+    }
+}
+
+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: reads the response body as text, splits on `\n`,
+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.
+*/
+function parseJsonLines<T>(response: Response): AsyncIterable<T> {
+    return {
+        [Symbol.asyncIterator](): AsyncIterator<T, void, undefined> {
+            const body = response.body
+            if (!body) {
+                return emptyIterator<T>()
+            }
+            const reader = body.pipeThrough(new TextDecoderStream()).getReader()
+            let buffer = ''
+            let bufferStart = 0
+            const pending: string[] = []
+            let done = false
+
+            async function pullLines(): Promise<void> {
+                while (pending.length === 0 && !done) {
+                    const { value, done: streamDone } = await reader.read()
+                    if (streamDone) {
+                        done = true
+                        if (bufferStart < buffer.length) {
+                            pending.push(buffer.slice(bufferStart))
+                            buffer = ''
+                            bufferStart = 0
+                        }
+                        return
+                    }
+                    if (bufferStart > buffer.length / 2) {
+                        buffer = buffer.slice(bufferStart) + value
+                        bufferStart = 0
+                    } else {
+                        buffer += value
+                    }
+                    let newline = buffer.indexOf('\n', bufferStart)
+                    while (newline !== -1) {
+                        const line = buffer.slice(bufferStart, newline)
+                        bufferStart = newline + 1
+                        if (line.length > 0) {
+                            pending.push(line)
+                        }
+                        newline = buffer.indexOf('\n', bufferStart)
+                    }
+                }
+            }
+
+            return {
+                async next() {
+                    while (true) {
+                        if (pending.length > 0) {
+                            const line = pending.shift() as string
+                            const parsed = JSON.parse(line) as Record<string, unknown> & {
+                                $error?: string
+                            }
+                            if (
+                                parsed &&
+                                typeof parsed === 'object' &&
+                                typeof parsed.$error === 'string'
+                            ) {
+                                throw new Error(parsed.$error)
+                            }
+                            return { value: parsed as T, done: false }
+                        }
+                        if (done) {
+                            return { value: undefined, done: true }
+                        }
+                        await pullLines()
+                    }
+                },
+                async return() {
+                    done = true
+                    await reader.cancel().catch(() => undefined)
+                    return { value: undefined, done: true }
+                },
+            }
+        },
+    }
+}
+
+function emptyIterator<T>(): AsyncIterator<T, void, undefined> {
+    return {
+        async next() {
+            return { value: undefined, done: true }
+        },
+        async return() {
+            return { value: undefined, done: true }
+        },
+    }
+}
+
+/*
+Builds the Subscribable returned by `fn.stream(args)`. The carried
+`name` is the cache-style key for (method, url, args) so subscribe()
+dedupes multiple subscribers to identical args into one underlying
+fetch. The fetch is deferred until the first iterator pull so simply
+constructing the Subscribable (which happens on every $derived
+re-evaluation) doesn't open a connection — subscribe()'s registry
+short-circuits the second instance before it iterates.
+*/
+export function subscribableFromResponse<T>(
+    name: string,
+    fetchResponse: () => Promise<Response>,
+): Subscribable<T> {
+    return {
+        name,
+        [Symbol.asyncIterator]() {
+            let inner: AsyncIterator<T, void, undefined> | undefined
+            return {
+                async next() {
+                    if (!inner) {
+                        const response = await fetchResponse()
+                        inner = streamResponse<T>(response)[Symbol.asyncIterator]()
+                    }
+                    return inner.next()
+                },
+                async return() {
+                    await inner?.return?.(undefined)
+                    return { value: undefined, done: true }
+                },
+            }
+        },
+    }
+}

package/src/lib/shared/toBunRoutePattern.ts

@@ -0,0 +1,28 @@
+import { parseRouteSegments } from './parseRouteSegments.ts'
+
+/*
+Translates a belte route URL (`/media/[id]/[...rest]`) into the pattern Bun
+needs (`/media/:id/*`) for `Bun.serve({ routes })`. Returns the catch-all
+segment's original name alongside so the server can rename Bun's `*` param
+back to that name on the way out, keeping page-prop destructuring consistent
+with the route file path.
+*/
+export function toBunRoutePattern(routeUrl: string): {
+    pattern: string
+    catchAllName: string | undefined
+} {
+    let catchAllName: string | undefined
+    const pattern = parseRouteSegments(routeUrl)
+        .map((segment) => {
+            if (segment.kind === 'literal') {
+                return segment.value
+            }
+            if (segment.catchAll) {
+                catchAllName = segment.name
+                return '*'
+            }
+            return `:${segment.name}`
+        })
+        .join('/')
+    return { pattern, catchAllName }
+}

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

@@ -0,0 +1,16 @@
+/*
+Stored shape per cache key. `request` is retained so SSR snapshot
+serialization can record the URL and method without re-deriving them from
+the function. `ttl`/`expiresAt` drive eviction: expiresAt = undefined means
+"no TTL" (lives forever); ttl = 0 means "dedupe only" (entry is pruned as
+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.
+*/
+export type CacheEntry = {
+    key: string
+    promise: Promise<Response>
+    request: Request
+    ttl: number | undefined
+    expiresAt: number | undefined
+}

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

@@ -0,0 +1,10 @@
+/*
+Options for cache(). `key` overrides the auto-derived WeakMap key — useful
+when sharing entries across calls or stripping noisy args. `ttl` is the
+milliseconds-past-resolve that the entry stays live: omitted = forever, 0 =
+dedupe only (entry dropped once the promise settles), any other number = TTL.
+*/
+export type CacheOptions = {
+    key?: string | unknown[] | Record<string, unknown>
+    ttl?: number
+}

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

@@ -0,0 +1,15 @@
+/*
+Wire format for a single cached response shipped from SSR to client hydration.
+Only GET/DELETE entries with a textual Content-Type are emitted — POST/PUT
+bodies can't be reconstructed without shipping the original request body,
+and binary bodies don't survive a JSON round-trip.
+*/
+export type CacheSnapshotEntry = {
+    key: string
+    url: string
+    method: 'GET' | 'DELETE'
+    status: number
+    statusText: string
+    headers: Array<[string, string]>
+    body: string
+}

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

@@ -0,0 +1,15 @@
+import type { CacheEntry } from './CacheEntry.ts'
+
+/*
+Cache map paired with a Svelte-aware per-key subscriber. Calling
+`subscribe(key)` from inside a tracking scope ($derived / $effect) registers
+that scope to re-run when the entry is invalidated; called outside tracking
+it's a no-op. Subscribers live for the lifetime of the store: the server
+uses a fresh store per request (so subscribers die with the response), the
+client uses a single module-level store (so subscribers persist for the tab).
+*/
+export type CacheStore = {
+    entries: Map<string, CacheEntry>
+    events: EventTarget
+    subscribe: (key: string) => void
+}

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

@@ -0,0 +1,11 @@
+/*
+Which client surfaces a verb or socket is exposed to. Browser is the
+historical default; MCP and CLI flip on automatically when the
+declaration carries a Standard Schema (the schema is what makes the
+non-browser surfaces safe to advertise). Explicit values always win.
+*/
+export type ClientFlags = {
+    browser: boolean
+    mcp: boolean
+    cli: boolean
+}

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

@@ -0,0 +1,15 @@
+/*
+The thing `subscribe()` reads from: an AsyncIterable carrying a stable
+`name` used as the subscription registry key. Both `Socket<T>` (the
+declared broadcast primitive) and the result of `fn.stream(args)`
+(per-call HTTP stream consumer) satisfy this shape, so subscribe() can
+share one iterator across multiple readers regardless of source.
+
+The name on a Socket comes from the file path under `src/server/sockets/`.
+The name on an fn.stream(args) result is `keyForRemoteCall(method, url,
+args)` — the same key cache() uses — so two subscribers to the same
+remote-call args dedupe to one underlying fetch.
+*/
+export interface Subscribable<T> extends AsyncIterable<T> {
+    readonly name: string
+}

package/src/lib/shared/writeRoutesDts.ts

@@ -0,0 +1,64 @@
+import { pageUrlForFile } from './pageUrlForFile.ts'
+import { parseRouteSegments } from './parseRouteSegments.ts'
+
+/*
+Walks a `[name]` / `[...rest]` route URL and returns the param shape it
+declares. Catch-all segments map to `string` under their declared name —
+the server's toBunRoutePattern renames Bun's `*` key back to that name
+when dispatching, so the page component sees `params.rest`, not
+`params['*']`.
+*/
+function paramsForRoute(routeUrl: string): Record<string, 'string'> {
+    const params: Record<string, 'string'> = {}
+    for (const segment of parseRouteSegments(routeUrl)) {
+        if (segment.kind === 'param') {
+            params[segment.name] = 'string'
+        }
+    }
+    return params
+}
+
+function renderParamsShape(shape: Record<string, 'string'>): string {
+    const keys = Object.keys(shape)
+    if (keys.length === 0) {
+        return 'Record<string, never>'
+    }
+    return `{ ${keys.map((key) => `${JSON.stringify(key)}: string`).join('; ')} }`
+}
+
+/*
+Emits a `.d.ts` that augments belte's `Routes` interface with one entry per
+page file in the project. Page picks this up as a discriminated union keyed
+on `route`, so `if (page.route === '/media/[id]') page.params.id` is typed
+automatically without consumers writing route types by hand.
+The file is written to `src/.belte/routes.d.ts` so the consumer's existing
+src tsconfig include picks it up with no extra configuration.
+*/
+export async function writeRoutesDts({
+    cwd,
+    pageFiles,
+}: {
+    cwd: string
+    pageFiles: string[]
+}): Promise<void> {
+    const entries = pageFiles
+        .map((file) => ({
+            route: pageUrlForFile(file),
+            params: paramsForRoute(pageUrlForFile(file)),
+        }))
+        .toSorted((a, b) => a.route.localeCompare(b.route))
+        .map(
+            ({ route, params }) => `        ${JSON.stringify(route)}: ${renderParamsShape(params)}`,
+        )
+        .join('\n')
+    const contents = `// Generated by belte. Do not edit by hand.
+declare module 'belte/browser/page' {
+    interface Routes {
+${entries}
+    }
+}
+
+export {}
+`
+    await Bun.write(`${cwd}/src/.belte/routes.d.ts`, contents)
+}

package/src/preload.ts

@@ -0,0 +1,20 @@
+import { plugin } from 'bun'
+import { belteResolverPlugin } from './belteResolverPlugin.ts'
+import { loadSvelteConfig } from './lib/shared/loadSvelteConfig.ts'
+import { sveltePlugin } from './sveltePlugin.ts'
+
+const mode = (process.env.BELTE_SVELTE_MODE ?? 'server') as 'server' | 'client'
+const svelteConfig = await loadSvelteConfig()
+
+await plugin(sveltePlugin({ generate: mode, svelteConfig }))
+await plugin(belteResolverPlugin({ target: mode }))
+
+await plugin({
+    name: 'css-noop',
+    setup(build) {
+        build.onLoad({ filter: /\.css$/ }, () => ({
+            contents: 'export default {};',
+            loader: 'js',
+        }))
+    },
+})

package/src/scaffold.ts

@@ -0,0 +1,92 @@
+import { Glob } from 'bun'
+import { log } from './lib/shared/log.ts'
+
+const TEMPLATE_DIR = new URL('../template', import.meta.url).pathname
+
+/*
+Copies the bundled template directory into `${cwd}/${name}`. Refuses to write
+into a non-empty directory so an accidental run doesn't overwrite real work.
+*/
+export async function scaffold({
+    cwd = process.cwd(),
+    name,
+}: {
+    cwd?: string
+    name: string
+}): Promise<string> {
+    const trimmed = name.trim()
+    if (trimmed === '') {
+        throw new Error('[belte] project name is required: bunx belte scaffold <name>')
+    }
+    const target = resolveTarget(cwd, trimmed)
+    if (await targetIsNonEmpty(target)) {
+        throw new Error(`[belte] target directory is not empty: ${target}`)
+    }
+    if (!(await Bun.file(`${TEMPLATE_DIR}/package.json`).exists())) {
+        throw new Error(`[belte] template missing at ${TEMPLATE_DIR}`)
+    }
+    await copyTree(TEMPLATE_DIR, target)
+    log.success(`scaffolded belte project at ${target}`)
+    log.detail('  next steps:')
+    if (target !== cwd) {
+        log.detail(`    cd ${trimmed}`)
+    }
+    log.detail('    bun install')
+    log.detail('    bun run dev')
+    return target
+}
+
+/*
+Copies every file under `from` into `to`, preserving relative paths. Uses
+Bun.Glob to enumerate (dotfiles included) and Bun.write to materialize each
+file — Bun.write auto-creates parent directories.
+*/
+async function copyTree(from: string, to: string): Promise<void> {
+    const files = await Array.fromAsync(
+        new Glob('**/*').scan({ cwd: from, onlyFiles: true, dot: true }),
+    )
+    await Promise.all(
+        files.map(async (relativePath) => {
+            const source = Bun.file(`${from}/${relativePath}`)
+            await Bun.write(`${to}/${relativePath}`, source)
+        }),
+    )
+}
+
+/*
+Resolves the user-supplied name against the working directory. Absolute
+paths (`/tmp/foo`) and `~`-prefixed paths are used as-is; relative names
+are joined onto `cwd`.
+*/
+function resolveTarget(cwd: string, name: string): string {
+    if (name === '.' || name === './') {
+        return cwd
+    }
+    if (name.startsWith('/')) {
+        return name
+    }
+    if (name.startsWith('~/')) {
+        const home = process.env.HOME ?? ''
+        return `${home}${name.slice(1)}`
+    }
+    return `${cwd}/${name}`
+}
+
+/*
+True when the target exists and contains at least one entry. Uses Bun.Glob
+rather than fs.readdir to honor the project's "Bun-first" rule. A missing
+directory is reported as empty so first-time scaffolds proceed.
+*/
+async function targetIsNonEmpty(target: string): Promise<boolean> {
+    try {
+        for await (const _ of new Glob('*').scan({ cwd: target, onlyFiles: false, dot: true })) {
+            return true
+        }
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+            return false
+        }
+        throw error
+    }
+    return false
+}

package/src/serverEntry.ts

@@ -0,0 +1,47 @@
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import * as appMod from './_virtual/app.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { appInfo } from './_virtual/app-info.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { assets } from './_virtual/assets.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import cliProgramName from './_virtual/cli-name.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { layouts } from './_virtual/layouts.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import mcp from './_virtual/mcp.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { mcpResources } from './_virtual/mcp-resources.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { pages } from './_virtual/pages.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { prompts } from './_virtual/prompts.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { publicAssets } from './_virtual/public-assets.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { rpc } from './_virtual/rpc.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { shell } from './_virtual/shell.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { sockets } from './_virtual/sockets.ts'
+import { createServer } from './lib/server/runtime/createServer.ts'
+import { requestContext } from './lib/server/runtime/requestContext.ts'
+import { setCacheStoreResolver } from './lib/shared/setCacheStoreResolver.ts'
+
+setCacheStoreResolver(() => requestContext.getStore()?.cache)
+
+await createServer({
+    pages,
+    rpc,
+    sockets,
+    prompts,
+    layouts,
+    shell,
+    app: appMod,
+    assets,
+    publicAssets,
+    mcpResources,
+    mcp,
+    cliProgramName,
+    appInfo,
+})