@belte/belte 0.19.0

package/src/lib/shared/createCacheStore.ts

@@ -0,0 +1,75 @@
+import { createSubscriber } from 'svelte/reactivity'
+import type { CacheEntry } from './types/CacheEntry.ts'
+import type { CacheInvalidation } from './types/CacheInvalidation.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+
+/*
+Returns a fresh cache store. On the server, every request gets its own
+store via the AsyncLocalStorage RequestStore. On the client, a single
+module-level store is created at startup and shared across the tab.
+
+Each key gets a lazily-created Svelte subscriber. Reading a key from a
+tracking scope ($derived / $effect) subscribes that scope; invalidating
+the key dispatches an 'invalidate' event whose detail is a Set of affected
+keys so each listener's lookup is O(1). The subscriber outlives entry
+eviction — invalidating/refetching a key reuses the same subscriber, so
+there's no listener churn or duplicate registration as cache values come
+and go. It's evicted only when its last reactive reader tears down (the
+client store is module-level/tab-scoped, so retaining a thunk per distinct
+key would otherwise grow unbounded across a session), identity-guarded so
+a concurrent re-subscribe isn't clobbered — mirroring subscribe.ts.
+*/
+export function createCacheStore(): CacheStore {
+    const entries = new Map<string, CacheEntry>()
+    const events = new EventTarget()
+    const subscribers = new Map<string, () => void>()
+    const pendingRefresh = new Set<string>()
+
+    function subscribe(key: string): void {
+        const existing = subscribers.get(key)
+        if (existing) {
+            existing()
+            return
+        }
+        const registered = createSubscriber((update) => {
+            const onInvalidate = (event: Event) => {
+                if ((event as CustomEvent<CacheInvalidation>).detail.has(key)) {
+                    update()
+                }
+            }
+            events.addEventListener('invalidate', onInvalidate)
+            return () => {
+                events.removeEventListener('invalidate', onInvalidate)
+                if (subscribers.get(key) === registered) {
+                    subscribers.delete(key)
+                }
+            }
+        })
+        subscribers.set(key, registered)
+        registered()
+    }
+
+    /*
+    Store-wide tap for in-flight lifecycle. cache.pending selectors match many
+    entries (or all), so they re-derive by scanning `entries` and only need a
+    single "something changed" signal rather than per-key granularity. One
+    lazily-created subscriber for the whole store, evicted when its last reader
+    tears down — mirroring subscribe(key) and subscribe.ts.
+    */
+    let lifecycle: (() => void) | undefined
+    function trackLifecycle(): void {
+        if (!lifecycle) {
+            lifecycle = createSubscriber((update) => {
+                const onLifecycle = () => update()
+                events.addEventListener('lifecycle', onLifecycle)
+                return () => {
+                    events.removeEventListener('lifecycle', onLifecycle)
+                    lifecycle = undefined
+                }
+            })
+        }
+        lifecycle()
+    }
+
+    return { entries, events, subscribe, trackLifecycle, pendingRefresh }
+}

package/src/lib/shared/createPushIterator.ts

