react-native-onyx 3.0.87 → 3.0.89

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
@@ -497,25 +483,7 @@ function keysChanged(collectionKey, partialCollection, partialPreviousCollection
         }
         try {
             lastConnectionCallbackData.set(subscriber.subscriptionID, { value: cachedCollection, matchedKey: subscriber.key });
-            if (subscriber.waitForCollectionCallback) {
-                subscriber.callback(cachedCollection, subscriber.key, partialCollection);
-                continue;
-            }
-            // Not using waitForCollectionCallback — notify per changed key.
-            // Re-check the subscription on each iteration because the callback may
-            // synchronously disconnect itself (removing it from callbackToStateMapping),
-            // in which case we must stop firing further callbacks for this subscriber.
-            for (const dataKey of changedMemberKeys) {
-                const currentSubscriber = callbackToStateMapping[subID];
-                if (!currentSubscriber || typeof currentSubscriber.callback !== 'function') {
-                    break;
-                }
-                if (cachedCollection[dataKey] === previousCollection[dataKey]) {
-                    continue;
-                }
-                const currentSubscriberCallback = currentSubscriber.callback;
-                currentSubscriberCallback(cachedCollection[dataKey], dataKey);
-            }
+            subscriber.callback(cachedCollection, subscriber.key, partialCollection);
         }
         catch (error) {
             Logger.logAlert(`[OnyxUtils.keysChanged] Subscriber callback threw an error for key '${collectionKey}': ${error}`);
@@ -533,7 +501,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}`);
@@ -582,9 +553,9 @@ function keyChanged(key, value, canUpdateSubscriber = () => true, isProcessingCo
                 if (lastData && lastData.matchedKey === key && lastData.value === value) {
                     continue;
                 }
-                if (OnyxKeys_1.default.isCollectionKey(subscriber.key) && subscriber.waitForCollectionCallback) {
-                    // Skip individual key changes for collection callbacks during collection updates
-                    // to prevent duplicate callbacks - the collection update will handle this properly
+                if (OnyxKeys_1.default.isCollectionKey(subscriber.key)) {
+                    // Skip individual key changes during collection updates to prevent duplicate
+                    // callbacks - the collection update will handle this properly.
                     if (isProcessingCollectionUpdate) {
                         continue;
                     }
@@ -601,7 +572,10 @@ function keyChanged(key, value, canUpdateSubscriber = () => true, isProcessingCo
                 }
                 const subscriberCallback = subscriber.callback;
                 subscriberCallback(value, key);
-                lastConnectionCallbackData.set(subscriber.subscriptionID, { value, matchedKey: key });
+                lastConnectionCallbackData.set(subscriber.subscriptionID, {
+                    value,
+                    matchedKey: key,
+                });
                 continue;
             }
             catch (error) {
@@ -616,17 +590,17 @@ function keyChanged(key, value, canUpdateSubscriber = () => true, isProcessingCo
  * Sends the data obtained from the keys to the connection.
  */
 function sendDataToConnection(mapping, matchedKey) {
-    var _a, _b;
+    var _a;
     // If the mapping no longer exists then we should not send any data.
     // This means our subscriber was disconnected.
     if (!callbackToStateMapping[mapping.subscriptionID]) {
         return;
     }
     // Always read the latest value from cache to avoid stale or duplicate data.
-    // For collection subscribers with waitForCollectionCallback, read the full collection.
+    // For collection-root subscribers, read the full collection.
     // For individual key subscribers, read just that key's value.
     let value;
-    if (OnyxKeys_1.default.isCollectionKey(mapping.key) && mapping.waitForCollectionCallback) {
+    if (OnyxKeys_1.default.isCollectionKey(mapping.key)) {
         const collection = getCachedCollection(mapping.key);
         value = Object.keys(collection).length > 0 ? collection : undefined;
     }
@@ -642,7 +616,7 @@ function sendDataToConnection(mapping, matchedKey) {
     if (lastData && lastData.matchedKey === matchedKey && (0, fast_equals_1.shallowEqual)(lastData.value, value)) {
         return;
     }
-    (_b = (_a = mapping).callback) === null || _b === void 0 ? void 0 : _b.call(_a, value, matchedKey);
+    (_a = mapping.callback) === null || _a === void 0 ? void 0 : _a.call(mapping, value, matchedKey);
 }
 /**
  * Gets the data for a given an array of matching keys, combines them into an object, and sends the result back to the subscriber.
@@ -666,44 +640,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 +721,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
@@ -948,27 +958,17 @@ function subscribeToKey(connectOptions) {
             if (mapping.key) {
                 OnyxCache_1.default.addNullishStorageKey(mapping.key);
             }
-            const matchedKey = OnyxKeys_1.default.isCollectionKey(mapping.key) && mapping.waitForCollectionCallback ? mapping.key : undefined;
+            const matchedKey = OnyxKeys_1.default.isCollectionKey(mapping.key) ? mapping.key : undefined;
             // Here we cannot use batching because the nullish value is expected to be set immediately for default props
             // or they will be undefined.
             sendDataToConnection(mapping, matchedKey);
             return;
         }
-        // When using a callback subscriber we will either trigger the provided callback for each key we find or combine all values
-        // into an object and just make a single call. The latter behavior is enabled by providing a waitForCollectionCallback key
-        // combined with a subscription to a collection key.
+        // When using a callback subscriber, a subscription to a collection key combines all matching
+        // member values into a single object and makes one call with the whole collection object.
         if (typeof mapping.callback === 'function') {
             if (OnyxKeys_1.default.isCollectionKey(mapping.key)) {
-                if (mapping.waitForCollectionCallback) {
-                    getCollectionDataAndSendAsObject(matchingKeys, mapping);
-                    return;
-                }
-                // We did not opt into using waitForCollectionCallback mode so the callback is called for every matching key.
-                multiGet(matchingKeys).then(() => {
-                    for (const key of matchingKeys) {
-                        sendDataToConnection(mapping, key);
-                    }
-                });
+                getCollectionDataAndSendAsObject(matchingKeys, mapping);
                 return;
             }
             // If we are not subscribed to a collection key then there's only a single key to send an update for.
@@ -1117,6 +1117,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);
@@ -1180,7 +1181,7 @@ function multiSetWithRetry(data, retryAttempt) {
             // and subscriber state, matching the original per-key notification semantics.
             OnyxCache_1.default.set(key, value);
             // Skip subscriber notification on retry — already notified on attempt 0.
-            // waitForCollectionCallback subscribers re-fire on every keyChanged by contract.
+            // Collection-root subscribers re-fire on every keyChanged by contract.
             if (!retryAttempt) {
                 keyChanged(key, value);
             }
@@ -1201,6 +1202,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);
@@ -1258,7 +1260,7 @@ function setCollectionWithRetry({ collectionKey, collection }, retryAttempt) {
         for (const [key, value] of keyValuePairs)
             OnyxCache_1.default.set(key, value);
         // Skip subscriber notification on retry — already notified on attempt 0.
-        // waitForCollectionCallback subscribers re-fire on every keysChanged by contract.
+        // Collection-root subscribers re-fire on every keysChanged by contract.
         if (!retryAttempt) {
             keysChanged(collectionKey, mutableCollection, previousCollection);
         }
@@ -1269,6 +1271,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);
@@ -1380,7 +1383,7 @@ function mergeCollectionWithPatches({ collectionKey, collection, mergeReplaceNul
             const previousCollection = getCachedCollection(collectionKey, existingKeys);
             OnyxCache_1.default.merge(finalMergedCollection);
             // Skip subscriber notification on retry — already notified on attempt 0.
-            // waitForCollectionCallback subscribers re-fire on every keysChanged by contract.
+            // Collection-root subscribers re-fire on every keysChanged by contract.
             if (!retryAttempt) {
                 keysChanged(collectionKey, finalMergedCollection, previousCollection);
             }
@@ -1398,7 +1401,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);
             });
@@ -1449,7 +1458,7 @@ function partialSetCollection({ collectionKey, collection }, retryAttempt) {
         for (const [key, value] of keyValuePairs)
             OnyxCache_1.default.set(key, value);
         // Skip subscriber notification on retry — already notified on attempt 0.
-        // waitForCollectionCallback subscribers re-fire on every keysChanged by contract.
+        // Collection-root subscribers re-fire on every keysChanged by contract.
         if (!retryAttempt) {
             keysChanged(collectionKey, mutableCollection, previousCollection);
         }
@@ -1459,6 +1468,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 };

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;