react-native-onyx 3.0.86 → 3.0.88

package/dist/CircuitBreaker/AbstractCircuitBreaker.d.ts

@@ -0,0 +1,91 @@
+import type { CircuitBreakerOptions, CircuitBreakerState } from './types';
+/**
+ * Generic circuit breaker built on {@link StateMachine}.
+ *
+ * - **closed**: requests are allowed; failures are counted.
+ * - **open**: requests are rejected until {@link resetTimeoutMs} elapses.
+ * - **half-open**: the recovery-probe state. After the open timeout, the breaker admits exactly ONE
+ *   probe request: success means the dependency recovered, so the circuit closes. Failure means it's
+ *   still down, so the circuit reopens. This single-request probe prevents a "thundering herd" where
+ *   every caller fails loudly when the service hasn't recovered yet.
+ *
+ * Subclasses implement the failure-counting policy by overriding {@link recordFailureInClosed} (and
+ * friends) — e.g. counting consecutive failures, or failures within a rolling time window, or any
+ * combination of those.
+ *
+ * @example
+ * class MyBreaker extends AbstractCircuitBreaker {
+ *     private failures = 0;
+ *     protected recordFailureInClosed() {
+ *         this.failures += 1;
+ *         return this.failures >= 3 ? `${this.failures} failures` : null;
+ *     }
+ *     protected recordSuccessInClosed() { this.failures = 0; }
+ *     protected resetFailureState() { this.failures = 0; }
+ * }
+ *
+ * const breaker = new MyBreaker({resetTimeoutMs: 30_000});
+ * if (breaker.isAllowed()) {
+ *     try {
+ *         doWork();
+ *         breaker.recordSuccess();
+ *     } catch {
+ *         breaker.recordFailure();
+ *     }
+ * }
+ */
+declare abstract class AbstractCircuitBreaker {
+    private machine;
+    private openedAt;
+    private isProbeInFlight;
+    private readonly resetTimeoutMs;
+    private readonly onTrip?;
+    private readonly onClose?;
+    constructor(options?: CircuitBreakerOptions);
+    /** Record a failure while the circuit is closed. Returns a trip reason when the threshold is exceeded. */
+    protected abstract recordFailureInClosed(): string | null;
+    /** Update failure state after a successful request while the circuit is closed. */
+    protected abstract recordSuccessInClosed(): void;
+    /** Clear accumulated failure state without changing circuit state. */
+    protected abstract resetFailureState(): void;
+    /**
+     * Whether a request may proceed.
+     *
+     * Returns `false` while open. In half-open, the FIRST caller is admitted as the recovery probe and
+     * `isProbeInFlight` is latched so every subsequent caller is rejected until that probe resolves
+     * (via {@link recordSuccess} → close, or {@link recordFailure} → reopen). That single-probe gate is
+     * the whole point of half-open: it tests recovery with one request instead of letting a herd of
+     * waiting callers stampede a dependency that may still be down.
+     */
+    isAllowed(): boolean;
+    /**
+     * Record a failed request. May open the circuit from closed or half-open.
+     * @returns `true` when the circuit is open after recording (the request must not proceed).
+     */
+    recordFailure(): boolean;
+    /** Record a successful request. Closes the circuit from half-open and clears failure counts. */
+    recordSuccess(): void;
+    /**
+     * The current state WITHOUT advancing recovery — a pure query, safe to call without side effects.
+     * The open→half-open transition is applied only at the admission point ({@link isAllowed}); by the
+     * time a caller queries state after being admitted, that transition has already happened.
+     */
+    peekState(): CircuitBreakerState;
+    /**
+     * Force the circuit back to closed from ANY state. This is a reset, not a transition, so it
+     * deliberately bypasses the transition graph (and does not fire {@link onClose}). Use only to wipe
+     * all state — e.g. between tests or sessions.
+     */
+    protected hardReset(): void;
+    private getCurrentState;
+    private trip;
+    private close;
+    /**
+     * Lazily advance open → half-open once the reset timeout has elapsed. This is checked on read
+     * (via {@link getCurrentState}) rather than on a timer, so there's nothing to schedule or clean up:
+     * the transition simply becomes visible to the next caller after the window. Entering half-open
+     * clears `isProbeInFlight` so the next admitted request becomes the recovery probe.
+     */
+    private maybeRecover;
+}
+export default AbstractCircuitBreaker;

