@ironflow/browser 0.26.0 → 0.28.0

package/dist/queue/queue.d.ts

@@ -0,0 +1,281 @@
+import { type QueuedWrite, type QueuedWriteKind, type QueueStats, type WriteLostReason, type WriteStatus } from "./types.js";
+/** What the drainer gets back from a successful send. */
+export interface SendOutcome {
+    eventId?: string;
+    entityVersion?: number;
+}
+export interface OfflineQueueOptions {
+    /** IndexedDB database name; scoped by the caller to serverUrl + environment. */
+    dbName: string;
+    /**
+     * Stable, app-supplied identity for the current principal.
+     *
+     * Not a hash of the credential: hashing identifies the credential, so
+     * rotating a token would make the same user look like a different one.
+     */
+    identity: string;
+    /** Sends one write to `path`. Injected so the queue never imports the client. */
+    send: (path: string, write: QueuedWrite) => Promise<SendOutcome>;
+    /** Endpoint for a write kind, or null if this SDK has none. */
+    resolvePath: (kind: QueuedWriteKind) => string | null;
+    /** The destination the client points at RIGHT NOW, read at send time. */
+    currentDestination: () => {
+        serverUrl: string;
+        environment: string;
+    };
+    maxItems?: number;
+    maxBytes?: number;
+    maxRetentionMs?: number;
+    maxDeadLettered?: number;
+    backoffInitialMs?: number;
+    backoffMaxMs?: number;
+    stopGraceMs?: number;
+    /** How long `onAuthRequired` may take before the attempt is abandoned. */
+    authTimeoutMs?: number;
+    /** Called once per write that will never be sent. */
+    onWriteLost?: (write: QueuedWrite, reason: WriteLostReason, message: string) => void;
+    /**
+     * Called when the server rejects a write with 401.
+     *
+     * The queue pauses (it does not dead-letter) and resumes once this resolves.
+     * 403 is deliberately NOT routed here: this codebase uses 403 for
+     * insufficient permissions, which no amount of re-authentication fixes, so
+     * pausing on it would wait forever.
+     */
+    onAuthRequired?: () => Promise<{
+        identity?: string;
+    } | void>;
+    /** Injectable clock, for retention tests. */
+    now?: () => number;
+    /**
+     * Injectable timer, so tests need not wait out real backoff.
+     * May return a cancel function; flush() and stop() use it to drop a pending
+     * retry instead of leaving an orphan timer running.
+     */
+    schedule?: (fn: () => void, ms: number) => (() => void) | void;
+}
+/** How the drainer should react to a failed send. */
+type Disposition = "retry" | "auth" | "poison";
+/**
+ * Classify a send failure.
+ *
+ * Reuses `IronflowError.retryable`, which the shared `send()` already sets from
+ * the HTTP status, rather than growing a second rule that drifts from the first.
+ */
+export declare function classifyFailure(error: unknown): Disposition;
+export declare class OfflineQueue {
+    private db;
+    private opts;
+    private state;
+    private pending;
+    private bytes;
+    private deadLettered;
+    private inFlight;
+    private sessionTotal;
+    private attempt;
+    private draining;
+    private stopped;
+    /** A backoff retry is already armed; don't stack a second timer on top. */
+    private retryArmed;
+    /** Cancels the armed retry. Without it, flush() would orphan the timer. */
+    private cancelRetry;
+    /** A counter refresh is already queued; collapse a burst into one re-read. */
+    private refreshQueued;
+    /** Counter mutations straddling an await right now. See {@link mutate}. */
+    private counterMutations;
+    /** Bumped by every completed counter mutation, so a racing read can tell. */
+    private counterEpoch;
+    /** Consecutive refreshes discarded for racing a local mutation. */
+    private refreshRetries;
+    /**
+     * A drain was requested while one was already running.
+     *
+     * Without this, a write enqueued in the window between the drainer reading an
+     * empty head and returning idle is stranded: its `drain()` call is dropped as
+     * a duplicate, and the idle path arms no timer to come back. Nothing would
+     * send it until the next enqueue, an explicit flush, or a page reload.
+     */
+    private drainRequested;
+    /** Cross-tab counter sync; null when BroadcastChannel is unavailable. */
+    private channel;
+    private readonly statsSubs;
+    private readonly watchers;
+    constructor(options: OfflineQueueOptions);
+    /** Open the database and hydrate the in-memory counters. */
+    start(): Promise<void>;
+    /**
+     * Keep sibling tabs' counters honest.
+     *
+     * The flush lock stops two tabs draining at once, but it does nothing for
+     * their *counters*: an in-memory `pending` in tab A cannot see tab B enqueue
+     * or drain, so B's badge silently goes stale. A `BroadcastChannel` ping tells
+     * the others to re-read, which keeps the cheap in-memory counters without
+     * making them per-tab fiction.
+     */
+    private openChannel;
+    /**
+     * Ask for a counter re-read, coalescing a burst into a single pass.
+     *
+     * Also the retry path for a read discarded by {@link counterRaced} — nothing
+     * else re-runs a refresh, so dropping one silently lets this tab under-count
+     * a sibling's writes for good and over-admit against its own cap.
+     */
+    private requestRefresh;
+    /**
+     * Re-resolve every live watcher against storage.
+     *
+     * `notifyWatcher` runs on the drain path, so it only ever fires in the tab
+     * that did the draining. Without this, a write enqueued in tab A and
+     * delivered by tab B leaves A's watcher on its provisional "pending" forever
+     * and leaks its entry for the life of the page — and multi-tab is exactly
+     * what the channel was added for.
+     *
+     * Inherits `resolveStatus`'s v1 limit: a localId in neither store reads as
+     * "sent", which is wrong for an evicted dead letter or an origin Safari
+     * cleared. Documented under Limits in the browser SDK reference.
+     *
+     * ponytail: two indexed reads per live watcher per refresh. Fine for a UI
+     * watching a handful of rows; if an app ever watches hundreds while a
+     * sibling drains a backlog, carry the drained localIds in the broadcast
+     * message instead of re-reading storage.
+     */
+    private reconcileWatchers;
+    /** Announce that this tab changed the stored state. */
+    private announce;
+    private refreshCounters;
+    /** Snapshot taken before a store read whose result will overwrite a counter. */
+    private counterMark;
+    /**
+     * Whether a counter mutation overlapped the read this mark was taken for —
+     * in flight at either end, or begun and finished in between.
+     */
+    private counterRaced;
+    /**
+     * Mark a section whose store mutation and in-memory counter update straddle
+     * an await, so a concurrent {@link refreshCounters} knows to discard its read.
+     */
+    private mutate;
+    /**
+     * Stop draining and close the database. Safe to call mid-flight.
+     *
+     * Gives an in-flight send a bounded grace period to finish, rather than
+     * abandoning a write whose fate would then be unknown. Bounded because a send
+     * can be stuck behind the client's own request timeout, and a `close()` that
+     * blocks for 30s is its own bug — after the grace period the database closes
+     * and the drain loop's next store call fails harmlessly.
+     */
+    stop(stopGraceMs?: number): Promise<void>;
+    /**
+     * Persist a write and return its handles.
+     *
+     * Serialisation happens before the IndexedDB transaction: structured clone
+     * accepts values `JSON.stringify` later rejects (cycles, `BigInt`), and
+     * reporting "saved" for a write that can never be transmitted is worse than
+     * failing now. It also gives an exact byte size for the cap.
+     *
+     * @throws {QueueFullError} at the item cap, byte cap, or storage quota.
+     */
+    enqueue(input: {
+        kind: QueuedWriteKind;
+        body: unknown;
+        idempotencyKey?: string;
+    }): Promise<{
+        localId: string;
+        idempotencyKey: string;
+    }>;
+    /**
+     * Ask the drainer to run. Idempotent; concurrent calls collapse into one.
+     *
+     * The loop exists so a pause for re-authentication can resume *without*
+     * holding the flush lock: `drainSession` returns, the lock is released,
+     * credentials are refreshed, and only then do we go round again. Recursing
+     * from inside the session would keep the lock across a login prompt, which is
+     * exactly what other tabs must not be stuck behind.
+     */
+    drain(): Promise<void>;
+    /** Explicit flush, for a "Retry now" button or a test. */
+    flush(): Promise<void>;
+    /**
+     * Drain until the queue empties or something stops us.
+     *
+     * Returning is how the flush lock is released: a pause for re-authentication
+     * exits this function rather than awaiting inside it, so other tabs are not
+     * blocked behind a login prompt the user may never answer.
+     */
+    private drainSession;
+    /** Move a write to the dead-letter store and tell everyone who cares. */
+    private retire;
+    /**
+     * Obtain fresh credentials.
+     *
+     * If the caller reports a DIFFERENT principal — the natural outcome when
+     * `onAuthRequired` shows a login prompt on a shared machine and someone else
+     * signs in — the queue rebinds to that identity. The pending records then fail
+     * the identity check and are quarantined instead of being transmitted under
+     * the new user's credentials.
+     *
+     * Bounded by `authTimeoutMs`. `drain()` awaits this while `draining` is true,
+     * so a callback that never settles never reaches the `finally` that clears
+     * the flag — and every later `drain()` and `flush()` then short-circuits on
+     * it. Delivery would stop for the life of the page with no in-app recovery,
+     * while `pending` climbed to `maxItems` and started throwing `QueueFullError`
+     * at the app. A dropped promise is the normal shape of a dismissed login
+     * modal, so this is an ordinary path, not a defensive one.
+     *
+     * Timing out returns false, which is the existing "no credentials obtained"
+     * branch: the caller backs off and tries again. Nothing is dead-lettered — a
+     * later login still delivers these writes.
+     *
+     * @returns whether fresh credentials were obtained.
+     */
+    private reauthenticate;
+    /**
+     * Exponential backoff with full jitter.
+     *
+     * Jitter matters more than usual here: every tab that came back online at the
+     * same moment would otherwise retry in lockstep and manufacture the 429 the
+     * queue is trying to survive.
+     */
+    private scheduleRetry;
+    /** Drop a pending retry so a new one does not run alongside it. */
+    private clearRetry;
+    /** Every write that will never be sent, oldest first. */
+    deadLetter(): Promise<import("./types.js").DeadLetteredWrite[]>;
+    /** Forget a dead-lettered write. Returns false if it was already gone. */
+    discard(localId: string): Promise<boolean>;
+    /**
+     * Put a dead-lettered write back on the queue.
+     *
+     * It goes to the BACK, with a fresh `seq` — re-inserting at its original
+     * position would mean rewriting keys, and everything that was behind it has
+     * already been delivered. The idempotency key is preserved so a replay of a
+     * write that did land is deduplicated by the engine.
+     */
+    retry(localId: string): Promise<boolean>;
+    stats(): QueueStats;
+    /** Subscribe to queue-wide stats. Returns an unsubscribe function. */
+    subscribe(cb: (stats: QueueStats) => void): () => void;
+    /**
+     * Watch one write by its `localId`.
+     *
+     * The `pending: true` on an enqueue result is a one-shot value; without this
+     * there is no way to learn that a specific row landed. Firestore's
+     * `hasPendingWrites` is a live flag, and copying the shape without the
+     * liveness would have been a dead end.
+     */
+    watch(localId: string, cb: (status: WriteStatus) => void): () => void;
+    /**
+     * Current status of one write, derived from what is actually stored.
+     *
+     * One transaction over both stores, not two reads: `deadLetter()` moves a
+     * record between them atomically, so separate reads can miss it in both and
+     * report a LOST write as delivered — the worst answer this surface can give.
+     */
+    private resolveStatus;
+    private notifyWatcher;
+    private setState;
+    private emitStats;
+    private requireDb;
+}
+export {};
+//# sourceMappingURL=queue.d.ts.map

package/dist/queue/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/queue/queue.ts"],"names":[],"mappings":"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"}