@abide/abide 0.57.1 → 0.100.0

package/src/lib/shared/createSocketSubRegistry.ts

@@ -1,112 +0,0 @@
-import type { SocketChannel } from './types/SocketChannel.ts'
-import type { SocketClientFrame } from './types/SocketClientFrame.ts'
-import type { SocketServerFrame } from './types/SocketServerFrame.ts'
-import type { SocketSubCallbacks } from './types/SocketSubCallbacks.ts'
-
-/*
-The multiplex bookkeeping every SocketChannel shares: the local subscription
-registry plus the inbound `SocketServerFrame` routing. A channel supplies only
-its transport (`send`, and when to call `drainSubs` on a drop); everything that
-encodes the wire contract — how a `msg` fans out to a socket's subs, how
-`replay`/`end`/`err` address one sub — lives here once, so the browser multiplex
-and the test harness cannot drift on the protocol (ADR-0005).
-
-`send` carries an outbound client frame however the channel can (the browser
-queues until open and reconnects; the test harness queues until open). Routing
-and the registry never touch the transport, so they stay identical across both.
-*/
-export function createSocketSubRegistry(send: (frame: SocketClientFrame) => void): {
-    channel: SocketChannel
-    routeFrame: (frame: SocketServerFrame) => void
-    drainSubs: () => SocketSubCallbacks[]
-} {
-    const subs = new Map<string, { socket: string; callbacks: SocketSubCallbacks }>()
-    /* Reverse index for `msg` fan-out: one server publish addresses a socket, not a sub. */
-    const subsBySocket = new Map<string, Set<string>>()
-
-    function dropSub(id: string): void {
-        const entry = subs.get(id)
-        if (!entry) {
-            return
-        }
-        subs.delete(id)
-        const set = subsBySocket.get(entry.socket)
-        if (set) {
-            set.delete(id)
-            if (set.size === 0) {
-                subsBySocket.delete(entry.socket)
-            }
-        }
-    }
-
-    /*
-    Routes one inbound frame to its sub(s):
-      `msg`    → every local sub of that socket (addressed by socket name)
-      `replay` → the one sub that requested the seed (its batched tail)
-      `end`/`err` → the one sub, dropped first so its iterator can't take another frame
-    A frame for an unknown sub/socket is ignored — a sub torn down between request
-    and delivery.
-    */
-    function routeFrame(frame: SocketServerFrame): void {
-        if (frame.type === 'msg') {
-            const targets = subsBySocket.get(frame.socket)
-            if (!targets) {
-                return
-            }
-            for (const subId of targets) {
-                subs.get(subId)?.callbacks.onMessage(frame.message)
-            }
-            return
-        }
-        if (frame.type === 'replay') {
-            subs.get(frame.sub)?.callbacks.onReplay(frame.messages)
-            return
-        }
-        const sub = subs.get(frame.sub)
-        if (!sub) {
-            return
-        }
-        dropSub(frame.sub)
-        if (frame.type === 'end') {
-            sub.callbacks.onEnd()
-        } else {
-            sub.callbacks.onError(frame.message)
-        }
-    }
-
-    /* Tear down every sub on a transport drop and hand the caller their callbacks.
-       Clears the registry BEFORE the caller runs `onDisconnect`, so a consumer that
-       re-subscribes in reaction (in a later microtask) registers onto fresh state. */
-    function drainSubs(): SocketSubCallbacks[] {
-        const active = [...subs.values()].map((entry) => entry.callbacks)
-        subs.clear()
-        subsBySocket.clear()
-        return active
-    }
-
-    const channel: SocketChannel = {
-        subscribe(id, socket, replay, callbacks) {
-            subs.set(id, { socket, callbacks })
-            /* Not getOrInsertComputed: browser-side code, and Safari/Chrome only shipped it within the last browser cycle (26.2 / 145). */
-            let set = subsBySocket.get(socket)
-            if (!set) {
-                set = new Set()
-                subsBySocket.set(socket, set)
-            }
-            set.add(id)
-            send({ type: 'sub', sub: id, socket, replay })
-        },
-        unsubscribe(id) {
-            if (!subs.has(id)) {
-                return
-            }
-            dropSub(id)
-            send({ type: 'unsub', sub: id })
-        },
-        publish(socket, message) {
-            send({ type: 'pub', socket, message })
-        },
-    }
-
-    return { channel, routeFrame, drainSubs }
-}

