npm - @0k/kal-sse-client - Versions diffs - 0.2.0 → 0.3.0 - Mend

@0k/kal-sse-client 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -22,6 +22,9 @@ Chrome 91 and later.
 npm install @0k/kal-sse-client
 ```
+The package is an ES module only: load it with `import`, as bundlers do.
+There is no CommonJS build for `require()`.
 ## Usage
 ### Snapshot and cursor channel
@@ -130,27 +133,26 @@ back to the server cursor instead of client-directed replay.
 ### `createSnapshotCursorSse<S>(options)`
-| Option                   | Type                            | Default  | Meaning                                                                                                                                                                |
-|--------------------------|---------------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `snapshotPath`           | `string`                        | Required | Snapshot endpoint path. After receiving a subscription id, later requests add `sub`.                                                                                   |
-| `streamPath`             | `string`                        | Required | SSE endpoint path. The client adds the server-owned `sub` id.                                                                                                          |
-| `resolveUrl`             | `(path: string) => string`      | Identity | Resolves endpoint paths, for example below a reverse-proxy prefix. It is used for both snapshot fetches and stream URLs.                                               |
-| `applySnapshot`          | `(body: S) => void`             | Required | Applies a successful snapshot after its non-empty `x-sub-id` header is read.                                                                                           |
-| `onMessage`              | `(event: MessageEvent) => void` | Required | Handles stream messages. Parse the event payload and update state here.                                                                                                |
-| `retrySnapshotAfter`     | `(body: S) => number \| null`   | None     | Returns a non-negative delay in milliseconds to retry this otherwise successful snapshot without applying it. Return `null` or no value to apply it.                   |
-| `onSnapshotError`        | `(reason: unknown) => void`     | None     | Receives failed snapshot fetch, HTTP, header, JSON, callback, or retry-delay validation errors before snapshot retry. Exceptions from this notification are swallowed. |
-| `onStreamError`          | `() => void`                    | None     | Receives errors reported by the underlying stream before its reconnect logic runs. Exceptions from this notification are swallowed.                                    |
-| `initialSnapshotRetryMs` | `number`                        | `250`    | First retry delay for a failed snapshot in milliseconds.                                                                                                               |
-| `maxSnapshotRetryMs`     | `number`                        | `30000`  | Maximum snapshot retry delay in milliseconds.                                                                                                                          |
+| Option                   | Type                            | Default  | Meaning                                                                                                                                                                                                                                                                                                                                          |
+|--------------------------|---------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `snapshotPath`           | `string`                        | Required | Snapshot endpoint path. After receiving a subscription id, later requests add `sub`.                                                                                                                                                                                                                                                             |
+| `streamPath`             | `string`                        | Required | SSE endpoint path. The client adds the server-owned `sub` id.                                                                                                                                                                                                                                                                                    |
+| `resolveUrl`             | `(path: string) => string`      | Identity | Resolves endpoint paths, for example below a reverse-proxy prefix. It is used for both snapshot fetches and stream URLs.                                                                                                                                                                                                                         |
+| `applySnapshot`          | `(body: S) => void`             | Required | Applies a successful snapshot after its non-empty `x-sub-id` header is read.                                                                                                                                                                                                                                                                     |
+| `onMessage`              | `(event: MessageEvent) => void` | Required | Handles stream messages. Parse the event payload and update state here.                                                                                                                                                                                                                                                                          |
+| `retrySnapshotAfter`     | `(body: S) => number \| null`   | None     | Returns a non-negative delay in milliseconds to retry this otherwise successful snapshot without applying it. Return `null` or no value to apply it.                                                                                                                                                                                             |
+| `onSnapshotError`        | `(reason: unknown) => void`     | None     | Receives failed snapshot fetch, HTTP, header, JSON, callback, or retry-delay validation errors before snapshot retry. An HTTP refusal is a `SnapshotHttpError` with the response `status`; its message is the body's `detail` or `error` string when the server gave one, else `HTTP <status>`. Exceptions from this notification are swallowed. |
+| `onStreamError`          | `() => void`                    | None     | Receives errors reported by the underlying stream before its reconnect logic runs. Exceptions from this notification are swallowed.                                                                                                                                                                                                              |
+| `initialSnapshotRetryMs` | `number`                        | `250`    | First retry delay for a failed snapshot in milliseconds.                                                                                                                                                                                                                                                                                         |
+| `maxSnapshotRetryMs`     | `number`                        | `30000`  | Maximum snapshot retry delay in milliseconds.                                                                                                                                                                                                                                                                                                    |
 ## Development
-Run the checks separately when working on the package:
+Run every check (tests, typecheck, build, and the Chrome 91 inspection
+of the built code) before delivering a change:
 ``` bash
