react-native-onyx 3.0.87 → 3.0.89

package/API.md

@@ -80,7 +80,6 @@ This method will be deprecated soon. Please use `Onyx.connectWithoutView()` inst
 | connectOptions | The options object that will define the behavior of the connection. |
 | connectOptions.key | The Onyx key to subscribe to. |
 | connectOptions.callback | A function that will be called when the Onyx data we are subscribed changes. |
-| connectOptions.waitForCollectionCallback | If set to `true`, it will return the entire collection to the callback as a single object. |
 | connectOptions.selector | This will be used to subscribe to a subset of an Onyx key's data. **Only used inside `useOnyx()` hook.**        Using this setting on `useOnyx()` can have very positive performance benefits because the component will only re-render        when the subset of data changes. Otherwise, any change of data on any property would normally        cause the component to re-render (and that can be expensive from a performance standpoint). |
 
 **Example**  
@@ -103,7 +102,6 @@ Connects to an Onyx key given the options passed and listens to its changes.
 | connectOptions | The options object that will define the behavior of the connection. |
 | connectOptions.key | The Onyx key to subscribe to. |
 | connectOptions.callback | A function that will be called when the Onyx data we are subscribed changes. |
-| connectOptions.waitForCollectionCallback | If set to `true`, it will return the entire collection to the callback as a single object. |
 | connectOptions.selector | This will be used to subscribe to a subset of an Onyx key's data. **Only used inside `useOnyx()` hook.**        Using this setting on `useOnyx()` can have very positive performance benefits because the component will only re-render        when the subset of data changes. Otherwise, any change of data on any property would normally        cause the component to re-render (and that can be expensive from a performance standpoint). |
 
 **Example**  

package/README.md

@@ -257,20 +257,10 @@ export default MyComponent;
 This will add a prop to the component called `allReports` which is an object of collection member key/values. Changes to the individual member keys will modify the entire object and new props will be passed with each individual key update. The prop doesn't update on the initial rendering of the component until the entire collection has been read out of Onyx.
 
 ```js
-Onyx.connect({key: ONYXKEYS.COLLECTION.REPORT}, callback: (memberValue, memberKey) => {...});
+Onyx.connect({key: ONYXKEYS.COLLECTION.REPORT}, callback: (allReports, collectionKey, sourceValue) => {...});
 ```
 
-This will fire the callback once per member key depending on how many collection member keys are currently stored. Changes to those keys after the initial callbacks fire will occur when each individual key is updated.
-
-```js
-Onyx.connect({
-    key: ONYXKEYS.COLLECTION.REPORT,
-    waitForCollectionCallback: true,
-    callback: (allReports, collectionKey, sourceValue) => {...},
-});
-```
-
-This final option forces `Onyx.connect()` to behave more like `useOnyx()` and only update the callback once with the entire collection initially and later with an updated version of the collection when individual keys update. The `sourceValue` parameter contains only the specific keys and values that triggered the current update, which can be useful for optimizing your code to only process what changed. This parameter is not available when `waitForCollectionCallback` is false or the key is not a collection key.
+This will fire the callback once with the entire collection initially and later with an updated version of the collection when individual keys update. The `sourceValue` parameter contains only the specific keys and values that triggered the current update, which can be useful for optimizing your code to only process what changed.
 
 ### Performance Considerations When Using Collections
 

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/Onyx.d.ts