package/src/lib/shared/createSubscriber.ts

@@ -1,55 +0,0 @@
-import { createSignalNode } from '../ui/runtime/createSignalNode.ts'
-import { OWNER } from '../ui/runtime/OWNER.ts'
-import { track } from '../ui/runtime/track.ts'
-import { trigger } from '../ui/runtime/trigger.ts'
-
-/*
-abide-ui-native `createSubscriber`: open-on-first-read, close-on-last-reader,
-grounded in abide's own signal core (no external reactivity library). The
-reactivity substrate lives in `../ui/runtime` — pure, DOM-free signal primitives
-that the isomorphic shared layer reuses, the same way the cache reuses other
-shared machinery.
-
-`start` opens the resource and returns a cleanup; the returned `subscribe()`,
-read inside a abide-ui effect/derived, registers that reader (via `track`) and
-re-runs it whenever `update` fires.
-
-Lifecycle rides the signal node's observer set. The resource opens SYNCHRONOUSLY
-on the first tracked read — a consumer like tail() flips state in
-`start` that its very read path checks, so a deferred open would let it read a
-not-yet-open entry and evict it. The close is deferred to a microtask scheduled on
-a reader's scope disposal: an effect re-run momentarily drops then re-adds itself
-as an observer, so checking on the microtask (not synchronously) avoids tearing the
-resource down and reopening it across a re-run. Called outside any tracking scope,
-`track` is a no-op, observers stay empty, and the resource never opens — matching
-the open-on-first-read contract.
-*/
-// @documentation plumbing
-export function createSubscriber(start: (update: () => void) => () => void): () => void {
-    const node = createSignalNode(undefined)
-    let cleanup: (() => void) | undefined
-    let closeScheduled = false
-
-    const maybeClose = (): void => {
-        closeScheduled = false
-        if (node.subsHead === undefined && cleanup !== undefined) {
-            cleanup()
-            cleanup = undefined
-        }
-    }
-
-    return () => {
-        track(node)
-        /* Open eagerly on the first reader within a tracking scope. */
-        if (cleanup === undefined && node.subsHead !== undefined) {
-            cleanup = start(() => trigger(node))
-        }
-        /* Close once this reader's scope tears down and no observers remain. */
-        OWNER.current?.push(() => {
-            if (!closeScheduled) {
-                closeScheduled = true
-                queueMicrotask(maybeClose)
-            }
-        })
-    }
-}

package/src/lib/shared/createTraceContext.ts

@@ -1,21 +0,0 @@
-import { parseTraceparent } from './parseTraceparent.ts'
-import { randomHexId } from './randomHexId.ts'
-import type { TraceContext } from './types/TraceContext.ts'
-
-/*
-Builds this request's trace position from an inbound `traceparent` header.
-Prefer-incoming rule: a valid header keeps its trace id and sampling flags
-(abide never overwrites a trace someone upstream started); the header's span
-id becomes `parentSpanId`. Either way abide mints a fresh `spanId` for this
-request — the one outbound hops carry as parent. No header (or a malformed
-one) starts a new trace, sampled ('01') so downstream recorders keep it.
-*/
-export function createTraceContext(header: string | null | undefined): TraceContext {
-    const incoming = header ? parseTraceparent(header) : undefined
-    return {
-        traceId: incoming?.traceId ?? randomHexId(16),
-        spanId: randomHexId(8),
-        parentSpanId: incoming?.spanId,
-        flags: incoming?.flags ?? '01',
-    }
-}

package/src/lib/shared/dataDirEnvPath.ts

