@abide/abide 0.46.0 → 0.48.0

package/src/lib/server/sockets/defineSocket.ts

@@ -1,13 +1,14 @@
+import { attachSocketSelectorMethods } from '../../shared/attachSocketSelectorMethods.ts'
 import { createPushIterator } from '../../shared/createPushIterator.ts'
 import { encodeRefJson } from '../../shared/encodeRefJson.ts'
 import { resolveClientFlags } from '../../shared/resolveClientFlags.ts'
 import { socketTapSlot } from '../../shared/socketTapSlot.ts'
+import type { Socket } from '../../shared/types/Socket.ts'
+import type { SocketServerFrame } from '../../shared/types/SocketServerFrame.ts'
 import type { TailHooks } from '../../shared/types/TailHooks.ts'
 import { getActiveServer } from '../runtime/getActiveServer.ts'
 import { registerSocket } from './registerSocket.ts'
-import type { Socket } from './types/Socket.ts'
 import type { SocketOptions } from './types/SocketOptions.ts'
-import type { SocketServerFrame } from './types/SocketServerFrame.ts'
 
 /*
 Server-side construction of a Socket. The bundler rewrites every
@@ -23,14 +24,18 @@ is the live stream — no replay. `chat.tail(count)` opens a subscription
 seeded with the last `count` retained frames (no-arg = the whole
 retained tail, clamped to the declared `tail` size). When `ttl` is set,
 retained frames older than `ttl` ms are evicted lazily on every
-read/append — no timer runs in the background. `chat.publish(m)` is isomorphic —
+read/append — no timer runs in the background. `chat.broadcast(m)` is isomorphic —
 called server-side it both notifies in-process iterators and broadcasts
 to remote subscribers; called client-side (via socketProxy) it sends a
 `pub` frame the dispatcher validates and forwards.
 */
 // @documentation plumbing
 export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<T> {
-    const retention = opts.tail ?? 0
+    /* Retention defaults to 1: the socket keeps its last frame so a late joiner, a
+       reconnect, and `.peek()` all have the current value to seed from. Bare iteration
+       still replays nothing (iterate(0) below) — a real-time `watch(socket, …)` reaction
+       must see only live frames, never re-process the retained one. `tail: 0` opts out. */
+    const retention = opts.tail ?? 1
     const ttl = opts.ttl
     const schema = opts.schema
     /*
@@ -150,8 +155,10 @@ export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<
                     }
                 })
                 pruneExpired(Date.now())
+                /* Floor: a fractional count (`?tail=1.5` over REST) must not
+                   produce a fractional buffer index. */
                 const replayCount =
-                    replay === 'all' ? buffer.length : Math.min(replay, buffer.length)
+                    replay === 'all' ? buffer.length : Math.min(Math.floor(replay), buffer.length)
                 if (replayCount > 0) {
                     const start = buffer.length - replayCount
                     for (let index = start; index < buffer.length; index++) {
@@ -168,13 +175,25 @@ export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<
         }
     }
 
-    const self: Socket<T> = {
+    const self = {
         name,
         clients,
-        publish,
+        /* `broadcast` is the public fan-out; `publish` remains the internal function name. */
+        broadcast: publish,
         tail: (count?: number, hooks?: TailHooks) => iterate(count ?? 'all', hooks),
+        /* The latest retained frame (after ttl pruning), or undefined when none is held. */
+        peek: () => {
+            pruneExpired(Date.now())
+            return buffer.length > 0 ? (buffer[buffer.length - 1] as BufferEntry).value : undefined
+        },
+        /* No-op on the server: it is the source of truth, so there is nothing to re-pull. */
+        refresh: () => undefined,
+        /* Inert on the server: reaction is a client-only concern, and an author `socket.watch(…)`
+           that survives the SSR effect-strip must be a safe no-op here. Returns a disposer. */
+        watch: () => () => {},
         [Symbol.asyncIterator]: () => iterate(0)[Symbol.asyncIterator](),
     }
+    attachSocketSelectorMethods(self)
     registerSocket({
         socket: self as Socket<unknown>,
         allowClientPublish: opts.clientPublish ?? false,

package/src/lib/server/sockets/types/SocketRegistryEntry.ts

@@ -1,6 +1,6 @@
 import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
+import type { Socket } from '../../../shared/types/Socket.ts'
 import type { StandardSchemaV1 } from '../../../shared/types/StandardSchemaV1.ts'
-import type { Socket } from './Socket.ts'
 
 /*
 Per-socket registry record. The Socket itself stays uniform between

package/src/lib/server/sockets/types/SocketRoutes.ts

@@ -1,4 +1,4 @@
-import type { Socket } from './Socket.ts'
+import type { Socket } from '../../../shared/types/Socket.ts'
 
 /*
 Manifest of socket-name → module loader. Produced by the resolver

package/src/lib/server/sse.ts

@@ -35,7 +35,7 @@ const KEEPALIVE_INTERVAL_MS = 15000
 export function sse<Frame>(
     iterable: AsyncIterable<Frame>,
     init?: ResponseInit,
-): TypedResponse<Frame> {
+): TypedResponse<AsyncIterable<Frame>> {
     const body = streamFromIterator(iterable, {
         encodeFrame: (value) => `data: ${JSON.stringify(value)}\n\n`,
         encodeError: (message) => sseErrorFrame.encode(message),
@@ -50,5 +50,5 @@ export function sse<Frame>(
             'X-Content-Type-Options': 'nosniff',
             Connection: 'keep-alive',
         }),
-    ) as TypedResponse<Frame>
+    ) as TypedResponse<AsyncIterable<Frame>>
 }

package/src/lib/shared/DEFER.ts

@@ -0,0 +1,8 @@
+/*
+The sentinel `bodyValueForKind` returns for the `streaming` and `binary` body kinds —
+those whose handling is side-specific (the live read throws on streaming and blobs on
+binary; the warm read has no synchronous equivalent), so the caller branches on it
+rather than receiving a directly-usable value. A `unique symbol` so a body value can
+never collide with it.
+*/
+export const DEFER: unique symbol = Symbol('defer')

package/src/lib/shared/activeCacheStore.ts

@@ -1,4 +1,4 @@
-import { cacheStoreResolver } from './cacheStoreResolver.ts'
+import { cacheStoreSlot } from './cacheStoreSlot.ts'
 import type { CacheStore } from './types/CacheStore.ts'
 
 /*
@@ -7,5 +7,5 @@ lazily-created fallback when none is registered (so isolated tests work). The
 fallback creator guarantees a value, hence the non-null assertion.
 */
 export function activeCacheStore(): CacheStore {
-    return cacheStoreResolver.get()!
+    return cacheStoreSlot.get()!
 }

package/src/lib/shared/activePage.ts

@@ -1,4 +1,4 @@
-import { pageResolver } from './pageResolver.ts'
+import { pageSlot } from './pageSlot.ts'
 import type { PageSnapshot } from './types/PageSnapshot.ts'
 
 /*
@@ -7,5 +7,5 @@ single lazily-created empty snapshot when none is registered (so isolated tests
 work). The fallback creator guarantees a value, hence the non-null assertion.
 */
 export function activePage(): PageSnapshot {
-    return pageResolver.get()!
+    return pageSlot.get()!
 }

package/src/lib/shared/attachRpcSelectorMethods.ts

@@ -0,0 +1,42 @@
+import { keyForRemoteCall } from './keyForRemoteCall.ts'
+import { keyPrefixForRemote } from './keyPrefixForRemote.ts'
+import { patch } from './patch.ts'
+import { peek } from './peek.ts'
+import { pending } from './pending.ts'
+import { refresh } from './refresh.ts'
+import { refreshing } from './refreshing.ts'
+import { rpcErrorRegistry } from './rpcErrorRegistry.ts'
+import type { RemoteFunction } from './types/RemoteFunction.ts'
+
+/*
+Attaches the pre-bound selector sugar onto an assembled RemoteFunction:
+`fn.pending(args?)` ≡ `pending(fn, args?)`, likewise refreshing / refresh / peek,
+`fn.patch(args?, updater)` ≡ `patch(fn, args, updater)`, and `fn.error(args?)` — the typed
+last error from the rpc error registry (most-recent across the rpc when args omitted, that
+exact call when given). The cached read is the bare call `fn(args, opts)` itself; refetch is
+`fn.refresh(args?)`. The methods only reference the globals at call time, so the shared import
+edge carries no module-init dependency (safe against any cache ↔ createRemoteFunction cycle).
+Attached in createRemoteFunction so the server (defineRpc) and client (remoteProxy) shapes are
+identical. `patch` is attached uniformly; the type omits it for a streaming rpc (harmless at
+runtime — a stream has no cache entry).
+*/
+export function attachRpcSelectorMethods<Args, Return>(fn: RemoteFunction<Args, Return>): void {
+    Object.assign(fn, {
+        pending: (args?: Args) => pending(fn, args),
+        refreshing: (args?: Args) => refreshing(fn, args),
+        refresh: (args?: Args) => refresh(fn, args),
+        peek: (args?: Args) => peek(fn, args),
+        patch: (argsOrUpdater?: unknown, updater?: unknown) =>
+            (patch as (fn: unknown, a?: unknown, b?: unknown) => void)(fn, argsOrUpdater, updater),
+        /* Reaction sugar is client-only (`watch` is a ui primitive that must not ride into a
+           server bundle), so the shared attach binds an inert no-op — the server (defineRpc)
+           shape carries `.watch` too, and an author `fn.watch(…)` surviving the SSR effect-strip
+           is a safe no-op. The client proxy (remoteProxy) overwrites this with the real
+           `watch(fn, …)`. */
+        watch: () => () => {},
+        error: (args?: Args) =>
+            args === undefined
+                ? rpcErrorRegistry.readAny(keyPrefixForRemote(fn.method, fn.url))
+                : rpcErrorRegistry.read(keyForRemoteCall(fn.method, fn.url, args)),
+    })
+}

package/src/lib/shared/attachSocketSelectorMethods.ts

@@ -0,0 +1,34 @@
+import { done } from './done.ts'
+import { pending } from './pending.ts'
+import { refreshing } from './refreshing.ts'
+import { tailProbeSlot } from './tailProbeSlot.ts'
+import type { Socket } from './types/Socket.ts'
+
+/* The socket surface before the probe sugar is attached — every Socket member except the
+   pre-bound probes this module adds. Both construction sites (defineSocket / buildSocketOverChannel)
+   build this shape, then the assertion below narrows it to a full Socket. */
+type SocketWithoutProbes<T> = Omit<Socket<T>, 'pending' | 'refreshing' | 'done' | 'error'>
+
+/*
+Attaches the pre-bound probe sugar onto an assembled Socket, mirroring
+attachRpcSelectorMethods for the rpc side: `socket.pending()` ≡ `pending(socket)`,
+likewise refreshing / done, and `socket.error()` reads the stream's terminal error (the
+tail prober's `error` field — instance-only, no bare global, same as the rpc's `.error`).
+The socket is the pre-bound stream selector. The methods reference the globals at call
+time, so the shared import edge carries no module-init dependency. Called by both
+buildSocketOverChannel (consumer / test) and defineSocket (server) so the two Socket
+shapes stay identical; on the server the tail prober is unregistered, so the probes read
+the same fallbacks the globals give there (pending true until a frame, refreshing/done
+false, error undefined). An assertion return narrows the base object to a full Socket at
+each call site, so neither construction literal needs a cast.
+*/
+export function attachSocketSelectorMethods<T>(
+    socket: SocketWithoutProbes<T>,
+): asserts socket is Socket<T> {
+    Object.assign(socket, {
+        pending: () => pending(socket),
+        refreshing: () => refreshing(socket),
+        done: () => done(socket),
+        error: () => tailProbeSlot.probe?.(socket.name)?.error,
+    })
+}

package/src/lib/shared/basePath.ts

@@ -1,4 +1,4 @@
-import { baseResolver } from './baseResolver.ts'
+import { baseSlot } from './baseSlot.ts'
 
 /*
 The current mount base path ('' at root). Resolved per side: the server installs
@@ -7,5 +7,5 @@ url() reads this to prefix rooted internal paths. Defaults to '' when no resolve
 or fallback is set.
 */
 export function basePath(): string {
-    return baseResolver.get() ?? ''
+    return baseSlot.get() ?? ''
 }

package/src/lib/shared/baseSlot.ts

@@ -1,8 +1,9 @@
-import { baseResolver } from './baseResolver.ts'
+import { createResolverSlot } from './createResolverSlot.ts'
 
 /*
-Internal slot the runtime entries register their mount-base resolver into (see
-baseResolver). Exposed so test helpers snapshot/poke `.resolver` and `.fallback`
-directly.
+The mount-base slot. The server entry installs an APP_URL-derived resolver at
+boot; the client entry one reading window.__SSR__.base. No lazy fallback
+creator — `.fallback` is a plain string set directly by isolated tests, and
+basePath() (the public read) supplies the '' default.
 */
-export const baseSlot = baseResolver.slot
+export const baseSlot = createResolverSlot<string>()

package/src/lib/shared/bodyValueForKind.ts

@@ -1,4 +1,5 @@
 import type { ContentBodyKind } from './contentBodyKind.ts'
+import { DEFER } from './DEFER.ts'
 
 /*
 The single body-kind → value mapping shared by the live read (decodeResponse) and
@@ -18,8 +19,6 @@ Returns the DEFER sentinel for `streaming` and `binary`: kinds whose handling is
 side-specific (the live read throws on streaming and blobs on binary; the warm
 read has no synchronous equivalent for either), so the caller branches on it.
 */
-export const DEFER: unique symbol = Symbol('defer')
-
 export function bodyValueForKind<Value>(
     kind: ContentBodyKind,
     json: () => Value,

package/src/lib/shared/buildSocketOverChannel.ts

@@ -1,8 +1,11 @@
-import type { Socket } from '../server/sockets/types/Socket.ts'
+import { attachSocketSelectorMethods } from './attachSocketSelectorMethods.ts'
 import { browserClientFlags } from './browserClientFlags.ts'
 import { createPushIterator } from './createPushIterator.ts'
+import { SOCKETS_PATH } from './SOCKETS_PATH.ts'
+import type { Socket } from './types/Socket.ts'
 import type { SocketChannel } from './types/SocketChannel.ts'
 import type { TailHooks } from './types/TailHooks.ts'
+import { withBase } from './withBase.ts'
 
 /* Per-channel-agnostic sub id counter; uniqueness within a channel is all the
    lifecycle routing needs, so one monotonic source across every socket is fine. */
@@ -24,6 +27,10 @@ export function buildSocketOverChannel<T>(
     name: string,
     resolveChannel: () => SocketChannel,
 ): Socket<T> {
+    /* The latest frame seen across every iterator of this socket — what peek() returns and
+       what refresh() re-seeds from the server tail. A plain slot (not reactive): peek(socket)
+       is a synchronous snapshot; live reactivity is the for-await / watch(socket) path. */
+    let lastFrame: T | undefined
     function iterate(replay: number | undefined, hooks?: TailHooks): AsyncIterable<T> {
         return {
             [Symbol.asyncIterator](): AsyncIterator<T, void, undefined> {
@@ -31,9 +38,13 @@ export function buildSocketOverChannel<T>(
                 const channel = resolveChannel()
                 const iterator = createPushIterator<T>(() => channel.unsubscribe(id))
                 channel.subscribe(id, name, replay, {
-                    onMessage: (value) => iterator.push(value as T),
+                    onMessage: (value) => {
+                        lastFrame = value as T
+                        iterator.push(value as T)
+                    },
                     onReplay: (messages) => {
                         for (const value of messages) {
+                            lastFrame = value as T
                             iterator.push(value as T)
                         }
                         if (hooks?.replayed) {
@@ -48,11 +59,36 @@ export function buildSocketOverChannel<T>(
             },
         }
     }
-    return {
+    const publish = (message: T) => resolveChannel().publish(name, message)
+    const socket = {
         name,
         clients: browserClientFlags,
-        publish: (message: T) => resolveChannel().publish(name, message),
+        /* `broadcast` sends a server-validated `pub` frame (the dispatcher gates it on the
+           topic's `clientPublish`); `publish` is the internal channel-send function name. */
+        broadcast: publish,
         tail: (count?: number, hooks?: TailHooks) => iterate(count, hooks),
+        /* The latest frame this client has seen, synchronously. */
+        peek: () => lastFrame,
+        /* Re-pull the server's retained tail over the HTTP face (GET /__abide/sockets/<name>
+           → JSON array of retained frames) and reset the local latest — a reconnect / ttl
+           resync. Fire-and-forget: the fetch runs in the background and updates what peek()
+           returns. A failed pull leaves the current value untouched. */
+        refresh: () => {
+            void fetch(withBase(`${SOCKETS_PATH}/${name}`))
+                .then((response) => (response.ok ? response.json() : undefined))
+                .then((frames) => {
+                    if (Array.isArray(frames) && frames.length > 0) {
+                        lastFrame = frames[frames.length - 1] as T
+                    }
+                })
+                .catch(() => undefined)
+        },
+        /* Inert default so the returned object satisfies Socket<T> without importing the ui-only
+           `watch` into this shared builder (which the test harness also uses). The client proxy
+           (socketProxy) overwrites it with the real `watch(socket, …)`. */
+        watch: () => () => {},
         [Symbol.asyncIterator]: () => iterate(0)[Symbol.asyncIterator](),
     }
+    attachSocketSelectorMethods(socket)
+    return socket
 }