@cplieger/sse 1.3.0-dev.4 → 1.5.0-dev.4

package/NOTICE

@@ -1,3 +1,3 @@
-sse
+go
 Copyright 2026 cplieger
-https://github.com/cplieger/sse
+https://github.com/cplieger/go

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 [cplieger/sse](https://github.com/cplieger/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](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
 
@@ -48,6 +48,8 @@ While `revalidate` runs, incoming frames are held and delivered in order once it
 
 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.
 
+A 401 ends the session's stream instead of retrying it: a 401 on the stream request, on an alive acknowledgement, or from a `revalidate` that rejects with `{ status: 401 }` stops the stream and emits an `auth_lost` record whose `route` is `stream`, `alive` or `digest`. A tab's own stream and the worker host behave alike, and the host passes the record to every tab. Any other status backs off and reconnects.
+
 `createWorkerHost` runs one stream per browser profile inside a `SharedWorker`, and `attachToWorker` connects each tab to it over a `MessagePort`, folding the tabs' visibility and network readings into that one connection; where `SharedWorker` is absent or the worker never answers, the tab falls back to its own stream and reports the switch. The `fallback` option returns a `TabFallback`: the `createStream` result together with the `versions` map and the `headers` record it was built on, which is what lets the `TabAttachment` work the same in both modes. `observe(subject, version, epoch)` reports a stamp the tab applied, into the host's version map or the fallback's; `reconnect({ resetCursor })` reconnects the stream the tab is attached to; `setTag(tag)` presents a new `SSE-Client` value with one reconnect, written into the host's headers or the fallback's; and `detach("logout")` ends the profile's stream. The tab writes its `tag` into the fallback's headers before the first connect, so a consumer never fills `SSE-Client` itself.
 
 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.
@@ -64,7 +66,7 @@ The package typechecks under `lib: ["ESNext", "WebWorker"]` as well as under the
 
 ## Full documentation
 
-The Go server API is in the [repository README](https://github.com/cplieger/sse#readme). The hub options and the presence hook are in [Running the hub](https://github.com/cplieger/sse/blob/main/docs/hub.md), and the hello's verdicts and the digest are in [The wire contract](https://github.com/cplieger/sse/blob/main/docs/wire.md). The shared timing constants both halves pin are in the repository's `timing.json`.
+The Go server API is in the [repository README](https://github.com/cplieger/go/tree/main/sse#readme). The hub options and the presence hook are in [Running the hub](https://github.com/cplieger/go/blob/main/sse/docs/hub.md), and the hello's verdicts and the digest are in [The wire contract](https://github.com/cplieger/go/blob/main/sse/docs/wire.md). The shared timing constants both halves pin are in [`timing.json`](https://github.com/cplieger/go/blob/main/sse/timing.json).
 
 ## Disclaimer
 

package/jsr.json

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

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@cplieger/sse",
-  "version": "1.3.0-dev.4",
+  "version": "1.5.0-dev.4",
   "description": "Server-Sent Events hub and client that resume from an exact cursor and reconcile after sleep",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cplieger/sse.git",
-    "directory": "web"
+    "url": "git+https://github.com/cplieger/go.git",
+    "directory": "sse/web"
   },
-  "homepage": "https://github.com/cplieger/sse",
+  "homepage": "https://github.com/cplieger/go/tree/main/sse",
   "bugs": {
-    "url": "https://github.com/cplieger/sse/issues"
+    "url": "https://github.com/cplieger/go/issues"
   },
   "author": "cplieger <917744+cplieger@users.noreply.github.com>",
   "keywords": [
@@ -38,11 +38,6 @@
     "LICENSE",
     "NOTICE"
   ],
-  "sseFixture": "./ssetest/cmd",
-  "browserEngines": [
-    "firefox",
-    "webkit"
-  ],
   "scripts": {
     "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.worker.json && tsc -p tsconfig.tests.json",
     "typecheck:tests": "tsc -p tsconfig.tests.json",
@@ -55,25 +50,26 @@
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@stryker-mutator/core": "10.0.0",
-    "@stryker-mutator/typescript-checker": "10.0.0",
-    "@stryker-mutator/vitest-runner": "10.0.0",
-    "@types/node": "26.6.5",
+    "@stryker-mutator/core": "10.1.1",
+    "@stryker-mutator/typescript-checker": "10.1.1",
+    "@stryker-mutator/vitest-runner": "10.1.1",
+    "@types/node": "26.6.6",
     "@typescript/native": "npm:typescript@7.0.2",
     "@vitest/browser": "5.0.5",
     "@vitest/browser-playwright": "5.0.5",
     "@vitest/coverage-v8": "5.0.5",
-    "eslint": "10.13.0",
-    "eventsource-parser": "4.1.2",
+    "eslint": "10.14.0",
+    "eventsource-parser": "4.1.3",
     "fast-check": "4.10.2",
-    "knip": "6.41.0",
+    "knip": "6.44.1",
     "playwright": "1.64.1",
     "prettier": "3.9.10",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.71.2",
+    "typescript-eslint": "8.72.1",
     "vitest": "5.0.5"
   },
   "overrides": {
-    "qs": "^6.15.2"
+    "qs": "^6.15.2",
+    "minimatch": "^11.0.1"
   }
 }

package/src/lifecycle.ts

@@ -54,7 +54,7 @@ export type LifecycleEvent =
   | { kind: "worker_dead"; sinceLastPortMessageMs: number }
   | { kind: "worker_unavailable"; cause: "silent" | "error" }
   | { kind: "worker_recovered" }
-  | { kind: "auth_lost"; route: string; status: number }
+  | { kind: "auth_lost"; route: "stream" | "alive" | "digest"; status: 401 }
   | { kind: "tab_attached"; replaced: boolean; state: ClientState["kind"] }
   | { kind: "tab_detached"; cause: string }
   | { kind: "port_expired"; sinceLastAckMs: number }

package/src/port-protocol.ts

@@ -55,7 +55,13 @@ export type TabToWorker =
   | { readonly type: "reconnect"; readonly resetCursor: boolean }
   | { readonly type: "set_tag"; readonly tag: string }
   | { readonly type: "revalidate_done"; readonly runId: number }
-  | { readonly type: "revalidate_failed"; readonly runId: number; readonly cause: string }
+  | {
+      readonly type: "revalidate_failed";
+      readonly runId: number;
+      readonly cause: string;
+      /** The rejection's numeric `status`, absent when it carried none. */
+      readonly status?: number;
+    }
   | { readonly type: "frame_failed"; readonly generation: number; readonly cursor: Cursor | null };
 
 /**

package/src/stream.ts

@@ -150,6 +150,15 @@ function transportGeneration(event: ClientEvent): number | null {
   }
 }
 
+/** The numeric `status` an error carries, or null. */
+export function statusOf(error: unknown): number | null {
+  if (typeof error !== "object" || error === null) {
+    return null;
+  }
+  const status = (error as { status?: unknown }).status;
+  return typeof status === "number" ? status : null;
+}
+
 function describe(error: unknown): string {
   if (error instanceof Error) {
     return error.message;
@@ -157,7 +166,12 @@ function describe(error: unknown): string {
   return String(error);
 }
 
-/** Creates the client runtime. Throws RangeError when `timing.maxBufferBytes` is below MAX_FRAME_BYTES. */
+/**
+ * Creates the client runtime. Throws RangeError when `timing.maxBufferBytes` is below MAX_FRAME_BYTES.
+ * A 401 stops the stream and emits `auth_lost`, with route `stream` for the stream request, `alive`
+ * for the alive acknowledgement and `digest` for a revalidate rejecting with `{status: 401}`; any
+ * other status backs off, or fails the run.
+ */
 export function createStream(opts: StreamOptions): Stream {
   const cfg = resolveTiming(opts.timing);
   const doFetch: typeof fetch = opts.fetch ?? ((input, init) => globalThis.fetch(input, init));
@@ -200,6 +214,11 @@ export function createStream(opts: StreamOptions): Stream {
     opts.onLifecycle?.(event);
   }
 
+  function authLost(route: "stream" | "alive" | "digest"): void {
+    stream.stop();
+    emit({ kind: "auth_lost", route, status: 401 });
+  }
+
   bindListener(opts.versions, (epoch) => {
     const previous = knownEpoch;
     knownEpoch = epoch;
@@ -323,6 +342,10 @@ export function createStream(opts: StreamOptions): Stream {
         onConnectFailed(g, reason) {
           if (g === state.generation) {
             emit({ kind: "connect_failed", reason });
+            if (reason.kind === "status" && reason.status === 401) {
+              authLost("stream");
+              return;
+            }
           }
           dispatch({ type: "connect_failed", generation: g, now: now(), reason, rand: rand() });
         },
@@ -579,6 +602,9 @@ export function createStream(opts: StreamOptions): Stream {
       .then(
         (response) => {
           emit({ kind: "alive_ack", ok: response.ok, status: response.status });
+          if (response.status === 401 && state.kind !== "stopped") {
+            authLost("alive");
+          }
         },
         () => {
           if (!scope.signal.aborted) {
@@ -644,6 +670,10 @@ export function createStream(opts: StreamOptions): Stream {
     if (inflight !== current) {
       return;
     }
+    if (rejected && statusOf(error) === 401) {
+      authLost("digest");
+      return;
+    }
     if (current.timer !== null) {
       clearTimeout(current.timer);
     }

package/src/tab.ts

@@ -7,7 +7,7 @@ import {
   isWorkerMessage,
 } from "./port-protocol.js";
 import type { ClientState } from "./reducer.js";
-import type { Frame, Stream } from "./stream.js";
+import { type Frame, type Stream, statusOf } from "./stream.js";
 import { DEFAULT_TIMING } from "./timing.js";
 import type { Subject, VersionMap } from "./versions.js";
 import {
@@ -229,10 +229,12 @@ export function attachToWorker(opts: AttachOptions): TabAttachment {
           reply({ type: "revalidate_done", runId });
         },
         (e: unknown) => {
+          const status = statusOf(e);
           reply({
             type: "revalidate_failed",
             runId,
             cause: e instanceof Error ? e.message : String(e),
+            ...(status === null ? {} : { status }),
           });
         },
       )

package/src/timing.ts

@@ -60,7 +60,7 @@ export interface TimingConfig {
 
 /**
  * The value every field a caller leaves unset takes. Each one is pinned, directly or by derivation,
- * to the repository's `timing.json` — the single source both halves of the protocol read — so a
+ * to the module's `timing.json` — the single source both halves of the protocol read — so a
  * client default and the server behaviour it assumes cannot drift apart.
  */
 export const DEFAULT_TIMING: TimingConfig = {

package/src/worker.ts

@@ -29,6 +29,8 @@ export interface TabSet {
   /**
    * Fans the run to every acknowledging tab; settles when each answered, expired or left.
    * With `verdict`, each tab's context carries `changed` and `removed`, so one digest serves them all.
+   * A failed run rejects with a tab's cause and its `status`, a 401 first, so a revalidate that
+   * rethrows it reaches `auth_lost` route `digest`.
    */
   run(ctx: RevalidateContext, verdict?: DigestVerdict): Promise<void>;
   size(): number;
@@ -56,8 +58,9 @@ export interface WorkerHostOptions extends Omit<
 /**
  * The profile's stream owner: one stream, one cursor and one version map behind however many tabs.
  * The stream starts when the first tab attaches, and it is stopped by `close()`, by a `logout` detach
- * or by a 401 — not by the last port going away, since the browser keeps a SharedWorker alive for its
- * owner documents and a tab that navigates is expected back.
+ * or by a 401 (createStream's `auth_lost`, which every tab receives), not by the last port going
+ * away, since the browser keeps a SharedWorker alive for its owner documents and a tab that
+ * navigates is expected back.
  */
 export interface WorkerHost {
   /** Called from the SharedWorker's onconnect with each new port. */
@@ -79,21 +82,13 @@ interface PortEntry {
 
 interface Quorum {
   readonly pending: Set<PortEntry>;
-  readonly failures: string[];
+  readonly failures: { readonly cause: string; readonly status: number | null }[];
   readonly resolve: () => void;
   readonly reject: (error: Error) => void;
 }
 
 const EXPIRY_BEATS = 3;
 
-function statusOf(error: unknown): number | null {
-  if (typeof error !== "object" || error === null) {
-    return null;
-  }
-  const status = (error as { status?: unknown }).status;
-  return typeof status === "number" ? status : null;
-}
-
 function cloneSafe(event: LifecycleEvent): LifecycleEvent {
   if (event.kind === "frame_rejected") {
     return {
@@ -198,11 +193,13 @@ export function createWorkerHost(opts: WorkerHostOptions): WorkerHost {
       return;
     }
     quorums.delete(runId);
-    const failure = quorum.failures[0];
+    const failure = quorum.failures.find((f) => f.status === 401) ?? quorum.failures[0];
     if (failure === undefined) {
       quorum.resolve();
+    } else if (failure.status === null) {
+      quorum.reject(new Error(failure.cause));
     } else {
-      quorum.reject(new Error(failure));
+      quorum.reject(Object.assign(new Error(failure.cause), { status: failure.status }));
     }
   }
 
@@ -214,11 +211,6 @@ export function createWorkerHost(opts: WorkerHostOptions): WorkerHost {
     }
   }
 
-  function authLost(route: string, status: number): void {
-    stream.stop();
-    emit({ kind: "auth_lost", route, status });
-  }
-
   const stream = createStream({
     ...opts,
     headers,
@@ -240,20 +232,8 @@ export function createWorkerHost(opts: WorkerHostOptions): WorkerHost {
         broadcast({ type: "state", state: stream.state() });
       }
       emit(event);
-      if (event.kind === "alive_ack" && event.status === 401) {
-        authLost("alive", 401);
-      }
-    },
-    async revalidate(ctx) {
-      try {
-        await opts.revalidate(ctx, tabs);
-      } catch (e: unknown) {
-        if (statusOf(e) === 401) {
-          authLost("digest", 401);
-        }
-        throw e;
-      }
     },
+    revalidate: (ctx) => opts.revalidate(ctx, tabs),
   });
   const controls = streamInternals(stream);
 
@@ -420,7 +400,10 @@ export function createWorkerHost(opts: WorkerHostOptions): WorkerHost {
           return;
         }
         if (message.type === "revalidate_failed") {
-          quorum.failures.push(message.cause);
+          quorum.failures.push({
+            cause: message.cause,
+            status: typeof message.status === "number" ? message.status : null,
+          });
         }
         settleQuorum(message.runId, quorum);
         return;