@@ -1,12 +0,0 @@
-import { join } from 'node:path'
-import { appDataDir } from './appDataDir.ts'
-
-/*
-The user's `.env` in the program's per-user data dir — the cwd-independent
-config layer the connect-screen form writes and the server loads first at
-boot. One statement of the location so the writer (controlServerWorker), the
-boot loader (loadEnvFromDataDir), and the embedded-port resolver can't drift.
-*/
-export function dataDirEnvPath(programName: string): string {
-    return join(appDataDir(programName), '.env')
-}

package/src/lib/shared/debugGate.ts

@@ -1,90 +0,0 @@
-import type { DebugGate } from './types/DebugGate.ts'
-
-/*
-The DEBUG-gate core: one memoized decision-maker per distinct DEBUG string,
-npm-debug conventions. `enabled(name)` answers "is gated channel X on?",
-`negated(name)` answers "did a `-X` pattern explicitly shut it off?" — the two
-questions isDebugEnabled / isDebugNegated expose. Both were re-deriving the same
-parse + filter work on every emission; here the include/exclude partition is
-computed once per env value (a single pass, not two throwaway-array filters) and
-each per-name boolean is cached, since the server's DEBUG is stable and channel
-names are a tiny fixed set.
-
-A new env string (the browser's abide-debug localStorage toggle, or tests
-mutating process.env.DEBUG) misses the single-slot memo and rebuilds — so a
-runtime DEBUG change takes effect on its next read.
-*/
-
-// One DEBUG pattern (already `-`-stripped) against one channel name: `*` matches
-// everything, `abide:*` matches 'abide' and every 'abide:…' sub-channel, else exact.
-function matches(name: string, pattern: string): boolean {
-    if (pattern === '*') {
-        return true
-    }
-    if (pattern.endsWith(':*')) {
-        const prefix = pattern.slice(0, -2)
-        return name === prefix || name.startsWith(`${prefix}:`)
-    }
-    return pattern === name
-}
-
-// Builds a gate for one env value: partitions the comma list into include/exclude
-// patterns in a single pass, then memoizes each per-name decision in a map.
-function buildGate(env: string | undefined): DebugGate {
-    const includes: string[] = []
-    const excludes: string[] = []
-    if (env) {
-        for (const raw of env.split(',')) {
-            const pattern = raw.trim()
-            if (pattern === '') {
-                continue
-            }
-            if (pattern.startsWith('-')) {
-                excludes.push(pattern.slice(1))
-            } else {
-                includes.push(pattern)
-            }
-        }
-    }
-    /* Cache-hit fast path: a Map keyed on channel name, since names are a tiny
-       fixed set and the gate runs on every log emission. Negated and enabled
-       cache separately — a channel can be queried through either question. */
-    const negatedCache = new Map<string, boolean>()
-    const enabledCache = new Map<string, boolean>()
-    return {
-        negated(name: string): boolean {
-            const cached = negatedCache.get(name)
-            if (cached !== undefined) {
-                return cached
-            }
-            const result = excludes.some((pattern) => matches(name, pattern))
-            negatedCache.set(name, result)
-            return result
-        },
-        enabled(name: string): boolean {
-            const cached = enabledCache.get(name)
-            if (cached !== undefined) {
-                return cached
-            }
-            // Exclusions win over inclusions (npm-debug negation precedence).
-            const result =
-                !excludes.some((pattern) => matches(name, pattern)) &&
-                includes.some((pattern) => matches(name, pattern))
-            enabledCache.set(name, result)
-            return result
-        },
-    }
-}
-
-/* Single-slot memo on the env string: the gate (partition + decision caches) is
-   rebuilt only when DEBUG changes. */
-let lastEnv: string | undefined
-let lastGate: DebugGate = buildGate(undefined)
-
-export function debugGate(env: string | undefined): DebugGate {
-    if (env !== lastEnv) {
-        lastEnv = env
-        lastGate = buildGate(env)
-    }
-    return lastGate
-}

package/src/lib/shared/decodeRefJson.ts

