@cplieger/sse 1.5.0-dev.8 → 2.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 > A Server-Sent-Events client that resumes exactly where it stopped, notices a dead stream, and reconciles after a sleep.
 
-The TypeScript half of [github.com/cplieger/go/sse](https://github.com/cplieger/go/tree/main/sse), speaking the wire the Go `sse` package serves: every frame carries an `epoch:offset` cursor, every connection opens with a hello that says whether that cursor was honoured, and the client turns both into a projection an application can trust across a page hide, a phone lock or a network change. A native `EventSource` cannot set a request header, cannot tell a silent stream from an idle one, and reconnects on its own schedule with whatever `Last-Event-ID` it last saw; this client owns the connection over `fetch` and `ReadableStream` instead, presents the cursor it holds, measures liveness on bytes, closes a hidden tab's stream after a minute and reopens it on return, backs off with full jitter, and holds incoming frames while the application asks the server what changed. It has no runtime dependencies, and the DOM readers (`document.visibilityState`, `navigator.onLine`) are injectable, so the same runtime runs in Node against the Go test fixture.
+The TypeScript half of [github.com/cplieger/go/sse/v2](https://github.com/cplieger/go/tree/main/sse), speaking the wire the Go `sse` package serves: every frame carries an `epoch:offset` cursor, every connection opens with a hello that says whether that cursor was honoured, and the client turns both into a projection an application can trust across a page hide, a phone lock or a network change. A native `EventSource` cannot set a request header, cannot tell a silent stream from an idle one, and reconnects on its own schedule with whatever `Last-Event-ID` it last saw; this client owns the connection over `fetch` and `ReadableStream` instead, presents the cursor it holds, measures liveness on bytes, closes a hidden tab's stream after a minute and reopens it on return, backs off with full jitter, and holds incoming frames while the application asks the server what changed. It has no runtime dependencies, and the DOM readers (`document.visibilityState`, `navigator.onLine`) are injectable, so the same runtime runs in Node against the Go test fixture.
 
 ## Install
 
@@ -44,6 +44,8 @@ The first frame of every connection is a hello: it names the server epoch, the r
 
 The client keeps its cursor as `epoch:offset`, presents it as `Last-Event-ID` on every connect, and advances it only as frames are delivered to `onFrame`, so a reconnect after a gap either replays exactly the missed frames or reports through the hello that the gap could not be covered, and the application reconciles instead of trusting the replay.
 
+`stream.state()` returns a `StreamState`: the connection kind (`stopped`, `connecting`, `open`, `backoff`, `offline` or `hidden_closed`), its generation and attempt, and the readings that kind acts on, such as `visible`, `online`, the hello's `keepaliveMs` and when a backoff ends. The package exports the factories, the wire helpers and the types they take and return; its parser, reducer and tab fold are internal.
+
 While `revalidate` runs, incoming frames are held and delivered in order once it settles; runs are single-flight, a second cause queues at most one more run, and a held queue past 2000 frames or 64 MiB ends the connection so the next connect resumes from the cursor instead.
 
 With `alive` set, every keepalive (or every `everyBeats`-th) is acknowledged with a `POST` to that URL carrying the stream's headers, so a server-side presence table keyed on `SSE-Client` sees which clients are still reading; a failed acknowledgement is reported as an `alive_ack` record.
@@ -54,7 +56,7 @@ A 401 ends the session's stream instead of retrying it: a 401 on the stream requ
 
 The host presents the first non-empty tag a tab attaches with and replaces it, reconnecting once, when a later attach or `setTag` carries a different one; the empty tag is ignored.
 
-The host's `revalidate(ctx, tabs)` body performs one digest for the profile and fans the verdict to every tab through `tabs.run(ctx, { changed, removed })`, so each tab's `revalidate` receives a `TabRevalidateContext` carrying `changed` and `removed` beside its own `signal`. A `state` message reaches a tab before the `lifecycle` record of the same transition, so `attachment.state()` is current inside the handler, and a tab attaching to a live stream receives `state` and then a `tab_attached` record naming that state.
+The host's `revalidate(ctx, tabs)` body performs one digest for the profile and fans the verdict to every tab through `tabs.run(ctx, { changed, removed })`, so each tab's `revalidate` receives a `TabRevalidateContext` carrying `changed` and `removed` beside its own `signal`. A `state` message reaches a tab before the `lifecycle` record of the same transition, so `attachment.state()`, a `StreamState`, is current inside the handler, and a tab attaching to a live stream receives `state` and then a `tab_attached` record naming that state.
 
 The package typechecks under `lib: ["ESNext", "WebWorker"]` as well as under the DOM lib (`tsconfig.worker.json` is the check), so a consumer's worker entry can import `createWorkerHost` from a worker-only program: the DOM visibility and online sources read `document` and `window` through `globalThis` and are inert where they are absent.
 

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/sse",
-  "version": "1.5.0-dev.8",
+  "version": "2.0.0",
   "license": "Apache-2.0",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/sse",
-  "version": "1.5.0-dev.8",
+  "version": "2.0.0",
   "description": "Server-Sent Events hub and client that resume from an exact cursor and reconcile after sleep",
   "license": "Apache-2.0",
   "type": "module",

package/src/digest.ts

@@ -3,7 +3,7 @@ import type { Held, Subject } from "./versions.js";
 import { compareOffset } from "./wire.js";
 
 /** A subject the server reports at a version other than the presented one: a fetch instruction. */
-export type State = Held;
+export type Changed = Held;
 
 /** A subject the server no longer answers for. */
 export interface Removed extends Subject {
@@ -19,7 +19,7 @@ export interface Removed extends Subject {
  */
 export type DigestResult =
   | { kind: "must_refetch"; epoch: string; head: string }
-  | { kind: "ok"; epoch: string; head: string; changed: State[]; removed: Removed[] };
+  | { kind: "ok"; epoch: string; head: string; changed: Changed[]; removed: Removed[] };
 
 /**
  * What one check asks about: the epoch the held versions were minted under, and the versions
@@ -100,7 +100,7 @@ interface Position {
 
 type BatchAnswer =
   | { kind: "must_refetch"; position: Position }
-  | { kind: "ok"; position: Position; changed: State[]; removed: Removed[] };
+  | { kind: "ok"; position: Position; changed: Changed[]; removed: Removed[] };
 
 /** Reads the position; null when the body is not even a positioned digest answer. */
 function readPosition(body: unknown): Position | null {
@@ -134,7 +134,7 @@ function readAnswer(
   }
   const requested = new Set(batch.map(subjectKey));
   const seen = new Set<string>();
-  const changed: State[] = [];
+  const changed: Changed[] = [];
   const removed: Removed[] = [];
   for (const entry of changedRaw as unknown[]) {
     if (!isRecord(entry)) {
@@ -259,7 +259,7 @@ export function createDigestClient(opts: DigestClientOptions): DigestClient {
         batches.push(snapshot.held.slice(i, i + maxSubjects));
       }
       const [first = [], ...rest] = batches;
-      const changed: State[] = [];
+      const changed: Changed[] = [];
       const removed: Removed[] = [];
       let answer = await post(snapshot.epoch, first, signal);
       for (let i = 0; ; i++) {

package/src/fold.ts

@@ -7,7 +7,7 @@ import type { VisibilityEvent, VisibilityInput, VisibilitySource } from "./visib
  * it leaves; the profile's network reading is not recomputed on a departure and keeps the last value
  * reported, by whichever tab.
  */
-export interface TabState {
+interface TabState {
   readonly visible: boolean;
   readonly online: boolean;
   /** A freshly attached tab may earn one pageshow; cleared by its first. */

package/src/index.ts

@@ -23,19 +23,9 @@ export {
   validateHello,
 } from "./wire.js";
 export type { Cursor, Hello, HelloRefusal, HelloResult, ResetReason } from "./wire.js";
-export { createParser } from "./parser.js";
-export type { ParsedEvent, Parser, ParserHandlers, ParserOptions } from "./parser.js";
-export { initialState, jitter, reduce } from "./reducer.js";
-export type {
-  ClientEvent,
-  ClientState,
-  ConnectFailure,
-  Effect,
-  Reduction,
-  StreamEnd,
-  Timer,
-} from "./reducer.js";
+export type { ConnectFailure, StreamEnd } from "./reducer.js";
 export type { HeldDiscardCause, LifecycleEvent, RevalidateCause } from "./lifecycle.js";
+export type { StreamState, StreamStateKind } from "./state.js";
 export {
   adaptVisibility,
   createDOMVisibilitySource,
@@ -50,40 +40,25 @@ export type {
 export { createDOMOnlineSource, createOnlineManager } from "./online.js";
 export type { OnlineManager, OnlineSource } from "./online.js";
 export { bindListener, createVersionMap, staleListener } from "./versions.js";
-export type { Held, Subject, VersionMap, VersionMapOptions } from "./versions.js";
+export type {
+  BindListener,
+  Held,
+  StaleListener,
+  Subject,
+  VersionMap,
+  VersionMapOptions,
+} from "./versions.js";
 export { DigestStatusError, createDigestClient } from "./digest.js";
 export type {
+  Changed,
   DigestClient,
   DigestClientOptions,
   DigestResult,
   DigestSnapshot,
   Removed,
-  State,
 } from "./digest.js";
 export { createStream } from "./stream.js";
 export type { Frame, RevalidateContext, Stream, StreamOptions } from "./stream.js";
-export type {
-  Connection,
-  ConnectOptions,
-  TransportCallbacks,
-  TransportFrame,
-} from "./transport.js";
-export {
-  anyVisible,
-  createFoldState,
-  createProfileOnlineSource,
-  createProfileVisibilitySource,
-  foldTabs,
-} from "./fold.js";
-export type {
-  FoldInput,
-  FoldOutput,
-  FoldState,
-  ProfileOnlineSource,
-  ProfileVisibilitySource,
-  TabState,
-} from "./fold.js";
-export { isTabMessage, isWorkerMessage } from "./port-protocol.js";
 export type {
   DetachCause,
   PortRevalidateContext,

package/src/lifecycle.ts

@@ -1,4 +1,5 @@
-import type { ClientState, ConnectFailure } from "./reducer.js";
+import type { ConnectFailure } from "./reducer.js";
+import type { StreamStateKind } from "./state.js";
 import type { Subject } from "./versions.js";
 import type { ResetReason } from "./wire.js";
 
@@ -22,7 +23,7 @@ export type HeldDiscardCause =
 
 /** Every record the observability feed (`onLifecycle`) can carry. Nothing branches on one. */
 export type LifecycleEvent =
-  | { kind: "state"; from: ClientState["kind"]; to: ClientState["kind"]; generation: number }
+  | { kind: "state"; from: StreamStateKind; to: StreamStateKind; generation: number }
   | {
       kind: "hello";
       verdict: string;
@@ -55,7 +56,7 @@ export type LifecycleEvent =
   | { kind: "worker_unavailable"; cause: "silent" | "error" }
   | { kind: "worker_recovered" }
   | { kind: "auth_lost"; route: "stream" | "alive" | "digest"; status: 401 }
-  | { kind: "tab_attached"; replaced: boolean; state: ClientState["kind"] }
+  | { kind: "tab_attached"; replaced: boolean; state: StreamStateKind }
   | { kind: "tab_detached"; cause: string }
   | { kind: "port_expired"; sinceLastAckMs: number }
   | { kind: "port_repaired" };

package/src/port-protocol.ts

@@ -1,6 +1,6 @@
-import type { Removed, State } from "./digest.js";
+import type { Changed, Removed } from "./digest.js";
 import type { LifecycleEvent, RevalidateCause } from "./lifecycle.js";
-import type { ClientState } from "./reducer.js";
+import type { StreamState } from "./state.js";
 import type { Frame } from "./stream.js";
 import type { Subject } from "./versions.js";
 import type { VisibilityInput } from "./visibility.js";
@@ -21,7 +21,7 @@ export interface PortRevalidateContext {
   readonly generation: number;
   readonly full: boolean;
   /** The host's digest verdict for this run, when its `revalidate` body performed one. */
-  readonly changed?: readonly State[];
+  readonly changed?: readonly Changed[];
   readonly removed?: readonly Removed[];
 }
 
@@ -80,7 +80,7 @@ export type WorkerToTab =
   | { readonly type: "pong"; readonly seq: number }
   | { readonly type: "revalidate_run"; readonly runId: number; readonly ctx: PortRevalidateContext }
   | { readonly type: "stale" }
-  | { readonly type: "state"; readonly state: ClientState };
+  | { readonly type: "state"; readonly state: StreamState };
 
 const TAB_TYPES: ReadonlySet<string> = new Set<TabToWorker["type"]>([
   "attach",

package/src/reducer.ts

@@ -157,7 +157,7 @@ export function initialState(): ClientState {
 }
 
 /** Full-jitter backoff delay for `attempt`; `rand` is drawn in [0, 1) by the runtime. */
-export function jitter(attempt: number, rand: number, cfg: TimingConfig): number {
+function jitter(attempt: number, rand: number, cfg: TimingConfig): number {
   return rand * Math.min(cfg.capMs, cfg.baseMs * 2 ** attempt);
 }
 

package/src/state.ts

@@ -0,0 +1,89 @@
+import type { ClientState } from "./reducer.js";
+
+/**
+ * A stream's connection state as an application reads it: the kind, the
+ * generation, and the readings each kind acts on, including when a backoff
+ * ends. It leaves out the timers the stream keeps for itself (when it opened,
+ * its last byte, when it went hidden), so those can change without a breaking
+ * release.
+ */
+export type StreamState =
+  | { readonly kind: "stopped"; readonly generation: number }
+  | {
+      readonly kind: "connecting";
+      readonly generation: number;
+      readonly attempt: number;
+      readonly visible: boolean;
+      readonly online: boolean;
+    }
+  | {
+      readonly kind: "open";
+      readonly generation: number;
+      readonly attempt: number;
+      /** The hello's keepalive_ms. */
+      readonly keepaliveMs: number;
+      readonly visible: boolean;
+      readonly online: boolean;
+    }
+  | {
+      readonly kind: "backoff";
+      readonly generation: number;
+      readonly attempt: number;
+      /** When the next attempt starts, in milliseconds on the stream's clock. */
+      readonly until: number;
+      readonly visible: boolean;
+      readonly online: boolean;
+    }
+  | {
+      readonly kind: "offline";
+      readonly generation: number;
+      readonly attempt: number;
+      readonly visible: boolean;
+    }
+  | {
+      readonly kind: "hidden_closed";
+      readonly generation: number;
+      readonly attempt: number;
+      readonly online: boolean;
+    };
+
+/** The kinds a {@link StreamState} can take, as lifecycle `state` records name them. */
+export type StreamStateKind = StreamState["kind"];
+
+/** The application's view of the reducer's state: the same kind with its timers left out. */
+export function toStreamState(s: ClientState): StreamState {
+  switch (s.kind) {
+    case "stopped":
+      return { kind: s.kind, generation: s.generation };
+    case "connecting":
+      return {
+        kind: s.kind,
+        generation: s.generation,
+        attempt: s.attempt,
+        visible: s.visible,
+        online: s.online,
+      };
+    case "backoff":
+      return {
+        kind: s.kind,
+        generation: s.generation,
+        attempt: s.attempt,
+        until: s.until,
+        visible: s.visible,
+        online: s.online,
+      };
+    case "open":
+      return {
+        kind: s.kind,
+        generation: s.generation,
+        attempt: s.attempt,
+        keepaliveMs: s.keepaliveMs,
+        visible: s.visible,
+        online: s.online,
+      };
+    case "offline":
+      return { kind: s.kind, generation: s.generation, attempt: s.attempt, visible: s.visible };
+    case "hidden_closed":
+      return { kind: s.kind, generation: s.generation, attempt: s.attempt, online: s.online };
+  }
+}

package/src/stream.ts

@@ -9,6 +9,7 @@ import {
   initialState,
   reduce,
 } from "./reducer.js";
+import { type StreamState, toStreamState } from "./state.js";
 import { DEFAULT_RETRY_MS, type TimingConfig, WIRE, resolveTiming } from "./timing.js";
 import { type Connection, type TransportFrame, connect } from "./transport.js";
 import { type VersionMap, bindListener, staleListener } from "./versions.js";
@@ -93,7 +94,8 @@ export interface Stream {
   stop(): void;
   /** Aborts the attempt and connects again in place; ignored in hidden_closed, offline and stopped. */
   reconnect(): void;
-  state(): ClientState;
+  /** The connection state, without the timers the stream keeps for itself. */
+  state(): StreamState;
   cursor(): Cursor | null;
   /** Drops the cursor; the next connect presents none and earns a fresh hello. */
   resetCursor(): void;
@@ -769,7 +771,7 @@ export function createStream(opts: StreamOptions): Stream {
     reconnect() {
       dispatch({ type: "reconnect", now: now() });
     },
-    state: () => state,
+    state: () => toStreamState(state),
     cursor: () => cursor,
     resetCursor() {
       cursor = null;

package/src/tab.ts

@@ -6,7 +6,7 @@ import {
   type WorkerToTab,
   isWorkerMessage,
 } from "./port-protocol.js";
-import type { ClientState } from "./reducer.js";
+import type { StreamState } from "./state.js";
 import { type Frame, type Stream, statusOf } from "./stream.js";
 import { DEFAULT_TIMING } from "./timing.js";
 import type { Subject, VersionMap } from "./versions.js";
@@ -75,7 +75,7 @@ export interface TabAttachment {
   /** Leaves the host; `logout` also ends the profile's stream, or this tab's fallback stream. */
   detach(cause?: "unload" | "logout"): void;
   /** The host's last state broadcast, or the fallback stream's own state. */
-  state(): ClientState | null;
+  state(): StreamState | null;
   mode(): "worker" | "fallback";
   /** Reports a stamp this tab applied, into the host's version map or the fallback's. */
   observe(subject: Subject, version: string, epoch: string): void;
@@ -113,7 +113,7 @@ export function attachToWorker(opts: AttachOptions): TabAttachment {
   let mode: "worker" | "fallback" = "worker";
   let link: Link | null = null;
   let fallback: TabFallback | null = null;
-  let lastState: ClientState | null = null;
+  let lastState: StreamState | null = null;
   let watchdog: ReturnType<typeof setTimeout> | null = null;
   let lastPortMessageAt = Date.now();
   let heartbeatSeen = false;

package/src/transport.ts

@@ -140,7 +140,7 @@ export function connect(opts: ConnectOptions): Connection {
             fail({ kind: "bad_hello" });
             return;
           }
-          const result = validateHello(data, opts.minWire, opts.maxWire);
+          const result = validateHello(data, opts);
           if (!result.ok) {
             fail(result.reason);
             return;

package/src/versions.ts

@@ -40,8 +40,8 @@ export interface VersionMapOptions {
   readonly onStale?: (subject: Subject, epoch: string) => void;
 }
 
-type BindListener = (epoch: string, dropped: number) => void;
-type StaleListener = (subject: Subject, epoch: string) => void;
+export type BindListener = (epoch: string, dropped: number) => void;
+export type StaleListener = (subject: Subject, epoch: string) => void;
 
 interface Listeners {
   readonly bound: Set<BindListener>;

package/src/wire.ts

@@ -94,7 +94,11 @@ const BAD_HELLO: HelloResult = { ok: false, reason: { kind: "bad_hello" } };
 
 // Structural pessimism follows Centrifugo's recovered/was_recovering: only `resumed === true` resumes.
 /** Validates a decoded hello payload against the wire contract and the accepted revision range. */
-export function validateHello(data: unknown, minWire: number, maxWire: number): HelloResult {
+export function validateHello(
+  data: unknown,
+  range: { readonly minWire: number; readonly maxWire: number },
+): HelloResult {
+  const { minWire, maxWire } = range;
   if (typeof data !== "object" || data === null) {
     return BAD_HELLO;
   }

package/src/worker.ts

@@ -1,4 +1,4 @@
-import type { Removed, State } from "./digest.js";
+import type { Changed, Removed } from "./digest.js";
 import { createProfileOnlineSource, createProfileVisibilitySource } from "./fold.js";
 import type { LifecycleEvent } from "./lifecycle.js";
 import { createOnlineManager } from "./online.js";
@@ -20,7 +20,7 @@ import { createVisibilityManager } from "./visibility.js";
 
 /** The changed and removed sets of one host-side digest, fanned to the tabs with the run. */
 export interface DigestVerdict {
-  readonly changed: readonly State[];
+  readonly changed: readonly Changed[];
   readonly removed: readonly Removed[];
 }