@@ -0,0 +1,93 @@
+/*
+Single-slot-mailbox AsyncIterator factory shared by the in-process
+socket fan-out (defineSocket) and the client-side ws proxy
+(socketProxy). Callers push values, signal end, or signal an error;
+the iterator drains a queue then awaits the next push. Cancellation
+runs the optional `onClose` so subscribers can drop their backref.
+
+The pending-value buffer is bounded: a subscriber whose `next()` falls
+behind a chatty producer would otherwise grow it without limit, which on
+the server is a remotely-triggerable memory-exhaustion vector. At the cap
+the oldest pending value is dropped (live fan-out is latest-wins) so
+memory stays bounded; terminal end/error slots are always appended and
+never dropped.
+*/
+
+type Slot<T> = { kind: 'value'; value: T } | { kind: 'end' } | { kind: 'error'; message: string }
+
+export type PushIterator<T> = AsyncIterator<T, void, undefined> & {
+    push(value: T): void
+    end(): void
+    error(message: string): void
+}
+
+const DEFAULT_MAX_BUFFER = 1024
+
+export function createPushIterator<T>(
+    onClose?: () => void,
+    maxBuffer = DEFAULT_MAX_BUFFER,
+): PushIterator<T> {
+    const buffer: Slot<T>[] = []
+    let waiter: ((slot: Slot<T>) => void) | undefined
+    let closed = false
+
+    function deliver(slot: Slot<T>): void {
+        if (closed) {
+            return
+        }
+        if (waiter) {
+            const wake = waiter
+            waiter = undefined
+            wake(slot)
+            return
+        }
+        // Drop the oldest pending value before exceeding the cap.
+        if (slot.kind === 'value' && buffer.length >= maxBuffer) {
+            buffer.shift()
+        }
+        buffer.push(slot)
+    }
+
+    function close(): void {
+        if (closed) {
+            return
+        }
+        closed = true
+        onClose?.()
+    }
+
+    return {
+        push(value) {
+            deliver({ kind: 'value', value })
+        },
+        end() {
+            deliver({ kind: 'end' })
+        },
+        error(message) {
+            deliver({ kind: 'error', message })
+        },
+        async next() {
+            if (closed) {
+                return { value: undefined, done: true }
+            }
+            const slot = buffer.shift() ?? (await new Promise<Slot<T>>((r) => (waiter = r)))
+            if (slot.kind === 'end') {
+                close()
+                return { value: undefined, done: true }
+            }
+            if (slot.kind === 'error') {
+                close()
+                throw new Error(slot.message)
+            }
+            return { value: slot.value, done: false }
+        },
+        async return() {
+            if (!closed) {
+                close()
+                waiter?.({ kind: 'end' })
+                waiter = undefined
+            }
+            return { value: undefined, done: true }
+        },
+    }
+}

package/src/lib/shared/createRemoteFunction.ts