@@ -1,112 +0,0 @@
-/*
-Inverse of encodeRefJson — rebuild a value graph (cycles, shared references, and the
-JSON-hostile types) from a `[rootValue, slots]` ref-json string. Two passes are
-required: pass one allocates every hoisted container as an empty shell, pass two fills
-them. The shell must exist before its contents are filled so a back-reference to an
-ancestor resolves to the already-allocated object — which is what reconnects a cycle.
-Inline primitives need no shell; they decode directly where they sit.
-*/
-import { REF_JSON_NUMBER_TOKENS, REF_JSON_TAGS } from './REF_JSON_TAGS.ts'
-import { setOwnProperty } from './setOwnProperty.ts'
-
-export function decodeRefJson(text: string): unknown {
-    const parsed = JSON.parse(text)
-    if (!Array.isArray(parsed) || parsed.length !== 2 || !Array.isArray(parsed[1])) {
-        // encodeRefJson always emits a `[rootValue, slots]` pair; anything else isn't our format.
-        throw new TypeError('decodeRefJson: not a ref-json payload')
-    }
-    const [rootValue, slots] = parsed as [unknown, unknown[]]
-    // Pass 1: an empty container shell per slot. Pass 2 fills them so a ref to an ancestor finds its shell.
-    const shells = slots.map(buildShell)
-    slots.forEach((slot, index) => {
-        fillShell(slot, shells[index], shells)
-    })
-    return resolveValue(rootValue, shells)
-}
-
-// Empty container matching a slot's kind. Every slot is a container (only containers are hoisted).
-function buildShell(slot: unknown): unknown {
-    if (Array.isArray(slot)) {
-        if (slot[0] === REF_JSON_TAGS.ARRAY) {
-            return []
-        }
-        if (slot[0] === REF_JSON_TAGS.MAP) {
-            return new Map()
-        }
-        if (slot[0] === REF_JSON_TAGS.SET) {
-            return new Set()
-        }
-    }
-    return {}
-}
-
-// Decode an inline value: bare primitive (itself), a leaf-special, or a reference to a built shell.
-function resolveValue(value: unknown, shells: unknown[]): unknown {
-    if (!Array.isArray(value)) {
-        return value
-    }
-    switch (value[0]) {
-        case REF_JSON_TAGS.REF:
-            return shells[value[1] as number]
-        case REF_JSON_TAGS.UNDEFINED:
-            return undefined
-        case REF_JSON_TAGS.DATE:
-            return new Date(value[1] as number)
-        case REF_JSON_TAGS.REGEXP:
-            return new RegExp(value[1] as string, value[2] as string)
-        case REF_JSON_TAGS.BIGINT:
-            return BigInt(value[1] as string)
-        case REF_JSON_TAGS.NUMBER:
-            return decodeNumberToken(value[1] as string)
-        default:
-            throw new TypeError(`decodeRefJson: unknown value tag ${String(value[0])}`)
-    }
-}
-
-// Fill a container shell from its slot, resolving each inline child.
-function fillShell(slot: unknown, shell: unknown, shells: unknown[]): void {
-    if (!Array.isArray(slot)) {
-        const target = shell as Record<string, unknown>
-        const record = slot as Record<string, unknown>
-        for (const key of Object.keys(record)) {
-            // setOwnProperty: a wire `__proto__` key must not hijack the shell's prototype.
-            setOwnProperty(target, key, resolveValue(record[key], shells))
-        }
-        return
-    }
-    if (slot[0] === REF_JSON_TAGS.ARRAY) {
-        const target = shell as unknown[]
-        // Loop (not push(...spread)) so a huge array can't blow the call-stack arg limit.
-        for (let index = 1; index < slot.length; index++) {
-            target.push(resolveValue(slot[index], shells))
-        }
-        return
-    }
-    if (slot[0] === REF_JSON_TAGS.MAP) {
-        const target = shell as Map<unknown, unknown>
-        for (const [key, val] of slot[1] as [unknown, unknown][]) {
-            target.set(resolveValue(key, shells), resolveValue(val, shells))
-        }
-        return
-    }
-    if (slot[0] === REF_JSON_TAGS.SET) {
-        const target = shell as Set<unknown>
-        for (const member of slot[1] as unknown[]) {
-            target.add(resolveValue(member, shells))
-        }
-    }
-}
-
-// Reverse of encodeRefJson's numberToken.
-function decodeNumberToken(token: string): number {
-    if (token === REF_JSON_NUMBER_TOKENS.NAN) {
-        return Number.NaN
-    }
-    if (token === REF_JSON_NUMBER_TOKENS.INFINITY) {
-        return Number.POSITIVE_INFINITY
-    }
-    if (token === REF_JSON_NUMBER_TOKENS.NEG_INFINITY) {
-        return Number.NEGATIVE_INFINITY
-    }
-    return -0
-}

