react-native-onyx 3.0.87 → 3.0.88

package/dist/StateMachine.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * An immutable, type-safe finite state machine.
+ * Pass the transition graph with `as const` so `transition` only accepts legal target states.
+ *
+ * @example
+ * const transitions = {
+ *     idle: ['loading'],
+ *     loading: ['success', 'error'],
+ *     success: [],
+ *     error: ['idle'],
+ * } as const;
+ *
+ * const idleMachine = new StateMachine('idle', transitions);
+ * const loadingMachine = idleMachine.transition('loading');
+ * loadingMachine.transition('success');
+ */
+class StateMachine {
+    constructor(currentState, transitions) {
+        this.state = currentState;
+        this.transitions = transitions;
+        Object.freeze(this);
+    }
+    /**
+     * Transition to a new state, returning a new state machine instance.
+     * Only transitions declared in the graph for the current state are accepted.
+     */
+    transition(target) {
+        const validTargets = this.transitions[this.state];
+        if (!(validTargets === null || validTargets === void 0 ? void 0 : validTargets.includes(target))) {
+            throw new Error(`Illegal transition from "${String(this.state)}" to "${String(target)}"`);
+        }
+        return new StateMachine(target, this.transitions);
+    }
+}
+exports.default = StateMachine;

package/dist/StorageCircuitBreaker.d.ts

@@ -0,0 +1,66 @@
+import AbstractCircuitBreaker from './CircuitBreaker/AbstractCircuitBreaker';
+/**
+ * Process-scoped circuit breaker for storage CAPACITY failures.
+ *
+ * The per-operation retry budget in `OnyxUtils.retryOperation` cannot stop a session-level storm:
+ * each evict -> OnyxDerived recompute -> new write starts its own fresh budget, so a full disk or
+ * exhausted quota can drive tens of thousands of evict+retry cycles that never make progress and
+ * freeze the app. This breaker is the session-level brake — `retryOperation` consults it before
+ * every eviction.
+ *
+ * It is ONE circuit (closed/open/half-open) fed by TWO failure-counting policies, both evaluated in
+ * {@link recordFailureInClosed}. It trips when EITHER:
+ *  - capacity failures within {@link ROLLING_WINDOW_MS} exceed {@link FAILURE_THRESHOLD}, or
+ *  - {@link NO_PROGRESS_CAP} consecutive evictions are each immediately followed by another capacity
+ *    failure (the eviction freed nothing the next write could use — a no-progress cycle). This is a
+ *    cheap proxy for `getDatabaseSize()`, which is costly and only reports origin-wide usage.
+ *
+ * Keeping both policies inside a single state machine — rather than composing two independent breakers
+ * — is deliberate: two breakers each with their own open/half-open/probe latch cannot share one
+ * coherent circuit state without races (stranded half-open probes, storms uncounted while the other
+ * probes, cross-contaminated counters).
+ *
+ * On trip it emits exactly ONE alert per incident (across reopen cycles). After {@link ROLLING_WINDOW_MS}
+ * the circuit moves to half-open and admits a single eviction+retry probe; a successful probe closes
+ * the circuit, a failed probe reopens it for another window.
+ */
+declare class StorageCircuitBreaker extends AbstractCircuitBreaker {
+    /** Timestamps of capacity failures still inside the rolling window. */
+    private failureTimestamps;
+    /** Consecutive evictions that each failed to free usable space. */
+    private consecutiveNoProgress;
+    /** Set when an eviction's retry is pending, so the next capacity failure counts as no-progress. */
+    private evictionAwaitingResult;
+    /** Guards the single alert per incident (the open→half-open→open cycle must not re-alert). */
+    private hasTripped;
+    constructor();
+    /**
+     * Record a CAPACITY failure. Call once per capacity failure in `retryOperation`, BEFORE deciding
+     * whether to evict. Returns `true` when the breaker is open and eviction must not proceed.
+     */
+    recordCapacityFailure(): boolean;
+    /** Record that `retryOperation` just evicted a key, so the next capacity failure counts as no-progress. */
+    recordEviction(): void;
+    /**
+     * Record that a storage write succeeded. Fires on EVERY successful write, so it must only act on the
+     * one that carries capacity information: a write whose eviction was awaiting its verdict. Such a
+     * success means an eviction's retry actually landed — usable space was freed. In half-open that is
+     * the recovery probe succeeding (closes the circuit); in closed it clears the no-progress streak. A
+     * plain write that happens to succeed proves nothing about capacity and is a no-op (the common case).
+     */
+    recordWriteSuccess(): void;
+    /**
+     * Record that the half-open recovery probe failed. `retryOperation` calls this when a write is
+     * rejected while a probe is in flight — the storage is still full, so reopen for another window.
+     * No-op while fully open (recordFailure short-circuits) and harmless while closed.
+     */
+    recordProbeFailure(): void;
+    /** Wipe all state back to a fresh closed circuit. Process-scoped, so reset between tests/sessions. */
+    reset(): void;
+    protected recordFailureInClosed(): string | null;
+    protected recordSuccessInClosed(): void;
+    protected resetFailureState(): void;
+    private handleTrip;
+}
+declare const _default: StorageCircuitBreaker;
+export default _default;