-npm test
-npm run typecheck
-npm run build
+npm run check
 ```
 For a local consumer, run `npm link` in this repository, then run
@@ -166,6 +168,37 @@ MIT, see `LICENSE`.
 ## Changelog
+### 0.3.0 (2026-11-06)
+#### New
+* Report a refused snapshot as ``SnapshotHttpError`` with the server's reason. [Valentin Lab]
+  A refused snapshot used to reach ``onSnapshotError`` as a bare
+  ``HTTP <status>`` error, dropping what the server said about why
+  (``path does not exist: ...``, ``permission denied``), so a host could
+  not show its user the actual reason.
+  It now raises the exported ``SnapshotHttpError``, which carries the
+  response ``status`` and, as its message, the JSON body's ``detail`` or
+  ``error`` string when the server gave one, else ``HTTP <status>`` as
+  before.
+#### Changes
+* Ship ESM only, compiled by ``tsc`` without minification. [Valentin Lab]
+  The package now ships a single ES module, ``dist/index.js``, with its
+  ``dist/index.d.ts`` types. The code is plain ``tsc`` output for
+  ES2020, readable and close to the source, so stack traces and reviews
+  of the installed package match ``src/``. It still runs on Chrome 91.
+  BREAKING CHANGE: the CommonJS build is gone. ``require()`` of the
+  package, ``dist/index.cjs``, the ``main`` and ``module`` fields and
+  the bundled source maps are removed. Load it with ``import``, as any
+  bundler (Vite, webpack, Rollup, esbuild) already does.
 ### 0.2.0 (2026-10-10)
 #### New

package/dist/index.d.ts CHANGED Viewed

@@ -14,6 +14,15 @@ export interface ResilientSseSubscription {
     stop(): void;
 }
 export declare function createResilientSse(opts: ResilientSseOptions): ResilientSseSubscription;
+/**
+ * A snapshot request the server refused.  The message is the server's own
+ * reason (the JSON body's `detail` or `error` string) when it gave one,
+ * else `HTTP <status>`.
+ */
+export declare class SnapshotHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, reason: string | null);
+}
 export interface SnapshotCursorSseOptions<S> {
     snapshotPath: string;
     streamPath: string;

package/dist/index.js CHANGED Viewed

@@ -1,129 +1,266 @@
-function T(e) {
-  const y = e.initialDelayMs ?? 250, c = e.maxDelayMs ?? 3e4, v = e.healthyWindowMs ?? 5e3;
-  let a = null, t = 0, r = null, u = null, l = null, d = !1, S = !1, n = !1, o = null, w = !1;
-  function E() {
-    a?.close(), a = null, u !== null && clearTimeout(u), u = null;
-  }
-  function f(m, i) {
-    n || (w = !0, t > 0 && u === null && (u = setTimeout(() => {
-      t = 0, u = null;
-    }, v)), m(i), e.resumeFromLastEventId && i.lastEventId && (o = i.lastEventId));
-  }
-  function b(m = !1) {
-    if (n) return;
-    E(), w = !1;
-    const i = e.url();
-    a = new EventSource(m ? g(i, "last_event_id", o) : i), e.resumeFromLastEventId && (a.onopen = () => {
-      w = !0;
-    }), a.onmessage = (s) => f(e.onMessage, s), a.onerror = () => {
-      if (!n) {
+export function createResilientSse(opts) {
+    const initial = opts.initialDelayMs ?? 250;
+    const maximum = opts.maxDelayMs ?? 30000;
+    const healthyWindow = opts.healthyWindowMs ?? 5000;
+    let source = null;
+    let delay = 0;
+    let timer = null;
+    let healthyTimer = null;
+    let wake = null;
+    let running = false;
+    let started = false;
+    let stopped = false;
+    let lastEventId = null;
+    let opened = false;
+    function close() {
+        source?.close();
+        source = null;
+        if (healthyTimer !== null)
+            clearTimeout(healthyTimer);
+        healthyTimer = null;
+    }
+    function receive(callback, event) {
+        if (stopped)
+            return;
+        opened = true;
+        if (delay > 0 && healthyTimer === null) {
+            healthyTimer = setTimeout(() => {
+                delay = 0;
+                healthyTimer = null;
+            }, healthyWindow);
+        }
+        callback(event);
+        if (opts.resumeFromLastEventId && event.lastEventId)
+            lastEventId = event.lastEventId;
+    }
+    function open(resume = false) {
+        if (stopped)
+            return;
+        close();
+        opened = false;
+        const url = opts.url();
+        source = new EventSource(resume ? joinQuery(url, "last_event_id", lastEventId) : url);
+        if (opts.resumeFromLastEventId)
+            source.onopen = () => { opened = true; };
+        source.onmessage = (event) => receive(opts.onMessage, event);
+        source.onerror = () => {
+            if (stopped)
+                return;
+            try {
+                opts.onError?.();
+            }
+            catch {
+                // Notification failures must not interrupt recovery.
+            }
+            void reconnect();
+        };
+        for (const [name, callback] of Object.entries(opts.onEvents ?? {})) {
+            source.addEventListener(name, (event) => receive(callback, event));
+        }
+    }
+    async function reconnect(waitBeforeAttempt = true) {
+        if (running || stopped)
+            return;
+        running = true;
+        const resume = Boolean(opts.resumeFromLastEventId && lastEventId !== null && opened);
+        close();
         try {
-          e.onError?.();
-        } catch {
+            if (waitBeforeAttempt && delay > 0) {
+                await new Promise((resolve) => {
+                    wake = resolve;
+                    timer = setTimeout(() => {
+                        timer = null;
+                        wake = null;
+                        resolve();
+                    }, delay);
+                });
+            }
+            if (stopped)
+                return;
+            delay = Math.min(delay === 0 ? initial : delay * 2, maximum);
+            if (!resume) {
+                lastEventId = null;
+                await opts.onBeforeReconnect?.();
+            }
+            if (!stopped)
+                open(resume);
         }
-        h();
-      }
+        catch {
+            if (!stopped) {
+                timer = setTimeout(() => {
+                    timer = null;
+                    running = false;
+                    void reconnect(false);
+                }, delay);
+                return;
+            }
+        }
+        finally {
+            if (timer === null || wake !== null)
+                running = false;
+        }
+    }
+    return {
+        start() {
+            if (started || stopped)
+                return;
+            started = true;
+            open();
+        },
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            close();
+            if (timer !== null)
+                clearTimeout(timer);
+            timer = null;
+            wake?.();
+            wake = null;
+        },
     };
-    for (const [s, I] of Object.entries(e.onEvents ?? {}))
-      a.addEventListener(s, (M) => f(I, M));
-  }
-  async function h(m = !0) {
-    if (d || n) return;
-    d = !0;
-    const i = !!(e.resumeFromLastEventId && o !== null && w);
-    E();
+}
+/**
+ * A snapshot request the server refused.  The message is the server's own
+ * reason (the JSON body's `detail` or `error` string) when it gave one,
+ * else `HTTP <status>`.
+ */
+export class SnapshotHttpError extends Error {
+    constructor(status, reason) {
+        super(reason ?? `HTTP ${status}`);
+        Object.defineProperty(this, "status", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "SnapshotHttpError";
+        this.status = status;
+    }
+}
+async function refusal(response) {
+    let reason = null;
     try {
-      if (m && t > 0 && await new Promise((s) => {
-        l = s, r = setTimeout(() => {
-          r = null, l = null, s();
-        }, t);
-      }), n) return;
-      t = Math.min(t === 0 ? y : t * 2, c), i || (o = null, await e.onBeforeReconnect?.()), n || b(i);
-    } catch {
-      if (!n) {
-        r = setTimeout(() => {
-          r = null, d = !1, h(!1);
-        }, t);
-        return;
-      }
-    } finally {
-      (r === null || l !== null) && (d = !1);
+        const body = (await response.json());
+        for (const text of [body?.detail, body?.error]) {
+            if (typeof text === "string" && text.trim()) {
+                reason = text;
+                break;
+            }
+        }
     }
-  }
-  return {
-    start() {
-      S || n || (S = !0, b());
-    },
-    stop() {
-      n || (n = !0, E(), r !== null && clearTimeout(r), r = null, l?.(), l = null);
+    catch {
+        // Not JSON: only the status is known.
     }
-  };
+    return new SnapshotHttpError(response.status, reason);
 }
-function g(e, y, c) {
-  return `${e}${e.includes("?") ? "&" : "?"}${y}=${encodeURIComponent(c)}`;
+function joinQuery(path, key, value) {
+    return `${path}${path.includes("?") ? "&" : "?"}${key}=${encodeURIComponent(value)}`;
 }
-function p(e) {
-  const y = e.resolveUrl ?? ((n) => n);
-  let c = null, v = null, a = null, t = null, r = null, u = null, l = !1;
-  function d(n) {
-    return new Promise((o) => {
-      r = o, t = setTimeout(() => {
-        t = null, r = null, o();
-      }, n);
-    });
-  }
-  async function S(n) {
-    let o = e.initialSnapshotRetryMs ?? 250;
-    const w = e.maxSnapshotRetryMs ?? 3e4;
-    let E = !1;
-    for (; !l; ) {
-      const f = new AbortController();
-      a = f;
-      try {
-        const b = c === null ? e.snapshotPath : g(e.snapshotPath, "sub", c), h = await fetch(y(b), { signal: f.signal });
-        if (!h.ok) throw new Error(`HTTP ${h.status}`);
-        const m = await h.json(), i = h.headers.get("x-sub-id")?.trim();
-        if (!i) throw new Error("Snapshot response missing non-empty x-sub-id");
-        const s = e.retrySnapshotAfter?.(m) ?? null;
-        if (s !== null) {
-          if (!Number.isFinite(s) || s < 0) throw new Error("Invalid snapshot retry delay");
-          await d(s);
-          continue;
-        }
-        if (l || f.signal.aborted) return;
-        c = i, e.applySnapshot(m);
-        return;
-      } catch (b) {
-        if (l || f.signal.aborted) return;
-        try {
-          e.onSnapshotError?.(b);
-        } catch {
-        }
-        E || n?.(), E = !0, await d(o), o = Math.min(o * 2, w);
-      } finally {
-        a === f && (a = null);
-      }
+export function createSnapshotCursorSse(opts) {
+    const resolveUrl = opts.resolveUrl ?? ((path) => path);
+    let subId = null;
+    let subscription = null;
+    let controller = null;
+    let timer = null;
+    let wake = null;
+    let started = null;
+    let stopped = false;
+    function wait(milliseconds) {
+        return new Promise((resolve) => {
+            wake = resolve;
+            timer = setTimeout(() => {
+                timer = null;
+                wake = null;
+                resolve();
+            }, milliseconds);
+        });
     }
-  }
-  return {
-    start() {
-      return u !== null ? u : l ? Promise.resolve() : (u = new Promise((n) => {
-        (async () => (await S(n), !l && c !== null && (v = T({
-          url: () => y(g(e.streamPath, "sub", c)),
-          onMessage: e.onMessage,
-          resumeFromLastEventId: !0,
-          ...e.onStreamError ? { onError: e.onStreamError } : {},
-          onBeforeReconnect: () => S()
-        }), v.start()), n()))();
-      }), u);
-    },
-    stop() {
-      l || (l = !0, a?.abort(), v?.stop(), t !== null && clearTimeout(t), t = null, r?.(), r = null);
+    async function snapshot(onFirstFailure) {
+        let delay = opts.initialSnapshotRetryMs ?? 250;
+        const maxDelay = opts.maxSnapshotRetryMs ?? 30000;
+        let failed = false;
+        while (!stopped) {
+            const abort = new AbortController();
+            controller = abort;
+            try {
+                const path = subId === null ? opts.snapshotPath : joinQuery(opts.snapshotPath, "sub", subId);
+                const response = await fetch(resolveUrl(path), { signal: abort.signal });
+                if (!response.ok)
+                    throw await refusal(response);
+                const body = (await response.json());
+                const id = response.headers.get("x-sub-id")?.trim();
+                if (!id)
+                    throw new Error("Snapshot response missing non-empty x-sub-id");
+                const retry = opts.retrySnapshotAfter?.(body) ?? null;
+                if (retry !== null) {
+                    if (!Number.isFinite(retry) || retry < 0)
+                        throw new Error("Invalid snapshot retry delay");
+                    await wait(retry);
+                    continue;
+                }
+                if (stopped || abort.signal.aborted)
+                    return;
+                subId = id;
+                opts.applySnapshot(body);
+                return;
+            }
+            catch (reason) {
+                if (stopped || abort.signal.aborted)
+                    return;
+                try {
+                    opts.onSnapshotError?.(reason);
+                }
+                catch {
+                    // Notification failures must not interrupt recovery.
+                }
+                if (!failed)
+                    onFirstFailure?.();
+                failed = true;
+                await wait(delay);
+                delay = Math.min(delay * 2, maxDelay);
+            }
+            finally {
+                if (controller === abort)
+                    controller = null;
+            }
+        }
     }
-  };
+    return {
+        start() {
+            if (started !== null)
+                return started;
+            if (stopped)
+                return Promise.resolve();
+            started = new Promise((resolve) => {
+                void (async () => {
+                    await snapshot(resolve);
+                    if (!stopped && subId !== null) {
+                        subscription = createResilientSse({
+                            url: () => resolveUrl(joinQuery(opts.streamPath, "sub", subId)),
+                            onMessage: opts.onMessage,
+                            resumeFromLastEventId: true,
+                            ...(opts.onStreamError ? { onError: opts.onStreamError } : {}),
+                            onBeforeReconnect: () => snapshot(),
+                        });
+                        subscription.start();
+                    }
+                    resolve();
+                })();
+            });
+            return started;
+        },
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            controller?.abort();
+            subscription?.stop();
+            if (timer !== null)
+                clearTimeout(timer);
+            timer = null;
+            wake?.();
+            wake = null;
+        },
+    };
 }
-export {
-  T as createResilientSse,
-  p as createSnapshotCursorSse
-};
-//# sourceMappingURL=index.js.map

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@0k/kal-sse-client",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Framework-agnostic browser client for kal-sse snapshot and server-owned cursor channels.",
   "keywords": [
     "sse",
@@ -27,31 +27,29 @@
     "README.md",
     "LICENSE"
   ],
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "default": "./dist/index.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "prepack": "npm run build",
+    "prepare": "npm run build",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
-    "build": "tsc -p tsconfig.build.json && vite build",
-    "check": "npm run test && npm run typecheck && npm run build"
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "check:chrome91": "node scripts/check-chrome91.mjs",
+    "check": "npm run test && npm run typecheck && npm run build && npm run check:chrome91"
   },
   "devDependencies": {
     "@types/node": "22.10.5",
     "jsdom": "25.0.1",
     "typescript": "5.7.3",
-    "vite": "6.4.4",
-    "vitest": "4.1.11"
+    "vite": "6.4.5",
+    "vitest": "4.1.12"
   }
 }

package/README.org DELETED Viewed

@@ -1,159 +0,0 @@
-#+TITLE: @0k/kal-sse-client
-[[https://www.npmjs.com/package/@0k/kal-sse-client][https://img.shields.io/npm/v/@0k/kal-sse-client.svg]]
-* Overview
-A kal-sse data channel pairs a REST snapshot with an SSE stream. The snapshot
-registers or refreshes the subscription, the server owns its ~sub~ id, and each
-stream event carries an SSE ~id:~. On reconnect, the client can send the last
-applied event id so the server can replay from that point.
-=@0k/kal-sse-client= owns the =EventSource= lifecycle, reconnect backoff,
-snapshot registration, and resume-first recovery. Your application owns endpoint
-paths, URL resolution, parsing event payloads, and rendering or otherwise
-updating application state. It supports Chrome 91 and later.
-* Installation
-#+begin_src sh
-npm install @0k/kal-sse-client
-#+end_src
-* Usage
-** Snapshot and cursor channel
-Use =createSnapshotCursorSse= for the usual kal-sse data channel: fetch a
-snapshot, render it, then apply changes from its SSE stream.
-#+begin_src ts
-import { createSnapshotCursorSse } from "@0k/kal-sse-client";
-type Archive = { items: Array<{ id: string; title: string }> };
-type ArchiveChange = { id: string; title: string };
-const archive = createSnapshotCursorSse<Archive>({
-  snapshotPath: "/api/archive",
-  streamPath: "/api/archive/events",
-  applySnapshot: (snapshot) => renderArchive(snapshot),
-  onMessage: (event) => applyArchiveChange(JSON.parse(event.data) as ArchiveChange),
-});
-await archive.start();
-// Later, for example when the view is disposed:
-archive.stop();
-#+end_src
-=start()= begins the snapshot request and returns one shared promise. That
-promise resolves when the first snapshot succeeds, or when its first attempt
-fails. Later snapshot retries continue in the background, so a resolved promise
-does not by itself mean a stream is already open.
-The snapshot response must provide a non-empty =x-sub-id= header. For a
-cross-origin snapshot endpoint, expose it to browser JavaScript with
-=Access-Control-Expose-Headers: x-sub-id=. Once the client knows this id, each
-later snapshot request adds ~?sub=<id>~ (or ~&sub=<id>~ when the path already
-has a query string). The stream URL always appends ~sub=<id>~ as a query
-parameter.
-** Plain SSE endpoint
-Use =createResilientSse= when the endpoint is not a snapshot cursor channel.
-By default it calls =onBeforeReconnect= before every reconnect, which is a
-place to refetch application state.
-#+begin_src ts
-import { createResilientSse } from "@0k/kal-sse-client";
-const notifications = createResilientSse({
-  url: () => "/api/notifications/events",
-  onMessage: (event) => showNotification(JSON.parse(event.data)),
-  onBeforeReconnect: async () => {
-    const response = await fetch("/api/notifications");
-    if (!response.ok) throw new Error(`HTTP ${response.status}`);
-    replaceNotifications(await response.json());
-  },
-});
-notifications.start();
-// Later:
-notifications.stop();
-#+end_src
-* Reconnection behavior
-The first reconnect attempt opens immediately. After that, reconnect delay
-starts at 250 ms, doubles after each attempt, and is capped at 30 s. A delivered
-event starts a 5 s healthy timer; when that timer elapses, the retry delay
-resets. Keep-alive comments do not count as delivered events and never reset
-the delay.
-=createSnapshotCursorSse= always resumes first, using its =sub= id and the
-last applied =last_event_id=. =createResilientSse= does this only when
-=resumeFromLastEventId: true=. An event id is remembered only after the relevant
-message callback returns normally.
-The client fetches a fresh snapshot if no event was applied since the last
-snapshot, or if a resume attempt fails before the stream opens. This is
-deliberately conservative: =EventSource= does not expose the HTTP response
-status, so =409 needs_snapshot= cannot be distinguished from other HTTP errors
-such as a proxy's =502=. A network drop differs: the browser retries with
-~readyState~ set to ~CONNECTING~. The client nevertheless treats any resume
-attempt that fails before opening the same way. While snapshot recovery is
-pending, the last successfully applied snapshot stays rendered.
-This resume protocol needs a =kal-sse= server version 0.2 or later, which
-accepts =last_event_id=. With a 0.1 server, typical Axum handlers ignore that
-unknown query parameter, so the connection silently falls back to the server
-cursor instead of client-directed replay.
-* Option reference
-** =createResilientSse(options)=
-| Option | Type | Default | Meaning |
-|-
-| ~url~ | ~() => string~ | Required | Returns the SSE URL for each new connection. |
-| ~onMessage~ | ~(event: MessageEvent) => void~ | Required | Handles unnamed SSE messages. A non-empty event id is remembered only after this callback returns when resume is enabled. |
-| ~onEvents~ | ~Record<string, (event: MessageEvent) => void>~ | None | Handles named SSE events. Use custom event names only, never the reserved names ~open~, ~error~, or ~message~. |
-| ~onBeforeReconnect~ | ~() => void \| Promise<void>~ | None | Runs before a non-resume reconnect. Use it to refetch state for a plain SSE endpoint. A rejected promise is retried with the reconnect delay. |
-| ~resumeFromLastEventId~ | ~boolean~ | ~false~ | When true, reconnect after an applied id and an opened stream with ~last_event_id=<id>~ appended as a query parameter. |
-| ~onError~ | ~() => void~ | None | Runs when the current =EventSource= reports an error, before reconnect scheduling. Exceptions from this notification are swallowed. |
-| ~initialDelayMs~ | ~number~ | ~250~ | First delayed reconnect interval in milliseconds. The first reconnect attempt itself is immediate. |
-| ~maxDelayMs~ | ~number~ | ~30000~ | Maximum reconnect interval in milliseconds. |
-| ~healthyWindowMs~ | ~number~ | ~5000~ | Milliseconds after a delivered event before the reconnect delay resets. |
-** =createSnapshotCursorSse<S>(options)=
-| Option | Type | Default | Meaning |
-|-
-| ~snapshotPath~ | ~string~ | Required | Snapshot endpoint path. After receiving a subscription id, later requests add =sub=. |
-| ~streamPath~ | ~string~ | Required | SSE endpoint path. The client adds the server-owned =sub= id. |
-| ~resolveUrl~ | ~(path: string) => string~ | Identity | Resolves endpoint paths, for example below a reverse-proxy prefix. It is used for both snapshot fetches and stream URLs. |
-| ~applySnapshot~ | ~(body: S) => void~ | Required | Applies a successful snapshot after its non-empty =x-sub-id= header is read. |
-| ~onMessage~ | ~(event: MessageEvent) => void~ | Required | Handles stream messages. Parse the event payload and update state here. |
-| ~retrySnapshotAfter~ | ~(body: S) => number \| null~ | None | Returns a non-negative delay in milliseconds to retry this otherwise successful snapshot without applying it. Return ~null~ or no value to apply it. |
-| ~onSnapshotError~ | ~(reason: unknown) => void~ | None | Receives failed snapshot fetch, HTTP, header, JSON, callback, or retry-delay validation errors before snapshot retry. Exceptions from this notification are swallowed. |
-| ~onStreamError~ | ~() => void~ | None | Receives errors reported by the underlying stream before its reconnect logic runs. Exceptions from this notification are swallowed. |
-| ~initialSnapshotRetryMs~ | ~number~ | ~250~ | First retry delay for a failed snapshot in milliseconds. |
-| ~maxSnapshotRetryMs~ | ~number~ | ~30000~ | Maximum snapshot retry delay in milliseconds. |
-* Development
-Run the checks separately when working on the package:
-#+begin_src sh
-npm test
-npm run typecheck
-npm run build
-#+end_src
-For a local consumer, run ~npm link~ in this repository, then run
-~npm link @0k/kal-sse-client~ in the consumer repository. The release process
-generates ~README.md~ from this file; do not commit that generated file.
-* License
-MIT, see ~LICENSE~.

package/dist/index.cjs DELETED Viewed

	@@ -1,2 +0,0 @@
1	- "use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function M(e){const y=e.initialDelayMs??250,c=e.maxDelayMs??3e4,S=e.healthyWindowMs??5e3;let a=null,t=0,r=null,o=null,l=null,d=!1,v=!1,n=!1,u=null,w=!1;function E(){a?.close(),a=null,o!==null&&clearTimeout(o),o=null}function f(m,i){n\|\|(w=!0,t>0&&o===null&&(o=setTimeout(()=>{t=0,o=null},S)),m(i),e.resumeFromLastEventId&&i.lastEventId&&(u=i.lastEventId))}function b(m=!1){if(n)return;E(),w=!1;const i=e.url();a=new EventSource(m?g(i,"last_event_id",u):i),e.resumeFromLastEventId&&(a.onopen=()=>{w=!0}),a.onmessage=s=>f(e.onMessage,s),a.onerror=()=>{if(!n){try{e.onError?.()}catch{}h()}};for(const[s,T]of Object.entries(e.onEvents??{}))a.addEventListener(s,I=>f(T,I))}async function h(m=!0){if(d\|\|n)return;d=!0;const i=!!(e.resumeFromLastEventId&&u!==null&&w);E();try{if(m&&t>0&&await new Promise(s=>{l=s,r=setTimeout(()=>{r=null,l=null,s()},t)}),n)return;t=Math.min(t===0?y:t2,c),i\|\|(u=null,await e.onBeforeReconnect?.()),n\|\|b(i)}catch{if(!n){r=setTimeout(()=>{r=null,d=!1,h(!1)},t);return}}finally{(r===null\|\|l!==null)&&(d=!1)}}return{start(){v\|\|n\|\|(v=!0,b())},stop(){n\|\|(n=!0,E(),r!==null&&clearTimeout(r),r=null,l?.(),l=null)}}}function g(e,y,c){return`${e}${e.includes("?")?"&":"?"}${y}=${encodeURIComponent(c)}`}function p(e){const y=e.resolveUrl??(n=>n);let c=null,S=null,a=null,t=null,r=null,o=null,l=!1;function d(n){return new Promise(u=>{r=u,t=setTimeout(()=>{t=null,r=null,u()},n)})}async function v(n){let u=e.initialSnapshotRetryMs??250;const w=e.maxSnapshotRetryMs??3e4;let E=!1;for(;!l;){const f=new AbortController;a=f;try{const b=c===null?e.snapshotPath:g(e.snapshotPath,"sub",c),h=await fetch(y(b),{signal:f.signal});if(!h.ok)throw new Error(`HTTP ${h.status}`);const m=await h.json(),i=h.headers.get("x-sub-id")?.trim();if(!i)throw new Error("Snapshot response missing non-empty x-sub-id");const s=e.retrySnapshotAfter?.(m)??null;if(s!==null){if(!Number.isFinite(s)\|\|s<0)throw new Error("Invalid snapshot retry delay");await d(s);continue}if(l\|\|f.signal.aborted)return;c=i,e.applySnapshot(m);return}catch(b){if(l\|\|f.signal.aborted)return;try{e.onSnapshotError?.(b)}catch{}E\|\|n?.(),E=!0,await d(u),u=Math.min(u2,w)}finally{a===f&&(a=null)}}}return{start(){return o!==null?o:l?Promise.resolve():(o=new Promise(n=>{(async()=>(await v(n),!l&&c!==null&&(S=M({url:()=>y(g(e.streamPath,"sub",c)),onMessage:e.onMessage,resumeFromLastEventId:!0,...e.onStreamError?{onError:e.onStreamError}:{},onBeforeReconnect:()=>v()}),S.start()),n()))()}),o)},stop(){l\|\|(l=!0,a?.abort(),S?.stop(),t!==null&&clearTimeout(t),t=null,r?.(),r=null)}}}exports.createResilientSse=M;exports.createSnapshotCursorSse=p;
2	- //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map DELETED Viewed

@@ -1 +0,0 @@

- {"version":3,"file":"index.cjs","sources":["../src/index.ts"],"sourcesContent":["export interface ResilientSseOptions {\n url: () => string;\n onMessage: (event: MessageEvent) => void;\n onEvents?: Record<string, (event: MessageEvent) => void>;\n onBeforeReconnect?: () => void | Promise<void>;\n resumeFromLastEventId?: boolean;\n onError?: () => void;\n initialDelayMs?: number;\n maxDelayMs?: number;\n healthyWindowMs?: number;\n}\n\nexport interface ResilientSseSubscription {\n start(): void;\n stop(): void;\n}\n\nexport function createResilientSse(opts: ResilientSseOptions): ResilientSseSubscription {\n const initial = opts.initialDelayMs ?? 250;\n const maximum = opts.maxDelayMs ?? 30_000;\n const healthyWindow = opts.healthyWindowMs ?? 5_000;\n let source: EventSource | null = null;\n let delay = 0;\n let timer: ReturnType<typeof setTimeout> | null = null;\n let healthyTimer: ReturnType<typeof setTimeout> | null = null;\n let wake: (() => void) | null = null;\n let running = false;\n let started = false;\n let stopped = false;\n let lastEventId: string | null = null;\n let opened = false;\n\n function close(): void {\n source?.close();\n source = null;\n if (healthyTimer !== null) clearTimeout(healthyTimer);\n healthyTimer = null;\n }\n\n function receive(callback: (event: MessageEvent) => void, event: MessageEvent): void {\n if (stopped) return;\n opened = true;\n if (delay > 0 && healthyTimer === null) {\n healthyTimer = setTimeout(() => {\n delay = 0;\n healthyTimer = null;\n }, healthyWindow);\n }\n callback(event);\n if (opts.resumeFromLastEventId && event.lastEventId) lastEventId = event.lastEventId;\n }\n\n function open(resume = false): void {\n if (stopped) return;\n close();\n opened = false;\n const url = opts.url();\n source = new EventSource(resume ? joinQuery(url, \"last_event_id\", lastEventId!) : url);\n if (opts.resumeFromLastEventId) source.onopen = () => { opened = true; };\n source.onmessage = (event) => receive(opts.onMessage, event);\n source.onerror = () => {\n if (stopped) return;\n try {\n opts.onError?.();\n } catch {\n // Notification failures must not interrupt recovery.\n }\n void reconnect();\n };\n for (const [name, callback] of Object.entries(opts.onEvents ?? {})) {\n source.addEventListener(name, (event) => receive(callback, event as MessageEvent));\n }\n }\n\n async function reconnect(waitBeforeAttempt = true): Promise<void> {\n if (running || stopped) return;\n running = true;\n const resume = Boolean(opts.resumeFromLastEventId && lastEventId !== null && opened);\n close();\n try {\n if (waitBeforeAttempt && delay > 0) {\n await new Promise<void>((resolve) => {\n wake = resolve;\n timer = setTimeout(() => {\n timer = null;\n wake = null;\n resolve();\n }, delay);\n });\n }\n if (stopped) return;\n delay = Math.min(delay === 0 ? initial : delay * 2, maximum);\n if (!resume) {\n lastEventId = null;\n await opts.onBeforeReconnect?.();\n }\n if (!stopped) open(resume);\n } catch {\n if (!stopped) {\n timer = setTimeout(() => {\n timer = null;\n running = false;\n void reconnect(false);\n }, delay);\n return;\n }\n } finally {\n if (timer === null || wake !== null) running = false;\n }\n }\n\n return {\n start(): void {\n if (started || stopped) return;\n started = true;\n open();\n },\n stop(): void {\n if (stopped) return;\n stopped = true;\n close();\n if (timer !== null) clearTimeout(timer);\n timer = null;\n wake?.();\n wake = null;\n },\n };\n}\n\nexport interface SnapshotCursorSseOptions<S> {\n snapshotPath: string;\n streamPath: string;\n resolveUrl?: (path: string) => string;\n applySnapshot: (body: S) => void;\n onMessage: (event: MessageEvent) => void;\n retrySnapshotAfter?: (body: S) => number | null;\n onSnapshotError?: (reason: unknown) => void;\n onStreamError?: () => void;\n initialSnapshotRetryMs?: number;\n maxSnapshotRetryMs?: number;\n}\n\nexport interface SnapshotCursorSseChannel {\n start(): Promise<void>;\n stop(): void;\n}\n\nfunction joinQuery(path: string, key: string, value: string): string {\n return `${path}${path.includes(\"?\") ? \"&\" : \"?\"}${key}=${encodeURIComponent(value)}`;\n}\n\nexport function createSnapshotCursorSse<S>(opts: SnapshotCursorSseOptions<S>): SnapshotCursorSseChannel {\n const resolveUrl = opts.resolveUrl ?? ((path: string) => path);\n let subId: string | null = null;\n let subscription: ResilientSseSubscription | null = null;\n let controller: AbortController | null = null;\n let timer: ReturnType<typeof setTimeout> | null = null;\n let wake: (() => void) | null = null;\n let started: Promise<void> | null = null;\n let stopped = false;\n\n function wait(milliseconds: number): Promise<void> {\n return new Promise<void>((resolve) => {\n wake = resolve;\n timer = setTimeout(() => {\n timer = null;\n wake = null;\n resolve();\n }, milliseconds);\n });\n }\n\n async function snapshot(onFirstFailure?: () => void): Promise<void> {\n let delay = opts.initialSnapshotRetryMs ?? 250;\n const maxDelay = opts.maxSnapshotRetryMs ?? 30_000;\n let failed = false;\n while (!stopped) {\n const abort = new AbortController();\n controller = abort;\n try {\n const path = subId === null ? opts.snapshotPath : joinQuery(opts.snapshotPath, \"sub\", subId);\n const response = await fetch(resolveUrl(path), { signal: abort.signal });\n if (!response.ok) throw new Error(`HTTP ${response.status}`);\n const body = (await response.json()) as S;\n const id = response.headers.get(\"x-sub-id\")?.trim();\n if (!id) throw new Error(\"Snapshot response missing non-empty x-sub-id\");\n const retry = opts.retrySnapshotAfter?.(body) ?? null;\n if (retry !== null) {\n if (!Number.isFinite(retry) || retry < 0) throw new Error(\"Invalid snapshot retry delay\");\n await wait(retry);\n continue;\n }\n if (stopped || abort.signal.aborted) return;\n subId = id;\n opts.applySnapshot(body);\n return;\n } catch (reason) {\n if (stopped || abort.signal.aborted) return;\n try {\n opts.onSnapshotError?.(reason);\n } catch {\n // Notification failures must not interrupt recovery.\n }\n if (!failed) onFirstFailure?.();\n failed = true;\n await wait(delay);\n delay = Math.min(delay * 2, maxDelay);\n } finally {\n if (controller === abort) controller = null;\n }\n }\n }\n\n return {\n start(): Promise<void> {\n if (started !== null) return started;\n if (stopped) return Promise.resolve();\n started = new Promise<void>((resolve) => {\n void (async () => {\n await snapshot(resolve);\n if (!stopped && subId !== null) {\n subscription = createResilientSse({\n url: () => resolveUrl(joinQuery(opts.streamPath, \"sub\", subId!)),\n onMessage: opts.onMessage,\n resumeFromLastEventId: true,\n ...(opts.onStreamError ? { onError: opts.onStreamError } : {}),\n onBeforeReconnect: () => snapshot(),\n });\n subscription.start();\n }\n resolve();\n })();\n });\n return started;\n },\n stop(): void {\n if (stopped) return;\n stopped = true;\n controller?.abort();\n subscription?.stop();\n if (timer !== null) clearTimeout(timer);\n timer = null;\n wake?.();\n wake = null;\n },\n };\n}\n"],"names":["createResilientSse","opts","initial","maximum","healthyWindow","source","delay","timer","healthyTimer","wake","running","started","stopped","lastEventId","opened","close","receive","callback","event","open","resume","url","joinQuery","reconnect","name","waitBeforeAttempt","resolve","path","key","value","createSnapshotCursorSse","resolveUrl","subId","subscription","controller","wait","milliseconds","snapshot","onFirstFailure","maxDelay","failed","abort","response","body","id","retry","reason"],"mappings":"gFAiBO,SAASA,EAAmBC,EAAqD,CACtF,MAAMC,EAAUD,EAAK,gBAAkB,IACjCE,EAAUF,EAAK,YAAc,IAC7BG,EAAgBH,EAAK,iBAAmB,IAC9C,IAAII,EAA6B,KAC7BC,EAAQ,EACRC,EAA8C,KAC9CC,EAAqD,KACrDC,EAA4B,KAC5BC,EAAU,GACVC,EAAU,GACVC,EAAU,GACVC,EAA6B,KAC7BC,EAAS,GAEb,SAASC,GAAc,CACrBV,GAAQ,MAAA,EACRA,EAAS,KACLG,IAAiB,MAAM,aAAaA,CAAY,EACpDA,EAAe,IACjB,CAEA,SAASQ,EAAQC,EAAyCC,EAA2B,CAC/EN,IACJE,EAAS,GACLR,EAAQ,GAAKE,IAAiB,OAChCA,EAAe,WAAW,IAAM,CAC9BF,EAAQ,EACRE,EAAe,IACjB,EAAGJ,CAAa,GAElBa,EAASC,CAAK,EACVjB,EAAK,uBAAyBiB,EAAM,gBAA2BA,EAAM,aAC3E,CAEA,SAASC,EAAKC,EAAS,GAAa,CAClC,GAAIR,EAAS,OACbG,EAAA,EACAD,EAAS,GACT,MAAMO,EAAMpB,EAAK,IAAA,EACjBI,EAAS,IAAI,YAAYe,EAASE,EAAUD,EAAK,gBAAiBR,CAAY,EAAIQ,CAAG,EACjFpB,EAAK,wBAAuBI,EAAO,OAAS,IAAM,CAAES,EAAS,EAAM,GACvET,EAAO,UAAaa,GAAUF,EAAQf,EAAK,UAAWiB,CAAK,EAC3Db,EAAO,QAAU,IAAM,CACrB,GAAI,CAAAO,EACJ,IAAI,CACFX,EAAK,UAAA,CACP,MAAQ,CAER,CACKsB,EAAA,EACP,EACA,SAAW,CAACC,EAAMP,CAAQ,IAAK,OAAO,QAAQhB,EAAK,UAAY,CAAA,CAAE,EAC/DI,EAAO,iBAAiBmB,EAAON,GAAUF,EAAQC,EAAUC,CAAqB,CAAC,CAErF,CAEA,eAAeK,EAAUE,EAAoB,GAAqB,CAChE,GAAIf,GAAWE,EAAS,OACxBF,EAAU,GACV,MAAMU,EAAS,GAAQnB,EAAK,uBAAyBY,IAAgB,MAAQC,GAC7EC,EAAA,EACA,GAAI,CAWF,GAVIU,GAAqBnB,EAAQ,GAC/B,MAAM,IAAI,QAAeoB,GAAY,CACnCjB,EAAOiB,EACPnB,EAAQ,WAAW,IAAM,CACvBA,EAAQ,KACRE,EAAO,KACPiB,EAAA,CACF,EAAGpB,CAAK,CACV,CAAC,EAECM,EAAS,OACbN,EAAQ,KAAK,IAAIA,IAAU,EAAIJ,EAAUI,EAAQ,EAAGH,CAAO,EACtDiB,IACHP,EAAc,KACd,MAAMZ,EAAK,oBAAA,GAERW,GAASO,EAAKC,CAAM,CAC3B,MAAQ,CACN,GAAI,CAACR,EAAS,CACZL,EAAQ,WAAW,IAAM,CACvBA,EAAQ,KACRG,EAAU,GACLa,EAAU,EAAK,CACtB,EAAGjB,CAAK,EACR,MACF,CACF,QAAA,EACMC,IAAU,MAAQE,IAAS,QAAMC,EAAU,GACjD,CACF,CAEA,MAAO,CACL,OAAc,CACRC,GAAWC,IACfD,EAAU,GACVQ,EAAA,EACF,EACA,MAAa,CACPP,IACJA,EAAU,GACVG,EAAA,EACIR,IAAU,MAAM,aAAaA,CAAK,EACtCA,EAAQ,KACRE,IAAA,EACAA,EAAO,KACT,CAAA,CAEJ,CAoBA,SAASa,EAAUK,EAAcC,EAAaC,EAAuB,CACnE,MAAO,GAAGF,CAAI,GAAGA,EAAK,SAAS,GAAG,EAAI,IAAM,GAAG,GAAGC,CAAG,IAAI,mBAAmBC,CAAK,CAAC,EACpF,CAEO,SAASC,EAA2B7B,EAA6D,CACtG,MAAM8B,EAAa9B,EAAK,aAAgB0B,GAAiBA,GACzD,IAAIK,EAAuB,KACvBC,EAAgD,KAChDC,EAAqC,KACrC3B,EAA8C,KAC9CE,EAA4B,KAC5BE,EAAgC,KAChCC,EAAU,GAEd,SAASuB,EAAKC,EAAqC,CACjD,OAAO,IAAI,QAAeV,GAAY,CACpCjB,EAAOiB,EACPnB,EAAQ,WAAW,IAAM,CACvBA,EAAQ,KACRE,EAAO,KACPiB,EAAA,CACF,EAAGU,CAAY,CACjB,CAAC,CACH,CAEA,eAAeC,EAASC,EAA4C,CAClE,IAAIhC,EAAQL,EAAK,wBAA0B,IAC3C,MAAMsC,EAAWtC,EAAK,oBAAsB,IAC5C,IAAIuC,EAAS,GACb,KAAO,CAAC5B,GAAS,CACf,MAAM6B,EAAQ,IAAI,gBAClBP,EAAaO,EACb,GAAI,CACF,MAAMd,EAAOK,IAAU,KAAO/B,EAAK,aAAeqB,EAAUrB,EAAK,aAAc,MAAO+B,CAAK,EACrFU,EAAW,MAAM,MAAMX,EAAWJ,CAAI,EAAG,CAAE,OAAQc,EAAM,OAAQ,EACvE,GAAI,CAACC,EAAS,GAAI,MAAM,IAAI,MAAM,QAAQA,EAAS,MAAM,EAAE,EAC3D,MAAMC,EAAQ,MAAMD,EAAS,KAAA,EACvBE,EAAKF,EAAS,QAAQ,IAAI,UAAU,GAAG,KAAA,EAC7C,GAAI,CAACE,EAAI,MAAM,IAAI,MAAM,8CAA8C,EACvE,MAAMC,EAAQ5C,EAAK,qBAAqB0C,CAAI,GAAK,KACjD,GAAIE,IAAU,KAAM,CAClB,GAAI,CAAC,OAAO,SAASA,CAAK,GAAKA,EAAQ,EAAG,MAAM,IAAI,MAAM,8BAA8B,EACxF,MAAMV,EAAKU,CAAK,EAChB,QACF,CACA,GAAIjC,GAAW6B,EAAM,OAAO,QAAS,OACrCT,EAAQY,EACR3C,EAAK,cAAc0C,CAAI,EACvB,MACF,OAASG,EAAQ,CACf,GAAIlC,GAAW6B,EAAM,OAAO,QAAS,OACrC,GAAI,CACFxC,EAAK,kBAAkB6C,CAAM,CAC/B,MAAQ,CAER,CACKN,GAAQF,IAAA,EACbE,EAAS,GACT,MAAML,EAAK7B,CAAK,EAChBA,EAAQ,KAAK,IAAIA,EAAQ,EAAGiC,CAAQ,CACtC,QAAA,CACML,IAAeO,IAAOP,EAAa,KACzC,CACF,CACF,CAEA,MAAO,CACL,OAAuB,CACrB,OAAIvB,IAAY,KAAaA,EACzBC,EAAgB,QAAQ,QAAA,GAC5BD,EAAU,IAAI,QAAee,GAAY,EACjC,UACJ,MAAMW,EAASX,CAAO,EAClB,CAACd,GAAWoB,IAAU,OACxBC,EAAejC,EAAmB,CAChC,IAAK,IAAM+B,EAAWT,EAAUrB,EAAK,WAAY,MAAO+B,CAAM,CAAC,EAC/D,UAAW/B,EAAK,UAChB,sBAAuB,GACvB,GAAIA,EAAK,cAAgB,CAAE,QAASA,EAAK,aAAA,EAAkB,CAAA,EAC3D,kBAAmB,IAAMoC,EAAA,CAAS,CACnC,EACDJ,EAAa,MAAA,GAEfP,EAAA,KAEJ,CAAC,EACMf,EACT,EACA,MAAa,CACPC,IACJA,EAAU,GACVsB,GAAY,MAAA,EACZD,GAAc,KAAA,EACV1B,IAAU,MAAM,aAAaA,CAAK,EACtCA,EAAQ,KACRE,IAAA,EACAA,EAAO,KACT,CAAA,CAEJ"}

