@abide/abide 0.58.0 → 0.101.0

package/src/lib/shared/createLifecycleChannel.ts

@@ -1,62 +0,0 @@
-import { createSubscriber } from './createSubscriber.ts'
-
-/*
-Lifecycle tap shared by the cache store and the tail registry: one
-"membership or state changed" signal for the pending()/refreshing() probes,
-which match a group of entries and re-derive by scanning. The owning
-registry decides the granularity — the cache store keeps a store-wide
-channel plus one per probed selector prefix; this module only owns the
-subscribe/notify semantics. track() inside a
-tracking scope ($derived / $effect) re-runs that scope on every mark();
-outside one it is a no-op. The subscriber is created lazily on the first
-tracked read and self-evicts when its last reader tears down,
-identity-guarded so a concurrent re-track isn't clobbered. mark() is a plain
-callback — the channel only ever has the one memoized listener, so no
-EventTarget dispatch is needed.
-
-mark() defers its notify to a microtask: registry mutations happen inside
-consumer read paths, and the documented read idiom is `$derived(await
-cache(fn)())` — a cold read there registers an entry mid-derived, where
-writing the subscriber's version source throws state_unsafe_mutation. The
-probes scan the registry at re-derive time, so a deferred ping reads state
-that is already current; marks within one tick coalesce into one notify.
-*/
-export function createLifecycleChannel(onIdle?: () => void): {
-    track: () => void
-    mark: () => void
-} {
-    let notify: (() => void) | undefined
-    let tracker: (() => void) | undefined
-    let marked = false
-    return {
-        track() {
-            if (!tracker) {
-                const created = createSubscriber((update) => {
-                    notify = update
-                    return () => {
-                        notify = undefined
-                        if (tracker === created) {
-                            tracker = undefined
-                        }
-                        /* Last reader torn down — let an owner (the cache store's per-prefix map)
-                           evict this now-inert channel instead of retaining it for the tab's life. */
-                        onIdle?.()
-                    }
-                })
-                tracker = created
-            }
-            tracker()
-        },
-        mark() {
-            if (notify === undefined || marked) {
-                return
-            }
-            marked = true
-            queueMicrotask(() => {
-                marked = false
-                /* Re-read: the last reader may have torn down during the deferral. */
-                notify?.()
-            })
-        },
-    }
-}

package/src/lib/shared/createLivenessWatch.ts

@@ -1,118 +0,0 @@
-/*
-The liveness state machine shared by every "is that server still there?"
-consumer: a recursive timer (never setInterval, so a slow probe can't overlap
-the next) runs `probe(url)`; a success resets the miss count, `failureLimit`
-consecutive misses declare the target down. Two modes by which hook is given:
-
-- `onLost` (terminal): the bundle launcher's mode — down fires onLost once
-  and the watch stops; the user reconnects deliberately.
-- `onChange` (continuous): the client health() mode — down fires
-  onChange(false), polling continues, and the first subsequent success fires
-  onChange(true). Transitions only, never per-poll — except the first success
-  after watch(), which always reports so a consumer that kept state across a
-  stop()/watch() cycle (health's backendAlive) resyncs with the machine.
-
-watch(url) (re)starts against a new target (first probe after one interval —
-probeNow() forces an immediate one); a probe resolving after the target
-changed is discarded (the url capture is the staleness guard). Probe
-transport is injected — the launcher passes the identity-endpoint check, the
-client health() a browser fetch — so the machine is side-neutral.
-*/
-export function createLivenessWatch(options: {
-    probe: (url: string) => Promise<boolean>
-    onLost?: (url: string) => void
-    onChange?: (alive: boolean) => void
-    intervalMs?: number
-    failureLimit?: number
-}): {
-    watch: (url: string) => void
-    stop: () => void
-    probeNow: () => void
-} {
-    const intervalMs = options.intervalMs ?? 4000
-    const failureLimit = options.failureLimit ?? 2
-    let watchedUrl: string | undefined
-    let timer: ReturnType<typeof setTimeout> | undefined
-    let inFlight = false
-    let failures = 0
-    let alive = true
-    /* No verdict reported since watch() — makes the first success always report. */
-    let fresh = true
-
-    async function runProbe(): Promise<void> {
-        const url = watchedUrl
-        if (!url) {
-            return
-        }
-        if (inFlight) {
-            /*
-            A stale probe from a previous target is still awaiting. Keep this
-            watch's timer armed — the stale resolution discards itself without
-            rescheduling, so returning bare here would leave no timer and the
-            new target silently unwatched.
-            */
-            timer = setTimeout(runProbe, intervalMs)
-            return
-        }
-        inFlight = true
-        const up = await options.probe(url)
-        inFlight = false
-        // A stop or re-watch during the await moved the target — discard.
-        if (watchedUrl !== url) {
-            return
-        }
-        if (up) {
-            failures = 0
-            if (!alive || fresh) {
-                alive = true
-                fresh = false
-                options.onChange?.(true)
-            }
-        } else {
-            failures += 1
-            if (failures >= failureLimit && alive) {
-                alive = false
-                fresh = false
-                if (options.onChange) {
-                    options.onChange(false)
-                } else {
-                    stop()
-                    options.onLost?.(url)
-                    return
-                }
-            }
-        }
-        timer = setTimeout(runProbe, intervalMs)
-    }
-
-    function watch(url: string): void {
-        stop()
-        watchedUrl = url
-        fresh = true
-        timer = setTimeout(runProbe, intervalMs)
-    }
-
-    function stop(): void {
-        if (timer) {
-            clearTimeout(timer)
-            timer = undefined
-        }
-        watchedUrl = undefined
-        failures = 0
-        alive = true
-    }
-
-    /* Event-accelerated check (visibility return, online event): probe immediately instead of waiting out the interval. */
-    function probeNow(): void {
-        if (!watchedUrl || inFlight) {
-            return
-        }
-        if (timer) {
-            clearTimeout(timer)
-            timer = undefined
-        }
-        void runProbe()
-    }
-
-    return { watch, stop, probeNow }
-}

