@abide/abide 0.45.0 → 0.47.0

package/src/lib/shared/cacheStoreResolver.ts

@@ -1,12 +0,0 @@
-import { createCacheStore } from './createCacheStore.ts'
-import { createResolverSlot } from './createResolverSlot.ts'
-import type { CacheStore } from './types/CacheStore.ts'
-
-/*
-The active-CacheStore slot/resolver/reader bundle. The server entry installs an
-ALS-backed resolver (request-scoped); the client entry a module-singleton one.
-With no resolver registered, a single fallback store is created lazily so
-isolated tests work without booting the runtime. cacheStoreSlot / activeCacheStore
-re-export the slot and reader; setCacheStoreResolver the setter.
-*/
-export const cacheStoreResolver = createResolverSlot<CacheStore>(createCacheStore)

package/src/lib/shared/globalCacheStoreResolver.ts

@@ -1,12 +0,0 @@
-import { createResolverSlot } from './createResolverSlot.ts'
-import type { CacheStore } from './types/CacheStore.ts'
-
-/*
-Slot + setter for the process-level cache store resolver used by cache() entries
-opting into `global: true`. The server entry registers a module-singleton store
-outliving any one request; the client entry points it at its single tab store so
-`global` is a no-op there. No fallback creator — when unset, globalCacheStore()
-falls through to the active store rather than minting an isolated one.
-globalCacheStoreSlot / setGlobalCacheStoreResolver re-export the slot and setter.
-*/
-export const globalCacheStoreResolver = createResolverSlot<CacheStore>()

package/src/lib/shared/pageResolver.ts

@@ -1,16 +0,0 @@
-import { createResolverSlot } from './createResolverSlot.ts'
-import type { PageSnapshot } from './types/PageSnapshot.ts'
-
-/*
-The active-page slot/resolver/reader bundle. The server entry installs an
-ALS-backed resolver (request-scoped, so concurrent and streaming renders never
-share state); the client entry a module-singleton one. With no resolver
-registered, a single empty snapshot is created lazily so isolated tests work.
-pageSlot / activePage re-export the slot and reader; setPageResolver the setter.
-*/
-export const pageResolver = createResolverSlot<PageSnapshot>(() => ({
-    route: '',
-    params: {},
-    url: new URL('http://localhost/'),
-    navigating: false,
-}))

package/src/lib/shared/recordCacheKey.ts

@@ -1,6 +0,0 @@
-import { cacheKeyStore } from './cacheKeyStore.ts'
-
-/* Tags a cache() read's returned promise with its store key (see cacheKeyStore). */
-export function recordCacheKey(promise: Promise<unknown>, key: string): void {
-    cacheKeyStore.set(promise, key)
-}

package/src/lib/shared/requestScopeResolver.ts

@@ -1,12 +0,0 @@
-import { createResolverSlot } from './createResolverSlot.ts'
-import type { RequestScopeInfo } from './types/RequestScopeInfo.ts'
-
-/*
-Slot + setter for the request-scope resolver. The server installs an ALS-backed
-resolver (createServer, reading the RequestStore); the client a module-singleton
-seeded from __SSR__ (startClient). No fallback creator — an unset resolver (or one
-returning undefined outside any request) means "no scope": callers read
-`.resolver?.()` and treat undefined as absent. requestScopeSlot /
-setRequestScopeResolver re-export the slot and setter.
-*/
-export const requestScopeResolver = createResolverSlot<RequestScopeInfo>()

package/src/lib/shared/setBaseResolver.ts

@@ -1,4 +0,0 @@
-import { baseResolver } from './baseResolver.ts'
-
-// Registers the runtime's mount-base resolver. Called once per side at boot.
-export const setBaseResolver = baseResolver.set

package/src/lib/shared/setCacheStoreResolver.ts

@@ -1,4 +0,0 @@
-import { cacheStoreResolver } from './cacheStoreResolver.ts'
-
-// Registers the runtime's active-CacheStore resolver. Called once per side at boot.
-export const setCacheStoreResolver = cacheStoreResolver.set