package/dist/CircuitBreaker/AbstractCircuitBreaker.js

@@ -0,0 +1,166 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const StateMachine_1 = __importDefault(require("../StateMachine"));
+const types_1 = require("./types");
+/**
+ * Generic circuit breaker built on {@link StateMachine}.
+ *
+ * - **closed**: requests are allowed; failures are counted.
+ * - **open**: requests are rejected until {@link resetTimeoutMs} elapses.
+ * - **half-open**: the recovery-probe state. After the open timeout, the breaker admits exactly ONE
+ *   probe request: success means the dependency recovered, so the circuit closes. Failure means it's
+ *   still down, so the circuit reopens. This single-request probe prevents a "thundering herd" where
+ *   every caller fails loudly when the service hasn't recovered yet.
+ *
+ * Subclasses implement the failure-counting policy by overriding {@link recordFailureInClosed} (and
+ * friends) — e.g. counting consecutive failures, or failures within a rolling time window, or any
+ * combination of those.
+ *
+ * @example
+ * class MyBreaker extends AbstractCircuitBreaker {
+ *     private failures = 0;
+ *     protected recordFailureInClosed() {
+ *         this.failures += 1;
+ *         return this.failures >= 3 ? `${this.failures} failures` : null;
+ *     }
+ *     protected recordSuccessInClosed() { this.failures = 0; }
+ *     protected resetFailureState() { this.failures = 0; }
+ * }
+ *
+ * const breaker = new MyBreaker({resetTimeoutMs: 30_000});
+ * if (breaker.isAllowed()) {
+ *     try {
+ *         doWork();
+ *         breaker.recordSuccess();
+ *     } catch {
+ *         breaker.recordFailure();
+ *     }
+ * }
+ */
+class AbstractCircuitBreaker {
+    constructor(options = {}) {
+        var _a;
+        this.openedAt = 0;
+        this.isProbeInFlight = false;
+        this.resetTimeoutMs = (_a = options.resetTimeoutMs) !== null && _a !== void 0 ? _a : 60000;
+        this.onTrip = options.onTrip;
+        this.onClose = options.onClose;
+        this.machine = new StateMachine_1.default('closed', types_1.CIRCUIT_BREAKER_TRANSITIONS);
+    }
+    /**
+     * Whether a request may proceed.
+     *
+     * Returns `false` while open. In half-open, the FIRST caller is admitted as the recovery probe and
+     * `isProbeInFlight` is latched so every subsequent caller is rejected until that probe resolves
+     * (via {@link recordSuccess} → close, or {@link recordFailure} → reopen). That single-probe gate is
+     * the whole point of half-open: it tests recovery with one request instead of letting a herd of
+     * waiting callers stampede a dependency that may still be down.
+     */
+    isAllowed() {
+        const currentState = this.getCurrentState();
+        if (currentState === 'open') {
+            return false;
+        }
+        if (currentState === 'half-open') {
+            if (this.isProbeInFlight) {
+                return false;
+            }
+            this.isProbeInFlight = true;
+        }
+        return true;
+    }
+    /**
+     * Record a failed request. May open the circuit from closed or half-open.
+     * @returns `true` when the circuit is open after recording (the request must not proceed).
+     */
+    recordFailure() {
+        if (this.machine.state === 'open') {
+            return true;
+        }
+        if (this.machine.state === 'half-open') {
+            this.trip();
+            return true;
+        }
+        const reason = this.recordFailureInClosed();
+        if (reason) {
+            this.trip(reason);
+            return true;
+        }
+        return false;
+    }
+    /** Record a successful request. Closes the circuit from half-open and clears failure counts. */
+    recordSuccess() {
+        if (this.machine.state === 'half-open') {
+            this.close();
+            return;
+        }
+        if (this.machine.state === 'closed') {
+            this.recordSuccessInClosed();
+        }
+    }
+    /**
+     * The current state WITHOUT advancing recovery — a pure query, safe to call without side effects.
+     * The open→half-open transition is applied only at the admission point ({@link isAllowed}); by the
+     * time a caller queries state after being admitted, that transition has already happened.
+     */
+    peekState() {
+        return this.machine.state;
+    }
+    /**
+     * Force the circuit back to closed from ANY state. This is a reset, not a transition, so it
+     * deliberately bypasses the transition graph (and does not fire {@link onClose}). Use only to wipe
+     * all state — e.g. between tests or sessions.
+     */
+    hardReset() {
+        this.machine = new StateMachine_1.default('closed', types_1.CIRCUIT_BREAKER_TRANSITIONS);
+        this.openedAt = 0;
+        this.isProbeInFlight = false;
+        this.resetFailureState();
+    }
+    getCurrentState() {
+        this.maybeRecover();
+        return this.machine.state;
+    }
+    trip(reason = '') {
+        var _a;
+        if (this.machine.state === 'open') {
+            return;
+        }
+        this.machine = this.machine.transition('open');
+        this.openedAt = Date.now();
+        this.isProbeInFlight = false;
+        this.resetFailureState();
+        (_a = this.onTrip) === null || _a === void 0 ? void 0 : _a.call(this, reason);
+    }
+    close() {
+        var _a;
+        // close() only ever runs from half-open (see recordSuccess), and half-open → closed is the one
+        // legal closing transition — so go through transition() to keep the illegal open → closed jump
+        // an error rather than silently constructing a fresh closed machine.
+        this.machine = this.machine.transition('closed');
+        this.openedAt = 0;
+        this.isProbeInFlight = false;
+        this.resetFailureState();
+        (_a = this.onClose) === null || _a === void 0 ? void 0 : _a.call(this);
+    }
+    /**
+     * Lazily advance open → half-open once the reset timeout has elapsed. This is checked on read
+     * (via {@link getCurrentState}) rather than on a timer, so there's nothing to schedule or clean up:
+     * the transition simply becomes visible to the next caller after the window. Entering half-open
+     * clears `isProbeInFlight` so the next admitted request becomes the recovery probe.
+     */
+    maybeRecover() {
+        if (this.machine.state !== 'open') {
+            return;
+        }
+        if (Date.now() - this.openedAt < this.resetTimeoutMs) {
+            return;
+        }
+        this.machine = this.machine.transition('half-open');
+        this.isProbeInFlight = false;
+    }
+}
+exports.default = AbstractCircuitBreaker;