package/src/lib/shared/createPushIterator.ts

@@ -1,132 +0,0 @@
-/*
-Bounded-queue AsyncIterator factory shared by the in-process
-socket fan-out (defineSocket) and the client-side ws proxy
-(socketProxy). Callers push values, signal end, signal an error, or
-signal a transport disconnect; the iterator drains a queue then awaits
-the next push. Cancellation runs the optional `onClose` so subscribers
-can drop their backref. `disconnect()` is terminal like `error()` but
-throws the typed SocketDisconnectedError so consumers can tell a
-recoverable transport loss from an application error.
-
-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.
-*/
-
-import { SocketDisconnectedError } from './SocketDisconnectedError.ts'
-
-type Slot<T> =
-    | { kind: 'value'; value: T }
-    | { kind: 'control'; run: () => void }
-    | { kind: 'end' }
-    | { kind: 'error'; message: string }
-    | { kind: 'disconnect' }
-
-export type PushIterator<T> = AsyncIterator<T, void, undefined> & {
-    push(value: T): void
-    /*
-    Queues an in-band signal (e.g. the replay/live boundary): `run` executes
-    inside next() when drained, strictly ordered against pushed values, and
-    is invisible to the consumer — next() continues to the following slot.
-    Never dropped by the buffer cap.
-    */
-    control(run: () => void): void
-    end(): void
-    error(message: string): void
-    disconnect(): 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 value slot before exceeding the cap — never a control or
-           terminal slot (end/error/disconnect), which the contract guarantees are
-           never dropped. If the buffer holds only non-value slots, drop nothing. */
-        if (slot.kind === 'value' && buffer.length >= maxBuffer) {
-            const oldestValue = buffer.findIndex((pending) => pending.kind === 'value')
-            if (oldestValue !== -1) {
-                buffer.splice(oldestValue, 1)
-            }
-        }
-        buffer.push(slot)
-    }
-
-    function close(): void {
-        if (closed) {
-            return
-        }
-        closed = true
-        onClose?.()
-    }
-
-    return {
-        push(value) {
-            deliver({ kind: 'value', value })
-        },
-        control(run) {
-            deliver({ kind: 'control', run })
-        },
-        end() {
-            deliver({ kind: 'end' })
-        },
-        error(message) {
-            deliver({ kind: 'error', message })
-        },
-        disconnect() {
-            deliver({ kind: 'disconnect' })
-        },
-        async next() {
-            while (true) {
-                if (closed) {
-                    return { value: undefined, done: true }
-                }
-                const slot = buffer.shift() ?? (await new Promise<Slot<T>>((r) => (waiter = r)))
-                if (slot.kind === 'control') {
-                    slot.run()
-                    continue
-                }
-                if (slot.kind === 'end') {
-                    close()
-                    return { value: undefined, done: true }
-                }
-                if (slot.kind === 'error') {
-                    close()
-                    throw new Error(slot.message)
-                }
-                if (slot.kind === 'disconnect') {
-                    close()
-                    throw new SocketDisconnectedError()
-                }
-                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/createReachable.ts

@@ -1,78 +0,0 @@
-/*
-The reachability registry behind `abide/shared/reachable`. A probe transport and the
-TTL are injected so the public name wires them from env + a real HEAD while tests drive
-scripted outcomes.
-
-Per origin, a TTL memoize: the first read — and any read after the cached verdict has
-aged past `ttlMs` — awaits a real probe (the FAITHFUL answer; its latency, a full timeout
-when the host is down, is the price of not guessing) and caches the verdict with its
-timestamp. Every read within the TTL resolves instantly off that cached value. Concurrent
-reads of a cold/stale origin share the one in-flight probe. No background poll: a host that
-goes down (or recovers) is noticed on the next read after its entry ages out, not
-continuously.
-*/
-export function createReachable(options: {
-    probe: (origin: string) => Promise<boolean>
-    ttlMs: number
-}): {
-    reachable: (host: string | URL) => Promise<boolean>
-    /* Drop every cached verdict — graceful reset and test isolation. */
-    stop: () => void
-    /* `using registry = createReachable(...)` — disposal clears the cache. */
-    [Symbol.dispose]: () => void
-} {
-    type Entry = {
-        alive: boolean
-        /* `Date.now()` when `alive` was taken; a read past `ttlMs` re-probes. */
-        probedAt: number
-        /* A probe in flight — concurrent cold/stale reads await the same one. */
-        inflight: Promise<boolean> | undefined
-    }
-    const cache = new Map<string, Entry>()
-
-    /* Re-probe an origin, folding the verdict + its timestamp back into the entry. A rejecting
-       probe reads as unreachable, not a permanent wedge (without the catch a thrown probe would
-       leave `inflight` set forever). */
-    function refresh(origin: string, entry: Entry): Promise<boolean> {
-        entry.inflight = options
-            .probe(origin)
-            .catch(() => false)
-            .then((alive) => {
-                entry.alive = alive
-                entry.probedAt = Date.now()
-                entry.inflight = undefined
-                return alive
-            })
-        return entry.inflight
-    }
-
-    function reachable(host: string | URL): Promise<boolean> {
-        /* HEAD the origin root: host connectivity, not endpoint health. A bare host defaults to
-           https (the external-dependency norm); an explicit http://… is honored. */
-        const url =
-            typeof host === 'string' && !/^https?:\/\//i.test(host) ? `https://${host}` : host
-        const origin = new URL(url).origin
-        const existing = cache.get(origin)
-        if (existing !== undefined) {
-            /* A probe already running → share it (dedupes concurrent cold/stale reads). */
-            if (existing.inflight !== undefined) {
-                return existing.inflight
-            }
-            /* Fresh within the TTL → instant warm read. */
-            if (Date.now() - existing.probedAt < options.ttlMs) {
-                return Promise.resolve(existing.alive)
-            }
-            /* Aged out → re-probe on this read. */
-            return refresh(origin, existing)
-        }
-        const entry: Entry = { alive: true, probedAt: 0, inflight: undefined }
-        cache.set(origin, entry)
-        return refresh(origin, entry)
-    }
-
-    function stop(): void {
-        cache.clear()
-    }
-
-    return { reachable, stop, [Symbol.dispose]: stop }
-}

package/src/lib/shared/createRemoteFunction.ts

@@ -1,210 +0,0 @@
-import { attachRpcSelectorMethods } from './attachRpcSelectorMethods.ts'
-import { cache } from './cache.ts'
-import { HttpError } from './HttpError.ts'
-import { keyForRemoteCall } from './keyForRemoteCall.ts'
-import { REMOTE_FUNCTION } from './REMOTE_FUNCTION.ts'
-import { recordRemoteMeta } from './recordRemoteMeta.ts'
-import { reviveWireOutput } from './reviveWireOutput.ts'
-import { rpcErrorRegistry } from './rpcErrorRegistry.ts'
-import { subscribableFromResponse } from './subscribableFromResponse.ts'
-import type { CachePolicy } from './types/CachePolicy.ts'
-import type { ClientFlags } from './types/ClientFlags.ts'
-import type { HttpMethod } from './types/HttpMethod.ts'
-import type { NamedAsyncIterable } from './types/NamedAsyncIterable.ts'
-import type { OutputWirePlan } from './types/OutputWirePlan.ts'
-import type { RawRemoteFunction } from './types/RawRemoteFunction.ts'
-import type { RemoteFunction } from './types/RemoteFunction.ts'
-import type { RpcOptions } from './types/RpcOptions.ts'
-import type { StreamPolicy } from './types/StreamPolicy.ts'
-
-/*
-Assembles the public RemoteFunction shape used identically by the
-server-side defineRpc (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 NamedAsyncIterable 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 defineRpc
-  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: HttpMethod
-    url: string
-    clients: ClientFlags
-    /* Server-side only: exempts a mutating rpc from the router's same-origin CSRF gate. */
-    crossOrigin?: boolean
-    buildRequest: (args: Args | undefined, opts?: RpcOptions) => Request
-    invoke: (
-        args: Args | undefined,
-        getRequest: () => Request,
-        opts?: RpcOptions,
-    ) => Promise<Response>
-    parseArgsForFetch?: (request: Request) => Promise<Args | undefined>
-    /* A streaming rpc (handler returns jsonl()/sse()): the bare call returns the NamedAsyncIterable
-       directly (the iterable IS the value) rather than decoding one Response body. Emitted by
-       the bundler's syntactic scan; false/undefined keeps the decode-a-Response path. */
-    streaming?: boolean
-    /* Endpoint cache/stream policy (ADR-0020) — stamped onto both callable variants so
-       readThrough reads it as the bottom policy layer. Declared once on the rpc definition. */
-    cache?: CachePolicy<Args>
-    stream?: StreamPolicy
-    /* Client-only: the output wire codec plan (ADR-0029) the remoteProxy stub carries — the decoded
-       response body's structured fields are revived through it (a `Set`/`Map`/`bigint`/`Date`). The
-       server defineRpc never sets it, so an in-process read is untouched. undefined leaves the body
-       as its honest-JSON form. */
-    outputWirePlan?: OutputWirePlan
-}): RemoteFunction<Args, Return> {
-    const {
-        method,
-        url,
-        clients,
-        crossOrigin,
-        buildRequest,
-        invoke,
-        parseArgsForFetch,
-        streaming,
-        cache: cachePolicy,
-        stream: streamPolicy,
-        outputWirePlan,
-    } = 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,
-        opts?: RpcOptions,
-        prebuilt?: Request,
-    ): Promise<Response> {
-        let cached = prebuilt
-        function getRequest(): Request {
-            if (cached === undefined) {
-                cached = buildRequest(args, opts)
-            }
-            return cached
-        }
-        const promise = invoke(args, getRequest, opts)
-        recordRemoteMeta(promise, getRequest)
-        return promise
-    }
-
-    /*
-    A body rpc 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, opts?: RpcOptions): Promise<Response> {
-        return dispatch(args as Args, opts)
-    }
-    rawCall.method = method
-    rawCall.url = url
-    /* Endpoint policy on both variants so readThrough can read it off whichever the caller
-       passed (`fn` for the decoded read, `fn.raw` for the raw escape hatch). */
-    rawCall.cache = cachePolicy
-    rawCall.stream = streamPolicy
-    /* Non-enumerable brand on both variants; see REMOTE_FUNCTION. */
-    Object.defineProperty(rawCall, REMOTE_FUNCTION, { value: true })
-    const raw = rawCall as RawRemoteFunction<Args>
-
-    function callable(args: Args | FormData): Promise<Return> | NamedAsyncIterable<Return> {
-        /* A streaming rpc (jsonl/sse) returns the NamedAsyncIterable directly — the iterable IS the
-           value (for await / state(fn(args))). Deferred fetch, keyForRemoteCall-keyed so tail()
-           dedupes readers; no decode, so the error-capture path below doesn't apply. */
-        if (streaming) {
-            return subscribableFromResponse(keyForRemoteCall(method, url, args), () =>
-                raw(args as Args),
-            )
-        }
-        /* The bare call IS the smart read: route through the cache store's smart-read
-           path so a replayable read is coalesced, retained (SWR unconditional), and
-           reactive, while a write is coalesce-only — the raw fetch moves to `.raw`.
-           `cache.read(callable, …)` brand-reads `callable.raw` for the undecoded variant
-           and decodes on the way out, so pass the callable (which carries `.raw`), not
-           `raw`. There is no call-site options argument any more — all cache policy is read
-           from the endpoint (`callable.cache`); per-call transport options live on `.raw`. */
-        const key = keyForRemoteCall(method, url, args)
-        /* Thread the derived key into the smart read so readThrough reuses it rather than
-           re-deriving the identical string (callable.raw carries the same method/url); the
-           key already tags the rpc-error registry entries in the handlers below. */
-        return cache.read(callable as RemoteFunction<Args, Return>, args as Args, key).then(
-            /* Capture the rejection into the rpc error registry (design Part 4) keyed by call
-               identity, and clear it on success — the reactive `fn.error()` probe reads it. */
-            (value) => {
-                rpcErrorRegistry.clear(key)
-                /* Revive the decoded body's structured fields per the baked output plan (ADR-0029):
-                   a wire array → `Set`/`Map`, a digit string → `bigint`, an ISO string → `Date`. The
-                   decoded value is call-private (a fresh decode or cloned warm value), so the revive
-                   mutates in place. No plan (undefined — every server-side read, or a client endpoint
-                   with no structured field) returns the value untouched. */
-                return reviveWireOutput(value, outputWirePlan) as Return
-            },
-            (error: unknown) => {
-                rpcErrorRegistry.record(key, error)
-                throw error
-            },
-        )
-    }
-    callable.method = method
-    callable.url = url
-    callable.clients = clients
-    callable.crossOrigin = crossOrigin
-    callable.cache = cachePolicy
-    callable.stream = streamPolicy
-    callable.raw = raw
-    /* Stamp the output wire codec plan (ADR-0029) so the public `cache(fn, args)` and
-       `cache.peek(fn, args)` can revive the decoded body's structured fields (Set/Map/Date/bigint)
-       exactly as the bare `fn(args)` read does above — otherwise those two read APIs return the raw
-       honest-JSON form and disagree with `fn(args)`. A runtime affordance, not on the RemoteFunction
-       surface (read via cast in cache.ts, like `settled`); undefined server-side / plan-less. */
-    ;(callable as { outputWirePlan?: OutputWirePlan }).outputWirePlan = outputWirePlan
-    /* Uniform runtime guard for every rpc — the per-rpc data typing lives entirely in the
-       RpcErrorGuard<Errors> signature RemoteFunction projects onto it (Errors flows from the
-       rpc helper's declared type, not from here). */
-    callable.isError = (error: unknown, kind: string): boolean =>
-        error instanceof HttpError && error.kind === kind
-    Object.defineProperty(callable, REMOTE_FUNCTION, { value: true })
-    callable.fetch = parseArgsForFetch
-        ? async (request: Request): Promise<Response> => {
-              let args: Args | undefined
-              try {
-                  args = await parseArgsForFetch(request)
-              } catch (error) {
-                  /*
-                  Parse-stage rejections that already chose their wire shape
-                  (readBodyWithinLimit's 413) return it; anything else (e.g.
-                  malformed JSON) keeps propagating to the scope's catch.
-                  Handler errors are outside this try on purpose — throwing
-                  is the app.handleError path, `return error(...)` the wire one.
-                  */
-                  if (error instanceof HttpError) {
-                      return error.response
-                  }
-                  throw error
-              }
-              return dispatch(args, undefined, request)
-          }
-        : (request: Request): Promise<Response> => {
-              return dispatch(undefined, undefined, request)
-          }
-    attachRpcSelectorMethods(callable as RemoteFunction<Args, Return>)
-    return callable as RemoteFunction<Args, Return>
-}

package/src/lib/shared/createResolverSlot.ts

@@ -1,30 +0,0 @@
-import type { ResolverSlot } from './types/ResolverSlot.ts'
-
-/*
-The resolver-slot seam the runtime entries share for cache store, page,
-request-scope, and mount-base state. A runtime entry registers a side-specific
-resolver by assigning `.resolver` (ALS-backed on the server, a module
-singleton on the client); `get()` returns the resolved value, falling back to
-a single lazily-created fallback when no resolver is registered so isolated
-tests work without booting the runtime. Pass `createFallback` for a
-lazily-built, cached fallback (cache store, page); omit it for a slot whose
-fallback is a plain value set directly (mount base) — `get()` then returns
-`T | undefined`.
-*/
-export function createResolverSlot<T>(createFallback?: () => T): ResolverSlot<T> {
-    const slot: ResolverSlot<T> = {
-        resolver: undefined,
-        fallback: undefined,
-        get(): T | undefined {
-            const fromResolver = slot.resolver?.()
-            if (fromResolver !== undefined) {
-                return fromResolver
-            }
-            if (createFallback && slot.fallback === undefined) {
-                slot.fallback = createFallback()
-            }
-            return slot.fallback
-        },
-    }
-    return slot
-}