package/src/lib/shared/decodeResponse.ts

@@ -1,54 +0,0 @@
-import { bodyValueForKind } from './bodyValueForKind.ts'
-import { contentBodyKind } from './contentBodyKind.ts'
-import { contentTypeOf } from './contentTypeOf.ts'
-import { DEFER } from './DEFER.ts'
-import { httpErrorFor } from './httpErrorFor.ts'
-
-/*
-Decodes a Response into the natural body value based on Content-Type:
-  application/json (or `*\/+json`) → parsed JSON
-  text/*                           → string
-  204 No Content                   → 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.
-A streaming rpc's bare call already returns a NamedAsyncIterable (the type makes
-`await fn(args)` a compile error), so this is a backstop for the paths that
-still decode a raw Response — `cache()` and the one-shot stream reader. The
-error points callers at the right tools: `state(fn(args))` for a reactive
-view, or `for await (… of fn(args))` for direct iteration.
-
-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 await httpErrorFor(response)
-    }
-    if (response.status === 204) {
-        return undefined
-    }
-    const contentType = contentTypeOf(response.headers)
-    const kind = contentBodyKind(contentType)
-    if (kind === 'streaming') {
-        throw new Error(
-            `[abide] response at ${response.url} is a stream (${contentType}) — a streaming rpc's bare call already returns a NamedAsyncIterable: use state(fn(args)) for a reactive view or \`for await (… of fn(args))\` for iteration, not await/cache()`,
-        )
-    }
-    /* json/text go through the shared mapping warmValueFromSnapshot also uses, so a warm
-       seed reads byte-identically to this live read; binary (the only DEFER kind left,
-       streaming already threw above) blobs. */
-    const value = bodyValueForKind(
-        kind,
-        () => response.json(),
-        () => response.text(),
-    )
-    return value === DEFER ? response.blob() : value
-}

package/src/lib/shared/decodeWireBody.ts

@@ -1,35 +0,0 @@
-/*
-The single decode point for the "is this ref-json?" policy: abide's own client speaks
-ref-json (encodeRefJson — restores the cycles/shared refs/structured types plain JSON
-can't carry); a foreign client (curl, an OpenAPI SDK, a raw ws client) speaks ordinary
-JSON. Both the rpc body face and the socket-frame face funnel through here so the
-codec fork lives in exactly one place instead of being re-derived per face.
-
-The discriminator is a genuine per-face input difference, kept thin at the call site:
-
-  - `isRefJson === true`  — the rpc client stamped REF_JSON_HEADER, so decode as ref-json.
-  - `isRefJson === false` — no header (a non-abide rpc body), so plain JSON.parse.
-  - `isRefJson === undefined` — no header is available at all (a ws frame carries none),
-    so sniff: try ref-json, fall back to plain JSON. The ref-json `[rootValue, slots]`
-    envelope is ambiguous with a legitimate 2-element array, but a frame is always an
-    object, so a foreign plain-JSON frame makes decodeRefJson throw and we fall back.
-
-Throws on a malformed payload (JSON.parse's own SyntaxError) — the caller decides
-whether that's a 400 (rpc) or a dropped frame (ws).
-*/
-import { decodeRefJson } from './decodeRefJson.ts'
-
-export function decodeWireBody(text: string, isRefJson: boolean | undefined): unknown {
-    if (isRefJson === true) {
-        return decodeRefJson(text)
-    }
-    if (isRefJson === false) {
-        return JSON.parse(text)
-    }
-    // No discriminator (a ws frame has no header): try ref-json, fall back to plain JSON.
-    try {
-        return decodeRefJson(text)
-    } catch {
-        return JSON.parse(text)
-    }
-}

