@estiva-app/platform 0.3.1 → 0.5.0

package/dist/retrying-read.js

@@ -0,0 +1,141 @@
+/**
+ * One read a tab holds on to, and reads again when it fails (FOL-5).
+ *
+ * Came from Peek's `useFolders` (FOL-42), which Ship needed word for word.
+ * Ship's read the Folder listing once and turned a failure into an empty list
+ * for the rest of the session: on production one refused read dropped every
+ * project out of its team until a reload. Peek had already paid for that
+ * lesson — a refused read left a project's channel unplaced and its team's dot
+ * dark — and fixed it with three rules, which are the whole of this object:
+ *
+ * 1. **A failure is read again**, on a backoff from `firstRetryMs` doubling to
+ *    `maxRetryMs`, until one succeeds. A quota refusal waits the relay's own
+ *    stated time instead ({@link retryHintMs}), never less than
+ *    {@link MIN_BACKOFF_MS}. A failure the caller says will answer the same
+ *    way (`retryable`) is not retried.
+ * 2. **A failure never replaces a good answer.** The last value stays; the
+ *    failure is reported only while there is nothing else to show.
+ * 3. **Held past the component that asked.** Every page mounts its own
+ *    sidebar; one of these per tab means a page change draws the answer the
+ *    tab already has rather than a skeleton (Peek's SID-2).
+ *
+ * No React, no relay: the app hands in the read and wraps the object in its
+ * own hook — `useSyncExternalStore(read.subscribe, read.snapshot)` — so the
+ * package stays framework-free (ADR 0002 §10), as `createRefreshScheduler` is.
+ */
+import { MIN_BACKOFF_MS, isRateLimited, retryHintMs } from './refresh.js';
+/** The first wait before reading a failed read again. Peek's `FOLDERS_RETRY_FIRST_MS`. */
+export const RETRY_FIRST_MS = 5_000;
+/** The longest wait between re-reads while a read keeps failing. */
+export const RETRY_MAX_MS = 60_000;
+const host = globalThis;
+/** The wait before the next attempt, after `failures` consecutive retryable failures. */
+export function retryDelayMs(failures, error, first = RETRY_FIRST_MS, max = RETRY_MAX_MS) {
+    const text = error instanceof Error ? error.message : String(error);
+    if (isRateLimited(text)) {
+        const hint = retryHintMs(text);
+        if (hint !== undefined)
+            return Math.max(MIN_BACKOFF_MS, hint);
+    }
+    return Math.min(first * 2 ** Math.max(0, failures - 1), max);
+}
+export function createRetryingRead(options = {}) {
+    const retryable = options.retryable ?? (() => true);
+    const first = options.firstRetryMs ?? RETRY_FIRST_MS;
+    const max = options.maxRetryMs ?? RETRY_MAX_MS;
+    const freshMs = options.freshMs ?? Number.POSITIVE_INFINITY;
+    // Taken when the object is made, as Peek's listing cache did: freshness is
+    // wall-clock, and a test's fake `Date` must not make a held answer look
+    // fresh (or stale) to the next test. Pass `now` to control it.
+    const now = options.now ?? Date.now;
+    const timers = () => options.timers ?? host;
+    let snapshot = { retrying: false };
+    let answeredAt = 0;
+    let failures = 0;
+    let inflight;
+    let timer;
+    const listeners = new Set();
+    const set = (next) => {
+        snapshot = next;
+        for (const listener of [...listeners])
+            listener();
+    };
+    const cancel = () => {
+        if (timer === undefined)
+            return;
+        timers().clearTimeout(timer);
+        timer = undefined;
+    };
+    /* Bumped by `clear`, so a read in flight across it cannot write the old
+       answer back or schedule a retry for it. */
+    let generation = 0;
+    const run = (load) => {
+        if (inflight)
+            return inflight;
+        cancel();
+        const started = generation;
+        inflight = (async () => {
+            try {
+                const value = await load();
+                if (started !== generation)
+                    return;
+                failures = 0;
+                answeredAt = now();
+                set({ value, retrying: false });
+            }
+            catch (error) {
+                if (started !== generation)
+                    return;
+                const again = retryable(error);
+                if (again) {
+                    failures += 1;
+                    timer = timers().setTimeout(() => {
+                        timer = undefined;
+                        void run(load);
+                    }, retryDelayMs(failures, error, first, max));
+                }
+                // A good answer outlives any failure after it.
+                set(snapshot.value !== undefined ? { value: snapshot.value, retrying: again } : { error, retrying: again });
+            }
+            finally {
+                if (started === generation)
+                    inflight = undefined;
+            }
+        })();
+        return inflight;
+    };
+    return {
+        snapshot: () => snapshot,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+                // Nobody is looking: a retry would spend the relay's budget on an
+                // answer no one draws. The snapshot still says a retry is due, and
+                // the next `ensure` makes it.
+                if (listeners.size === 0)
+                    cancel();
+            };
+        },
+        ensure(load) {
+            if (inflight)
+                return inflight;
+            if (timer !== undefined)
+                return Promise.resolve();
+            if (snapshot.value !== undefined && now() - answeredAt < freshMs)
+                return Promise.resolve();
+            return run(load);
+        },
+        reload: run,
+        dispose: cancel,
+        clear() {
+            generation += 1;
+            cancel();
+            inflight = undefined;
+            failures = 0;
+            answeredAt = 0;
+            set({ retrying: false });
+        },
+    };
+}
+//# sourceMappingURL=retrying-read.js.map

package/dist/retrying-read.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@estiva-app/platform",
-  "version": "0.3.1",
-  "description": "Browser lifecycle two Estiva apps share: the one live relay socket a tab should hold, its credential read per connect, the network coming back, and when a tab re-reads.",
+  "version": "0.5.0",
+  "description": "Browser lifecycle two Estiva apps share: the one live relay socket a tab should hold, its credential read per connect, the network coming back, when a tab re-reads, and the copy on the device a reload draws from.",
   "license": "MIT",
   "type": "module",
   "exports": {