package/src/lib/shared/setGlobalCacheStoreResolver.ts

@@ -1,4 +0,0 @@
-import { globalCacheStoreResolver } from './globalCacheStoreResolver.ts'
-
-// Registers the process-level cache store resolver. Called once per side at boot.
-export const setGlobalCacheStoreResolver = globalCacheStoreResolver.set

package/src/lib/shared/setPageResolver.ts

@@ -1,4 +0,0 @@
-import { pageResolver } from './pageResolver.ts'
-
-// Registers the runtime's page resolver. Called once per side at boot.
-export const setPageResolver = pageResolver.set

package/src/lib/shared/setRequestScopeResolver.ts

@@ -1,4 +0,0 @@
-import { requestScopeResolver } from './requestScopeResolver.ts'
-
-// Registers the runtime's request-scope resolver. Called once per side at boot.
-export const setRequestScopeResolver = requestScopeResolver.set

package/src/lib/shared/toBunRoutePattern.ts

@@ -1,28 +0,0 @@
-import { parseRouteSegments } from './parseRouteSegments.ts'
-
-/*
-Translates a abide 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/TailOptions.ts

@@ -1,10 +0,0 @@
-/*
-Window form of `tail()`: `last` is the rolling window size — the reader holds
-the last ≤`last` frames, however they arrived. A source that retains a tail
-(a socket declared with `{ tail: n }`) seeds the window by replaying up to
-`last` retained frames; a source with no retention (an rpc stream, an
-undeclared socket) fills it from live frames only. Integer ≥ 1.
-*/
-export interface TailOptions {
-    readonly last: number
-}

package/src/lib/ui/deferResume.ts

@@ -1,29 +0,0 @@
-import { activeCacheStore } from '../shared/activeCacheStore.ts'
-import { cacheKeyOf } from '../shared/cacheKeyOf.ts'
-import { snapshotShippable } from '../shared/snapshotShippable.ts'
-import type { DeferMarker, ResumeEntry } from './runtime/RESUME.ts'
-
-/*
-The resume-manifest entry for a blocking `{#await expr then value}`. When the awaited value
-is a shippable cache-backed read, DEFER it: flag the store entry so its SSR snapshot seeds
-lazily (the body is decoded on first read, not at hydration) and return a `{ defer, key }`
-marker in place of the value. Hydration then adopts the server branch inert and decodes
-neither copy — the blocking form's contract: "render it on the server, keep the page, refetch
-only when I read or invalidate it." A non-cache value (a plain promise, a computation) or a
-cache read whose entry can't ship inlines its value as before. Server-only in practice — the
-client codegen never calls it. */
-// @documentation plumbing
-export function deferResume(promise: unknown, value: unknown): ResumeEntry | DeferMarker {
-    const isPromise =
-        promise !== null && typeof (promise as { then?: unknown })?.then === 'function'
-    const key = isPromise ? cacheKeyOf(promise as Promise<unknown>) : undefined
-    if (key === undefined) {
-        return { ok: true, value }
-    }
-    const entry = activeCacheStore().entries.get(key)
-    if (entry === undefined || !snapshotShippable(entry)) {
-        return { ok: true, value }
-    }
-    entry.deferred = true
-    return { defer: true, key }
-}

package/src/lib/ui/matchRoute.ts