package/src/lib/shared/detectRpcMethod.ts

@@ -1,24 +0,0 @@
-import { HTTP_METHODS } from './HTTP_METHODS.ts'
-import type { HttpMethod } from './types/HttpMethod.ts'
-
-/*
-Reads the HTTP method of an $rpc module from its source. Every file under
-src/server/rpc/ follows the convention `export const <name> = GET(fn)` (the
-rpc helper picks the method, possibly with an explicit generic
-`GET<{…}>(fn)`), so the helper name at the export is the method. Returns
-undefined when no rpc export matches — the caller skips the file rather
-than guessing. Used by the rpc.d.ts codegen to type url() against
-query-carrying rpcs; matching the same convention the bundler rewrites
-keeps the two from drifting.
-
-The FAIL-OPEN fallback for writeRpcDts's method resolution (ADR-0025 D2/D3): when a
-warm server program is present the method is read off the export's helper SYMBOL
-(alias/re-export-aware), and this regex — keyed on the literal helper name — is used
-only when no program built or the query didn't resolve. Byte-identical to the pre-ADR
-path when no program is present.
-*/
-const RPC_EXPORT = new RegExp(`export\\s+const\\s+\\w+\\s*=\\s*(${HTTP_METHODS.join('|')})\\s*[<(]`)
-
-export function detectRpcMethod(source: string): HttpMethod | undefined {
-    return (source.match(RPC_EXPORT)?.[1] as HttpMethod | undefined) ?? undefined
-}

package/src/lib/shared/detectTarget.ts

@@ -1,27 +0,0 @@
-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(
-            `[abide] unsupported host platform ${platform}/${arch}. Pass --target=<bun-...> explicitly.`,
-        )
-    }
-    return target
-}

package/src/lib/shared/docSnapshotsSlot.ts

@@ -1,13 +0,0 @@
-import { createResolverSlot } from './createResolverSlot.ts'
-import type { DocSnapshots } from './types/DocSnapshots.ts'
-
-/*
-The active doc-snapshot slot — mirrors `resolvedCellsSlot`. The server entry installs an ALS-backed
-resolver (a fresh list per request, so concurrent SSR renders never mix their doc seeds); with no
-resolver registered a single fallback list is created lazily so isolated tests work without booting
-the runtime. `createScope` pushes a `{ id, take }` for each rendered scope server-side; the page
-renderer reads it at render-return to stamp `__SSR__.docs`.
-*/
-export const docSnapshotsSlot = createResolverSlot<DocSnapshots>(() => ({
-    entries: [],
-}))

package/src/lib/shared/done.ts

@@ -1,20 +0,0 @@
-import { tailProbeSlot } from './tailProbeSlot.ts'
-import type { NamedAsyncIterable } from './types/NamedAsyncIterable.ts'
-
-/*
-Reactive terminal-state reader for a stream: true once the source has closed (its
-tail entry status === 'done'). Stream-only — a cache entry's "done" is just
-`!pending && !refreshing`, so there is no cache-selector form. The residual bit the
-`pending` / `refreshing` / `error` probes don't cover (see design Part 4). No prober
-registered (server render, or tail never imported) reads as not-done.
-*/
-// @documentation probes
-export function done(subscribable: NamedAsyncIterable<unknown>): boolean {
-    /* Null-tolerant: a promise/iterable subexpression peek-lifts to `undefined` while
-       pending (ADR-0032), so `done(getFeed())` in a template hands us `undefined` on the
-       first pass — treat a missing source as not-done rather than throwing. */
-    if (subscribable == null) {
-        return false
-    }
-    return tailProbeSlot.probe?.(subscribable.name)?.done ?? false
-}