@@ -0,0 +1,99 @@
+import { decodeResponse } from './decodeResponse.ts'
+import { keyForRemoteCall } from './keyForRemoteCall.ts'
+import { recordRemoteMeta } from './recordRemoteMeta.ts'
+import { subscribableFromResponse } from './subscribableFromResponse.ts'
+import type { ClientFlags } from './types/ClientFlags.ts'
+import type { HttpVerb } from './types/HttpVerb.ts'
+import type { RawRemoteFunction } from './types/RawRemoteFunction.ts'
+import type { RemoteFunction } from './types/RemoteFunction.ts'
+import type { Subscribable } from './types/Subscribable.ts'
+
+/*
+Assembles the public RemoteFunction shape used identically by the
+server-side defineVerb (in-process handler invocation) and the
+client-side remoteProxy (network fetch). Centralising the wiring here
+keeps the call/raw/stream/fetch semantics — including WeakMap meta
+recording, Content-Type decode, and Subscribable derivation — in one
+place so the two halves can't drift.
+
+- `buildRequest(args)` synthesizes the Request a meta reader (cache()) or
+  the client invoke needs. Server uses the inbound request's URL as the
+  base; client uses window.location. The result is memoised inside the
+  per-call `getRequest` thunk so the Request is built at most once per
+  call regardless of how many readers pull on it.
+- `invoke(args, getRequest)` actually runs the call: server defineVerb
+  runs the handler and ignores `getRequest`; client remoteProxy calls
+  `fetch(getRequest())`. The thunk lets the server skip the Request
+  allocation entirely on the SSR hot path — the only consumer that ever
+  forces it is cache(), via the meta thunk recorded below.
+- `parseArgsForFetch` is optional and only set by the server, so the
+  framework's router can call `.fetch(inboundRequest)` and have the
+  handler receive parsed args. Client `remoteProxy.fetch` just
+  forwards the request through invoke().
+*/
+export function createRemoteFunction<Args, Return>(opts: {
+    method: HttpVerb
+    url: string
+    clients: ClientFlags
+    buildRequest: (args: Args | undefined) => Request
+    invoke: (args: Args | undefined, getRequest: () => Request) => Promise<Response>
+    parseArgsForFetch?: (request: Request) => Promise<Args | undefined>
+}): RemoteFunction<Args, Return> {
+    const { method, url, clients, buildRequest, invoke, parseArgsForFetch } = opts
+
+    /*
+    Dispatch is the one-stop entry for both the plain call (no prebuilt
+    Request) and the fetch path (router hands us the inbound Request as
+    `prebuilt`). The `getRequest` thunk lazily synthesizes — or
+    short-circuits to the prebuilt one — and caches the result so the
+    client invoke + the cache meta reader share a single Request.
+    */
+    function dispatch(args: Args | undefined, prebuilt?: Request): Promise<Response> {
+        let cached = prebuilt
+        function getRequest(): Request {
+            if (cached === undefined) {
+                cached = buildRequest(args)
+            }
+            return cached
+        }
+        const promise = invoke(args, getRequest)
+        recordRemoteMeta(promise, getRequest)
+        return promise
+    }
+
+    /*
+    A body verb may receive a FormData in place of typed Args (the upload
+    escape hatch). It flows through dispatch only into buildRpcRequest /
+    keyForRemoteCall, both of which take it as-is, so the cast to Args is a
+    contained type lie — buildRpcRequest's `instanceof FormData` branch handles
+    it at runtime.
+    */
+    function rawCall(args: Args | FormData): Promise<Response> {
+        return dispatch(args as Args)
+    }
+    rawCall.method = method
+    rawCall.url = url
+    const raw = rawCall as RawRemoteFunction<Args>
+
+    function callable(args: Args | FormData): Promise<Return> {
+        return raw(args).then(decodeResponse) as Promise<Return>
+    }
+    callable.method = method
+    callable.url = url
+    callable.clients = clients
+    callable.raw = raw
+    callable.stream = (args?: Args | FormData): Subscribable<Return> => {
+        return subscribableFromResponse(keyForRemoteCall(method, url, args), () =>
+            raw(args as Args),
+        )
+    }
+    callable.fetch = parseArgsForFetch
+        ? async (request: Request): Promise<Response> => {
+              const args = await parseArgsForFetch(request)
+              return dispatch(args, request)
+          }
+        : (request: Request): Promise<Response> => {
+              return dispatch(undefined, request)
+          }
+    return callable as RemoteFunction<Args, Return>
+}

package/src/lib/shared/decodeResponse.ts

@@ -0,0 +1,47 @@
+import { HttpError } from './HttpError.ts'
+import { STREAMING_CONTENT_TYPES } from './STREAMING_CONTENT_TYPES.ts'
+
+/*
+Decodes a Response into the natural body value based on Content-Type:
+  application/json (or `*\/+json`) → parsed JSON
+  text/*                           → string
+  204 No Content / empty body      → undefined
+  everything else                  → Blob
+
+Non-2xx responses throw HttpError so the happy path never has to check
+`.ok` — error handling moves into try/catch (or unhandled exception
+propagation), and the success path types as Promise<Return> cleanly.
+
+Streaming Content-Types (SSE / JSONL / NDJSON) throw a clear error
+rather than silently doing the wrong thing: response.text() would hang
+forever on a never-ending body and response.json() would fail mid-parse.
+The error points callers at the right tools — `subscribe(fn.stream)(args)`
+for a shared reactive view, or `fn.stream(args)` directly for a fresh
+per-call AsyncIterable — both of which know how to consume the body
+frame-by-frame.
+
+Callers that need headers, streaming, or per-status branching should use
+the `.raw(args)` escape hatch on the remote function instead — that
+returns the underlying Response untouched.
+*/
+export async function decodeResponse(response: Response): Promise<unknown> {
+    if (!response.ok) {
+        throw new HttpError(response)
+    }
+    if (response.status === 204) {
+        return undefined
+    }
+    const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
+    if (STREAMING_CONTENT_TYPES.some((type) => contentType.startsWith(type))) {
+        throw new Error(
+            `[belte] response at ${response.url} is a stream (${contentType}) — use subscribe(fn.stream)(args) for a reactive view, or fn.stream(args) for per-call iteration, instead of awaiting the bare call or cache()`,
+        )
+    }
+    if (contentType.includes('json')) {
+        return response.json()
+    }
+    if (contentType.startsWith('text/')) {
+        return response.text()
+    }
+    return response.blob()
+}

