experimental-a2 0.4.0 → 0.5.0

package/src/store-polling.ts

@@ -0,0 +1,102 @@
+/**
+ * The shared polling stream — how poll-based backends (sqlite,
+ * postgres) implement `A2Store.stream`.
+ *
+ * The cadence is activity-adaptive: while events are flowing, polls
+ * run at a tight floor (25ms) so streams feel pushed — a token
+ * generation reads smoothly instead of clumping at the idle interval;
+ * every empty poll doubles the gap until the idle ceiling. The cadence
+ * is owned (POLL_TIMINGS in internal.ts), not a public option: the
+ * floor already keeps active streams smooth, so tuning it is a cost
+ * decision a2 makes, not one it delegates. Correctness never depends
+ * on the cadence — each poll is a catch-up read (`index > last`, in
+ * order), so nothing can be missed, only arrive a beat later.
+ */
+
+import { POLL_TIMINGS } from './internal.ts'
+import type { StoredEvent } from './store.ts'
+
+/** One cancellable sleep — the injection seam for cadence tests. */
+export type Sleeper = { promise: Promise<void>; cancel: () => void }
+
+/** Unref'd cancellable timer — shared with the redis safety read. */
+export const defaultSleep = (ms: number): Sleeper => {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let wake: (() => void) | undefined
+  const promise = new Promise<void>((resolve) => {
+    wake = resolve // assigned synchronously by the executor
+    timer = setTimeout(resolve, ms)
+    // Don't hold the process open for an idle poll.
+    ;(timer as { unref?: () => void }).unref?.()
+  })
+  return {
+    promise,
+    cancel: () => {
+      clearTimeout(timer)
+      wake?.()
+    },
+  }
+}
+
+// Read the seam lazily — tests shrink POLL_TIMINGS in their setup.
+const ceiling = (): number => POLL_TIMINGS.idleCeilingMs
+const floor = (): number =>
+  Math.min(POLL_TIMINGS.activeFloorMs, POLL_TIMINGS.idleCeilingMs)
+
+export type PollingStreamOptions = {
+  /** Deliver events strictly after this index (exclusive). */
+  startAfter?: number
+  /** Injectable sleep — tests assert the cadence without wall-clock waits. */
+  sleep?: (ms: number) => Sleeper
+}
+
+/**
+ * Build the `stream()` iterable from a backend's catch-up read. The
+ * iterable ends when the consumer calls `return()` (a disconnecting
+ * SSE client), waking any pending sleep immediately.
+ */
+export function pollingStream(
+  readAfter: (afterIndex: number) => StoredEvent[] | Promise<StoredEvent[]>,
+  options: PollingStreamOptions,
+): AsyncIterable<StoredEvent> {
+  const startAfter = options.startAfter ?? 0
+  const sleep = options.sleep ?? defaultSleep
+
+  return {
+    [Symbol.asyncIterator](): AsyncIterator<StoredEvent> {
+      let last = startAfter
+      let buffer: StoredEvent[] = []
+      let closed = false
+      let pending: Sleeper | null = null
+      let interval = floor()
+
+      return {
+        async next(): Promise<IteratorResult<StoredEvent>> {
+          for (;;) {
+            if (closed) return { value: undefined, done: true }
+            // oxlint-disable-next-line no-await-in-loop -- poll loop
+            if (buffer.length === 0) buffer = await readAfter(last)
+            const row = buffer.shift()
+            if (row) {
+              // Activity: tighten back to the floor.
+              interval = floor()
+              last = row.index
+              return { value: row, done: false }
+            }
+            // Empty poll: wait, then back off toward the idle ceiling.
+            pending = sleep(interval)
+            // oxlint-disable-next-line no-await-in-loop -- poll loop
+            await pending.promise
+            pending = null
+            interval = Math.min(interval * 2, ceiling())
+          }
+        },
+        async return(): Promise<IteratorResult<StoredEvent>> {
+          closed = true
+          pending?.cancel()
+          return { value: undefined, done: true }
+        },
+      }
+    },
+  }
+}