@@ -1,106 +0,0 @@
-import type { RouteSegment } from '../shared/parseRouteSegments.ts'
-import { parseRouteSegments } from '../shared/parseRouteSegments.ts'
-
-/*
-Per-route parse cache. The route set is stable across a session, so parsing a
-pattern into segments (and counting its literals, the specificity tie-breaker) is
-done once per route rather than twice per route on every navigation. Keyed by the
-pattern string; entries never need eviction since routes don't churn.
-*/
-const PARSED_ROUTES = new Map<string, { segments: RouteSegment[]; literals: number }>()
-
-function parsedRoute(route: string): { segments: RouteSegment[]; literals: number } {
-    let parsed = PARSED_ROUTES.get(route)
-    if (parsed === undefined) {
-        const segments = parseRouteSegments(route)
-        const literals = segments.filter((segment) => segment.kind === 'literal').length
-        parsed = { segments, literals }
-        PARSED_ROUTES.set(route, parsed)
-    }
-    return parsed
-}
-
-/*
-Client route matcher: given the registered route patterns and the current
-pathname, returns the matching route + decoded params, or undefined. Mirrors the
-server's segment grammar via the shared `parseRouteSegments` (literal / `[name]` /
-`[...rest]`), so client navigation decodes params the same way SSR does. The most
-specific match wins — the pattern with the most literal segments — so a static
-route beats a param route at the same depth.
-*/
-export function matchRoute(
-    routes: string[],
-    pathname: string,
-): { route: string; params: Record<string, string> } | undefined {
-    /* Normalize a trailing slash (except root) so `/users/` matches `/users` —
-       otherwise the extra empty segment makes the length guard reject it (a 404 the
-       server's own routing wouldn't give) or lets `/users/[id]` capture an empty id. */
-    const normalized =
-        pathname.length > 1 && pathname.endsWith('/') ? pathname.slice(0, -1) : pathname
-    const pathSegments = normalized.split('/')
-    let best: { route: string; params: Record<string, string>; literals: number } | undefined
-    for (const route of routes) {
-        const parsed = parsedRoute(route)
-        const params = matchSegments(parsed.segments, pathSegments)
-        if (params === undefined) {
-            continue
-        }
-        if (best === undefined || parsed.literals > best.literals) {
-            best = { route, params, literals: parsed.literals }
-        }
-    }
-    return best === undefined ? undefined : { route: best.route, params: best.params }
-}
-
-/* Percent-decodes a captured `[name]` value. Bun's `req.params` decoding is
-   lenient (malformed sequences pass through), so mirror that by falling back to
-   the raw value rather than throwing on a malformed `%` a page navigation would
-   otherwise crash on. */
-function decodeParam(value: string): string {
-    try {
-        return decodeURIComponent(value)
-    } catch {
-        return value
-    }
-}
-
-/* Matches one parsed pattern against the path's segments, capturing params;
-   undefined on mismatch. A catch-all consumes every remaining segment. */
-function matchSegments(
-    segments: RouteSegment[],
-    pathSegments: string[],
-): Record<string, string> | undefined {
-    const params: Record<string, string> = {}
-    for (let index = 0; index < segments.length; index += 1) {
-        const segment = segments[index]
-        if (segment === undefined) {
-            return undefined
-        }
-        if (segment.kind === 'param' && segment.catchAll) {
-            params[segment.name] = pathSegments.slice(index).join('/')
-            return params
-        }
-        const value = pathSegments[index]
-        if (value === undefined) {
-            return undefined
-        }
-        if (segment.kind === 'literal') {
-            if (segment.value !== value) {
-                return undefined
-            }
-        } else {
-            /* A `[name]` param never captures an empty segment (e.g. `/users//5`). */
-            if (value === '') {
-                return undefined
-            }
-            /* `url()` encodes a `[name]` value whole, and Bun decodes `req.params`
-               server-side, so decode here to hand the page the same value SSR does
-               (e.g. `The%20Daily%20Show` → `The Daily Show`). The catch-all above
-               stays raw to match the server, which reconstructs it from the raw
-               pathname. */
-            params[segment.name] = decodeParam(value)
-        }
-    }
-    /* No catch-all consumed the tail, so the path must have no extra segments. */
-    return pathSegments.length === segments.length ? params : undefined
-}

package/src/lib/ui/tail.ts

