@briancray/belte 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@briancray/belte",
-    "version": "0.6.0",
+    "version": "0.8.0",
     "type": "module",
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
     "license": "MIT",

package/src/lib/browser/cache.ts

@@ -63,10 +63,12 @@ export function cache<Args, Return>(
         /*
         Tag an existing entry with this call's scope so a later
         cache.invalidate({ scope }) reaches entries hydrated from the SSR
-        snapshot (which carry a value but no scope) without a refetch.
+        snapshot (which carry a value but no scope) without a refetch. Merge
+        rather than replace so a read tagging one group can't drop tags a
+        different read site already added.
         */
         if (existing && options?.scope !== undefined) {
-            existing.scope = options.scope
+            existing.scope = mergeScopes(existing.scope, options.scope)
         }
         /*
         Snapshot warm path: hydration pre-decoded the SSR body onto the
@@ -117,7 +119,7 @@ function invokeWithCache<Args>(
         request,
         ttl,
         expiresAt: undefined as number | undefined,
-        scope: options?.scope,
+        scope: options?.scope === undefined ? undefined : toScopeSet(options.scope),
     }
     store.entries.set(key, entry)
     function deleteIfCurrent() {
@@ -163,10 +165,11 @@ function shareable(promise: Promise<Response>): Promise<Response> {
 Three call shapes:
   invalidate()                  → drop everything
   invalidate(fn)                → drop one function's calls (method+url prefix)
-  invalidate({ key?, scope? })  → drop one entry by key and/or a tagged group
+  invalidate({ key?, scope? })  → drop one entry by key and/or tagged groups
 A selector with both fields drops the union; an empty or unmatched selector
 is a no-op. `key` accepts the same string/array/object the cache() `key`
-option does and is canonicalised the same way.
+option does and is canonicalised the same way. `scope` accepts one tag or an
+array; an entry is dropped when its tag set shares any tag with the request.
 */
 function invalidate<Args, Return>(
     arg?: AnyRemote<Args, Return> | Pick<CacheOptions, 'key' | 'scope'>,
@@ -195,11 +198,15 @@ function invalidate<Args, Return>(
     }
     const target = arg.key !== undefined ? canonicalKey(arg.key) : undefined
     const byKey = target !== undefined && store.entries.has(target) ? [target] : []
+    const requestedScopes = arg.scope === undefined ? undefined : toScopeSet(arg.scope)
     const byScope =
-        arg.scope === undefined
+        requestedScopes === undefined
             ? []
             : Array.from(store.entries.values())
-                  .filter((entry) => entry.scope === arg.scope)
+                  .filter(
+                      (entry) =>
+                          entry.scope !== undefined && intersects(entry.scope, requestedScopes),
+                  )
                   .map((entry) => entry.key)
     /* emit() dedupes via a Set, so a key matching both criteria is harmless. */
     const affected = [...byKey, ...byScope]
@@ -227,6 +234,21 @@ function canonicalKey(value: CacheOptions['key']): string {
     return canonicalJson(value)
 }
 
+/* Normalizes a scope option (one tag or many) to a Set for O(1) membership. */
+function toScopeSet(scope: string | string[]): Set<string> {
+    return new Set(typeof scope === 'string' ? [scope] : scope)
+}
+
+/* Folds new tags into an entry's existing set without duplicating them. */
+function mergeScopes(existing: Set<string> | undefined, incoming: string | string[]): Set<string> {
+    return new Set([...(existing ?? []), ...toScopeSet(incoming)])
+}
+
+/* True when an entry's tags and the requested tags overlap on any tag. */
+function intersects(entryScopes: Set<string>, requestedScopes: Set<string>): boolean {
+    return Array.from(requestedScopes).some((scope) => entryScopes.has(scope))
+}
+
 /*
 Detail is a Set so each subscriber's `has(key)` check is O(1) regardless of
 how many keys a single invalidate touches.

package/src/lib/server/runtime/createRouteDispatcher.ts

@@ -0,0 +1,100 @@
+import type { Pages } from '../../browser/types/Pages.ts'
+import { NO_STORE } from '../../shared/cacheControlValues.ts'
+import { memoizeByKey } from '../../shared/memoizeByKey.ts'
+import type { HttpVerb } from '../rpc/types/HttpVerb.ts'
+import type { RemoteFunction } from '../rpc/types/RemoteFunction.ts'
+import type { RemoteRoutes } from '../rpc/types/RemoteRoutes.ts'
+import type { RequestStore } from './types/RequestStore.ts'
+
+type AnyRemoteFunction = RemoteFunction<unknown, unknown>
+
+/* Resolves a matched route to a Response, given the request and its scope. */
+type RouteHandler = (
+    req: Request,
+    pathParams: Record<string, string>,
+    store: RequestStore,
+) => Promise<Response>
+
+/* Renders the page at `routeUrl` — injected so dispatch is testable without SSR. */
+type RenderPage = (
+    routeUrl: string,
+    params: Record<string, string>,
+    store: RequestStore,
+) => Promise<Response>
+
+/* The framework's 405 — `Allow` names the permitted verb(s), body and NO_STORE shared so the rpc and page branches can't drift. */
+function methodNotAllowed(allow: string): Response {
+    return new Response('Method Not Allowed', {
+        status: 405,
+        headers: { Allow: allow, 'Cache-Control': NO_STORE },
+    })
+}
+
+/*
+Owns route dispatch: deciding, per registered URL, whether a request hits an
+rpc verb, a page render, or nothing — and the method-matching that picks the
+status. Page URLs (under src/browser/pages/) serve GET/HEAD by rendering; rpc
+URLs (under src/server/rpc/, `/rpc/...`) dispatch to the single declared verb,
+405 on method mismatch; an unregistered URL is 404. Page and rpc URLs are
+disjoint by construction, so each route lands in exactly one branch.
+
+`renderPage` is injected rather than built here: dispatch decisions (the
+405/404 branches and the rpc method match) are the behaviour worth testing,
+and keeping the Svelte render behind the seam lets a test exercise them with a
+stub instead of booting a server. The rpc-module loader is memoised internally
+so each module loads once.
+*/
+export function createRouteDispatcher({
+    pages,
+    rpc,
+    renderPage,
+}: {
+    pages: Pages
+    rpc: RemoteRoutes
+    renderPage: RenderPage
+}): (routeUrl: string) => RouteHandler {
+    const loadRpc = memoizeByKey((url): Promise<AnyRemoteFunction | undefined> | undefined => {
+        const loader = rpc[url]
+        if (!loader) {
+            return undefined
+        }
+        /*
+        Each $rpc module has exactly one named export, validated at build
+        time. Pick the first export that looks like a RemoteFunction so the
+        framework stays tolerant of incidental re-exports.
+        */
+        return loader().then((mod) => {
+            for (const value of Object.values(mod)) {
+                if (typeof value === 'function' && 'method' in value && 'url' in value) {
+                    return value as AnyRemoteFunction
+                }
+            }
+            return undefined
+        })
+    })
+
+    return function buildRouteHandler(routeUrl: string): RouteHandler {
+        const hasPage = pages[routeUrl] !== undefined
+        const hasRpc = rpc[routeUrl] !== undefined
+        return async function routeHandler(req, pathParams, store) {
+            const method = req.method as HttpVerb
+            if (hasRpc) {
+                const fn = await loadRpc(routeUrl)
+                if (fn && fn.method === method) {
+                    return fn.fetch(req)
+                }
+                return methodNotAllowed(fn ? fn.method : '')
+            }
+            if (hasPage) {
+                if (method !== 'GET' && method !== 'HEAD') {
+                    return methodNotAllowed('GET, HEAD')
+                }
+                return renderPage(routeUrl, pathParams, store)
+            }
+            return new Response('Not Found', {
+                status: 404,
+                headers: { 'Cache-Control': NO_STORE },
+            })
+        }
+    }
+}

package/src/lib/server/runtime/createServer.ts

@@ -8,18 +8,14 @@ import { createMcpResourceServer } from '../../mcp/createMcpResourceServer.ts'
 import { setMcpResourceServer } from '../../mcp/mcpResourceServerSlot.ts'
 import type { McpServer } from '../../mcp/types/McpServer.ts'
 import { NO_STORE, SSR_CACHE_CONTROL } from '../../shared/cacheControlValues.ts'
-import { createCacheStore } from '../../shared/createCacheStore.ts'
 import { isDebugEnabled } from '../../shared/isDebugEnabled.ts'
 import { log } from '../../shared/log.ts'
-import { memoizeByKey } from '../../shared/memoizeByKey.ts'
 import { nearestLayoutPrefix, normalizeLayoutPrefixes } from '../../shared/nearestLayoutPrefix.ts'
 import { toBunRoutePattern } from '../../shared/toBunRoutePattern.ts'
 import type { AppModule } from '../AppModule.ts'
 import { handleCliDownload } from '../cli/handleCliDownload.ts'
 import { handleCliInstall } from '../cli/handleCliInstall.ts'
 import type { PromptRoutes } from '../prompts/types/PromptRoutes.ts'
-import type { HttpVerb } from '../rpc/types/HttpVerb.ts'
-import type { RemoteFunction } from '../rpc/types/RemoteFunction.ts'
 import type { RemoteRoutes } from '../rpc/types/RemoteRoutes.ts'
 import { createSocketDispatcher } from '../sockets/createSocketDispatcher.ts'
 import type { SocketRoutes } from '../sockets/types/SocketRoutes.ts'
@@ -29,12 +25,16 @@ import { cacheControlForAsset } from './cacheControlForAsset.ts'
 import { containsTraversal } from './containsTraversal.ts'
 import { createAssetHeaderCache } from './createAssetHeaderCache.ts'
 import { createPublicAssetServer } from './createPublicAssetServer.ts'
+import { createRouteDispatcher } from './createRouteDispatcher.ts'
+import { disableIdleTimeoutForStream } from './disableIdleTimeoutForStream.ts'
 import { findOpenPort } from './findOpenPort.ts'
 import { globToPathSet } from './globToPathSet.ts'
+import { internalErrorResponse } from './internalErrorResponse.ts'
 import { logBrowserOnlyRoutes } from './logBrowserOnlyRoutes.ts'
+import { parseIdleTimeout } from './parseIdleTimeout.ts'
 import { parsePort } from './parsePort.ts'
 import { ensureRegistriesLoaded, setRegistryManifests } from './registryManifests.ts'
-import { requestContext } from './requestContext.ts'
+import { runWithRequestScope } from './runWithRequestScope.ts'
 import { safeJsonForScript } from './safeJsonForScript.ts'
 import { serializeCacheSnapshot } from './serializeCacheSnapshot.ts'
 import { setActiveServer } from './setActiveServer.ts'
@@ -48,21 +48,6 @@ function wantsJson(req: Request): boolean {
 // SSR placeholders the shell carries; filled in a single pass per render.
 const SSR_MARKER = /<!--ssr:(head|body|state)-->/g
 
-/*
-The framework's default 500 response — a `<pre>` stack dump. Shared by the
-per-request catch and Bun.serve's global error() fallback so the two can't
-drift. Only reached when the app supplies no `handleError` hook.
-*/
-function internalErrorResponse(err: unknown): Response {
-    return new Response(`<pre>${String((err as Error)?.stack ?? err)}</pre>`, {
-        status: 500,
-        headers: {
-            'Content-Type': 'text/html; charset=utf-8',
-            'Cache-Control': NO_STORE,
-        },
-    })
-}
-
 const IDENTITY_PATH = '/__belte/identity'
 const SOCKETS_PATH = '/__belte/sockets'
 const SOCKETS_REST_PREFIX = '/__belte/sockets/'
@@ -79,8 +64,6 @@ conventional root path where external tooling and scanners expect to find it
 */
 const OPENAPI_PATH = '/openapi.json'
 
-type AnyRemoteFunction = RemoteFunction<unknown, unknown>
-
 /*
 Starts a Bun HTTP server that ties together the framework conventions:
 page.svelte + layout.svelte under src/browser/pages/ for views, one named export
@@ -112,6 +95,13 @@ export async function createServer({
     // No PORT set → scan for the first open port at/above 3000 rather than
     // hardcoding 3000, so a second app boots cleanly instead of colliding.
     port = parsePort(process.env.PORT) ?? findOpenPort(3000),
+    /*
+    Bun's per-connection idle timeout in seconds (its own default is 10).
+    Surfaced for apps whose unary handlers legitimately compute longer than
+    that; streaming responses opt out per-request via disableIdleTimeoutForStream
+    regardless of this floor.
+    */
+    idleTimeout = parseIdleTimeout(process.env.BELTE_IDLE_TIMEOUT) ?? 10,
 }: {
     pages: Pages
     rpc: RemoteRoutes
@@ -130,6 +120,7 @@ export async function createServer({
     publicDir?: string
     resourcesDir?: string
     port?: number
+    idleTimeout?: number
 }): Promise<Server<unknown>> {
     setRegistryManifests({ rpc, sockets, prompts })
     setMcpResourceServer(createMcpResourceServer({ resourcesDir, mcpResources }))
@@ -153,26 +144,6 @@ export async function createServer({
               (file) => `/_app/${file.replace(/\.zst$/, '')}`,
           )
 
-    const loadRpc = memoizeByKey((url): Promise<AnyRemoteFunction | undefined> | undefined => {
-        const loader = rpc[url]
-        if (!loader) {
-            return undefined
-        }
-        /*
-        Each $rpc module has exactly one named export, validated at build
-        time. Pick the first export that looks like a RemoteFunction so the
-        framework stays tolerant of incidental re-exports.
-        */
-        return loader().then((mod) => {
-            for (const value of Object.values(mod)) {
-                if (typeof value === 'function' && 'method' in value && 'url' in value) {
-                    return value as AnyRemoteFunction
-                }
-            }
-            return undefined
-        })
-    })
-
     const logRequests = isDebugEnabled('belte')
 
     // Per-pathname asset header bundles, hashed-chunk-aware Cache-Control.
@@ -274,51 +245,11 @@ export async function createServer({
     }
 
     /*
-    Per-route handler bound by buildRoutes(). Receives a BunRequest with
-    `params` filled from the route pattern (only pages use path params;
-    $rpc URLs are flat). Page URLs (under src/browser/pages/) serve GET/HEAD by
-    rendering; rpc URLs (under src/server/rpc/, prefixed with `/rpc/`) dispatch
-    to the single declared verb-bound handler. URLs are disjoint by
-    construction so each path goes to exactly one branch.
+    Route dispatch — rpc-vs-page-vs-404 resolution and method matching — lives
+    behind createRouteDispatcher; renderPage is injected so those decisions stay
+    testable without SSR. buildRoutes() below binds the returned handler per URL.
     */
-    function buildRouteHandler(routeUrl: string) {
-        const hasPage = pages[routeUrl] !== undefined
-        const hasRpc = rpc[routeUrl] !== undefined
-        return async function routeHandler(
-            req: Request,
-            pathParams: Record<string, string>,
-            store: RequestStore,
-        ): Promise<Response> {
-            const method = req.method as HttpVerb
-            if (hasRpc) {
-                const fn = await loadRpc(routeUrl)
-                if (fn && fn.method === method) {
-                    return fn.fetch(req)
-                }
-                const allow = fn ? fn.method : ''
-                return new Response('Method Not Allowed', {
-                    status: 405,
-                    headers: {
-                        Allow: allow,
-                        'Cache-Control': NO_STORE,
-                    },
-                })
-            }
-            if (hasPage) {
-                if (method !== 'GET' && method !== 'HEAD') {
-                    return new Response('Method Not Allowed', {
-                        status: 405,
-                        headers: { Allow: 'GET, HEAD', 'Cache-Control': NO_STORE },
-                    })
-                }
-                return renderPage(routeUrl, pathParams, store)
-            }
-            return new Response('Not Found', {
-                status: 404,
-                headers: { 'Cache-Control': NO_STORE },
-            })
-        }
-    }
+    const buildRouteHandler = createRouteDispatcher({ pages, rpc, renderPage })
 
     /*
     Page URLs (folder paths, e.g. `/media/[id]`) get translated to Bun's
@@ -361,42 +292,12 @@ export async function createServer({
             store: RequestStore,
         ) => Promise<Response>,
     ): Promise<Response> {
-        return runWithStore(req, async (store) => {
-            if (!app?.handle) {
-                return handler(req, pathParams, store)
-            }
-            return app.handle(req, (next) => handler(next, pathParams, store))
-        })
-    }
-
-    function runWithStore(
-        req: Request,
-        body: (store: RequestStore) => Promise<Response>,
-    ): Promise<Response> {
-        const url = new URL(req.url)
-        const store: RequestStore = {
-            url,
-            req,
-            cache: createCacheStore(),
-        }
-        return requestContext.run(store, async () => {
-            const start = logRequests ? Bun.nanoseconds() : 0
-            let response: Response
-            try {
-                response = await body(store)
-            } catch (error) {
-                if (app?.handleError) {
-                    response = await app.handleError(error, req)
-                } else {
-                    log.error(error)
-                    response = internalErrorResponse(error)
-                }
-            }
-            if (logRequests) {
-                const ms = (Bun.nanoseconds() - start) / 1e6
-                log.request(req.method, `${url.pathname}${url.search}`, response.status, ms)
-            }
-            return response
+        return runWithRequestScope(req, { app, logRequests }, async (store) => {
+            const response = app?.handle
+                ? await app.handle(req, (next) => handler(next, pathParams, store))
+                : await handler(req, pathParams, store)
+            // Streaming bodies (sse/jsonl, socket tail) opt out of the idle timeout.
+            return disableIdleTimeoutForStream(server, req, response)
         })
     }
 
@@ -412,6 +313,7 @@ export async function createServer({
     // Server<unknown> pins Bun's WebSocketData generic so upgrade({ data: {} }) typechecks.
     const server: Server<unknown> = Bun.serve({
         port,
+        idleTimeout,
 
         websocket: {
             open(ws) {

package/src/lib/server/runtime/disableIdleTimeoutForStream.ts

@@ -0,0 +1,23 @@
+import type { Server } from 'bun'
+import { isStreamingResponse } from '../../shared/isStreamingResponse.ts'
+
+/*
+Opts a streaming response out of Bun's per-connection idle timeout. A stream
+can stay quiet for longer than the 10s default between frames, which Bun would
+otherwise read as an idle connection and close mid-stream. `server.timeout(req,
+0)` clears the timeout for just this in-flight request, leaving the global
+default in place for ordinary request/response traffic. Streaming is detected
+by Content-Type (the shared signal the CLI/MCP drain paths use) rather than
+`body instanceof ReadableStream`, since every bodied Response exposes one.
+Non-stream responses pass through untouched.
+*/
+export function disableIdleTimeoutForStream(
+    server: Server<unknown>,
+    req: Request,
+    response: Response,
+): Response {
+    if (isStreamingResponse(response)) {
+        server.timeout(req, 0)
+    }
+    return response
+}

package/src/lib/server/runtime/internalErrorResponse.ts

@@ -0,0 +1,17 @@
+import { NO_STORE } from '../../shared/cacheControlValues.ts'
+
+/*
+The framework's default 500 response — a `<pre>` stack dump. Shared by the
+per-request scope's catch (runWithRequestScope) and Bun.serve's global
+error() fallback so the two can't drift. Only reached when the app supplies
+no `handleError` hook.
+*/
+export function internalErrorResponse(error: unknown): Response {
+    return new Response(`<pre>${String((error as Error)?.stack ?? error)}</pre>`, {
+        status: 500,
+        headers: {
+            'Content-Type': 'text/html; charset=utf-8',
+            'Cache-Control': NO_STORE,
+        },
+    })
+}

package/src/lib/server/runtime/parseIdleTimeout.ts

@@ -0,0 +1,10 @@
+import { parseBoundedEnvInt } from '../../shared/parseBoundedEnvInt.ts'
+
+/*
+Parses BELTE_IDLE_TIMEOUT into Bun's per-connection idle timeout in seconds.
+Bun accepts 0–255 (0 disables the timeout); returns undefined for missing,
+empty, or out-of-range/non-integer input so the caller keeps its default.
+*/
+export function parseIdleTimeout(value: string | undefined): number | undefined {
+    return parseBoundedEnvInt(value, 0, 255)
+}

package/src/lib/server/runtime/parsePort.ts

@@ -1,16 +1,11 @@
+import { parseBoundedEnvInt } from '../../shared/parseBoundedEnvInt.ts'
+
 /*
-Parses a PORT env value into a usable TCP port, returning undefined for
-missing, empty, or out-of-range/non-integer input so the caller can fall back
-to a default. A bare Number() turns '' into 0 (a random kernel-assigned port)
-and 'abc' into NaN, both silently wrong; this rejects them instead.
+Parses a PORT env value into a usable TCP port (0–65535), returning undefined
+for missing, empty, or out-of-range/non-integer input so the caller can fall
+back to a default. A bare Number() would turn '' into 0 (a random
+kernel-assigned port) and 'abc' into NaN, both silently wrong.
 */
 export function parsePort(value: string | undefined): number | undefined {
-    if (value === undefined || value.trim() === '') {
-        return undefined
-    }
-    const port = Number(value)
-    if (!Number.isInteger(port) || port < 0 || port > 65535) {
-        return undefined
-    }
-    return port
+    return parseBoundedEnvInt(value, 0, 65535)
 }

package/src/lib/server/runtime/runWithRequestScope.ts

@@ -0,0 +1,47 @@
+import { createCacheStore } from '../../shared/createCacheStore.ts'
+import { log } from '../../shared/log.ts'
+import type { AppModule } from '../AppModule.ts'
+import { internalErrorResponse } from './internalErrorResponse.ts'
+import { requestContext } from './requestContext.ts'
+import type { RequestStore } from './types/RequestStore.ts'
+
+/*
+Establishes the per-request scope and runs `body` inside it: a fresh
+CacheStore plus request metadata published through the AsyncLocalStorage
+RequestStore (so cache() and request()/server() resolve without threading
+args), the app's handleError — or the framework's 500 fallback — on a thrown
+body, and optional request logging. The single seam every dynamic route
+crosses; extracted from createServer so the scope, error, and logging
+behaviour is exercisable through this interface without booting a Bun server.
+*/
+export function runWithRequestScope(
+    req: Request,
+    options: { app?: AppModule; logRequests: boolean },
+    body: (store: RequestStore) => Promise<Response>,
+): Promise<Response> {
+    const url = new URL(req.url)
+    const store: RequestStore = {
+        url,
+        req,
+        cache: createCacheStore(),
+    }
+    return requestContext.run(store, async () => {
+        const start = options.logRequests ? Bun.nanoseconds() : 0
+        let response: Response
+        try {
+            response = await body(store)
+        } catch (error) {
+            if (options.app?.handleError) {
+                response = await options.app.handleError(error, req)
+            } else {
+                log.error(error)
+                response = internalErrorResponse(error)
+            }
+        }
+        if (options.logRequests) {
+            const ms = (Bun.nanoseconds() - start) / 1e6
+            log.request(req.method, `${url.pathname}${url.search}`, response.status, ms)
+        }
+        return response
+    })
+}

package/src/lib/shared/parseBoundedEnvInt.ts

@@ -0,0 +1,20 @@
+/*
+Parses an env string into an integer within [min, max], returning undefined for
+missing, empty, or out-of-range/non-integer input so the caller can fall back to
+a default. A bare Number() turns '' into 0 and 'abc' into NaN, both silently
+wrong; this rejects them instead.
+*/
+export function parseBoundedEnvInt(
+    value: string | undefined,
+    min: number,
+    max: number,
+): number | undefined {
+    if (value === undefined || value.trim() === '') {
+        return undefined
+    }
+    const parsed = Number(value)
+    if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+        return undefined
+    }
+    return parsed
+}

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

@@ -12,8 +12,9 @@ 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.
 
-`scope` mirrors the cache() call's `scope` option so
-`cache.invalidate({ scope })` can drop every entry sharing the tag.
+`scope` holds the cache() call's scope tags as a Set so
+`cache.invalidate({ scope })` can drop every entry sharing any tag with O(1)
+membership; a re-read merges new tags in rather than replacing them.
 */
 export type CacheEntry = {
     key: string
@@ -22,5 +23,5 @@ export type CacheEntry = {
     ttl: number | undefined
     expiresAt: number | undefined
     value?: unknown
-    scope?: string
+    scope?: Set<string>
 }

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

@@ -3,11 +3,12 @@ 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.
-`scope` is a free-form tag grouping unrelated calls so one
-`cache.invalidate({ scope })` drops them together.
+`scope` is one or more free-form tags grouping unrelated calls so one
+`cache.invalidate({ scope })` drops every entry sharing any of them — pass an
+array when a call belongs to multiple invalidation groups.
 */
 export type CacheOptions = {
     key?: string | unknown[] | Record<string, unknown>
     ttl?: number
-    scope?: string
+    scope?: string | string[]
 }