package/dist/index.js.map DELETED Viewed

@@ -1 +0,0 @@

- {"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":["export interface ResilientSseOptions {\n url: () => string;\n onMessage: (event: MessageEvent) => void;\n onEvents?: Record<string, (event: MessageEvent) => void>;\n onBeforeReconnect?: () => void | Promise<void>;\n resumeFromLastEventId?: boolean;\n onError?: () => void;\n initialDelayMs?: number;\n maxDelayMs?: number;\n healthyWindowMs?: number;\n}\n\nexport interface ResilientSseSubscription {\n start(): void;\n stop(): void;\n}\n\nexport function createResilientSse(opts: ResilientSseOptions): ResilientSseSubscription {\n const initial = opts.initialDelayMs ?? 250;\n const maximum = opts.maxDelayMs ?? 30_000;\n const healthyWindow = opts.healthyWindowMs ?? 5_000;\n let source: EventSource | null = null;\n let delay = 0;\n let timer: ReturnType<typeof setTimeout> | null = null;\n let healthyTimer: ReturnType<typeof setTimeout> | null = null;\n let wake: (() => void) | null = null;\n let running = false;\n let started = false;\n let stopped = false;\n let lastEventId: string | null = null;\n let opened = false;\n\n function close(): void {\n source?.close();\n source = null;\n if (healthyTimer !== null) clearTimeout(healthyTimer);\n healthyTimer = null;\n }\n\n function receive(callback: (event: MessageEvent) => void, event: MessageEvent): void {\n if (stopped) return;\n opened = true;\n if (delay > 0 && healthyTimer === null) {\n healthyTimer = setTimeout(() => {\n delay = 0;\n healthyTimer = null;\n }, healthyWindow);\n }\n callback(event);\n if (opts.resumeFromLastEventId && event.lastEventId) lastEventId = event.lastEventId;\n }\n\n function open(resume = false): void {\n if (stopped) return;\n close();\n opened = false;\n const url = opts.url();\n source = new EventSource(resume ? joinQuery(url, \"last_event_id\", lastEventId!) : url);\n if (opts.resumeFromLastEventId) source.onopen = () => { opened = true; };\n source.onmessage = (event) => receive(opts.onMessage, event);\n source.onerror = () => {\n if (stopped) return;\n try {\n opts.onError?.();\n } catch {\n // Notification failures must not interrupt recovery.\n }\n void reconnect();\n };\n for (const [name, callback] of Object.entries(opts.onEvents ?? {})) {\n source.addEventListener(name, (event) => receive(callback, event as MessageEvent));\n }\n }\n\n async function reconnect(waitBeforeAttempt = true): Promise<void> {\n if (running || stopped) return;\n running = true;\n const resume = Boolean(opts.resumeFromLastEventId && lastEventId !== null && opened);\n close();\n try {\n if (waitBeforeAttempt && delay > 0) {\n await new Promise<void>((resolve) => {\n wake = resolve;\n timer = setTimeout(() => {\n timer = null;\n wake = null;\n resolve();\n }, delay);\n });\n }\n if (stopped) return;\n delay = Math.min(delay === 0 ? initial : delay * 2, maximum);\n if (!resume) {\n lastEventId = null;\n await opts.onBeforeReconnect?.();\n }\n if (!stopped) open(resume);\n } catch {\n if (!stopped) {\n timer = setTimeout(() => {\n timer = null;\n running = false;\n void reconnect(false);\n }, delay);\n return;\n }\n } finally {\n if (timer === null || wake !== null) running = false;\n }\n }\n\n return {\n start(): void {\n if (started || stopped) return;\n started = true;\n open();\n },\n stop(): void {\n if (stopped) return;\n stopped = true;\n close();\n if (timer !== null) clearTimeout(timer);\n timer = null;\n wake?.();\n wake = null;\n },\n };\n}\n\nexport interface SnapshotCursorSseOptions<S> {\n snapshotPath: string;\n streamPath: string;\n resolveUrl?: (path: string) => string;\n applySnapshot: (body: S) => void;\n onMessage: (event: MessageEvent) => void;\n retrySnapshotAfter?: (body: S) => number | null;\n onSnapshotError?: (reason: unknown) => void;\n onStreamError?: () => void;\n initialSnapshotRetryMs?: number;\n maxSnapshotRetryMs?: number;\n}\n\nexport interface SnapshotCursorSseChannel {\n start(): Promise<void>;\n stop(): void;\n}\n\nfunction joinQuery(path: string, key: string, value: string): string {\n return `${path}${path.includes(\"?\") ? \"&\" : \"?\"}${key}=${encodeURIComponent(value)}`;\n}\n\nexport function createSnapshotCursorSse<S>(opts: SnapshotCursorSseOptions<S>): SnapshotCursorSseChannel {\n const resolveUrl = opts.resolveUrl ?? ((path: string) => path);\n let subId: string | null = null;\n let subscription: ResilientSseSubscription | null = null;\n let controller: AbortController | null = null;\n let timer: ReturnType<typeof setTimeout> | null = null;\n let wake: (() => void) | null = null;\n let started: Promise<void> | null = null;\n let stopped = false;\n\n function wait(milliseconds: number): Promise<void> {\n return new Promise<void>((resolve) => {\n wake = resolve;\n timer = setTimeout(() => {\n timer = null;\n wake = null;\n resolve();\n }, milliseconds);\n });\n }\n\n async function snapshot(onFirstFailure?: () => void): Promise<void> {\n let delay = opts.initialSnapshotRetryMs ?? 250;\n const maxDelay = opts.maxSnapshotRetryMs ?? 30_000;\n let failed = false;\n while (!stopped) {\n const abort = new AbortController();\n controller = abort;\n try {\n const path = subId === null ? opts.snapshotPath : joinQuery(opts.snapshotPath, \"sub\", subId);\n const response = await fetch(resolveUrl(path), { signal: abort.signal });\n if (!response.ok) throw new Error(`HTTP ${response.status}`);\n const body = (await response.json()) as S;\n const id = response.headers.get(\"x-sub-id\")?.trim();\n if (!id) throw new Error(\"Snapshot response missing non-empty x-sub-id\");\n const retry = opts.retrySnapshotAfter?.(body) ?? null;\n if (retry !== null) {\n if (!Number.isFinite(retry) || retry < 0) throw new Error(\"Invalid snapshot retry delay\");\n await wait(retry);\n continue;\n }\n if (stopped || abort.signal.aborted) return;\n subId = id;\n opts.applySnapshot(body);\n return;\n } catch (reason) {\n if (stopped || abort.signal.aborted) return;\n try {\n opts.onSnapshotError?.(reason);\n } catch {\n // Notification failures must not interrupt recovery.\n }\n if (!failed) onFirstFailure?.();\n failed = true;\n await wait(delay);\n delay = Math.min(delay * 2, maxDelay);\n } finally {\n if (controller === abort) controller = null;\n }\n }\n }\n\n return {\n start(): Promise<void> {\n if (started !== null) return started;\n if (stopped) return Promise.resolve();\n started = new Promise<void>((resolve) => {\n void (async () => {\n await snapshot(resolve);\n if (!stopped && subId !== null) {\n subscription = createResilientSse({\n url: () => resolveUrl(joinQuery(opts.streamPath, \"sub\", subId!)),\n onMessage: opts.onMessage,\n resumeFromLastEventId: true,\n ...(opts.onStreamError ? { onError: opts.onStreamError } : {}),\n onBeforeReconnect: () => snapshot(),\n });\n subscription.start();\n }\n resolve();\n })();\n });\n return started;\n },\n stop(): void {\n if (stopped) return;\n stopped = true;\n controller?.abort();\n subscription?.stop();\n if (timer !== null) clearTimeout(timer);\n timer = null;\n wake?.();\n wake = null;\n },\n };\n}\n"],"names":["createResilientSse","opts","initial","maximum","healthyWindow","source","delay","timer","healthyTimer","wake","running","started","stopped","lastEventId","opened","close","receive","callback","event","open","resume","url","joinQuery","reconnect","name","waitBeforeAttempt","resolve","path","key","value","createSnapshotCursorSse","resolveUrl","subId","subscription","controller","wait","milliseconds","snapshot","onFirstFailure","maxDelay","failed","abort","response","body","id","retry","reason"],"mappings":"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"}