package/src/lib/shared/detectTarget.ts

@@ -0,0 +1,27 @@
+import type { CompileTarget } from './types/CompileTarget.ts'
+
+/*
+Picks the Bun compile target matching the current host. Throws if the
+platform/arch pair isn't one of the supported Bun standalone targets — the
+CLI's `--target` flag is the escape hatch for cross-compilation.
+*/
+const HOST_TO_TARGET: Record<string, CompileTarget> = {
+    'darwin-arm64': 'bun-darwin-arm64',
+    'darwin-x64': 'bun-darwin-x64',
+    'linux-arm64': 'bun-linux-arm64',
+    'linux-x64': 'bun-linux-x64',
+    'win32-x64': 'bun-windows-x64',
+}
+
+export function detectTarget(
+    platform: NodeJS.Platform = process.platform,
+    arch: NodeJS.Architecture = process.arch,
+): CompileTarget {
+    const target = HOST_TO_TARGET[`${platform}-${arch}`]
+    if (!target) {
+        throw new Error(
+            `[belte] unsupported host platform ${platform}/${arch}. Pass --target=<bun-...> explicitly.`,
+        )
+    }
+    return target
+}

package/src/lib/shared/exeSuffix.ts

@@ -0,0 +1,9 @@
+import type { CompileTarget } from './types/CompileTarget.ts'
+
+/*
+Executable filename suffix for a compile target — `.exe` on Windows targets,
+empty elsewhere. Single source so every cross-compile output path agrees.
+*/
+export function exeSuffix(target: CompileTarget): string {
+    return target.includes('windows') ? '.exe' : ''
+}

package/src/lib/shared/exitOnBuildFailure.ts

@@ -0,0 +1,17 @@
+import type { BuildOutput } from 'bun'
+import { log } from './log.ts'
+
+/*
+On a failed Bun.build(), logs each diagnostic and exits non-zero. Every belte
+build entrypoint (build / compile / buildCli / bundleApp) funnels its result
+through here so failure reporting can't drift between them.
+*/
+export function exitOnBuildFailure(result: BuildOutput): void {
+    if (result.success) {
+        return
+    }
+    result.logs.forEach((entry) => {
+        log.error(entry)
+    })
+    process.exit(1)
+}

package/src/lib/shared/extraForwardHeaders.ts

@@ -0,0 +1,16 @@
+/*
+App-configured inbound header names to forward onto in-process rpc Requests,
+on top of the built-in FORWARDED_HEADERS. Set once at boot from
+app.forwardHeaders so the SSR in-process path (defineVerb) and the MCP
+dispatcher honour the same list without re-reading app config per call. A
+module-level slot rather than threaded config because both call sites are deep
+in the request path and the value is fixed for the process lifetime.
+*/
+let names: readonly string[] = []
+
+export const extraForwardHeaders = {
+    get: (): readonly string[] => names,
+    set: (configured: readonly string[]): void => {
+        names = configured
+    },
+}

package/src/lib/shared/fileStem.ts

@@ -0,0 +1,9 @@
+/*
+The bare filename of a path, with directory and trailing extension stripped —
+e.g. `users/list.ts` → `list`, `/_virtual/mcp-resources.ts` → `mcp-resources`.
+Used to derive a virtual-module name from its path and to check an $rpc /
+$sockets module's single export name against its file stem.
+*/
+export function fileStem(path: string): string {
+    return (path.split('/').pop() ?? '').replace(/\.[^.]+$/, '')
+}