@@ -18,7 +18,6 @@ declare function init({ keys, initialKeyStates, evictableKeys, shouldSyncMultipl
  * @param connectOptions The options object that will define the behavior of the connection.
  * @param connectOptions.key The Onyx key to subscribe to.
  * @param connectOptions.callback A function that will be called when the Onyx data we are subscribed changes.
- * @param connectOptions.waitForCollectionCallback If set to `true`, it will return the entire collection to the callback as a single object.
  * @param connectOptions.selector This will be used to subscribe to a subset of an Onyx key's data. **Only used inside `useOnyx()` hook.**
  *        Using this setting on `useOnyx()` can have very positive performance benefits because the component will only re-render
  *        when the subset of data changes. Otherwise, any change of data on any property would normally
@@ -40,7 +39,6 @@ declare function connect<TKey extends OnyxKey>(connectOptions: ConnectOptions<TK
  * @param connectOptions The options object that will define the behavior of the connection.
  * @param connectOptions.key The Onyx key to subscribe to.
  * @param connectOptions.callback A function that will be called when the Onyx data we are subscribed changes.
- * @param connectOptions.waitForCollectionCallback If set to `true`, it will return the entire collection to the callback as a single object.
  * @param connectOptions.selector This will be used to subscribe to a subset of an Onyx key's data. **Only used inside `useOnyx()` hook.**
  *        Using this setting on `useOnyx()` can have very positive performance benefits because the component will only re-render
  *        when the subset of data changes. Otherwise, any change of data on any property would normally

package/dist/Onyx.js

@@ -93,7 +93,6 @@ function init({ keys = {}, initialKeyStates = {}, evictableKeys = [], shouldSync
  * @param connectOptions The options object that will define the behavior of the connection.
  * @param connectOptions.key The Onyx key to subscribe to.
  * @param connectOptions.callback A function that will be called when the Onyx data we are subscribed changes.
- * @param connectOptions.waitForCollectionCallback If set to `true`, it will return the entire collection to the callback as a single object.
  * @param connectOptions.selector This will be used to subscribe to a subset of an Onyx key's data. **Only used inside `useOnyx()` hook.**
  *        Using this setting on `useOnyx()` can have very positive performance benefits because the component will only re-render
  *        when the subset of data changes. Otherwise, any change of data on any property would normally
@@ -117,7 +116,6 @@ function connect(connectOptions) {
  * @param connectOptions The options object that will define the behavior of the connection.
  * @param connectOptions.key The Onyx key to subscribe to.
  * @param connectOptions.callback A function that will be called when the Onyx data we are subscribed changes.
- * @param connectOptions.waitForCollectionCallback If set to `true`, it will return the entire collection to the callback as a single object.
  * @param connectOptions.selector This will be used to subscribe to a subset of an Onyx key's data. **Only used inside `useOnyx()` hook.**
  *        Using this setting on `useOnyx()` can have very positive performance benefits because the component will only re-render
  *        when the subset of data changes. Otherwise, any change of data on any property would normally

package/dist/OnyxConnectionManager.js

@@ -60,18 +60,17 @@ class OnyxConnectionManager {
      * according to their purpose and effect they produce in the Onyx connection.
      */
     generateConnectionID(connectOptions) {
-        const { key, reuseConnection, waitForCollectionCallback } = connectOptions;
+        const { key, reuseConnection } = connectOptions;
         // The current session ID is appended to the connection ID so we can have different connections
         // after an `Onyx.clear()` operation.
         let suffix = `,sessionID=${this.sessionID}`;
-        // We will generate a unique ID in any of the following situations:
-        // - `reuseConnection` is `false`. That means the subscriber explicitly wants the connection to not be reused.
-        // - `key` is a collection key AND `waitForCollectionCallback` is `undefined/false`. This combination needs a new connection at every subscription
-        //   in order to send all the collection entries, so the connection can't be reused.
-        if (reuseConnection === false || (OnyxKeys_1.default.isCollectionKey(key) && (waitForCollectionCallback === undefined || waitForCollectionCallback === false))) {
+        // We will generate a unique ID when `reuseConnection` is `false`, which means the subscriber
+        // explicitly wants the connection to not be reused. Collection-root subscriptions are now always
+        // snapshot mode, so they can be reused like any other connection.
+        if (reuseConnection === false) {
             suffix += `,uniqueID=${Str.guid()}`;
         }
-        return `onyxKey=${key},waitForCollectionCallback=${waitForCollectionCallback !== null && waitForCollectionCallback !== void 0 ? waitForCollectionCallback : false}${suffix}`;
+        return `onyxKey=${key}${suffix}`;
     }
     /**
      * Fires all the subscribers callbacks associated with that connection ID.
@@ -82,11 +81,16 @@ class OnyxConnectionManager {
             return;
         }
         for (const callback of connection.callbacks.values()) {
-            if (connection.waitForCollectionCallback) {
-                callback(connection.cachedCallbackValue, connection.cachedCallbackKey, connection.sourceValue);
+            try {
+                if (OnyxKeys_1.default.isCollectionKey(connection.onyxKey)) {
+                    callback(connection.cachedCallbackValue, connection.cachedCallbackKey, connection.sourceValue);
+                }
+                else {
+                    callback(connection.cachedCallbackValue, connection.cachedCallbackKey);
+                }
             }
-            else {
-                callback(connection.cachedCallbackValue, connection.cachedCallbackKey);
+            catch (error) {
+                Logger.logAlert(`[ConnectionManager] Subscriber callback threw an error for key '${connection.onyxKey}': ${error}`);
             }
         }
     }
@@ -115,13 +119,12 @@ class OnyxConnectionManager {
                     this.fireCallbacks(connectionID);
                 }
             };
-            subscriptionID = OnyxUtils_1.default.subscribeToKey(Object.assign(Object.assign({}, connectOptions), { callback: callback }));
+            subscriptionID = OnyxUtils_1.default.subscribeToKey(Object.assign(Object.assign({}, connectOptions), { callback }));
             connectionMetadata = {
                 subscriptionID,
                 onyxKey: connectOptions.key,
                 isConnectionMade: false,
                 callbacks: new Map(),
-                waitForCollectionCallback: connectOptions.waitForCollectionCallback,
             };
             this.connectionsMap.set(connectionID, connectionMetadata);
         }
@@ -134,8 +137,8 @@ class OnyxConnectionManager {
             // Defer the callback execution to the next tick of the event loop.
             // This ensures that the current execution flow completes and the result connection object is available when the callback fires.
             Promise.resolve().then(() => {
-                var _a, _b;
-                (_b = (_a = connectOptions).callback) === null || _b === void 0 ? void 0 : _b.call(_a, connectionMetadata.cachedCallbackValue, connectionMetadata.cachedCallbackKey);
+                var _a;
+                (_a = connectOptions.callback) === null || _a === void 0 ? void 0 : _a.call(connectOptions, connectionMetadata.cachedCallbackValue, connectionMetadata.cachedCallbackKey);
             });
         }
         return { id: connectionID, callbackID };

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>;
 /**