easy-ping 0.5.0 → 0.6.1

package/dist/client.d.cts

@@ -19,14 +19,70 @@ type NotifyState = {
     isLoading: boolean;
     error: Error | null;
 };
+type Transport = "auto" | "sse" | "poll";
+type TransportStatus = {
+    /** "leader" holds this browser's single connection; "follower" mirrors it; "solo" has no Web Locks. */
+    role: "leader" | "follower" | "solo";
+    /** What the leader is using right now. */
+    transport: "sse" | "poll";
+    /** True while the event stream has said `ready` and not since closed. */
+    connected: boolean;
+};
+type LockManagerLike = {
+    request(name: string, options: {
+        mode: "exclusive";
+        signal?: AbortSignal;
+    }, callback: () => Promise<void>): Promise<void>;
+};
+type ChannelLike = {
+    postMessage(message: unknown): void;
+    addEventListener(type: "message", handler: (event: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: "message", handler: (event: {
+        data: unknown;
+    }) => void): void;
+    close(): void;
+};
+type MessageTargetLike = {
+    addEventListener(type: string, handler: (event: {
+        data?: unknown;
+    }) => void): void;
+    removeEventListener(type: string, handler: (event: {
+        data?: unknown;
+    }) => void): void;
+};
 type NotifyClientOptions = {
     baseUrl?: string | undefined;
     fetch?: typeof globalThis.fetch | undefined;
     limit?: number | undefined;
+    /** Poll interval while the user is active and no stream is connected. Default 15 s. */
     pollIntervalMs?: number | undefined;
+    /** Ceiling the idle backoff grows to. Default 10 min. */
     maxPollIntervalMs?: number | undefined;
+    /** Poll interval while the event stream is connected: a safety net. Default 5 min. */
+    safetyNetMs?: number | undefined;
+    /** How long after user input polling stays at the base interval. Default 60 s. */
+    activeWindowMs?: number | undefined;
+    /** "auto" streams when a DOM is present, "poll" never streams, "sse" always tries. */
+    transport?: Transport | undefined;
     /** Injectable so the poller can be tested without a DOM. */
     isDocumentHidden?: (() => boolean) | undefined;
+    /** Web Locks, for one connection per browser. Defaults to navigator.locks; null disables. */
+    locks?: LockManagerLike | null | undefined;
+    /** Cross-tab channel factory. Defaults to BroadcastChannel; null disables. */
+    channel?: (() => ChannelLike) | null | undefined;
+    /** Where push relays arrive. Defaults to navigator.serviceWorker; null disables. */
+    serviceWorker?: MessageTargetLike | null | undefined;
+    /** Where user activity is observed. Defaults to window; null disables. */
+    activityTarget?: MessageTargetLike | null | undefined;
+    now?: (() => number) | undefined;
+    /**
+     * Separates browsers' tab groups when identity is not a cookie: pass the
+     * current user's id (or session id) so tabs signed in as different users
+     * never share a leader or mirror each other's inbox.
+     */
+    scope?: string | undefined;
 };
 declare function createNotifyClient(options?: NotifyClientOptions): {
     subscribe: (listener: (state: NotifyState) => void) => () => void;
@@ -35,8 +91,10 @@ declare function createNotifyClient(options?: NotifyClientOptions): {
     markAsRead: (id: string) => Promise<void>;
     markAllRead: () => Promise<void>;
     markSeen: () => Promise<void>;
+    instrument: (inner: typeof globalThis.fetch) => typeof globalThis.fetch;
     getState: () => NotifyState;
+    getTransport: () => TransportStatus;
 };
 type NotifyClient = ReturnType<typeof createNotifyClient>;
 
-export { type NotificationView, type NotifyClient, type NotifyClientOptions, type NotifyState, createNotifyClient };
+export { type NotificationView, type NotifyClient, type NotifyClientOptions, type NotifyState, type Transport, type TransportStatus, createNotifyClient };

package/dist/client.d.ts

@@ -19,14 +19,70 @@ type NotifyState = {
     isLoading: boolean;
     error: Error | null;
 };
+type Transport = "auto" | "sse" | "poll";
+type TransportStatus = {
+    /** "leader" holds this browser's single connection; "follower" mirrors it; "solo" has no Web Locks. */
+    role: "leader" | "follower" | "solo";
+    /** What the leader is using right now. */
+    transport: "sse" | "poll";
+    /** True while the event stream has said `ready` and not since closed. */
+    connected: boolean;
+};
+type LockManagerLike = {
+    request(name: string, options: {
+        mode: "exclusive";
+        signal?: AbortSignal;
+    }, callback: () => Promise<void>): Promise<void>;
+};
+type ChannelLike = {
+    postMessage(message: unknown): void;
+    addEventListener(type: "message", handler: (event: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: "message", handler: (event: {
+        data: unknown;
+    }) => void): void;
+    close(): void;
+};
+type MessageTargetLike = {
+    addEventListener(type: string, handler: (event: {
+        data?: unknown;
+    }) => void): void;
+    removeEventListener(type: string, handler: (event: {
+        data?: unknown;
+    }) => void): void;
+};
 type NotifyClientOptions = {
     baseUrl?: string | undefined;
     fetch?: typeof globalThis.fetch | undefined;
     limit?: number | undefined;
+    /** Poll interval while the user is active and no stream is connected. Default 15 s. */
     pollIntervalMs?: number | undefined;
+    /** Ceiling the idle backoff grows to. Default 10 min. */
     maxPollIntervalMs?: number | undefined;
+    /** Poll interval while the event stream is connected: a safety net. Default 5 min. */
+    safetyNetMs?: number | undefined;
+    /** How long after user input polling stays at the base interval. Default 60 s. */
+    activeWindowMs?: number | undefined;
+    /** "auto" streams when a DOM is present, "poll" never streams, "sse" always tries. */
+    transport?: Transport | undefined;
     /** Injectable so the poller can be tested without a DOM. */
     isDocumentHidden?: (() => boolean) | undefined;
+    /** Web Locks, for one connection per browser. Defaults to navigator.locks; null disables. */
+    locks?: LockManagerLike | null | undefined;
+    /** Cross-tab channel factory. Defaults to BroadcastChannel; null disables. */
+    channel?: (() => ChannelLike) | null | undefined;
+    /** Where push relays arrive. Defaults to navigator.serviceWorker; null disables. */
+    serviceWorker?: MessageTargetLike | null | undefined;
+    /** Where user activity is observed. Defaults to window; null disables. */
+    activityTarget?: MessageTargetLike | null | undefined;
+    now?: (() => number) | undefined;
+    /**
+     * Separates browsers' tab groups when identity is not a cookie: pass the
+     * current user's id (or session id) so tabs signed in as different users
+     * never share a leader or mirror each other's inbox.
+     */
+    scope?: string | undefined;
 };
 declare function createNotifyClient(options?: NotifyClientOptions): {
     subscribe: (listener: (state: NotifyState) => void) => () => void;
@@ -35,8 +91,10 @@ declare function createNotifyClient(options?: NotifyClientOptions): {
     markAsRead: (id: string) => Promise<void>;
     markAllRead: () => Promise<void>;
     markSeen: () => Promise<void>;
+    instrument: (inner: typeof globalThis.fetch) => typeof globalThis.fetch;
     getState: () => NotifyState;
+    getTransport: () => TransportStatus;
 };
 type NotifyClient = ReturnType<typeof createNotifyClient>;
 
-export { type NotificationView, type NotifyClient, type NotifyClientOptions, type NotifyState, createNotifyClient };
+export { type NotificationView, type NotifyClient, type NotifyClientOptions, type NotifyState, type Transport, type TransportStatus, createNotifyClient };

package/dist/client.js

@@ -8,22 +8,63 @@ var INITIAL = {
   error: null
 };
 var countUnread = (rows) => rows.reduce((total, row) => row.readAt === null ? total + 1 : total, 0);
+var SHORT_STREAM_MS = 15e3;
+var SHORT_STREAMS_BEFORE_GIVING_UP = 3;
 function createNotifyClient(options = {}) {
   const baseUrl = (options.baseUrl ?? "/api/notifications").replace(/\/$/, "");
   const doFetch = options.fetch ?? ((...args) => globalThis.fetch(...args));
   const limit = options.limit ?? 20;
   const pollIntervalMs = options.pollIntervalMs ?? 15e3;
-  const maxPollIntervalMs = options.maxPollIntervalMs ?? 5 * 6e4;
+  const maxPollIntervalMs = options.maxPollIntervalMs ?? 10 * 6e4;
+  const safetyNetMs = options.safetyNetMs ?? 5 * 6e4;
+  const activeWindowMs = options.activeWindowMs ?? 6e4;
+  const now = options.now ?? (() => Date.now());
+  const groupKey = options.scope ? `${baseUrl}#${options.scope}` : baseUrl;
+  const hasDom = typeof window !== "undefined" && typeof document !== "undefined";
+  const transport = options.transport ?? "auto";
+  const wantsStream = transport === "sse" || transport === "auto" && hasDom;
   const isHidden = options.isDocumentHidden ?? (() => typeof document !== "undefined" && document.visibilityState === "hidden");
+  const locks = options.locks === void 0 ? typeof navigator !== "undefined" ? navigator.locks ?? null : null : options.locks;
+  const makeChannel = options.channel === void 0 ? typeof BroadcastChannel !== "undefined" ? () => new BroadcastChannel(`easy-ping:${groupKey}`) : null : options.channel;
+  const serviceWorker = options.serviceWorker === void 0 ? typeof navigator !== "undefined" ? navigator.serviceWorker ?? null : null : options.serviceWorker;
+  const activityTarget = options.activityTarget === void 0 ? hasDom ? window : null : options.activityTarget;
   let state = INITIAL;
   const listeners = /* @__PURE__ */ new Set();
+  let role = "solo";
+  let running = false;
+  let channel;
+  let releaseLock;
+  let lockAbort;
   let timer;
   let consecutiveFailures = 0;
+  let idleTicks = 0;
+  let activeUntil = 0;
+  let lastRefreshAt = 0;
+  let refreshing;
+  let refreshAgain = false;
+  let streamAbort;
+  let streamConnected = false;
+  let streamDisabled = !wantsStream;
+  let shortStreams = 0;
+  let streamFailures = 0;
   let generation = 0;
+  const localReads = /* @__PURE__ */ new Set();
+  let localSeen = false;
+  const stamp = () => (/* @__PURE__ */ new Date()).toISOString();
+  function emit() {
+    for (const listener of listeners) listener(state);
+  }
   function set(patch) {
     state = { ...state, ...patch };
     state = { ...state, unreadCount: countUnread(state.notifications) };
-    for (const listener of listeners) listener(state);
+    emit();
+    if (role === "leader") post({ type: "state", state });
+  }
+  function post(message) {
+    try {
+      channel?.postMessage(message);
+    } catch {
+    }
   }
   async function request(path, init) {
     const response = await doFetch(`${baseUrl}${path}`, {
@@ -34,7 +75,7 @@ function createNotifyClient(options = {}) {
       throw new Error(`${init?.method ?? "GET"} ${path} failed: ${response.status}`);
     return await response.json();
   }
-  async function refresh() {
+  async function fetchPage() {
     const startedAt = generation;
     const page = await request(`/?limit=${limit}`);
     const unseenCount = page.unseenCount ?? (await request("/count")).unseen;
@@ -47,6 +88,24 @@ function createNotifyClient(options = {}) {
       error: null
     });
   }
+  function refresh() {
+    if (refreshing) {
+      refreshAgain = true;
+      return refreshing;
+    }
+    refreshing = (async () => {
+      try {
+        do {
+          refreshAgain = false;
+          await fetchPage();
+          lastRefreshAt = now();
+        } while (refreshAgain);
+      } finally {
+        refreshing = void 0;
+      }
+    })();
+    return refreshing;
+  }
   let loadingMore;
   async function loadMore() {
     if (!state.nextCursor) return;
@@ -75,30 +134,39 @@ function createNotifyClient(options = {}) {
     set({ notifications: apply(state.notifications), ...patch });
     try {
       await send();
+      if (role === "follower") post({ type: "mutated" });
     } catch (error) {
       generation += 1;
       state = previous;
-      for (const listener of listeners) listener(state);
+      emit();
       throw error;
     }
   }
-  const stamp = () => (/* @__PURE__ */ new Date()).toISOString();
   async function markAsRead(id) {
+    if (role === "follower") localReads.add(id);
     await optimistic(
       (rows) => rows.map((row) => row.id === id ? { ...row, readAt: row.readAt ?? stamp() } : row),
       {},
       () => request("/read", { method: "POST", body: JSON.stringify({ ids: [id] }) })
-    );
+    ).catch((error) => {
+      localReads.delete(id);
+      throw error;
+    });
   }
   async function markAllRead() {
+    if (role === "follower") for (const row of state.notifications) localReads.add(row.id);
     await optimistic(
       (rows) => rows.map((row) => ({ ...row, readAt: row.readAt ?? stamp() })),
       {},
       () => request("/read-all", { method: "POST" })
-    );
+    ).catch((error) => {
+      localReads.clear();
+      throw error;
+    });
   }
   async function markSeen() {
     const newest = state.notifications[0]?.createdAt;
+    if (role === "follower") localSeen = true;
     await optimistic(
       (rows) => rows.map((row) => ({ ...row, seenAt: row.seenAt ?? stamp() })),
       { unseenCount: 0 },
@@ -106,13 +174,55 @@ function createNotifyClient(options = {}) {
         method: "POST",
         body: JSON.stringify(newest ? { before: newest } : {})
       })
-    );
+    ).catch((error) => {
+      localSeen = false;
+      throw error;
+    });
+  }
+  function applyRemoteState(remote) {
+    const notifications = remote.notifications.map((row) => {
+      if (!localReads.has(row.id)) return row;
+      if (row.readAt) {
+        localReads.delete(row.id);
+        return row;
+      }
+      return { ...row, readAt: stamp() };
+    });
+    if (localSeen && remote.unseenCount === 0) localSeen = false;
+    state = {
+      ...remote,
+      notifications,
+      unseenCount: localSeen ? 0 : remote.unseenCount,
+      unreadCount: countUnread(notifications)
+    };
+    emit();
+  }
+  function onTabMessage(event) {
+    const message = event.data;
+    if (!message || typeof message !== "object") return;
+    if (role === "leader") {
+      if (message.type === "hello") post({ type: "state", state });
+      else if (message.type === "mutated") void refresh().catch(() => {
+      });
+      return;
+    }
+    if (message.type === "state") applyRemoteState(message.state);
   }
   function schedule(delay) {
     clearTimeout(timer);
     timer = setTimeout(tick, delay);
   }
+  function nextDelay() {
+    if (consecutiveFailures > 0) {
+      return Math.min(pollIntervalMs * 2 ** consecutiveFailures, maxPollIntervalMs);
+    }
+    if (streamConnected) return safetyNetMs;
+    if (now() < activeUntil) return pollIntervalMs;
+    idleTicks += 1;
+    return Math.min(pollIntervalMs * 2 ** idleTicks, maxPollIntervalMs);
+  }
   async function tick() {
+    if (!running) return;
     if (isHidden()) {
       schedule(pollIntervalMs);
       return;
@@ -124,20 +234,184 @@ function createNotifyClient(options = {}) {
       consecutiveFailures += 1;
       set({ isLoading: false, error: error instanceof Error ? error : new Error(String(error)) });
     }
-    schedule(
-      consecutiveFailures === 0 ? pollIntervalMs : Math.min(pollIntervalMs * 2 ** consecutiveFailures, maxPollIntervalMs)
-    );
+    if (running) schedule(nextDelay());
+  }
+  function onActivity() {
+    if (!running || role === "follower") return;
+    activeUntil = now() + activeWindowMs;
+    idleTicks = 0;
+    if (!isHidden() && now() - lastRefreshAt > pollIntervalMs) {
+      void refresh().catch(() => {
+      });
+      schedule(nextDelay());
+    }
+  }
+  const onVisibility = () => {
+    if (!isHidden()) onActivity();
+  };
+  const ACTIVITY_EVENTS = ["focus", "pointerdown", "keydown", "online"];
+  function changed() {
+    if (!running) return;
+    void refresh().catch(() => {
+    });
+  }
+  async function readStream(signal) {
+    const openedAt = now();
+    const response = await doFetch(`${baseUrl}/events`, {
+      headers: { accept: "text/event-stream" },
+      signal
+    });
+    if (!response.ok || !response.body) throw new Error(`GET /events failed: ${response.status}`);
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let eventName = "";
+    try {
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        let newline = buffer.indexOf("\n");
+        while (newline >= 0) {
+          const line = buffer.slice(0, newline).replace(/\r$/, "");
+          buffer = buffer.slice(newline + 1);
+          if (line === "") {
+            if (eventName === "ready") {
+              streamConnected = true;
+              streamFailures = 0;
+              schedule(nextDelay());
+            } else if (eventName === "changed") changed();
+            eventName = "";
+          } else if (line.startsWith("event:")) eventName = line.slice(6).trim();
+          newline = buffer.indexOf("\n");
+        }
+      }
+    } finally {
+      streamConnected = false;
+      if (now() - openedAt < SHORT_STREAM_MS) shortStreams += 1;
+      else shortStreams = 0;
+    }
+  }
+  const isFollower = () => role === "follower";
+  async function streamLoop() {
+    while (running && !streamDisabled && !isFollower()) {
+      streamAbort = new AbortController();
+      try {
+        await readStream(streamAbort.signal);
+      } catch {
+        if (!running) return;
+        streamFailures += 1;
+      }
+      if (!running || isFollower()) return;
+      if (shortStreams >= SHORT_STREAMS_BEFORE_GIVING_UP) {
+        streamDisabled = true;
+        schedule(nextDelay());
+        return;
+      }
+      await new Promise(
+        (resolve) => setTimeout(resolve, Math.min(3e3 * 2 ** streamFailures, 6e4))
+      );
+    }
+  }
+  function becomeLeader() {
+    role = "leader";
+    post({ type: "leader" });
+    post({ type: "state", state });
+    void tick();
+    if (!streamDisabled) void streamLoop();
+  }
+  function becomeFollower() {
+    role = "follower";
+    post({ type: "hello" });
+  }
+  function acquireLeadership() {
+    if (!locks || !channel) {
+      role = "solo";
+      void tick();
+      if (!streamDisabled) void streamLoop();
+      return;
+    }
+    becomeFollower();
+    lockAbort = new AbortController();
+    locks.request(
+      `easy-ping:leader:${groupKey}`,
+      { mode: "exclusive", signal: lockAbort.signal },
+      () => new Promise((resolve) => {
+        releaseLock = resolve;
+        if (running) becomeLeader();
+        else resolve();
+      })
+    ).catch(() => {
+    });
+  }
+  function start() {
+    running = true;
+    channel = makeChannel ? makeChannel() : void 0;
+    channel?.addEventListener("message", onTabMessage);
+    serviceWorker?.addEventListener("message", onRelay);
+    if (activityTarget) {
+      for (const name of ACTIVITY_EVENTS) activityTarget.addEventListener(name, onActivity);
+    }
+    if (typeof document !== "undefined") {
+      document.addEventListener("visibilitychange", onVisibility);
+    }
+    activeUntil = now() + activeWindowMs;
+    acquireLeadership();
+  }
+  function stop() {
+    running = false;
+    clearTimeout(timer);
+    timer = void 0;
+    streamAbort?.abort();
+    streamAbort = void 0;
+    lockAbort?.abort();
+    lockAbort = void 0;
+    releaseLock?.();
+    releaseLock = void 0;
+    channel?.removeEventListener("message", onTabMessage);
+    channel?.close();
+    channel = void 0;
+    serviceWorker?.removeEventListener("message", onRelay);
+    if (activityTarget) {
+      for (const name of ACTIVITY_EVENTS) activityTarget.removeEventListener(name, onActivity);
+    }
+    if (typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", onVisibility);
+    }
+    role = "solo";
+  }
+  function onRelay(event) {
+    const data = event.data;
+    if (data?.source === "easy-ping" && data.type === "changed") changed();
+  }
+  let lastInboxVersion = null;
+  const sameOrigin = (response) => {
+    if (!response.url || typeof location === "undefined") return true;
+    try {
+      return new URL(response.url).origin === location.origin;
+    } catch {
+      return false;
+    }
+  };
+  function instrument(inner) {
+    return (async (...args) => {
+      const response = await inner(...args);
+      const version = sameOrigin(response) ? response.headers.get("x-easy-ping-inbox") : null;
+      if (version !== null && version !== lastInboxVersion) {
+        const first = lastInboxVersion === null;
+        lastInboxVersion = version;
+        if (!first && role !== "follower") changed();
+      }
+      return response;
+    });
   }
   function subscribe(listener) {
     listeners.add(listener);
     listener(state);
-    if (listeners.size === 1) void tick();
+    if (listeners.size === 1) start();
     return () => {
       listeners.delete(listener);
-      if (listeners.size === 0) {
-        clearTimeout(timer);
-        timer = void 0;
-      }
+      if (listeners.size === 0) stop();
     };
   }
   return {
@@ -147,7 +421,13 @@ function createNotifyClient(options = {}) {
     markAsRead,
     markAllRead,
     markSeen,
-    getState: () => state
+    instrument,
+    getState: () => state,
+    getTransport: () => ({
+      role,
+      transport: streamDisabled ? "poll" : "sse",
+      connected: streamConnected
+    })
   };
 }