package/dist/CircuitBreaker/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * States of the circuit breaker.
+ *
+ * - **closed**: normal operation; requests flow and failures are counted.
+ * - **open**: tripped; requests are rejected outright so a known-bad dependency isn't hammered.
+ * - **half-open**: a trial state entered after the open timeout — see {@link CIRCUIT_BREAKER_TRANSITIONS}.
+ */
+type CircuitBreakerState = 'closed' | 'open' | 'half-open';
+/**
+ * Legal state transitions. The flow is closed → open → half-open → (closed | open).
+ *
+ * The **half-open** state exists so the breaker can test whether the dependency has recovered WITHOUT
+ * flipping straight back to fully closed. Going open → closed blindly would, on a dependency that is
+ * still down, immediately re-admit the full load and re-trip — flapping between open and closed every
+ * window. Instead, after the open timeout the breaker moves to half-open and admits a single trial
+ * ("probe") request:
+ *  - probe succeeds → the dependency is healthy again → transition to **closed** (resume normal flow).
+ *  - probe fails    → still broken → transition back to **open** for another timeout window.
+ *
+ * Admitting exactly one probe (rather than reopening the floodgates) is also what prevents the
+ * "thundering herd": many callers retrying at once the instant the timeout elapses, re-overwhelming a
+ * dependency that was just starting to recover.
+ */
+declare const CIRCUIT_BREAKER_TRANSITIONS: {
+    readonly closed: readonly ["open"];
+    readonly open: readonly ["half-open"];
+    readonly 'half-open': readonly ["closed", "open"];
+};
+type CircuitBreakerOptions = {
+    /** Time in milliseconds the circuit stays open before moving to half-open. */
+    resetTimeoutMs?: number;
+    /** Called once each time the circuit opens. */
+    onTrip?: (reason: string) => void;
+    /** Called when the circuit closes. */
+    onClose?: () => void;
+};
+export type { CircuitBreakerOptions, CircuitBreakerState };
+export { CIRCUIT_BREAKER_TRANSITIONS };