package/dist/StorageCircuitBreaker.js

@@ -0,0 +1,177 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const AbstractCircuitBreaker_1 = __importDefault(require("./CircuitBreaker/AbstractCircuitBreaker"));
+const Logger = __importStar(require("./Logger"));
+/** Rolling window over which capacity failures are counted, and how long a trip stays open. */
+const ROLLING_WINDOW_MS = 60 * 1000;
+/** Capacity failures within the window above which the breaker trips (storm backstop). */
+const FAILURE_THRESHOLD = 50;
+/** Consecutive no-progress evictions (evict -> still capacity failure) above which the breaker trips. */
+const NO_PROGRESS_CAP = 5;
+/**
+ * Process-scoped circuit breaker for storage CAPACITY failures.
+ *
+ * The per-operation retry budget in `OnyxUtils.retryOperation` cannot stop a session-level storm:
+ * each evict -> OnyxDerived recompute -> new write starts its own fresh budget, so a full disk or
+ * exhausted quota can drive tens of thousands of evict+retry cycles that never make progress and
+ * freeze the app. This breaker is the session-level brake — `retryOperation` consults it before
+ * every eviction.
+ *
+ * It is ONE circuit (closed/open/half-open) fed by TWO failure-counting policies, both evaluated in
+ * {@link recordFailureInClosed}. It trips when EITHER:
+ *  - capacity failures within {@link ROLLING_WINDOW_MS} exceed {@link FAILURE_THRESHOLD}, or
+ *  - {@link NO_PROGRESS_CAP} consecutive evictions are each immediately followed by another capacity
+ *    failure (the eviction freed nothing the next write could use — a no-progress cycle). This is a
+ *    cheap proxy for `getDatabaseSize()`, which is costly and only reports origin-wide usage.
+ *
+ * Keeping both policies inside a single state machine — rather than composing two independent breakers
+ * — is deliberate: two breakers each with their own open/half-open/probe latch cannot share one
+ * coherent circuit state without races (stranded half-open probes, storms uncounted while the other
+ * probes, cross-contaminated counters).
+ *
+ * On trip it emits exactly ONE alert per incident (across reopen cycles). After {@link ROLLING_WINDOW_MS}
+ * the circuit moves to half-open and admits a single eviction+retry probe; a successful probe closes
+ * the circuit, a failed probe reopens it for another window.
+ */
+class StorageCircuitBreaker extends AbstractCircuitBreaker_1.default {
+    constructor() {
+        super({
+            resetTimeoutMs: ROLLING_WINDOW_MS,
+            onTrip: (reason) => this.handleTrip(reason),
+            onClose: () => {
+                this.hasTripped = false;
+            },
+        });
+        /** Timestamps of capacity failures still inside the rolling window. */
+        this.failureTimestamps = [];
+        /** Consecutive evictions that each failed to free usable space. */
+        this.consecutiveNoProgress = 0;
+        /** Set when an eviction's retry is pending, so the next capacity failure counts as no-progress. */
+        this.evictionAwaitingResult = false;
+        /** Guards the single alert per incident (the open→half-open→open cycle must not re-alert). */
+        this.hasTripped = false;
+    }
+    /**
+     * Record a CAPACITY failure. Call once per capacity failure in `retryOperation`, BEFORE deciding
+     * whether to evict. Returns `true` when the breaker is open and eviction must not proceed.
+     */
+    recordCapacityFailure() {
+        // We only get here when isAllowed() admitted this caller. In half-open that means THIS is the
+        // single recovery probe: the eviction+retry that follows is the actual test, so the capacity
+        // failure that triggered it must not re-trip the circuit. Let it proceed; the probe's outcome
+        // is the verdict — recordWriteSuccess (retry landed) closes, recordProbeFailure (retry failed,
+        // re-entering retryOperation) reopens.
+        if (this.peekState() === 'half-open') {
+            return false;
+        }
+        return this.recordFailure();
+    }
+    /** Record that `retryOperation` just evicted a key, so the next capacity failure counts as no-progress. */
+    recordEviction() {
+        this.evictionAwaitingResult = true;
+    }
+    /**
+     * Record that a storage write succeeded. Fires on EVERY successful write, so it must only act on the
+     * one that carries capacity information: a write whose eviction was awaiting its verdict. Such a
+     * success means an eviction's retry actually landed — usable space was freed. In half-open that is
+     * the recovery probe succeeding (closes the circuit); in closed it clears the no-progress streak. A
+     * plain write that happens to succeed proves nothing about capacity and is a no-op (the common case).
+     */
+    recordWriteSuccess() {
+        if (!this.evictionAwaitingResult) {
+            return;
+        }
+        this.recordSuccess();
+    }
+    /**
+     * Record that the half-open recovery probe failed. `retryOperation` calls this when a write is
+     * rejected while a probe is in flight — the storage is still full, so reopen for another window.
+     * No-op while fully open (recordFailure short-circuits) and harmless while closed.
+     */
+    recordProbeFailure() {
+        this.recordFailure();
+    }
+    /** Wipe all state back to a fresh closed circuit. Process-scoped, so reset between tests/sessions. */
+    reset() {
+        this.hardReset();
+        this.hasTripped = false;
+    }
+    recordFailureInClosed() {
+        const now = Date.now();
+        this.failureTimestamps = this.failureTimestamps.filter((timestamp) => now - timestamp < ROLLING_WINDOW_MS);
+        // A fresh storm (nothing left in the window) resets the no-progress tracking so a stale eviction
+        // from an earlier, unrelated incident can't be miscounted as no-progress for this one.
+        if (this.failureTimestamps.length === 0) {
+            this.consecutiveNoProgress = 0;
+            this.evictionAwaitingResult = false;
+        }
+        // We evicted on the previous cycle and we're back here with another capacity failure, so that
+        // eviction freed no usable space.
+        if (this.evictionAwaitingResult) {
+            this.consecutiveNoProgress += 1;
+            this.evictionAwaitingResult = false;
+        }
+        this.failureTimestamps.push(now);
+        if (this.failureTimestamps.length > FAILURE_THRESHOLD) {
+            return `${this.failureTimestamps.length} capacity failures within ${ROLLING_WINDOW_MS / 1000}s`;
+        }
+        if (this.consecutiveNoProgress >= NO_PROGRESS_CAP) {
+            return `${this.consecutiveNoProgress} consecutive evictions freed no usable space`;
+        }
+        return null;
+    }
+    recordSuccessInClosed() {
+        // An eviction's retry succeeded: the eviction made progress, so break the no-progress streak.
+        this.consecutiveNoProgress = 0;
+        this.evictionAwaitingResult = false;
+    }
+    resetFailureState() {
+        this.failureTimestamps = [];
+        this.consecutiveNoProgress = 0;
+        this.evictionAwaitingResult = false;
+    }
+    handleTrip(reason) {
+        if (this.hasTripped) {
+            return;
+        }
+        this.hasTripped = true;
+        Logger.logAlert(`Storage circuit breaker tripped: ${reason}. Halting eviction/retry for ${ROLLING_WINDOW_MS / 1000}s to stop a storage failure storm.`);
+    }
+}
+exports.default = new StorageCircuitBreaker();

