pending-task-kit 0.1.0

package/dist/engine-ClhasLko.d.cts

@@ -0,0 +1,362 @@
+import { UseBoundStore, StoreApi } from 'zustand';
+
+/** What `handler.check()` itself reports about the task on a given poll: still going, or
+ *  finished — with the finished outcome being a business-level judgment (`success`/`failure`)
+ *  the handler makes, not something the engine interprets. */
+type PendingTaskStatus = "pending" | "success" | "failure";
+/**
+ * The final way a task's tracking concluded, as reported to `onResult`:
+ * - `success`/`failure` — `check()` gave a definite answer (mirrors `PendingTaskStatus`).
+ * - `error` — `check()` itself kept throwing until `maxFailureCount` was reached; the engine
+ *   never learned whether the task actually succeeded or failed.
+ * - `expired` — the task's TTL ran out before a definite answer arrived; same "never learned
+ *   the outcome" situation as `error`, just timed out rather than failing outright.
+ */
+type PendingTaskResultStatus = "success" | "failure" | "error" | "expired";
+/**
+ * Free-form bag for whatever your app wants attached to a task — a display title, a link, an
+ * owning user/tenant id, whatever `check()` or your UI needs. Entirely yours: the engine never
+ * reads or writes anything in here (see `PendingTask.failureCount`/`ttlMs` for the fields it
+ * *does* maintain itself — kept as separate top-level fields precisely so they can never
+ * collide with a key you pick here).
+ */
+type PendingTaskMetadata = Record<string, unknown>;
+interface PendingTask<TType extends string = string> {
+    /** Stable, globally-unique id. Re-adding a task with the same id replaces it. */
+    id: string;
+    type: TType;
+    taskId: number | string;
+    startedAt: number;
+    lastCheckedAt?: number;
+    /** Consecutive check-failure count; maintained by the poller, not by handlers. */
+    failureCount?: number;
+    /** TTL (ms) frozen onto the task at creation time — see `PendingTaskRegistry.addTask`. */
+    ttlMs?: number;
+    metadata?: PendingTaskMetadata;
+}
+interface PendingTaskCheckResult {
+    status: PendingTaskStatus;
+    /** Merged into `task.metadata` on the next store update — a percent, a stage name,
+     *  a step count, or whatever shape your handler's progress reporting needs. */
+    progress?: Record<string, unknown>;
+    /**
+     * Free-form payload for the caller's own `onResult` handling — a link, a toast message,
+     * an action-button label, what cache to invalidate, or anything else. The engine has no
+     * opinion on shape or on what a "result" should look like; it only ever passes this through.
+     */
+    data?: unknown;
+}
+interface PendingTaskHandler<TType extends string = string> {
+    check: (task: PendingTask<TType>) => Promise<PendingTaskCheckResult>;
+    /** How often (ms) this task type is checked. Defaults to the poller's `defaultPollIntervalMs`. */
+    pollIntervalMs?: number;
+    /** How long (ms) an untracked-to-completion task is kept before being dropped. */
+    ttlMs?: number;
+    /** Force one last `check()` exactly at TTL expiry instead of silently dropping the task. */
+    finalCheckOnExpiry?: boolean;
+    /** Suppress `onResult` for a `failure` or `error` outcome (still resolved internally).
+     *  `expired` is always silent regardless of this flag — see `PendingTaskResultStatus`. */
+    silentOnFailure?: boolean;
+    /** Suppress `onResult` for a `success` outcome. */
+    silentOnSuccess?: boolean;
+}
+type PendingTaskRegistry<TType extends string = string> = Partial<Record<TType, PendingTaskHandler<TType>>>;
+interface PendingTaskResultEventDetail<TType extends string = string> {
+    task: PendingTask<TType>;
+    status: PendingTaskResultStatus;
+    data?: unknown;
+}
+
+declare const DEFAULT_TTL_MS: number;
+declare const DEFAULT_STORAGE_KEY = "pending-tasks";
+interface PendingTaskStoreState<TType extends string = string> {
+    tasks: PendingTask<TType>[];
+    addTask: (task: PendingTask<TType>) => void;
+    removeTask: (id: string) => void;
+    updateTask: (id: string, patch: Partial<PendingTask<TType>>) => void;
+    /** Removes every task for which `predicate` returns false — e.g. drop tasks that don't
+     *  belong to the account now signed in, however your app identifies "belongs to". */
+    pruneTasksBy: (predicate: (task: PendingTask<TType>) => boolean) => void;
+    clearAllTasks: () => void;
+}
+type PendingTaskStore<TType extends string = string> = UseBoundStore<StoreApi<PendingTaskStoreState<TType>>> & {
+    storageKey: string;
+    /**
+     * True when the most recent write to this store's localStorage entry threw (quota exceeded,
+     * Safari private browsing, storage disabled, ...) instead of landing — by whichever writer
+     * made it: this store's own mutators, or an external batched write via `writeTasks` (e.g.
+     * `PendingTaskPoller`'s `flushBatch`/cross-tab `storage` sync). While true, persisted storage
+     * no longer reflects this tab's in-memory state, so anything about to rebuild `tasks` from a
+     * freshly-read persisted snapshot should build on `getState().tasks` instead, and anything
+     * checking "does another tab already have this task" (e.g. `addTaskIfMissing`) should not
+     * trust a persisted-storage read either. Flips back to `false` as soon as a write through
+     * this store's own mutators or `writeTasks` succeeds again.
+     *
+     * This is the single shared source of truth for that fact — treat it as read-only from
+     * outside this module; it's written only by this store's own mutators and by `writeTasks`.
+     */
+    hasUnpersistedWrites: boolean;
+    /**
+     * Writes `tasks` to this store the same way its own mutators do, through the single shared
+     * safe-write path that also updates `hasUnpersistedWrites`. Anything outside this module that
+     * replaces the whole `tasks` array wholesale (currently `PendingTaskPoller`'s batched
+     * `flushBatch` writes and its cross-tab `storage`-event sync) must go through this instead of
+     * calling `setState` directly — otherwise its own write failures would be invisible to this
+     * store's mutators (and vice versa), letting the two silently drift out of sync about whether
+     * persisted storage can currently be trusted.
+     */
+    writeTasks: (tasks: PendingTask<TType>[]) => void;
+};
+interface CreatePendingTaskStoreOptions {
+    /** localStorage key. Defaults to `"pending-tasks"`. Must be unique per app if you run multiple stores. */
+    storageKey?: string;
+}
+declare function isPendingTaskShape(value: unknown): value is PendingTask;
+/** Parses the raw string a zustand-persist localStorage entry holds, tolerating garbage/foreign values. */
+declare function parseTasksFromStorageValue<TType extends string = string>(value: string | null): PendingTask<TType>[];
+/**
+ * Creates an isolated pending-task store. Each store persists to its own localStorage key,
+ * so most apps should create exactly one instance and share it (module-level singleton).
+ *
+ * Every mutator re-reads the persisted value before writing, rather than trusting the
+ * in-memory snapshot — this avoids resurrecting a task another tab already removed.
+ */
+declare function createPendingTaskStore<TType extends string = string>(options?: CreatePendingTaskStoreOptions): PendingTaskStore<TType>;
+
+declare const DEFAULT_POLL_TICK_MS = 2000;
+declare const DEFAULT_POLL_INTERVAL_MS = 10000;
+declare const DEFAULT_MAX_FAILURE_COUNT = 5;
+declare const DEFAULT_RESULT_EVENT = "pending-task-result";
+/** Multiplied by the effective `pollTickMs` to get the default `pollLeaseTtlMs` — see that
+ *  option's doc comment for why it needs headroom over a single tick. */
+declare const DEFAULT_POLL_LEASE_TTL_MULTIPLIER = 4;
+interface PendingTaskPollerOptions<TType extends string = string> {
+    store: PendingTaskStore<TType>;
+    registry: PendingTaskRegistry<TType>;
+    /** Called for every non-silent `success`/`failure`/`error` outcome. This is where apps show a toast, navigate, or invalidate a cache — the engine has no opinion on any of that. */
+    onResult?: (detail: PendingTaskResultEventDetail<TType>) => void;
+    /**
+     * Called whenever `handler.check` throws, before the normal failure-count/backoff/expiry
+     * handling runs. The engine has no notion of auth, tokens, or sessions — if `check()` can
+     * fail for a reason that shouldn't count as a normal transient error (e.g. the caller's own
+     * session just ended), inspect `error` here and return `true` to skip the normal failure
+     * counting and stop the *current* tick early (the task is left as-is, `lastCheckedAt` is
+     * still bumped so it isn't treated as overdue again immediately). Return `false`/`undefined`
+     * (or omit this option) to fall through to the standard failure-count/backoff/expiry path.
+     */
+    onCheckError?: (error: unknown, task: PendingTask<TType>) => boolean | void;
+    /**
+     * Optional cross-tab "claim once" gate around the final `onResult`/DOM-event dispatch
+     * (task removal from the store always happens regardless). Compose `withTabLock` +
+     * `createTtlDedupeCache` here to prevent duplicate toasts when multiple tabs race to
+     * process the same completed task. This guards `onResult`/the toast-equivalent side effect
+     * specifically — it's orthogonal to `crossTabPollLeaderElection`, which is about not
+     * duplicating the *polling* itself; keep both if you want both properties.
+     *
+     * If your own implementation layers in something time-sensitive of its own — e.g. only
+     * proceeding while a session is still valid — check that condition *after* your `withTabLock`
+     * call resolves, not only before it: `withTabLock` is a genuine async yield (real cross-tab
+     * lock arbitration), so state can legitimately change while it's pending. A check placed only
+     * before it can pass, then have the underlying condition change during the wait, and the
+     * claimed/dispatched side effect would still fire against the now-stale state. (`finalize()`
+     * itself calls this once and acts on the result immediately after, with no further `await` in
+     * between — the same "recheck right before acting" discipline applies to whatever you put
+     * inside this callback.)
+     *
+     * On the leader tab specifically, returning `false` here also suppresses the cross-tab result
+     * relay (see `resultRelayKey`) for this result — not just this tab's own `onResult`/DOM event.
+     * That's the right call for the dedup use case above (another tab already claimed it, so that
+     * other tab is the one that will relay). If you layer in a veto unrelated to dedup (the
+     * session-validity check above, evaluated on the *leader's* state), a `false` there means
+     * *every* open tab loses this result, including ones whose own session is still fine — for a
+     * receiving-side-only veto that only affects the tab evaluating it, use `acceptRelayedResult`
+     * instead (or alongside this).
+     */
+    claimResultOnce?: (task: PendingTask<TType>) => Promise<boolean> | boolean;
+    /** How often the engine re-scans the task list. Individual tasks still respect their own poll interval. */
+    pollTickMs?: number;
+    /** Fallback per-check interval (ms) for handlers that don't set `pollIntervalMs`. */
+    defaultPollIntervalMs?: number;
+    /** Fallback TTL (ms) for tasks whose handler doesn't set `ttlMs`. */
+    defaultTtlMs?: number;
+    maxFailureCount?: number;
+    /** Also `window.dispatchEvent(new CustomEvent(eventName, { detail }))` for cross-component listening. Defaults to true when `window` exists. */
+    dispatchDomEvent?: boolean;
+    eventName?: string;
+    /** localStorage key the store persists to — must match what `createPendingTaskStore` was given. */
+    storageKey?: string;
+    /**
+     * When multiple browser tabs share the same store (the normal case — the store already
+     * syncs across tabs via `storage` events), only one of them actually calls `handler.check()`
+     * for a given task at a time; the others skip their own network work entirely for tasks
+     * that tab isn't the elected leader for, and instead learn the outcome via the (also
+     * newly-enabled) result relay once the leader dispatches it — see `resultRelayKey`.
+     *
+     * Defaults to `true`. Safe to leave on for single-tab usage: an uncontested instance always
+     * successfully claims/renews its own lease, so this changes nothing when there's no
+     * contention. Turn it off only if you specifically don't want that (e.g. you're not running
+     * in an environment with shared `localStorage` across the "tabs" this is designed for, or
+     * you're intentionally running independent pollers that must each poll everything).
+     */
+    crossTabPollLeaderElection?: boolean;
+    /** localStorage key (and Web Lock name) backing the poll-leader lease. Defaults to
+     *  `` `${storageKey}-poll-leader` ``. Only relevant when `crossTabPollLeaderElection` is on. */
+    pollLeaseKey?: string;
+    /**
+     * How long a claimed poll-leader lease stays valid without renewal before another tab may
+     * claim it. Defaults to `pollTickMs * 4` — comfortably longer than one normal tick, so a
+     * live leader always renews well before expiry, but short enough that a leader that stops
+     * renewing (closed, crashed, or frozen in the browser's back/forward cache) only blocks
+     * takeover for a bounded, short window rather than indefinitely.
+     *
+     * Note this bounds *renewal cadence*, not any single `handler.check()` call's own duration:
+     * a single slow request can still outlast this TTL, which is exactly why the engine
+     * re-confirms leadership again right after `check()` resolves/throws, before acting on a
+     * possibly-stale outcome — see the source of `runTick` if you're curious about the mechanism.
+     * Raising this value doesn't need to account for that case; it only trades off how long a
+     * genuinely dead leader blocks takeover.
+     */
+    pollLeaseTtlMs?: number;
+    /** localStorage key used to relay a completed task's result to other tabs when
+     *  `crossTabPollLeaderElection` is on (only the leader tab detects completion, so without
+     *  this, every other tab's `dispatchDomEvent` listeners would never fire). Defaults to
+     *  `` `${storageKey}-result-relay` ``. */
+    resultRelayKey?: string;
+    /**
+     * Optional gate on the *receiving* side of the cross-tab result relay (only relevant when
+     * `crossTabPollLeaderElection` is on): called right before this tab re-dispatches a result
+     * that arrived via another tab's `storage` write, letting this tab veto it. Return `false`
+     * to skip the dispatch entirely. Omit it (the default) to always accept, matching the
+     * engine's behavior before this option existed.
+     *
+     * The engine has no notion of sessions — if a relayed result could belong to a session that
+     * has since ended in *this* tab (a different account signed in, a logout), and re-surfacing
+     * it to this tab's own listeners would be wrong (the task's `metadata`/`data` can carry
+     * PII), inspect `detail` here and check whatever your app considers "still valid" — the same
+     * way `claimResultOnce` lets you gate the leader's own outgoing dispatch. This is the
+     * receiving-side half of that same concern; without it, there was previously no way to
+     * intercept an inbound relayed result at all.
+     *
+     * Evaluated synchronously with no `await` before the dispatch it gates (unlike
+     * `claimResultOnce`, there's no cross-tab claim to arbitrate on this side — only this tab
+     * decides whether to act on what it received, so there's no lock-arbitration window for
+     * your condition to go stale in between). If your own check is inherently async (e.g. reads
+     * from IndexedDB), resolve it eagerly elsewhere and read a synchronous flag here rather than
+     * awaiting inline.
+     */
+    acceptRelayedResult?: (detail: PendingTaskResultEventDetail<TType>) => boolean;
+}
+/**
+ * Framework-agnostic polling engine: scans the store's tasks on an interval, calls the
+ * matching handler's `check()`, and resolves each task to `pending` (re-check later),
+ * `success`/`failure` (dispatched via `onResult`, then removed), silently-or-not `error`
+ * (removed; dispatched unless `silentOnFailure`) when `check()` itself kept failing, or
+ * silently expired (removed, never dispatched — unless the handler opts into
+ * `finalCheckOnExpiry` for one last check).
+ *
+ * When multiple tabs share a store, `crossTabPollLeaderElection` (on by default) ensures only
+ * one of them actually polls at a time — see that option and `resultRelayKey` for how the
+ * others still learn about results without polling themselves.
+ *
+ * Framework bindings (see `./react`) are thin wrappers that call `start()`/`stop()` at the
+ * right lifecycle moments and expose `forceCheckAll()` for e.g. tab-focus recovery.
+ *
+ * Note: `stop()` prevents any *new* tick from starting, but a tick already awaiting
+ * `handler.check()` when `stop()` is called will still run to completion (there is no
+ * `AbortSignal` plumbed into the handler contract). Design handlers to be safe to finish
+ * even if the caller has logically "stopped" — e.g. don't assume side effects are undone.
+ */
+declare class PendingTaskPoller<TType extends string = string> {
+    private readonly options;
+    /** Stable for this instance's whole lifetime — e.g. one `PendingTaskPoller` construction per
+     *  browser tab (that's how the React binding uses it). Regenerating this per claim would make
+     *  a tab unable to recognize its own still-valid lease as "mine" on the next renewal. */
+    private readonly ownerId;
+    private readonly pollLease;
+    private intervalId;
+    private storageListener;
+    private isChecking;
+    private pendingForce;
+    private stopped;
+    private latestTasksCache;
+    /** 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. */
+    private readonly finalCheckAttempted;
+    constructor(options: PendingTaskPollerOptions<TType>);
+    start(): void;
+    stop(): void;
+    /** Re-check every tracked task right now, bypassing each task's poll interval (e.g. on tab focus). */
+    forceCheckAll(): void;
+    private claimLeadership;
+    /**
+     * 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`.
+     */
+    private reconfirmLeadership;
+    private releaseLeadership;
+    /** 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. */
+    private runTickSafely;
+    /** 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. */
+    private getLatestTask;
+    /** 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`. */
+    private flushBatch;
+    private finalize;
+    /**
+     * 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.
+     */
+    private dispatchRelayedResult;
+    private runTick;
+}
+
+export { type CreatePendingTaskStoreOptions as C, DEFAULT_MAX_FAILURE_COUNT as D, type PendingTaskStore as P, type PendingTaskRegistry as a, type PendingTask as b, type PendingTaskResultEventDetail as c, DEFAULT_POLL_INTERVAL_MS as d, DEFAULT_POLL_LEASE_TTL_MULTIPLIER as e, DEFAULT_POLL_TICK_MS as f, DEFAULT_RESULT_EVENT as g, DEFAULT_STORAGE_KEY as h, DEFAULT_TTL_MS as i, type PendingTaskCheckResult as j, type PendingTaskHandler as k, type PendingTaskMetadata as l, PendingTaskPoller as m, type PendingTaskPollerOptions as n, type PendingTaskResultStatus as o, type PendingTaskStatus as p, type PendingTaskStoreState as q, createPendingTaskStore as r, isPendingTaskShape as s, parseTasksFromStorageValue as t };