package/dist/CircuitBreaker/types.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CIRCUIT_BREAKER_TRANSITIONS = void 0;
+/**
+ * Legal state transitions. The flow is closed → open → half-open → (closed | open).
+ *
+ * The **half-open** state exists so the breaker can test whether the dependency has recovered WITHOUT
+ * flipping straight back to fully closed. Going open → closed blindly would, on a dependency that is
+ * still down, immediately re-admit the full load and re-trip — flapping between open and closed every
+ * window. Instead, after the open timeout the breaker moves to half-open and admits a single trial
+ * ("probe") request:
+ *  - probe succeeds → the dependency is healthy again → transition to **closed** (resume normal flow).
+ *  - probe fails    → still broken → transition back to **open** for another timeout window.
+ *
+ * Admitting exactly one probe (rather than reopening the floodgates) is also what prevents the
+ * "thundering herd": many callers retrying at once the instant the timeout elapses, re-overwhelming a
+ * dependency that was just starting to recover.
+ */
+const CIRCUIT_BREAKER_TRANSITIONS = {
+    closed: ['open'],
+    open: ['half-open'],
+    'half-open': ['closed', 'open'],
+};
+exports.CIRCUIT_BREAKER_TRANSITIONS = CIRCUIT_BREAKER_TRANSITIONS;

package/dist/OnyxUtils.d.ts

