pending-task-kit 0.1.0 → 0.2.0

package/dist/react.js

@@ -90,8 +90,7 @@ function parseTasksFromStorageValue(value) {
   }
 }
 function readPersistedTasks(storageKey) {
-  if (typeof localStorage === "undefined") return [];
-  return parseTasksFromStorageValue(localStorage.getItem(storageKey));
+  return parseTasksFromStorageValue(safeGetItem(storageKey));
 }
 
 // src/result-relay.ts
@@ -148,6 +147,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.
@@ -177,7 +180,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);
@@ -220,6 +225,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;
@@ -230,6 +236,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). */
@@ -239,6 +246,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
@@ -256,11 +282,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();
@@ -394,8 +420,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) {
@@ -408,7 +434,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);
@@ -434,25 +472,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);
@@ -472,21 +516,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, {
@@ -502,8 +550,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);
@@ -524,7 +587,9 @@ function usePendingTaskPoller(options) {
       onResult: (detail) => optionsRef.current.onResult?.(detail),
       onCheckError: (error, task) => optionsRef.current.onCheckError?.(error, task),
       claimResultOnce: (task) => optionsRef.current.claimResultOnce ? optionsRef.current.claimResultOnce(task) : true,
-      acceptRelayedResult: (detail) => optionsRef.current.acceptRelayedResult?.(detail) ?? true
+      acceptRelayedResult: (detail) => optionsRef.current.acceptRelayedResult?.(detail) ?? true,
+      onLeaderChange: (isLeader) => optionsRef.current.onLeaderChange?.(isLeader),
+      onTick: (info) => optionsRef.current.onTick?.(info)
     });
     poller.start();
     const handleVisibility = () => {