pending-task-kit 0.1.0

package/dist/react.js

@@ -0,0 +1,546 @@
+// src/react.ts
+import { useEffect, useRef } from "react";
+
+// 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;
+  }
+}
+
+// src/poll-lease.ts
+function readLease(storageKey) {
+  const raw = safeGetItem(storageKey);
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.ownerId !== "string" || typeof parsed.expiresAt !== "number" || typeof parsed.fence !== "number") {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function writeLease(storageKey, lease) {
+  safeSetItem(storageKey, JSON.stringify(lease));
+}
+function createPollLeaseClaimer(storageKey, ttlMs) {
+  if (ttlMs <= 0 && typeof console !== "undefined") {
+    console.warn(`pending-task-kit: pollLeaseTtlMs must be positive, got ${ttlMs}`);
+  }
+  return {
+    claim(ownerId) {
+      const current = readLease(storageKey);
+      const now = Date.now();
+      if (current && current.ownerId !== ownerId && current.expiresAt > now) {
+        return { leader: false };
+      }
+      const isRenewal = current !== null && current.ownerId === ownerId && current.expiresAt > now;
+      const fence = isRenewal ? current.fence : (current?.fence ?? 0) + 1;
+      writeLease(storageKey, { ownerId, fence, expiresAt: now + ttlMs });
+      return { leader: true, fence };
+    },
+    release(ownerId) {
+      const current = readLease(storageKey);
+      if (current?.ownerId === ownerId) {
+        writeLease(storageKey, { ownerId, fence: current.fence, expiresAt: 0 });
+      }
+    }
+  };
+}
+function generatePollOwnerId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+// src/store.ts
+import { create } from "zustand";
+import { createJSONStorage, persist } from "zustand/middleware";
+var DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
+var DEFAULT_STORAGE_KEY = "pending-tasks";
+function isPendingTaskShape(value) {
+  if (!value || typeof value !== "object") return false;
+  const t = value;
+  return typeof t.id === "string" && typeof t.type === "string" && typeof t.startedAt === "number" && (typeof t.taskId === "number" || typeof t.taskId === "string");
+}
+function parseTasksFromStorageValue(value) {
+  if (!value) return [];
+  try {
+    const parsed = JSON.parse(value);
+    const tasks = parsed?.state?.tasks;
+    if (!Array.isArray(tasks)) return [];
+    return tasks.filter(isPendingTaskShape);
+  } catch {
+    return [];
+  }
+}
+function readPersistedTasks(storageKey) {
+  if (typeof localStorage === "undefined") return [];
+  return parseTasksFromStorageValue(localStorage.getItem(storageKey));
+}
+
+// src/result-relay.ts
+var RESULT_STATUSES = [
+  "success",
+  "failure",
+  "error",
+  "expired"
+];
+function isResultStatus(value) {
+  return typeof value === "string" && RESULT_STATUSES.includes(value);
+}
+function writeResultRelay(storageKey, detail) {
+  try {
+    const serialized = JSON.stringify(detail);
+    safeSetItem(storageKey, serialized);
+  } catch {
+  }
+}
+function parseResultRelay(value) {
+  if (!value) return null;
+  try {
+    const parsed = JSON.parse(value);
+    if (!isPendingTaskShape(parsed.task) || !isResultStatus(parsed.status)) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+// src/tab-lock.ts
+async function withTabLock(name, operation) {
+  const locks = typeof navigator !== "undefined" ? navigator.locks : void 0;
+  if (!locks) {
+    return operation();
+  }
+  return locks.request(name, async () => operation());
+}
+
+// src/engine.ts
+var DEFAULT_POLL_TICK_MS = 2e3;
+var DEFAULT_POLL_INTERVAL_MS = 1e4;
+var DEFAULT_MAX_FAILURE_COUNT = 5;
+var DEFAULT_RESULT_EVENT = "pending-task-result";
+var DEFAULT_POLL_LEASE_TTL_MULTIPLIER = 4;
+function describeError(error) {
+  if (error instanceof Error) return error.message;
+  return typeof error === "string" ? error : "Unknown error";
+}
+var PendingTaskPoller = class {
+  constructor(options) {
+    this.isChecking = false;
+    this.pendingForce = false;
+    this.stopped = 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.
+     *
+     *  Every id added here (only when a task is expired, right before its final `check()`) is
+     *  removed again before the *same* tick's iteration moves past that task — either by
+     *  `finalize()`'s first line, or by one of the leadership-loss/`onCheckError`-intercept
+     *  branches that bail out without ever reaching `finalize()`. Nothing here is meant to
+     *  survive past the tick that added it. */
+    this.finalCheckAttempted = /* @__PURE__ */ new Set();
+    const storageKey = options.storageKey ?? options.store.storageKey ?? DEFAULT_STORAGE_KEY;
+    const pollTickMs = options.pollTickMs ?? DEFAULT_POLL_TICK_MS;
+    this.options = {
+      store: options.store,
+      registry: options.registry,
+      pollTickMs,
+      defaultPollIntervalMs: options.defaultPollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+      defaultTtlMs: options.defaultTtlMs ?? DEFAULT_TTL_MS,
+      maxFailureCount: options.maxFailureCount ?? DEFAULT_MAX_FAILURE_COUNT,
+      dispatchDomEvent: options.dispatchDomEvent ?? typeof window !== "undefined",
+      eventName: options.eventName ?? DEFAULT_RESULT_EVENT,
+      storageKey,
+      crossTabPollLeaderElection: options.crossTabPollLeaderElection ?? true,
+      pollLeaseKey: options.pollLeaseKey ?? `${storageKey}-poll-leader`,
+      pollLeaseTtlMs: options.pollLeaseTtlMs ?? pollTickMs * DEFAULT_POLL_LEASE_TTL_MULTIPLIER,
+      resultRelayKey: options.resultRelayKey ?? `${storageKey}-result-relay`,
+      onResult: options.onResult,
+      onCheckError: options.onCheckError,
+      claimResultOnce: options.claimResultOnce,
+      acceptRelayedResult: options.acceptRelayedResult
+    };
+    this.ownerId = generatePollOwnerId();
+    this.pollLease = createPollLeaseClaimer(this.options.pollLeaseKey, this.options.pollLeaseTtlMs);
+  }
+  start() {
+    this.stopped = false;
+    if (this.intervalId !== void 0) return;
+    this.intervalId = setInterval(() => {
+      this.runTickSafely(false);
+    }, this.options.pollTickMs);
+    if (typeof window !== "undefined") {
+      this.storageListener = (event) => {
+        if (event.key === null) {
+          this.options.store.writeTasks([]);
+          return;
+        }
+        if (event.key === this.options.storageKey) {
+          this.options.store.writeTasks(parseTasksFromStorageValue(event.newValue));
+          return;
+        }
+        if (this.options.crossTabPollLeaderElection && event.key === this.options.resultRelayKey) {
+          const detail = parseResultRelay(event.newValue);
+          if (!detail) return;
+          let accepted;
+          try {
+            accepted = this.options.acceptRelayedResult?.(detail) ?? true;
+          } catch (error) {
+            queueMicrotask(() => {
+              throw error;
+            });
+            return;
+          }
+          if (accepted) void this.dispatchRelayedResult(detail);
+        }
+      };
+      window.addEventListener("storage", this.storageListener);
+    }
+    this.runTickSafely(false);
+  }
+  stop() {
+    this.stopped = true;
+    this.pendingForce = false;
+    if (this.intervalId !== void 0) {
+      clearInterval(this.intervalId);
+      this.intervalId = void 0;
+    }
+    if (this.storageListener && typeof window !== "undefined") {
+      window.removeEventListener("storage", this.storageListener);
+      this.storageListener = void 0;
+    }
+    if (this.options.crossTabPollLeaderElection) {
+      void this.releaseLeadership().catch(() => void 0);
+    }
+  }
+  /** Re-check every tracked task right now, bypassing each task's poll interval (e.g. on tab focus). */
+  forceCheckAll() {
+    this.runTickSafely(true);
+  }
+  claimLeadership() {
+    return withTabLock(this.options.pollLeaseKey, () => this.pollLease.claim(this.ownerId));
+  }
+  /**
+   * 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
+   * no-op returning `fence` unchanged when `crossTabPollLeaderElection` is off). Clears `task`'s
+   * `finalCheckAttempted` bookkeeping and returns `false` if not — the caller should stop
+   * treating this tick's remaining due tasks as network-eligible (though it may still process
+   * ones that need no leadership) rather than act on a possibly-stale outcome.
+   *
+   * A fence mismatch (rather than just an owner-id mismatch) is needed to catch leadership
+   * having churned through another tab and back to this one while a slow `handler.check()` was
+   * in flight: this tab's lease can expire mid-check, another tab claims it and fully resolves
+   * the same task, and that tab's own lease can *also* expire before this tab's stale response
+   * comes back — at which point this tab's next claim legitimately succeeds under its own
+   * stable owner id (nothing currently holds the lease), even though leadership genuinely
+   * 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;
+    }
+    let result;
+    try {
+      result = await this.claimLeadership();
+    } catch (error) {
+      if (expired) this.finalCheckAttempted.delete(task.id);
+      throw error;
+    }
+    if (result.leader && result.fence === fence) return result.fence;
+    if (expired) this.finalCheckAttempted.delete(task.id);
+    return false;
+  }
+  releaseLeadership() {
+    return withTabLock(this.options.pollLeaseKey, () => {
+      this.pollLease.release(this.ownerId);
+    });
+  }
+  /** Fires `runTick`, but instead of leaving its promise `void`-called (which would turn an
+   *  exception thrown by a consumer callback — `onResult`, `onCheckError`, or a `dispatchEvent`
+   *  listener — into a silent unhandled rejection), re-throws it as an uncaught exception on a
+   *  fresh microtask. `runTick`'s own `finally` has already flushed the batch and reset
+   *  `isChecking` by the time this ever runs, so a broken consumer callback can't take the
+   *  poller down — it just becomes visible the way any other uncaught error in the host
+   *  environment would be, instead of vanishing. */
+  runTickSafely(force) {
+    this.runTick(force).catch((error) => {
+      queueMicrotask(() => {
+        throw error;
+      });
+    });
+  }
+  /** Reads the freshest snapshot of `task` from the store, in case another tab wrote to it
+   *  while this tab's `handler.check()` was in flight — narrows, but doesn't eliminate, the
+   *  window where a concurrent cross-tab write to the same task could be clobbered.
+   *
+   *  Indexes `store.getState().tasks` into a Map keyed by id rather than doing a linear find
+   *  each call — this is called once per pending/failing task per tick, so a plain find would
+   *  make a tick O(n²). The cache keys off the `tasks` array reference, which zustand only
+   *  replaces on an actual write, so it's rebuilt only when the store has genuinely changed. */
+  getLatestTask(task) {
+    const tasks = this.options.store.getState().tasks;
+    if (this.latestTasksCache?.tasks !== tasks) {
+      this.latestTasksCache = { tasks, byId: new Map(tasks.map((t) => [t.id, t])) };
+    }
+    return this.latestTasksCache.byId.get(task.id) ?? task;
+  }
+  /** Applies a whole tick's worth of per-task updates/removals (`patch: null` means "remove")
+   *  in a single read-modify-write, instead of one persisted-storage round trip per task.
+   *  Reads the freshest persisted list right before writing (same "never resurrect a task
+   *  another tab already removed" guarantee `PendingTaskStore`'s own mutators give) — unless
+   *  the store's `hasUnpersistedWrites` is set (a write on *any* path for this store, including
+   *  this store's own direct mutators, failed and hasn't yet been followed by a success), in
+   *  which case persisted storage is stale relative to this tab's memory, so this flush builds
+   *  on `store.getState().tasks` instead. Writes through `writeTasks`, which swallows a
+   *  throwing write and updates that same shared flag — see the comment in `store.ts`. */
+  flushBatch(batch) {
+    if (batch.size === 0) return;
+    const base = this.options.store.hasUnpersistedWrites ? this.options.store.getState().tasks : readPersistedTasks(this.options.storageKey);
+    const next = [];
+    for (const t of base) {
+      if (!batch.has(t.id)) {
+        next.push(t);
+        continue;
+      }
+      const patch = batch.get(t.id);
+      if (patch !== null) next.push({ ...t, ...patch });
+    }
+    this.options.store.writeTasks(next);
+  }
+  async finalize(task, detail, handler, batch) {
+    this.finalCheckAttempted.delete(task.id);
+    batch.set(task.id, null);
+    if (detail.status === "expired") return;
+    const silent = detail.status === "success" ? handler?.silentOnSuccess : handler?.silentOnFailure;
+    if (silent) return;
+    let claimed;
+    try {
+      claimed = this.options.claimResultOnce ? await this.options.claimResultOnce(task) : true;
+    } catch {
+      return;
+    }
+    if (!claimed) return;
+    const fullDetail = { task, ...detail };
+    if (this.options.crossTabPollLeaderElection) {
+      writeResultRelay(this.options.resultRelayKey, fullDetail);
+    }
+    this.options.onResult?.(fullDetail);
+    if (this.options.dispatchDomEvent && typeof window !== "undefined") {
+      window.dispatchEvent(new CustomEvent(this.options.eventName, { detail: fullDetail }));
+    }
+  }
+  /**
+   * Handles a result relayed from another tab's leader — mirrors finalize()'s own
+   * `claimResultOnce` gate and dispatch, so a `claimResultOnce` composed for "one notification
+   * system-wide" (see its doc comment's "keep both if you want both properties") applies
+   * uniformly whether this tab detected the result itself or only learned about it via the
+   * relay, not just to the narrower direct-detection race `claimResultOnce` guarded before this
+   * relay existed.
+   *
+   * Fired-and-forgotten (`void`-called) from the "storage" listener rather than awaited, so it
+   * has no `this.stopped` check of its own: `stop()` removes the listener (no *new* relayed
+   * result starts one of these after that), but one already in flight when `stop()` is called
+   * (e.g. awaiting a slow `claimResultOnce`) still runs to completion — the same tolerance
+   * `runTick`'s own doc comment describes for an in-flight tick.
+   */
+  async dispatchRelayedResult(detail) {
+    let claimed;
+    try {
+      claimed = this.options.claimResultOnce ? await this.options.claimResultOnce(detail.task) : true;
+    } catch {
+      return;
+    }
+    if (!claimed) return;
+    try {
+      this.options.onResult?.(detail);
+      if (this.options.dispatchDomEvent && typeof window !== "undefined") {
+        window.dispatchEvent(new CustomEvent(this.options.eventName, { detail }));
+      }
+    } catch (error) {
+      queueMicrotask(() => {
+        throw error;
+      });
+    }
+  }
+  async runTick(force) {
+    if (this.stopped) return;
+    if (this.isChecking) {
+      this.pendingForce = this.pendingForce || force;
+      return;
+    }
+    const tasks = this.options.store.getState().tasks;
+    if (tasks.length === 0) return;
+    this.isChecking = true;
+    const batch = /* @__PURE__ */ new Map();
+    try {
+      const now = Date.now();
+      let fence;
+      let leadershipLost = false;
+      for (const task of tasks) {
+        const handler = this.options.registry[task.type];
+        const ttlMs = task.ttlMs ?? this.options.defaultTtlMs;
+        const expired = now - task.startedAt >= ttlMs;
+        if (!handler) {
+          if (expired) {
+            await this.finalize(task, { status: "expired" }, handler, batch);
+          }
+          continue;
+        }
+        const interval = handler.pollIntervalMs ?? this.options.defaultPollIntervalMs;
+        const lastChecked = task.lastCheckedAt ?? task.startedAt;
+        const due = force || now - lastChecked >= interval;
+        const finalAttemptDone = this.finalCheckAttempted.has(task.id);
+        if (expired && (!handler.finalCheckOnExpiry || finalAttemptDone)) {
+          await this.finalize(task, { status: "expired" }, handler, batch);
+          continue;
+        }
+        if (!due && !expired) continue;
+        if (expired) {
+          this.finalCheckAttempted.add(task.id);
+        }
+        if (this.options.crossTabPollLeaderElection) {
+          if (leadershipLost || this.stopped) {
+            leadershipLost = true;
+            if (expired) this.finalCheckAttempted.delete(task.id);
+            continue;
+          }
+          if (fence === void 0) {
+            let claimed;
+            try {
+              claimed = await this.claimLeadership();
+            } catch (error) {
+              if (expired) this.finalCheckAttempted.delete(task.id);
+              throw error;
+            }
+            if (!claimed.leader) {
+              leadershipLost = true;
+              if (expired) this.finalCheckAttempted.delete(task.id);
+              continue;
+            }
+            fence = claimed.fence;
+          }
+        }
+        let result;
+        try {
+          result = await handler.check(task);
+        } catch (error) {
+          const reconfirmedOnError = await this.reconfirmLeadership(task, expired, fence);
+          if (reconfirmedOnError === false) {
+            leadershipLost = true;
+            fence = void 0;
+            continue;
+          }
+          fence = reconfirmedOnError;
+          let intercepted;
+          try {
+            intercepted = this.options.onCheckError?.(error, task);
+          } catch (onCheckErrorError) {
+            queueMicrotask(() => {
+              throw onCheckErrorError;
+            });
+            intercepted = false;
+          }
+          if (intercepted) {
+            batch.set(task.id, { lastCheckedAt: now });
+            this.finalCheckAttempted.delete(task.id);
+            break;
+          }
+          if (expired) {
+            await this.finalize(task, { status: "expired" }, handler, batch);
+            continue;
+          }
+          const latest = this.getLatestTask(task);
+          const failureCount = (latest.failureCount ?? 0) + 1;
+          if (failureCount >= this.options.maxFailureCount) {
+            await this.finalize(task, { status: "error", data: describeError(error) }, handler, batch);
+          } else {
+            batch.set(task.id, { lastCheckedAt: now, failureCount });
+          }
+          continue;
+        }
+        const reconfirmedOnSuccess = await this.reconfirmLeadership(task, expired, fence);
+        if (reconfirmedOnSuccess === false) {
+          leadershipLost = true;
+          fence = void 0;
+          continue;
+        }
+        fence = reconfirmedOnSuccess;
+        if (result.status === "pending") {
+          const latest = this.getLatestTask(task);
+          batch.set(task.id, {
+            lastCheckedAt: now,
+            failureCount: 0,
+            metadata: { ...latest.metadata, ...result.progress }
+          });
+          if (expired) {
+            await this.finalize(task, { status: "expired" }, handler, batch);
+          }
+          continue;
+        }
+        await this.finalize(task, { status: result.status, data: result.data }, handler, batch);
+      }
+    } finally {
+      this.flushBatch(batch);
+      this.isChecking = false;
+      if (this.pendingForce && !this.stopped) {
+        this.pendingForce = false;
+        this.runTickSafely(true);
+      }
+    }
+  }
+};
+
+// src/react.ts
+function usePendingTaskPoller(options) {
+  const { enabled = true, ...pollerOptions } = options;
+  const optionsRef = useRef(pollerOptions);
+  optionsRef.current = pollerOptions;
+  useEffect(() => {
+    if (!enabled) return;
+    const poller = new PendingTaskPoller({
+      ...optionsRef.current,
+      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
+    });
+    poller.start();
+    const handleVisibility = () => {
+      if (document.visibilityState === "visible") {
+        poller.forceCheckAll();
+      }
+    };
+    document.addEventListener("visibilitychange", handleVisibility);
+    return () => {
+      document.removeEventListener("visibilitychange", handleVisibility);
+      poller.stop();
+    };
+  }, [enabled, pollerOptions.store, pollerOptions.registry]);
+}
+export {
+  PendingTaskPoller,
+  usePendingTaskPoller
+};
+//# sourceMappingURL=react.js.map