package/dist/storage/__mocks__/index.d.ts

@@ -1,5 +1,15 @@
 declare const StorageMock: {
     init: jest.Mock<void, [], any>;
+    classifyError: jest.Mock<import("type-fest").ValueOf<{
+        readonly TRANSIENT: "transient";
+        readonly CAPACITY: "capacity";
+        readonly INVALID_DATA: "invalidData";
+        readonly FATAL: "fatal";
+        readonly UNKNOWN: "unknown";
+    }>, [error: unknown], any>;
+    getStorageProvider: jest.Mock<import("../providers/types").default<{
+        [x: string]: unknown;
+    }>, [], any>;
     getItem: jest.Mock<Promise<unknown>, [key: any], any>;
     multiGet: jest.Mock<Promise<import("../providers/types").StorageKeyValuePair[]>, [keys: import("../providers/types").StorageKeyList], any>;
     setItem: jest.Mock<Promise<void>, [key: any, value: unknown], any>;

package/dist/storage/__mocks__/index.js

@@ -32,12 +32,27 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const MemoryOnlyProvider_1 = __importStar(require("../providers/MemoryOnlyProvider"));
+const classifyError_1 = __importDefault(require("../providers/IDBKeyValProvider/classifyError"));
+const classifySQLiteError_1 = __importDefault(require("../providers/classifySQLiteError"));
+const errors_1 = require("../errors");
 const init = jest.fn(MemoryOnlyProvider_1.default.init);
 init();
+// Tests exercise retryOperation against both IndexedDB- and SQLite-shaped errors, so the mock facade
+// classifies with each engine's real (native-dep-free) classifier in turn. Mirrors how the real facade
+// delegates to the active provider; here we cover both engines since one mock stands in for all.
+const classifyError = (error) => {
+    const idbClass = (0, classifyError_1.default)(error);
+    return idbClass === errors_1.StorageErrorClass.UNKNOWN ? (0, classifySQLiteError_1.default)(error) : idbClass;
+};
 const StorageMock = {
     init,
+    classifyError: jest.fn(classifyError),
+    getStorageProvider: jest.fn(() => MemoryOnlyProvider_1.default),
     getItem: jest.fn(MemoryOnlyProvider_1.default.getItem),
     multiGet: jest.fn(MemoryOnlyProvider_1.default.multiGet),
     setItem: jest.fn(MemoryOnlyProvider_1.default.setItem),

package/dist/storage/errors.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared vocabulary for storage write failures. The *classes* are engine-agnostic; the *matching*
+ * is not — each storage provider knows its own error dialect and owns its classifier (see each
+ * provider's `classifyError`). This module deliberately holds NO string matchers: it is the common
+ * taxonomy the two reacting layers agree on, while the per-engine knowledge lives with the engine.
+ *
+ * - the connection layer (`createStore`) recovers TRANSIENT and FATAL errors by reopening the DB, and
+ * - the operation layer (`OnyxUtils.retryOperation`) recovers CAPACITY by eviction and retries UNKNOWN.
+ *
+ * This module has no Onyx dependencies (and no engine dependencies) so it can live in the storage
+ * layer, and be imported by every provider, without creating an import cycle.
+ */
+declare const StorageErrorClass: {
+    /** Connection/transport failure (stale connection). Owner: connection layer — reopen + retry once. */
+    readonly TRANSIENT: "transient";
+    /** Quota exceeded / disk full. Owner: operation layer — evict and retry. */
+    readonly CAPACITY: "capacity";
+    /** Non-serializable payload. Never retriable — the same data will always fail. */
+    readonly INVALID_DATA: "invalidData";
+    /** Backing-store corruption. Owner: connection layer — budgeted heal, then give up. */
+    readonly FATAL: "fatal";
+    /** Unmatched by the active provider. Owner: operation layer — bounded retry, and log the shape so
+     *  recurring cases can be promoted into one of the classes above. */
+    readonly UNKNOWN: "unknown";
+};
+/**
+ * Normalizes any thrown value into a lowercased `{name, message}` pair for matching. Shared by every
+ * provider's classifier so they all extract the error the same way.
+ */
+declare function getErrorParts(error: unknown): {
+    name: string;
+    message: string;
+};
+export { StorageErrorClass, getErrorParts };

package/dist/storage/errors.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageErrorClass = void 0;
+exports.getErrorParts = getErrorParts;
+/**
+ * Shared vocabulary for storage write failures. The *classes* are engine-agnostic; the *matching*
+ * is not — each storage provider knows its own error dialect and owns its classifier (see each
+ * provider's `classifyError`). This module deliberately holds NO string matchers: it is the common
+ * taxonomy the two reacting layers agree on, while the per-engine knowledge lives with the engine.
+ *
+ * - the connection layer (`createStore`) recovers TRANSIENT and FATAL errors by reopening the DB, and
+ * - the operation layer (`OnyxUtils.retryOperation`) recovers CAPACITY by eviction and retries UNKNOWN.
+ *
+ * This module has no Onyx dependencies (and no engine dependencies) so it can live in the storage
+ * layer, and be imported by every provider, without creating an import cycle.
+ */
+const StorageErrorClass = {
+    /** Connection/transport failure (stale connection). Owner: connection layer — reopen + retry once. */
+    TRANSIENT: 'transient',
+    /** Quota exceeded / disk full. Owner: operation layer — evict and retry. */
+    CAPACITY: 'capacity',
+    /** Non-serializable payload. Never retriable — the same data will always fail. */
+    INVALID_DATA: 'invalidData',
+    /** Backing-store corruption. Owner: connection layer — budgeted heal, then give up. */
+    FATAL: 'fatal',
+    /** Unmatched by the active provider. Owner: operation layer — bounded retry, and log the shape so
+     *  recurring cases can be promoted into one of the classes above. */
+    UNKNOWN: 'unknown',
+};
+exports.StorageErrorClass = StorageErrorClass;
+/**
+ * Normalizes any thrown value into a lowercased `{name, message}` pair for matching. Shared by every
+ * provider's classifier so they all extract the error the same way.
+ */
+function getErrorParts(error) {
+    var _a, _b;
+    if (error instanceof Error || (typeof DOMException !== 'undefined' && error instanceof DOMException)) {
+        return { name: ((_a = error.name) !== null && _a !== void 0 ? _a : '').toLowerCase(), message: ((_b = error.message) !== null && _b !== void 0 ? _b : '').toLowerCase() };
+    }
+    return { name: '', message: String(error !== null && error !== void 0 ? error : '').toLowerCase() };
+}

package/dist/storage/index.js

@@ -76,6 +76,11 @@ const storage = {
     getStorageProvider() {
         return provider;
     },
+    /**
+     * Classifies a write error using the active provider's own classifier. Synchronous and pure —
+     * never wrapped in tryOrDegradePerformance.
+     */
+    classifyError: (error) => provider.classifyError(error),
     /**
      * Initializes all providers in the list of storage providers
      * and enables fallback providers if necessary

package/dist/storage/providers/IDBKeyValProvider/classifyError.d.ts

@@ -0,0 +1,9 @@
+import type { ValueOf } from 'type-fest';
+import { StorageErrorClass } from '../../errors';
+/**
+ * Classifies an IndexedDB write failure into the shared storage taxonomy (lib/storage/errors.ts).
+ * Matching is done on the lowercased error name and message. This is the IndexedDB engine's own
+ * dialect — it is NOT shared with other engines.
+ */
+declare function classifyIDBError(error: unknown): ValueOf<typeof StorageErrorClass>;
+export default classifyIDBError;

package/dist/storage/providers/IDBKeyValProvider/classifyError.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const errors_1 = require("../../errors");
+/**
+ * Classifies an IndexedDB write failure into the shared storage taxonomy (lib/storage/errors.ts).
+ * Matching is done on the lowercased error name and message. This is the IndexedDB engine's own
+ * dialect — it is NOT shared with other engines.
+ */
+function classifyIDBError(error) {
+    const { name, message } = (0, errors_1.getErrorParts)(error);
+    // Non-serializable data passed to IDBObjectStore.put — retrying is futile.
+    if (message.includes("failed to execute 'put' on 'idbobjectstore'")) {
+        return errors_1.StorageErrorClass.INVALID_DATA;
+    }
+    // Browser quota exceeded.
+    if (name.includes('quotaexceedederror') || message.includes('quotaexceedederror')) {
+        return errors_1.StorageErrorClass.CAPACITY;
+    }
+    // Backing-store corruption (Chromium LevelDB). Recoverable only via a budgeted reopen.
+    if (message.includes('internal error opening backing store')) {
+        return errors_1.StorageErrorClass.FATAL;
+    }
+    // Transient connection/transport failures — the cached connection is stale and a reopen fixes it:
+    // - InvalidStateError: connection closed between getDB() resolving and db.transaction().
+    // - AbortError: write transaction aborted (connection close / versionchange / sibling abort).
+    // - Safari/WebKit IDB server termination for backgrounded tabs.
+    if (name.includes('invalidstateerror') ||
+        name.includes('aborterror') ||
+        message.includes('connection to indexed database server lost') ||
+        message.includes('connection is closing') ||
+        // This is related to https://github.com/Expensify/react-native-onyx/pull/796 — remove this comment when #796 is merged.
+        message.includes('idb write transaction aborted without an error')) {
+        return errors_1.StorageErrorClass.TRANSIENT;
+    }
+    return errors_1.StorageErrorClass.UNKNOWN;
+}
+exports.default = classifyIDBError;

package/dist/storage/providers/IDBKeyValProvider/createStore.js

@@ -32,47 +32,15 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const IDB = __importStar(require("idb-keyval"));
 const Logger = __importStar(require("../../../Logger"));
+const errors_1 = require("../../errors");
+const classifyError_1 = __importDefault(require("./classifyError"));
 const HEAL_ATTEMPTS_MAX = 3;
-/**
- * Detects the Chromium-specific IDB backing store corruption error.
- * Fires when LevelDB files backing IndexedDB are corrupted and Chrome's
- * internal recovery (RepairDB -> delete -> recreate) also fails.
- */
-function isBackingStoreError(error) {
-    return (error instanceof Error || error instanceof DOMException) && error.message.includes('Internal error opening backing store');
-}
-/**
- * Detects Safari/WebKit IDB connection termination errors.
- * Fires when Safari kills the IDB server process for backgrounded tabs.
- * WebKit bugs: https://bugs.webkit.org/show_bug.cgi?id=197050, https://bugs.webkit.org/show_bug.cgi?id=201483
- */
-function isConnectionLostError(error) {
-    if (!(error instanceof Error || error instanceof DOMException))
-        return false;
-    const msg = error.message.toLowerCase();
-    return msg.includes('connection to indexed database server lost') || msg.includes('connection is closing');
-}
-function isInvalidStateError(error) {
-    return (error instanceof Error || error instanceof DOMException) && error.name === 'InvalidStateError';
-}
-/** Errors that trigger a budgeted heal-and-retry in store(). */
-function isBudgetedHealError(error) {
-    return isBackingStoreError(error) || isConnectionLostError(error);
-}
-function getBudgetedHealErrorLabel(error) {
-    if (isBackingStoreError(error))
-        return 'backing store';
-    if (isConnectionLostError(error))
-        return 'connection lost';
-    return 'unknown';
-}
-/** Union of all error types indicating a stale/dead IDB connection. Used by the visibilitychange probe. */
-function isStaleConnectionError(error) {
-    return isInvalidStateError(error) || isBackingStoreError(error) || isConnectionLostError(error);
-}
 // This is a copy of the createStore function from idb-keyval, we need a custom implementation
 // because we need to create the database manually in order to ensure that the store exists before we use it.
 // If the store does not exist, idb-keyval will throw an error
@@ -94,7 +62,10 @@ function createStore(dbName, storeName) {
         // https://developer.mozilla.org/en-US/docs/Web/API/IDBDatabase/versionchange_event
         // eslint-disable-next-line no-param-reassign
         db.onversionchange = () => {
-            Logger.logInfo('IDB connection closing due to version change', { dbName, storeName });
+            Logger.logInfo('IDB connection closing due to version change', {
+                dbName,
+                storeName,
+            });
             db.close();
             dbp = undefined;
         };
@@ -161,7 +132,11 @@ function createStore(dbName, storeName) {
         Logger.logInfo('IDB visibilitychange probe: tab became visible, checking connection health', { dbName, storeName });
         const probePromise = dbp;
         const dropCacheIfStale = (error) => {
-            if (dbp !== probePromise || !isStaleConnectionError(error)) {
+            // A stale/dead connection surfaces as TRANSIENT (InvalidStateError, Safari connection lost)
+            // or FATAL (Chromium backing-store corruption) per the shared taxonomy (lib/storage/errors.ts).
+            const errorClass = (0, classifyError_1.default)(error);
+            const isStaleConnection = errorClass === errors_1.StorageErrorClass.TRANSIENT || errorClass === errors_1.StorageErrorClass.FATAL;
+            if (dbp !== probePromise || !isStaleConnection) {
                 return;
             }
             Logger.logAlert('IDB visibilitychange probe: stale connection detected, dropping cached connection', {
@@ -196,21 +171,25 @@ function createStore(dbName, storeName) {
             // branch. Swallow here so the probe's separate branch doesn't surface an unhandled rejection.
         });
     });
-    // Handles three recoverable error classes:
-    // 1. InvalidStateError — connection closed between getDB() resolving and db.transaction().
-    //    Retry once with a fresh connection. No budget limit (transient, always worth one reopen).
-    // 2. Backing store corruption (Chromium UnknownError) — drop cached connection and reopen.
-    // 3. Connection lost (Safari UnknownError) — IDB server terminated for backgrounded tabs.
-    //    Both 2 and 3 share a heal budget (3 attempts, reset on success).
-    //    Mirrors Dexie's PR1398_maxLoop pattern: https://github.com/dexie/Dexie.js/blob/master/src/functions/temp-transaction.ts
-    // Note: concurrent store() calls share the budget. Under overlapping failures each caller
+    // The connection layer owns recovery for connection/transport failures. It reacts per the shared
+    // error taxonomy (see lib/storage/errors.ts):
+    // - TRANSIENT (InvalidStateError, AbortError, Safari connection lost) — the cached connection is
+    //   stale. Drop it and retry once with a fresh one. Unbudgeted: a single reopen is always worth it
+    //   and is bounded per operation.
+    // - FATAL (Chromium backing-store corruption) — reopening can recover transient corruption, but
+    //   repeating forever is futile, so the heal is budgeted (3 attempts, reset on success).
+    //   Mirrors Dexie's PR1398_maxLoop pattern: https://github.com/dexie/Dexie.js/blob/master/src/functions/temp-transaction.ts
+    // - CAPACITY / UNKNOWN are NOT the connection layer's responsibility — propagate to the operation
+    //   layer (OnyxUtils.retryOperation) without retrying here, to avoid compounding retries.
+    // Note: concurrent store() calls share the heal budget. Under overlapping failures each caller
     // decrements independently, so the budget may drain faster than one-per-incident. This is
     // acceptable — same as Dexie's approach — and the budget resets on any success.
     return (txMode, callback) => executeTransaction(txMode, callback)
         .then(resetHealBudget)
         .catch((error) => {
-        if (isInvalidStateError(error)) {
-            Logger.logInfo('IDB InvalidStateError — dropping cached connection and retrying', {
+        const errorClass = (0, classifyError_1.default)(error);
+        if (errorClass === errors_1.StorageErrorClass.TRANSIENT) {
+            Logger.logInfo('IDB transient error — dropping cached connection and retrying once', {
                 dbName,
                 storeName,
                 txMode,
@@ -219,29 +198,33 @@ function createStore(dbName, storeName) {
             dbp = undefined;
             return executeTransaction(txMode, callback).then(resetHealBudget);
         }
-        if (isBudgetedHealError(error) && healAttemptsRemaining > 0) {
+        if (errorClass === errors_1.StorageErrorClass.FATAL && healAttemptsRemaining > 0) {
             healAttemptsRemaining--;
-            const label = getBudgetedHealErrorLabel(error);
-            Logger.logInfo(`IDB heal: ${label} error detected — dropping cached connection and reopening (${healAttemptsRemaining} attempts left)`, {
+            Logger.logInfo(`IDB heal: backing store error detected — dropping cached connection and reopening (${healAttemptsRemaining} attempts left)`, {
                 dbName,
                 storeName,
             });
             dbp = undefined;
             return executeTransaction(txMode, callback).then((result) => {
-                Logger.logInfo(`IDB heal: successfully recovered after ${label} error`, { dbName, storeName });
+                Logger.logInfo('IDB heal: successfully recovered after backing store error', { dbName, storeName });
                 return resetHealBudget(result);
             });
         }
-        if (isBudgetedHealError(error)) {
-            Logger.logAlert(`IDB heal: ${getBudgetedHealErrorLabel(error)} error — heal budget exhausted, giving up`, {
+        if (errorClass === errors_1.StorageErrorClass.FATAL) {
+            Logger.logAlert('IDB heal: backing store error — heal budget exhausted, giving up', {
                 dbName,
                 storeName,
             });
         }
-        else {
-            Logger.logAlert('IDB error is not recoverable, giving up', {
+        else if (errorClass === errors_1.StorageErrorClass.UNKNOWN) {
+            // UNKNOWN — unexpected at this layer; record it so it's visible. CAPACITY is the
+            // expected propagation path (the operation layer owns its logging, and suppresses it
+            // entirely once the circuit breaker is open), so we do NOT log it here — doing so was a
+            // per-failed-write line that dominated the storm.
+            Logger.logInfo('IDB error not recoverable at the connection layer, propagating', {
                 dbName,
                 storeName,
+                errorClass,
                 errorMessage: error instanceof Error ? error.message : String(error),
             });
         }

package/dist/storage/providers/IDBKeyValProvider/index.js

@@ -39,6 +39,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const IDB = __importStar(require("idb-keyval"));
 const utils_1 = __importDefault(require("../../../utils"));
 const createStore_1 = __importDefault(require("./createStore"));
+const classifyError_1 = __importDefault(require("./classifyError"));
 const DB_NAME = 'OnyxDB';
 const STORE_NAME = 'keyvaluepairs';
 /**
@@ -60,6 +61,10 @@ const provider = {
      * The name of the provider that can be printed to the logs
      */
     name: 'IDBKeyValProvider',
+    /**
+     * Classifies an IndexedDB write failure into the shared storage taxonomy.
+     */
+    classifyError: classifyError_1.default,
     /**
      * Initializes the storage provider
      */