@@ -134,11 +134,17 @@ declare function getCollectionDataAndSendAsObject<TKey extends OnyxKey>(matching
 declare function remove<TKey extends OnyxKey>(key: TKey, isProcessingCollectionUpdate?: boolean): Promise<void>;
 declare function reportStorageQuota(error?: Error): Promise<void>;
 /**
- * Handles storage operation failures based on the error type:
- * - Storage capacity errors: evicts data and retries the operation
- * - Invalid data errors: logs an alert and throws an error
- * - Non-retriable errors: logs an alert and resolves without retrying
- * - Other errors: retries the operation
+ * Handles storage operation failures based on the error class (see lib/storage/errors.ts).
+ * The connection layer (createStore) owns connection/transport recovery; this operation layer owns
+ * capacity recovery (eviction) so that a given failure is retried by exactly one layer:
+ * - INVALID_DATA: logs an alert and throws (the same data will always fail).
+ * - TRANSIENT / FATAL: the connection layer already retried (transient) or exhausted its heal budget
+ *   and alerted (fatal). Retrying here would only re-amplify, so we skip the write quietly.
+ * - CAPACITY: evicts the least recently accessed evictable key and retries, under a session-level
+ *   circuit breaker (see lib/StorageCircuitBreaker.ts) that halts the loop once eviction stops making
+ *   progress or failures storm — the per-operation budget alone cannot stop a session-wide storm.
+ * - UNKNOWN: the provider couldn't classify it — log the full error shape (name + message +
+ *   provider) once so it's visible, then bounded retry without eviction.
  */
 declare function retryOperation<TMethod extends RetriableOnyxOperation>(error: Error, onyxMethod: TMethod, defaultParams: Parameters<TMethod>[0], retryAttempt: number | undefined, inFlightKeys?: Set<OnyxKey>): Promise<void>;
 /**

package/dist/OnyxUtils.js

@@ -43,8 +43,9 @@ const DevTools_1 = __importDefault(require("./DevTools"));
 const Logger = __importStar(require("./Logger"));
 const OnyxCache_1 = __importStar(require("./OnyxCache"));
 const OnyxKeys_1 = __importDefault(require("./OnyxKeys"));
-const Str = __importStar(require("./Str"));
+const StorageCircuitBreaker_1 = __importDefault(require("./StorageCircuitBreaker"));
 const storage_1 = __importDefault(require("./storage"));
+const errors_1 = require("./storage/errors");
 const utils_1 = __importDefault(require("./utils"));
 const createDeferredTask_1 = __importDefault(require("./createDeferredTask"));
 const logMessages_1 = __importDefault(require("./logMessages"));
@@ -57,21 +58,6 @@ const METHOD = {
     MULTI_SET: 'multiset',
     CLEAR: 'clear',
 };
-// IndexedDB errors that indicate storage capacity issues where eviction can help
-const IDB_STORAGE_ERRORS = [
-    'quotaexceedederror', // Browser storage quota exceeded
-];
-// SQLite errors that indicate storage capacity issues where eviction can help
-const SQLITE_STORAGE_ERRORS = [
-    'database or disk is full', // Device storage is full
-];
-const STORAGE_ERRORS = [...IDB_STORAGE_ERRORS, ...SQLITE_STORAGE_ERRORS];
-// IndexedDB errors where retrying is futile because the underlying connection/store is broken.
-// The healing path (separate from retryOperation) is responsible for recovery.
-const IDB_NON_RETRIABLE_ERRORS = [
-    'internal error opening backing store', // LevelDB backing store is broken at the filesystem level
-];
-const NON_RETRIABLE_ERRORS = [...IDB_NON_RETRIABLE_ERRORS];
 // Max number of retries for failed storage operations
 const MAX_STORAGE_OPERATION_RETRY_ATTEMPTS = 5;
 // Key/value store of Onyx key and arrays of values to merge
@@ -496,7 +482,10 @@ function keysChanged(collectionKey, partialCollection, partialPreviousCollection
             continue;
         }
         try {
-            lastConnectionCallbackData.set(subscriber.subscriptionID, { value: cachedCollection, matchedKey: subscriber.key });
+            lastConnectionCallbackData.set(subscriber.subscriptionID, {
+                value: cachedCollection,
+                matchedKey: subscriber.key,
+            });
             if (subscriber.waitForCollectionCallback) {
                 subscriber.callback(cachedCollection, subscriber.key, partialCollection);
                 continue;
@@ -533,7 +522,10 @@ function keysChanged(collectionKey, partialCollection, partialPreviousCollection
         try {
             const subscriberCallback = subscriber.callback;
             subscriberCallback(cachedCollection[subscriber.key], subscriber.key);
-            lastConnectionCallbackData.set(subscriber.subscriptionID, { value: cachedCollection[subscriber.key], matchedKey: subscriber.key });
+            lastConnectionCallbackData.set(subscriber.subscriptionID, {
+                value: cachedCollection[subscriber.key],
+                matchedKey: subscriber.key,
+            });
         }
         catch (error) {
             Logger.logAlert(`[OnyxUtils.keysChanged] Subscriber callback threw an error for key '${collectionKey}': ${error}`);
@@ -595,13 +587,21 @@ function keyChanged(key, value, canUpdateSubscriber = () => true, isProcessingCo
                         cachedCollection = getCachedCollection(subscriber.key);
                         cachedCollections[subscriber.key] = cachedCollection;
                     }
-                    lastConnectionCallbackData.set(subscriber.subscriptionID, { value: cachedCollection, matchedKey: subscriber.key });
-                    subscriber.callback(cachedCollection, subscriber.key, { [key]: value });
+                    lastConnectionCallbackData.set(subscriber.subscriptionID, {
+                        value: cachedCollection,
+                        matchedKey: subscriber.key,
+                    });
+                    subscriber.callback(cachedCollection, subscriber.key, {
+                        [key]: value,
+                    });
                     continue;
                 }
                 const subscriberCallback = subscriber.callback;
                 subscriberCallback(value, key);
-                lastConnectionCallbackData.set(subscriber.subscriptionID, { value, matchedKey: key });
+                lastConnectionCallbackData.set(subscriber.subscriptionID, {
+                    value,
+                    matchedKey: key,
+                });
                 continue;
             }
             catch (error) {
@@ -666,44 +666,73 @@ function remove(key, isProcessingCollectionUpdate) {
 function reportStorageQuota(error) {
     return storage_1.default.getDatabaseSize()
         .then(({ bytesUsed, bytesRemaining, usageDetails }) => {
-        Logger.logInfo(`Storage Quota Check -- bytesUsed: ${bytesUsed} bytesRemaining: ${bytesRemaining}${usageDetails ? ` usageDetails: ${JSON.stringify(usageDetails)}` : ''}. Original error: ${error}`);
+        // `bytesRemaining` comes from navigator.storage.estimate() and is an ORIGIN-WIDE estimate,
+        // not headroom for this database. The browser allocates IndexedDB storage dynamically, so a
+        // QuotaExceededError can legitimately occur even when this number still looks large.
+        Logger.logInfo(`Storage Quota Check -- bytesUsed: ${bytesUsed} originWideBytesRemaining (estimate, not per-DB headroom): ${bytesRemaining}${usageDetails ? ` usageDetails: ${JSON.stringify(usageDetails)}` : ''}. Original error: ${error}`);
     })
         .catch((dbSizeError) => {
         Logger.logAlert(`Unable to get database size. getDatabaseSize error: ${dbSizeError}. Original error: ${error}`);
     });
 }
 /**
- * Handles storage operation failures based on the error type:
- * - Storage capacity errors: evicts data and retries the operation
- * - Invalid data errors: logs an alert and throws an error
- * - Non-retriable errors: logs an alert and resolves without retrying
- * - Other errors: retries the operation
+ * Handles storage operation failures based on the error class (see lib/storage/errors.ts).
+ * The connection layer (createStore) owns connection/transport recovery; this operation layer owns
+ * capacity recovery (eviction) so that a given failure is retried by exactly one layer:
+ * - INVALID_DATA: logs an alert and throws (the same data will always fail).
+ * - TRANSIENT / FATAL: the connection layer already retried (transient) or exhausted its heal budget
+ *   and alerted (fatal). Retrying here would only re-amplify, so we skip the write quietly.
+ * - CAPACITY: evicts the least recently accessed evictable key and retries, under a session-level
+ *   circuit breaker (see lib/StorageCircuitBreaker.ts) that halts the loop once eviction stops making
+ *   progress or failures storm — the per-operation budget alone cannot stop a session-wide storm.
+ * - UNKNOWN: the provider couldn't classify it — log the full error shape (name + message +
+ *   provider) once so it's visible, then bounded retry without eviction.
  */
 function retryOperation(error, onyxMethod, defaultParams, retryAttempt, inFlightKeys) {
-    var _a, _b, _c, _d;
     const currentRetryAttempt = retryAttempt !== null && retryAttempt !== void 0 ? retryAttempt : 0;
     const nextRetryAttempt = currentRetryAttempt + 1;
-    Logger.logInfo(`Failed to save to storage. Error: ${error}. onyxMethod: ${onyxMethod.name}. retryAttempt: ${currentRetryAttempt}/${MAX_STORAGE_OPERATION_RETRY_ATTEMPTS}`);
-    if (error && Str.startsWith(error.message, "Failed to execute 'put' on 'IDBObjectStore'")) {
+    const errorClass = storage_1.default.classifyError(error);
+    // While open (or while a half-open probe is already in flight), drop capacity retries silently —
+    // the breaker already emitted its single alert, and logging per failed write is exactly the storm
+    // we are suppressing. A rejected half-open caller is the in-flight probe failing; record that so
+    // the circuit reopens for another window. (We return before the log line below on purpose.)
+    if (errorClass === errors_1.StorageErrorClass.CAPACITY && !StorageCircuitBreaker_1.default.isAllowed()) {
+        StorageCircuitBreaker_1.default.recordProbeFailure();
+        return Promise.resolve();
+    }
+    Logger.logInfo(`Failed to save to storage. Error: ${error}. class: ${errorClass}. onyxMethod: ${onyxMethod.name}. retryAttempt: ${currentRetryAttempt}/${MAX_STORAGE_OPERATION_RETRY_ATTEMPTS}`);
+    if (errorClass === errors_1.StorageErrorClass.INVALID_DATA) {
         Logger.logAlert(`Attempted to set invalid data set in Onyx. Please ensure all data is serializable. Error: ${error}`);
         throw error;
     }
-    const errorMessage = (_b = (_a = error === null || error === void 0 ? void 0 : error.message) === null || _a === void 0 ? void 0 : _a.toLowerCase) === null || _b === void 0 ? void 0 : _b.call(_a);
-    const errorName = (_d = (_c = error === null || error === void 0 ? void 0 : error.name) === null || _c === void 0 ? void 0 : _c.toLowerCase) === null || _d === void 0 ? void 0 : _d.call(_c);
-    const isStorageCapacityError = STORAGE_ERRORS.some((storageError) => (errorName === null || errorName === void 0 ? void 0 : errorName.includes(storageError)) || (errorMessage === null || errorMessage === void 0 ? void 0 : errorMessage.includes(storageError)));
-    const isNonRetriableError = NON_RETRIABLE_ERRORS.some((nonRetriableError) => (errorName === null || errorName === void 0 ? void 0 : errorName.includes(nonRetriableError)) || (errorMessage === null || errorMessage === void 0 ? void 0 : errorMessage.includes(nonRetriableError)));
-    if (isNonRetriableError) {
-        Logger.logAlert(`Storage operation skipped retry for non-retriable error. Error: ${error}. onyxMethod: ${onyxMethod.name}.`);
+    if (errorClass === errors_1.StorageErrorClass.TRANSIENT || errorClass === errors_1.StorageErrorClass.FATAL) {
+        Logger.logInfo(`Storage operation skipped retry; ${errorClass} errors are handled by the connection layer. Error: ${error}. onyxMethod: ${onyxMethod.name}.`);
         return Promise.resolve();
     }
     if (nextRetryAttempt > MAX_STORAGE_OPERATION_RETRY_ATTEMPTS) {
-        Logger.logAlert(`Storage operation failed after 5 retries. Error: ${error}. onyxMethod: ${onyxMethod.name}.`);
+        Logger.logAlert(`Storage operation failed after ${MAX_STORAGE_OPERATION_RETRY_ATTEMPTS} retries. Error: ${error}. onyxMethod: ${onyxMethod.name}.`);
         return Promise.resolve();
     }
-    if (!isStorageCapacityError) {
+    if (errorClass === errors_1.StorageErrorClass.UNKNOWN) {
+        // UNKNOWN is the blind spot: the active provider's classifier did not recognize this error, so
+        // we cannot route it to a real recovery strategy. Log the full error shape (name + message +
+        // provider) once per operation so telemetry can reveal what lives in UNKNOWN, letting us promote
+        // recurring cases into TRANSIENT/CAPACITY/FATAL. Logged on the first attempt only to avoid the
+        // per-retry amplification this mechanism is trying to kill. Then bounded retry without eviction.
+        if (currentRetryAttempt === 0) {
+            Logger.logAlert(`Unclassified storage error. provider: ${storage_1.default.getStorageProvider().name}. name: ${error === null || error === void 0 ? void 0 : error.name}. message: ${error === null || error === void 0 ? void 0 : error.message}. onyxMethod: ${onyxMethod.name}.`);
+        }
         // @ts-expect-error No overload matches this call.
         return onyxMethod(defaultParams, nextRetryAttempt);
     }
+    // CAPACITY: feed the session-level circuit breaker before evicting. The per-operation budget above
+    // cannot stop a session-wide storm — each evicted key triggers an OnyxDerived recompute that spawns
+    // a fresh write with its own budget — so the breaker is what actually halts the meltdown. (The
+    // already-open case returned silently at the top of this function.)
+    if (StorageCircuitBreaker_1.default.recordCapacityFailure()) {
+        // This failure tripped the breaker; it already emitted its single alert. Stop here.
+        return Promise.resolve();
+    }
     // Find the least recently accessed evictable key that we can remove. Never evict an in-flight
     // key — its cache value is the merge base this retry depends on, so dropping it would truncate
     // the write to just the delta and diverge cache from storage.
@@ -718,8 +747,15 @@ function retryOperation(error, onyxMethod, defaultParams, retryAttempt, inFlight
     // Remove the least recently accessed key and retry.
     Logger.logInfo(`Out of storage. Evicting least recently accessed key (${keyForRemoval}) and retrying. Error: ${error}`);
     reportStorageQuota(error);
-    // @ts-expect-error No overload matches this call.
-    return remove(keyForRemoval).then(() => onyxMethod(defaultParams, nextRetryAttempt));
+    return remove(keyForRemoval).then(() => {
+        // Mark the eviction only once the deletion has actually completed, immediately before the
+        // retry it pairs with. Recording earlier lets a concurrent write's capacity failure consume
+        // the marker as a no-progress cycle while this deletion is still pending and may yet free
+        // space — so the verdict belongs to the retry that follows the deletion, not the eviction call.
+        StorageCircuitBreaker_1.default.recordEviction();
+        // @ts-expect-error No overload matches this call.
+        return onyxMethod(defaultParams, nextRetryAttempt);
+    });
 }
 /**
  * Notifies subscribers and writes current value to cache
@@ -1117,6 +1153,7 @@ function setWithRetry({ key, value, options }, retryAttempt) {
         return Promise.resolve();
     }
     return storage_1.default.setItem(key, valueWithoutNestedNullValues)
+        .then(() => StorageCircuitBreaker_1.default.recordWriteSuccess())
         .catch((error) => OnyxUtils.retryOperation(error, setWithRetry, { key, value: valueWithoutNestedNullValues, options }, retryAttempt))
         .then(() => {
         OnyxUtils.sendActionToDevTools(OnyxUtils.METHOD.SET, key, valueWithoutNestedNullValues);
@@ -1201,6 +1238,7 @@ function multiSetWithRetry(data, retryAttempt) {
     });
     const inFlightKeys = new Set(keyValuePairsToSet.map(([key]) => key));
     return storage_1.default.multiSet(keyValuePairsToStore)
+        .then(() => StorageCircuitBreaker_1.default.recordWriteSuccess())
         .catch((error) => OnyxUtils.retryOperation(error, multiSetWithRetry, newData, retryAttempt, inFlightKeys))
         .then(() => {
         OnyxUtils.sendActionToDevTools(OnyxUtils.METHOD.MULTI_SET, undefined, newData);
@@ -1269,6 +1307,7 @@ function setCollectionWithRetry({ collectionKey, collection }, retryAttempt) {
         }
         const inFlightKeys = new Set(keyValuePairs.map(([key]) => key));
         return storage_1.default.multiSet(keyValuePairs)
+            .then(() => StorageCircuitBreaker_1.default.recordWriteSuccess())
             .catch((error) => OnyxUtils.retryOperation(error, setCollectionWithRetry, { collectionKey, collection }, retryAttempt, inFlightKeys))
             .then(() => {
             OnyxUtils.sendActionToDevTools(OnyxUtils.METHOD.SET_COLLECTION, undefined, mutableCollection);
@@ -1398,7 +1437,13 @@ function mergeCollectionWithPatches({ collectionKey, collection, mergeReplaceNul
             }
             const inFlightKeys = new Set(Object.keys(finalMergedCollection));
             return Promise.all(promises)
-                .catch((error) => retryOperation(error, mergeCollectionWithPatches, { collectionKey, collection: resultCollection, mergeReplaceNullPatches, isProcessingCollectionUpdate }, retryAttempt, inFlightKeys))
+                .then(() => StorageCircuitBreaker_1.default.recordWriteSuccess())
+                .catch((error) => retryOperation(error, mergeCollectionWithPatches, {
+                collectionKey,
+                collection: resultCollection,
+                mergeReplaceNullPatches,
+                isProcessingCollectionUpdate,
+            }, retryAttempt, inFlightKeys))
                 .then(() => {
                 sendActionToDevTools(METHOD.MERGE_COLLECTION, undefined, resultCollection);
             });
@@ -1459,6 +1504,7 @@ function partialSetCollection({ collectionKey, collection }, retryAttempt) {
         }
         const inFlightKeys = new Set(keyValuePairs.map(([key]) => key));
         return storage_1.default.multiSet(keyValuePairs)
+            .then(() => StorageCircuitBreaker_1.default.recordWriteSuccess())
             .catch((error) => retryOperation(error, partialSetCollection, { collectionKey, collection }, retryAttempt, inFlightKeys))
             .then(() => {
             sendActionToDevTools(METHOD.SET_COLLECTION, undefined, mutableCollection);

package/dist/StateMachine.d.ts

@@ -0,0 +1,45 @@
+import type { ReadonlyDeep } from 'type-fest';
+/**
+ * A directed transition graph keyed by state name.
+ * Use `as const` when defining a graph so illegal transitions are caught at compile time.
+ *
+ * @example
+ * const transitions = {
+ *     idle: ['loading'],
+ *     loading: ['success', 'error'],
+ *     success: [],
+ *     error: ['idle'],
+ * } as const;
+ */
+type TransitionGraph = Readonly<Record<string, readonly string[]>>;
+/** Target states reachable from `Current` according to `Graph`. */
+type TransitionsFrom<Graph extends TransitionGraph, Current extends keyof Graph & string> = Graph[Current] extends ReadonlyArray<infer Target extends string> ? Target : never;
+/**
+ * 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');
+ */
+declare class StateMachine<const Graph extends TransitionGraph, Current extends keyof Graph & string> {
+    /** The current state. Deeply readonly and owned by this state machine instance. */
+    readonly state: ReadonlyDeep<Current>;
+    private readonly transitions;
+    constructor(currentState: Current, transitions: Graph);
+    /**
+     * 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 extends TransitionsFrom<Graph, Current>>(target: Target): StateMachine<Graph, Target>;
+}
+export default StateMachine;
+export type { TransitionGraph, TransitionsFrom };