@@ -1,324 +0,0 @@
-import { createLifecycleChannel } from '../shared/createLifecycleChannel.ts'
-import { createSubscriber } from '../shared/createSubscriber.ts'
-import { SocketDisconnectedError } from '../shared/SocketDisconnectedError.ts'
-import { tailProbeSlot } from '../shared/tailProbeSlot.ts'
-import type { Subscribable } from '../shared/types/Subscribable.ts'
-import type { TailOptions } from '../shared/types/TailOptions.ts'
-
-type TailStatus = 'pending' | 'open' | 'done' | 'error'
-
-/*
-One entry shape for both read forms: the bare latest-wins read is a window of
-1 projected to its single frame, so the frame loop, reconnect handling, and
-probes have exactly one path. The bare form keys by name alone (so `tail(x)`
-and `tail(x, { last: 1 })` stay independent subscriptions); probes match on
-`source`.
-*/
-type Entry<T> = {
-    source: string
-    key: string
-    /* window cap; 1 for the bare latest-wins form */
-    last: number
-    window: T[]
-    error: Error | undefined
-    status: TailStatus
-    refreshing: boolean
-    /* true while the createSubscriber connect callback holds the iterator open */
-    live: boolean
-    tap: () => void
-}
-
-const registry = new Map<string, Entry<unknown>>()
-
-/*
-Registry-wide lifecycle channel for the pending()/refreshing() probes — the
-tail-side counterpart of the cache store's. Probes match entries by source
-name (or all) without creating them, so they tap one "membership or state
-changed" signal instead of opening a stream the way a tail() read would.
-*/
-const lifecycle = createLifecycleChannel()
-
-/*
-Prober for the shared pending()/refreshing() probes. Probes report, never
-act: an absent entry is read as "no value yet" (pending) without opening a
-stream. A name spans every entry on that source — latest-wins and window
-forms alike; the bare form spans every registered stream.
-*/
-tailProbeSlot.probe = (name) => {
-    lifecycle.track()
-    const entries = [...registry.values()].filter(
-        (entry) => name === undefined || entry.source === name,
-    )
-    return {
-        pending:
-            (name !== undefined && entries.length === 0) ||
-            entries.some((entry) => entry.status === 'pending'),
-        refreshing: entries.some((entry) => entry.refreshing),
-    }
-}
-
-/*
-Reactive consumer for streaming sources. Takes a Subscribable<T> — the shape
-both `Socket<T>` (declared under src/server/sockets/) and the result of
-`fn.stream(args)` satisfy:
-
-  const latest = $derived(tail(chat))                      // socket, latest frame
-  const recent = $derived(tail(chat, { last: 20 }))        // live window of the last ≤20
-  const tick   = $derived(tail(tickFeed.stream()))         // rpc stream
-
-The bare form is latest-wins: T | undefined, pending until the first frame.
-The window form returns T[] — `[]` while pending, never undefined — holding
-the last ≤`last` frames however they arrived. Seeding rides the source's
-optional retention capability (`Subscribable.tail(count)`): a socket declared
-`{ tail: n }` replays up to `last` retained frames (1 for the bare form — a
-latest-wins reader only needs the newest); a source without the capability
-(rpc stream, undeclared socket) starts live-only. tail() never requires
-retention — the window semantics are identical either way, only how much
-past it can show differs.
-
-Lifecycle mirrors cache(): the entry's tracker is a createSubscriber,
-so the first derived read in a tracking scope opens the underlying iterator
-and the last derived to stop reading closes it. Many deriveds reading the
-same source share one underlying subscription — the registry dedupes by
-`subscribable.name`, with `last` folded into the key, so the bare form and
-each window size are independent subscriptions. Passing fresh `fn.stream(args)`
-Subscribables across re-renders is safe: same args → same key → shared
-subscription. tail.error / tail.status take the same options to address the
-same entry.
-
-Reconnect-with-retained-value: a transport loss (the typed
-SocketDisconnectedError, raised only by the ws channel — an rpc stream is a
-one-shot Response and never disconnects) does not surface as an error. The
-entry keeps its window, flags `refreshing` (the probe contract: value held,
-fresher source in flight — never merely `open`), and re-invokes the source;
-the channel's backoff owns the retry. The reopened source's replay commits
-over the window atomically at the `replayed` boundary (TailHooks) — appended
-it would duplicate, rebuilt frame-by-frame it would flash — and an empty
-replay keeps the held window, with live frames appending after. For the
-bare form the commit is exactly latest-wins convergence. Initial opens seed
-the same way, so a window's first paint is the full seed, not a staircase.
-
-tail is a no-op on the server (returns undefined / []) — SSR can't keep a
-stream open across the request boundary. Pages that want a seeded value in
-the initial HTML should fetch via cache() against an HTTP rpc handler and
-layer tail() on top for live updates after hydration.
-
-Errors are surfaced through tail.error(x) rather than thrown, so reading
-from a $derived can't crash the component. Status distinguishes "haven't
-received the first frame" (pending) from "stream ended cleanly" (done) and
-"wire layer surfaced an error" (error).
-*/
-// @documentation tail
-export function tail<T>(subscribable: Subscribable<T>): T | undefined
-export function tail<T>(subscribable: Subscribable<T>, options: TailOptions): T[]
-export function tail<T>(subscribable: Subscribable<T>, options?: TailOptions): T | T[] | undefined {
-    if (options) {
-        return readField(subscribable, options, 'window') ?? []
-    }
-    return readField(subscribable, undefined, 'window')?.[0]
-}
-
-tail.error = function tailError<T>(
-    subscribable: Subscribable<T>,
-    options?: TailOptions,
-): Error | undefined {
-    return readField(subscribable, options, 'error')
-}
-
-tail.status = function tailStatus<T>(
-    subscribable: Subscribable<T>,
-    options?: TailOptions,
-): TailStatus {
-    return readField(subscribable, options, 'status') ?? 'pending'
-}
-
-function readField<T, K extends keyof Entry<T>>(
-    subscribable: Subscribable<T>,
-    options: TailOptions | undefined,
-    field: K,
-): Entry<T>[K] | undefined {
-    if (options && (!Number.isInteger(options.last) || options.last < 1)) {
-        throw new RangeError(`[abide] tail() \`last\` must be an integer ≥ 1, got ${options.last}`)
-    }
-    if (typeof window === 'undefined') {
-        return undefined
-    }
-    const entry = getOrCreateEntry(subscribable, options)
-    entry.tap()
-    const value = entry[field]
-    /*
-    Untracked read (outside $derived/$effect): tap() never connects, so no
-    teardown will ever evict the entry — drop it now or it sits in the
-    registry as a permanently-pending zombie the bare probes keep seeing.
-    */
-    if (!entry.live) {
-        evictIfCurrent(entry as Entry<unknown>)
-    }
-    return value
-}
-
-/* Delete only if this entry still owns its key — a fresh Subscribable with the
-   same name may have replaced it, and a stale cleanup must not nuke the new entry. */
-function evictIfCurrent(entry: Entry<unknown>): boolean {
-    if (registry.get(entry.key) === entry) {
-        registry.delete(entry.key)
-        return true
-    }
-    return false
-}
-
-function getOrCreateEntry<T>(
-    subscribable: Subscribable<T>,
-    options: TailOptions | undefined,
-): Entry<T> {
-    const key = options ? `${subscribable.name}#${options.last}` : subscribable.name
-    const cached = registry.get(key)
-    if (cached) {
-        return cached as Entry<T>
-    }
-    const last = options?.last ?? 1
-    const entry: Entry<T> = {
-        source: subscribable.name,
-        key,
-        last,
-        window: [],
-        error: undefined,
-        status: 'pending',
-        refreshing: false,
-        live: false,
-        tap: () => undefined,
-    }
-    entry.tap = createSubscriber((update) => {
-        entry.window = []
-        entry.error = undefined
-        entry.status = 'pending'
-        entry.refreshing = false
-        entry.live = true
-        let cancelled = false
-        const notify = () => {
-            update()
-            lifecycle.mark()
-        }
-        /*
-        Seed-and-commit: frames from a retaining source accumulate silently
-        until its in-band `replayed` boundary, then commit to the window in
-        one update — readers never see the window rebuild frame-by-frame.
-        An empty seed keeps the held window across a gap: nothing was
-        replayed, so nothing can duplicate, and the live frames that follow
-        append. Sources without the capability have no replay; their frames
-        append directly.
-        */
-        let seeding = false
-        let seed: T[] = []
-        const commit = () => {
-            if (cancelled || !seeding) {
-                return
-            }
-            seeding = false
-            if (seed.length > 0) {
-                entry.window = seed
-                seed = []
-            }
-            if (entry.window.length > 0) {
-                entry.status = 'open'
-            }
-            entry.refreshing = false
-            notify()
-        }
-        /*
-        A retaining source bounds replay to what the reader keeps: 1 frame
-        seeds the bare form, `last` seeds a window.
-        */
-        const open = () => {
-            if (!subscribable.tail) {
-                return subscribable[Symbol.asyncIterator]()
-            }
-            seeding = true
-            seed = []
-            return subscribable.tail(last, { replayed: commit })[Symbol.asyncIterator]()
-        }
-        /* `let`: the reconnect path swaps in a fresh iterator; teardown closes the current one. */
-        let iterator = open()
-        ;(async () => {
-            while (!cancelled) {
-                try {
-                    const next = await iterator.next()
-                    if (cancelled) {
-                        return
-                    }
-                    if (next.done) {
-                        /* a retaining source that ends without signalling still commits its seed */
-                        commit()
-                        if (entry.status !== 'error') {
-                            entry.status = 'done'
-                        }
-                        entry.refreshing = false
-                        notify()
-                        return
-                    }
-                    if (seeding) {
-                        seed.push(next.value)
-                        if (seed.length > last) {
-                            seed.shift()
-                        }
-                        continue
-                    }
-                    /*
-                    Probes read only status/refreshing, so the registry
-                    channel pings on transitions, not per frame — a chatty
-                    stream must not re-derive every bare pending()/refreshing()
-                    reader on each value. (A frame after a reconnect is the
-                    seed landing — current again, hence a transition.)
-                    */
-                    const transitioned = entry.status !== 'open' || entry.refreshing
-                    /* One copy per frame: take the surviving suffix, then append. */
-                    const base = entry.window
-                    const frames =
-                        base.length < last ? base.slice() : base.slice(base.length - last + 1)
-                    frames.push(next.value)
-                    entry.window = frames
-                    entry.status = 'open'
-                    entry.refreshing = false
-                    update()
-                    if (transitioned) {
-                        lifecycle.mark()
-                    }
-                } catch (error) {
-                    if (cancelled) {
-                        return
-                    }
-                    if (error instanceof SocketDisconnectedError) {
-                        /*
-                        Recoverable transport loss: retain the window, flag the
-                        gap, reopen — open() re-arms seeding so the reopened
-                        source's replay commits atomically over the held
-                        window. The fresh sub frame queues on the channel and
-                        flushes when its backoff attempt reconnects, so this
-                        loop just awaits the next push — no spin.
-                        */
-                        entry.refreshing = entry.window.length > 0
-                        notify()
-                        iterator = open()
-                        continue
-                    }
-                    entry.error = error instanceof Error ? error : new Error(String(error))
-                    entry.status = 'error'
-                    entry.refreshing = false
-                    notify()
-                    return
-                }
-            }
-        })()
-        lifecycle.mark()
-        return () => {
-            cancelled = true
-            entry.live = false
-            iterator.return?.(undefined)?.catch(() => undefined)
-            if (evictIfCurrent(entry as Entry<unknown>)) {
-                lifecycle.mark()
-            }
-        }
-    })
-    registry.set(key, entry as Entry<unknown>)
-    return entry
-}