pending-task-kit 0.1.0 → 0.2.0

package/dist/react.cjs

@@ -1,572 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/react.ts
-var react_exports = {};
-__export(react_exports, {
-  PendingTaskPoller: () => PendingTaskPoller,
-  usePendingTaskPoller: () => usePendingTaskPoller
-});
-module.exports = __toCommonJS(react_exports);
-var import_react = require("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
-var import_zustand = require("zustand");
-var import_middleware = require("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 = (0, import_react.useRef)(pollerOptions);
-  optionsRef.current = pollerOptions;
-  (0, import_react.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]);
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  PendingTaskPoller,
-  usePendingTaskPoller
-});
-//# sourceMappingURL=react.cjs.map