pending-task-kit 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,8 +1,37 @@
 // src/store.ts
 import { create } from "zustand";
 import { createJSONStorage, persist } from "zustand/middleware";
+
+// src/safe-storage.ts
+function safeGetItem(key) {
+  try {
+    if (typeof localStorage === "undefined") return null;
+    return localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+function safeSetItem(key, value) {
+  try {
+    if (typeof localStorage === "undefined") return false;
+    localStorage.setItem(key, value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function safeRemoveItem(key) {
+  try {
+    if (typeof localStorage === "undefined") return;
+    localStorage.removeItem(key);
+  } catch {
+  }
+}
+
+// src/store.ts
 var DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
 var DEFAULT_STORAGE_KEY = "pending-tasks";
+var DEFAULT_TASK_LIST_WARN_THRESHOLD = 200;
 function isPendingTaskShape(value) {
   if (!value || typeof value !== "object") return false;
   const t = value;
@@ -20,13 +49,25 @@ function parseTasksFromStorageValue(value) {
   }
 }
 function readPersistedTasks(storageKey) {
-  if (typeof localStorage === "undefined") return [];
-  return parseTasksFromStorageValue(localStorage.getItem(storageKey));
+  return parseTasksFromStorageValue(safeGetItem(storageKey));
 }
 function createPendingTaskStore(options = {}) {
   const storageKey = options.storageKey ?? DEFAULT_STORAGE_KEY;
+  const taskListWarnThreshold = options.taskListWarnThreshold === void 0 || Number.isNaN(options.taskListWarnThreshold) ? DEFAULT_TASK_LIST_WARN_THRESHOLD : options.taskListWarnThreshold;
   const readPersisted = () => readPersistedTasks(storageKey);
+  let hasWarnedAboutTaskListSize = false;
+  const warnIfTaskListTooLarge = (length) => {
+    if (hasWarnedAboutTaskListSize || length <= taskListWarnThreshold) return;
+    hasWarnedAboutTaskListSize = true;
+    try {
+      console.warn(
+        `pending-task-kit: tracking ${length} tasks for storageKey "${storageKey}", past the soft warning threshold of ${taskListWarnThreshold}. The whole list is persisted as a single localStorage entry on every change \u2014 a very large list risks the ~5MB per-origin quota and slows down every write. Consider pruning stale tasks more aggressively (see pruneTasksBy), or pass a higher taskListWarnThreshold if this app genuinely needs to track this many.`
+      );
+    } catch {
+    }
+  };
   const writeTasks = (tasks) => {
+    warnIfTaskListTooLarge(tasks.length);
     try {
       useStore.setState({ tasks });
       useStore.hasUnpersistedWrites = false;
@@ -60,7 +101,15 @@ function createPendingTaskStore(options = {}) {
       {
         name: storageKey,
         storage: createJSONStorage(() => localStorage),
-        partialize: (state) => ({ tasks: state.tasks })
+        partialize: (state) => ({ tasks: state.tasks }),
+        // The one path that bypasses `writeTasks` (and so its size-warning check) entirely:
+        // zustand's own initial rehydrate-from-storage on store creation calls its internal
+        // `setState` directly, not through `writeTasks`. Without this, an app that starts up
+        // with an already-oversized persisted list would only ever get warned on its *next*
+        // mutation, not on load — the case this app most needs the warning for.
+        onRehydrateStorage: () => (state) => {
+          if (state) warnIfTaskListTooLarge(state.tasks.length);
+        }
       }
     )
   );
@@ -88,32 +137,6 @@ function createPendingTaskRegistryBinding(store, registry) {
   return { addTask, addTaskIfMissing };
 }
 
-// src/safe-storage.ts
-function safeGetItem(key) {
-  try {
-    if (typeof localStorage === "undefined") return null;
-    return localStorage.getItem(key);
-  } catch {
-    return null;
-  }
-}
-function safeSetItem(key, value) {
-  try {
-    if (typeof localStorage === "undefined") return false;
-    localStorage.setItem(key, value);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function safeRemoveItem(key) {
-  try {
-    if (typeof localStorage === "undefined") return;
-    localStorage.removeItem(key);
-  } catch {
-  }
-}
-
 // src/poll-lease.ts
 function readLease(storageKey) {
   const raw = safeGetItem(storageKey);
@@ -219,6 +242,10 @@ var PendingTaskPoller = class {
     this.isChecking = false;
     this.pendingForce = false;
     this.stopped = false;
+    /** This tab's own most recently reported leadership status, for `onLeaderChange` — tracked
+     *  here (rather than derived fresh each time from `fence`) purely so that callback fires only
+     *  on an actual flip, not once per tick it happens to still hold/still lack leadership. */
+    this.isLeaderTab = false;
     /** Task ids that already got their one `finalCheckOnExpiry` attempt, so a repeatedly-failing
      *  final check doesn't get retried every tick. Reset on process restart — worst case that
      *  costs one extra check, never an infinite retry loop.
@@ -248,7 +275,9 @@ var PendingTaskPoller = class {
       onResult: options.onResult,
       onCheckError: options.onCheckError,
       claimResultOnce: options.claimResultOnce,
-      acceptRelayedResult: options.acceptRelayedResult
+      acceptRelayedResult: options.acceptRelayedResult,
+      onLeaderChange: options.onLeaderChange,
+      onTick: options.onTick
     };
     this.ownerId = generatePollOwnerId();
     this.pollLease = createPollLeaseClaimer(this.options.pollLeaseKey, this.options.pollLeaseTtlMs);
@@ -291,6 +320,7 @@ var PendingTaskPoller = class {
   stop() {
     this.stopped = true;
     this.pendingForce = false;
+    this.inFlightAbortController?.abort();
     if (this.intervalId !== void 0) {
       clearInterval(this.intervalId);
       this.intervalId = void 0;
@@ -301,6 +331,7 @@ var PendingTaskPoller = class {
     }
     if (this.options.crossTabPollLeaderElection) {
       void this.releaseLeadership().catch(() => void 0);
+      this.setLeaderStatus(false);
     }
   }
   /** Re-check every tracked task right now, bypassing each task's poll interval (e.g. on tab focus). */
@@ -310,6 +341,25 @@ var PendingTaskPoller = class {
   claimLeadership() {
     return withTabLock(this.options.pollLeaseKey, () => this.pollLease.claim(this.ownerId));
   }
+  /** Updates `isLeaderTab` and fires `onLeaderChange`, but only on an actual flip — see that
+   *  option's doc comment, including the "only ever called when `crossTabPollLeaderElection` is
+   *  on" part, which this enforces itself rather than relying on every call site to remember to
+   *  guard it (a call site that forgot would otherwise be a real, undetected bug — the whole
+   *  reason this guard lives here instead of at each of this method's several call sites). Safe
+   *  to call redundantly (e.g. after every successful claim/reconfirm in a tick, not just the
+   *  first) since a no-op call is just an equality check. */
+  setLeaderStatus(isLeader) {
+    if (!this.options.crossTabPollLeaderElection) return;
+    if (this.isLeaderTab === isLeader) return;
+    this.isLeaderTab = isLeader;
+    try {
+      this.options.onLeaderChange?.(isLeader);
+    } catch (error) {
+      queueMicrotask(() => {
+        throw error;
+      });
+    }
+  }
   /**
    * Re-confirms that poll leadership is still this tab's — and still the *same continuous
    * tenure* as when `fence` was captured, not just "is nobody else currently holding it" (a
@@ -327,11 +377,11 @@ var PendingTaskPoller = class {
    * changed hands in between. See `PollLeaseClaimResult`.
    */
   async reconfirmLeadership(task, expired, fence) {
-    if (!this.options.crossTabPollLeaderElection) return fence;
     if (this.stopped) {
       if (expired) this.finalCheckAttempted.delete(task.id);
       return false;
     }
+    if (!this.options.crossTabPollLeaderElection) return fence;
     let result;
     try {
       result = await this.claimLeadership();
@@ -465,8 +515,8 @@ var PendingTaskPoller = class {
     if (tasks.length === 0) return;
     this.isChecking = true;
     const batch = /* @__PURE__ */ new Map();
+    const now = Date.now();
     try {
-      const now = Date.now();
       let fence;
       let leadershipLost = false;
       for (const task of tasks) {
@@ -479,7 +529,19 @@ var PendingTaskPoller = class {
           }
           continue;
         }
-        const interval = handler.pollIntervalMs ?? this.options.defaultPollIntervalMs;
+        const failureCount = task.failureCount ?? 0;
+        let backoffMs;
+        if (failureCount > 0) {
+          try {
+            backoffMs = handler.retryBackoffMs?.(failureCount);
+          } catch (retryBackoffMsError) {
+            queueMicrotask(() => {
+              throw retryBackoffMsError;
+            });
+            backoffMs = void 0;
+          }
+        }
+        const interval = backoffMs !== void 0 && Number.isFinite(backoffMs) && backoffMs > 0 ? backoffMs : handler.pollIntervalMs ?? this.options.defaultPollIntervalMs;
         const lastChecked = task.lastCheckedAt ?? task.startedAt;
         const due = force || now - lastChecked >= interval;
         const finalAttemptDone = this.finalCheckAttempted.has(task.id);
@@ -505,25 +567,31 @@ var PendingTaskPoller = class {
               if (expired) this.finalCheckAttempted.delete(task.id);
               throw error;
             }
-            if (!claimed.leader) {
+            if (this.stopped || !claimed.leader) {
               leadershipLost = true;
+              this.setLeaderStatus(false);
               if (expired) this.finalCheckAttempted.delete(task.id);
               continue;
             }
             fence = claimed.fence;
+            this.setLeaderStatus(true);
           }
         }
         let result;
+        const abortController = new AbortController();
+        this.inFlightAbortController = abortController;
         try {
-          result = await handler.check(task);
+          result = await handler.check(task, abortController.signal);
         } catch (error) {
           const reconfirmedOnError = await this.reconfirmLeadership(task, expired, fence);
           if (reconfirmedOnError === false) {
             leadershipLost = true;
             fence = void 0;
+            this.setLeaderStatus(false);
             continue;
           }
           fence = reconfirmedOnError;
+          this.setLeaderStatus(true);
           let intercepted;
           try {
             intercepted = this.options.onCheckError?.(error, task);
@@ -543,21 +611,25 @@ var PendingTaskPoller = class {
             continue;
           }
           const latest = this.getLatestTask(task);
-          const failureCount = (latest.failureCount ?? 0) + 1;
-          if (failureCount >= this.options.maxFailureCount) {
+          const failureCount2 = (latest.failureCount ?? 0) + 1;
+          if (failureCount2 >= this.options.maxFailureCount) {
             await this.finalize(task, { status: "error", data: describeError(error) }, handler, batch);
           } else {
-            batch.set(task.id, { lastCheckedAt: now, failureCount });
+            batch.set(task.id, { lastCheckedAt: now, failureCount: failureCount2 });
           }
           continue;
+        } finally {
+          if (this.inFlightAbortController === abortController) this.inFlightAbortController = void 0;
         }
         const reconfirmedOnSuccess = await this.reconfirmLeadership(task, expired, fence);
         if (reconfirmedOnSuccess === false) {
           leadershipLost = true;
           fence = void 0;
+          this.setLeaderStatus(false);
           continue;
         }
         fence = reconfirmedOnSuccess;
+        this.setLeaderStatus(true);
         if (result.status === "pending") {
           const latest = this.getLatestTask(task);
           batch.set(task.id, {
@@ -573,8 +645,23 @@ var PendingTaskPoller = class {
         await this.finalize(task, { status: result.status, data: result.data }, handler, batch);
       }
     } finally {
-      this.flushBatch(batch);
       this.isChecking = false;
+      try {
+        this.flushBatch(batch);
+      } catch (error) {
+        queueMicrotask(() => {
+          throw error;
+        });
+      }
+      if (this.options.onTick) {
+        try {
+          this.options.onTick({ durationMs: Date.now() - now, taskCount: tasks.length });
+        } catch (error) {
+          queueMicrotask(() => {
+            throw error;
+          });
+        }
+      }
       if (this.pendingForce && !this.stopped) {
         this.pendingForce = false;
         this.runTickSafely(true);
@@ -643,6 +730,7 @@ export {
   DEFAULT_POLL_TICK_MS,
   DEFAULT_RESULT_EVENT,
   DEFAULT_STORAGE_KEY,
+  DEFAULT_TASK_LIST_WARN_THRESHOLD,
   DEFAULT_TTL_MS,
   PendingTaskPoller,
   clearResultRelay,