react-native-onyx 3.0.118 → 3.0.120

package/API.md

@@ -63,6 +63,19 @@ Any existing collection members not included in the new data will be removed.</p
 Live RAM-only values and writes that have not reached storage are not included.
 Treat the returned object and its nested values as read-only.</p>
 </dd>
+<dt><a href="#get">get(key)</a> ⇒</dt>
+<dd><p>Reads the current value of an Onyx key once, without subscribing. Use <code>useOnyx()</code> or
+<code>Onyx.connectWithoutView()</code> when the value has to stay current.</p>
+<p>The read is served from the cache, which <code>init()</code> fills with the whole store, so it returns what a
+subscription to the same key would deliver. The value is the cached one rather than a copy, so treat
+it as read-only.</p>
+</dd>
+<dt><a href="#multiGet">multiGet(keys)</a> ⇒</dt>
+<dd><p>Reads several Onyx keys at once, without subscribing. Use <code>useOnyx()</code> or <code>Onyx.connectWithoutView()</code> when
+the values have to stay current.</p>
+<p>Values come back in the order of the keys given, and each is what get() returns for its key. To read a
+whole collection, pass the collection key rather than listing its members.</p>
+</dd>
 </dl>
 
 <a name="init"></a>
@@ -280,3 +293,49 @@ Live RAM-only values and writes that have not reached storage are not included.
 Treat the returned object and its nested values as read-only.
 
 **Kind**: global function  
+<a name="get"></a>
+
+## get(key) ⇒
+Reads the current value of an Onyx key once, without subscribing. Use `useOnyx()` or
+`Onyx.connectWithoutView()` when the value has to stay current.
+
+The read is served from the cache, which `init()` fills with the whole store, so it returns what a
+subscription to the same key would deliver. The value is the cached one rather than a copy, so treat
+it as read-only.
+
+**Kind**: global function  
+**Returns**: The current value, or `undefined` if the key has none.  
+
+| Param | Description |
+| --- | --- |
+| key | ONYXKEY to read, either a collection key or a single key |
+
+**Example**  
+```js
+const report = await Onyx.get(`${ONYXKEYS.COLLECTION.REPORT}${reportID}`);
+const allReports = await Onyx.get(ONYXKEYS.COLLECTION.REPORT);
+```
+<a name="multiGet"></a>
+
+## multiGet(keys) ⇒
+Reads several Onyx keys at once, without subscribing. Use `useOnyx()` or `Onyx.connectWithoutView()` when
+the values have to stay current.
+
+Values come back in the order of the keys given, and each is what get() returns for its key. To read a
+whole collection, pass the collection key rather than listing its members.
+
+**Kind**: global function  
+**Returns**: The values in the order of their keys, each `undefined` where a key has no value.  
+
+| Param | Description |
+| --- | --- |
+| keys | ONYXKEYS to read, in any mix of collection keys and single keys |
+
+**Example**  
+```js
+const [session, wallet, report] = await Onyx.multiGet([
+    ONYXKEYS.SESSION,
+    ONYXKEYS.WALLET,
+    `${ONYXKEYS.COLLECTION.REPORT}${reportID}`,
+]);
+```

package/dist/Onyx.d.ts

@@ -161,6 +161,42 @@ declare function setCollection<TKey extends CollectionKeyBase>(collectionKey: TK
  * Treat the returned object and its nested values as read-only.
  */
 declare function exportState(): Promise<Record<OnyxKey, OnyxValue<OnyxKey>>>;
+/**
+ * Reads the current value of an Onyx key once, without subscribing. Use `useOnyx()` or
+ * `Onyx.connectWithoutView()` when the value has to stay current.
+ *
+ * The read is served from the cache, which `init()` fills with the whole store, so it returns what a
+ * subscription to the same key would deliver. The value is the cached one rather than a copy, so treat
+ * it as read-only.
+ *
+ * @example
+ * const report = await Onyx.get(`${ONYXKEYS.COLLECTION.REPORT}${reportID}`);
+ * const allReports = await Onyx.get(ONYXKEYS.COLLECTION.REPORT);
+ *
+ * @param key ONYXKEY to read, either a collection key or a single key
+ * @returns The current value, or `undefined` if the key has none.
+ */
+declare function get<TKey extends OnyxKey>(key: TKey): Promise<OnyxValue<TKey>>;
+/**
+ * Reads several Onyx keys at once, without subscribing. Use `useOnyx()` or `Onyx.connectWithoutView()` when
+ * the values have to stay current.
+ *
+ * Values come back in the order of the keys given, and each is what get() returns for its key. To read a
+ * whole collection, pass the collection key rather than listing its members.
+ *
+ * @example
+ * const [session, wallet, report] = await Onyx.multiGet([
+ *     ONYXKEYS.SESSION,
+ *     ONYXKEYS.WALLET,
+ *     `${ONYXKEYS.COLLECTION.REPORT}${reportID}`,
+ * ]);
+ *
+ * @param keys ONYXKEYS to read, in any mix of collection keys and single keys
+ * @returns The values in the order of their keys, each `undefined` where a key has no value.
+ */
+declare function multiGet<const Keys extends readonly OnyxKey[]>(keys: Keys): Promise<{
+    [Index in keyof Keys]: OnyxValue<Keys[Index]>;
+}>;
 declare const Onyx: {
     METHOD: {
         readonly SET: "set";
@@ -182,6 +218,8 @@ declare const Onyx: {
     clear: typeof clear;
     exportState: typeof exportState;
     init: typeof init;
+    get: typeof get;
+    multiGet: typeof multiGet;
     registerLogger: typeof Logger.registerLogger;
 };
 export default Onyx;

package/dist/Onyx.js

@@ -473,6 +473,7 @@ function clear(keysToPreserve = []) {
                 .then(() => storage_1.default.multiSet(defaultKeyValuePairs))
                 .then(() => {
                 DevTools_1.default.clearState(keysToPreserve);
+                OnyxSubscriptionManager_1.default.resetCacheMissReports();
                 // Notify the subscribers for each key/value group so they can receive the new values
                 for (const [key, value] of Object.entries(keyValuesToResetIndividually)) {
                     OnyxUtils_1.default.notifyKey(key, value);
@@ -662,6 +663,45 @@ function exportState() {
         return state;
     }));
 }
+/**
+ * Reads the current value of an Onyx key once, without subscribing. Use `useOnyx()` or
+ * `Onyx.connectWithoutView()` when the value has to stay current.
+ *
+ * The read is served from the cache, which `init()` fills with the whole store, so it returns what a
+ * subscription to the same key would deliver. The value is the cached one rather than a copy, so treat
+ * it as read-only.
+ *
+ * @example
+ * const report = await Onyx.get(`${ONYXKEYS.COLLECTION.REPORT}${reportID}`);
+ * const allReports = await Onyx.get(ONYXKEYS.COLLECTION.REPORT);
+ *
+ * @param key ONYXKEY to read, either a collection key or a single key
+ * @returns The current value, or `undefined` if the key has none.
+ */
+function get(key) {
+    return OnyxUtils_1.default.afterInit(() => { var _a; return Promise.resolve(((_a = OnyxSubscriptionManager_1.default.getState(key)) !== null && _a !== void 0 ? _a : undefined)); });
+}
+/**
+ * Reads several Onyx keys at once, without subscribing. Use `useOnyx()` or `Onyx.connectWithoutView()` when
+ * the values have to stay current.
+ *
+ * Values come back in the order of the keys given, and each is what get() returns for its key. To read a
+ * whole collection, pass the collection key rather than listing its members.
+ *
+ * @example
+ * const [session, wallet, report] = await Onyx.multiGet([
+ *     ONYXKEYS.SESSION,
+ *     ONYXKEYS.WALLET,
+ *     `${ONYXKEYS.COLLECTION.REPORT}${reportID}`,
+ * ]);
+ *
+ * @param keys ONYXKEYS to read, in any mix of collection keys and single keys
+ * @returns The values in the order of their keys, each `undefined` where a key has no value.
+ */
+function multiGet(keys) {
+    // map() widens the key tuple to an array, so the per-slot value types survive only through the cast.
+    return OnyxUtils_1.default.afterInit(() => Promise.resolve(keys.map((key) => { var _a; return (_a = OnyxSubscriptionManager_1.default.getState(key)) !== null && _a !== void 0 ? _a : undefined; })));
+}
 const Onyx = {
     METHOD: OnyxUtils_1.default.METHOD,
     connect,
@@ -676,6 +716,8 @@ const Onyx = {
     clear,
     exportState,
     init,
+    get,
+    multiGet,
     registerLogger: Logger.registerLogger,
 };
 exports.default = Onyx;

package/dist/OnyxSubscriptionManager.d.ts

@@ -48,6 +48,7 @@ declare class OnyxSubscriptionManager {
      * Wipe all subscriptions. Used by tests and `Onyx.clear()` follow-on.
      */
     clearAll(): void;
+    resetCacheMissReports(): void;
     /**
      * True if there are any subscribers for the given key (exact or parent collection).
      */

package/dist/OnyxSubscriptionManager.js

@@ -39,6 +39,29 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const Logger = __importStar(require("./Logger"));
 const OnyxCache_1 = __importDefault(require("./OnyxCache"));
 const OnyxKeys_1 = __importDefault(require("./OnyxKeys"));
+const storage_1 = __importDefault(require("./storage"));
+const reportedCacheMisses = new Set();
+function reportCacheMissIfStorageHasValue(key) {
+    var _a;
+    if (OnyxKeys_1.default.isRamOnlyKey(key) || !OnyxCache_1.default.getAllKeys().has(key) || OnyxCache_1.default.hasNullishStorageKey(key)) {
+        return;
+    }
+    const reportKey = (_a = OnyxKeys_1.default.getCollectionKey(key)) !== null && _a !== void 0 ? _a : key;
+    if (reportedCacheMisses.has(reportKey)) {
+        return;
+    }
+    reportedCacheMisses.add(reportKey);
+    storage_1.default.getItem(key)
+        .then((value) => {
+        if (value === undefined || value === null) {
+            return;
+        }
+        Logger.logHmmm(`Cache held no value for a key storage still has: ${reportKey}`);
+    })
+        .catch((error) => {
+        Logger.logInfo(`Could not check storage for a suspected cache miss on ${reportKey}. Error: ${String(error)}`);
+    });
+}
 /**
  * OnyxSubscriptionManager is a registry for Onyx subscriptions.
  * Subscriptions are stored in `keyListeners`, a flat map keyed by OnyxKey.
@@ -58,7 +81,11 @@ class OnyxSubscriptionManager {
         if (OnyxKeys_1.default.isCollectionKey(key)) {
             return OnyxCache_1.default.getCollectionData(key);
         }
-        return OnyxCache_1.default.get(key);
+        const value = OnyxCache_1.default.get(key);
+        if (value === undefined) {
+            reportCacheMissIfStorageHasValue(key);
+        }
+        return value;
     }
     /**
      * Subscribe to an exact key. For a collection root key this is "collection mode": the
@@ -164,6 +191,10 @@ class OnyxSubscriptionManager {
      */
     clearAll() {
         this.keyListeners.clear();
+        this.resetCacheMissReports();
+    }
+    resetCacheMissReports() {
+        reportedCacheMisses.clear();
     }
     /**
      * True if there are any subscribers for the given key (exact or parent collection).

package/dist/OnyxUtils.d.ts

@@ -122,16 +122,16 @@ declare function reportStorageQuota(error?: Error): Promise<void>;
  * 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.
+ * - TRANSIENT / FATAL: the connection layer already retried (transient) or spent a heal attempt
+ *   (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.
  * - DISK_PRESSURE: the device disk itself is full (or the database files are unreadable), so neither
  *   retries nor in-DB eviction can free space — the write is dropped (cache stays authoritative) with
  *   a single throttled alert + quota snapshot per burst.
- * - UNAVAILABLE: the storage engine does not exist in this environment, so the storage layer has
- *   already degraded to the in-memory provider. No retry.
+ * - UNAVAILABLE: the storage engine does not exist in this environment or its heal budget ran out, so
+ *   the storage layer has already degraded to the in-memory provider. No retry.
  * - 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.
  */

package/dist/OnyxUtils.js

@@ -469,16 +469,16 @@ function reportStorageQuota(error) {
  * 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.
+ * - TRANSIENT / FATAL: the connection layer already retried (transient) or spent a heal attempt
+ *   (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.
  * - DISK_PRESSURE: the device disk itself is full (or the database files are unreadable), so neither
  *   retries nor in-DB eviction can free space — the write is dropped (cache stays authoritative) with
  *   a single throttled alert + quota snapshot per burst.
- * - UNAVAILABLE: the storage engine does not exist in this environment, so the storage layer has
- *   already degraded to the in-memory provider. No retry.
+ * - UNAVAILABLE: the storage engine does not exist in this environment or its heal budget ran out, so
+ *   the storage layer has already degraded to the in-memory provider. No retry.
  * - 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.
  */
@@ -752,6 +752,9 @@ function initializeWithDefaultKeyStates() {
     })
         .catch((error) => {
         Logger.logAlert(`Failed to load data from storage during init. The app will boot with default key states only. Error: ${error}`);
+        if (storage_1.default.classifyError(error) === errors_1.StorageErrorClass.FATAL) {
+            storage_1.default.degradeToMemoryOnly(error);
+        }
         // Populate the key index so getAllKeys() returns correct results for default keys.
         // Without this, subscribers that check getAllKeys() would see an empty set even
         // though we have default values in cache.

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

@@ -12,6 +12,7 @@ declare const StorageMock: {
     getStorageProvider: jest.Mock<import("../providers/types").default<{
         [x: string]: unknown;
     }>, [], any>;
+    degradeToMemoryOnly: jest.Mock<any, any, any>;
     getItem: jest.Mock<Promise<unknown>, [key: any], any>;
     multiGet: jest.Mock<Promise<import("../providers/types").StorageKeyValuePair[]>, [keys: import("../providers/types").StorageKeyList], any>;
     setItem: jest.Mock<Promise<void>, [key: any, value: unknown], any>;

package/dist/storage/__mocks__/index.js

@@ -53,6 +53,7 @@ const StorageMock = {
     init,
     classifyError: jest.fn(classifyError),
     getStorageProvider: jest.fn(() => MemoryOnlyProvider_1.default),
+    degradeToMemoryOnly: jest.fn(),
     getItem: jest.fn(MemoryOnlyProvider_1.default.getItem),
     multiGet: jest.fn(MemoryOnlyProvider_1.default.multiGet),
     setItem: jest.fn(MemoryOnlyProvider_1.default.setItem),

package/dist/storage/errors.d.ts

@@ -22,12 +22,12 @@ declare const StorageErrorClass: {
     readonly DISK_PRESSURE: "diskPressure";
     /** Non-serializable payload. Never retriable — the same data will always fail. */
     readonly INVALID_DATA: "invalidData";
-    /** Backing-store corruption. Owner: connection layer — budgeted heal, then give up. */
+    /** Backing-store corruption. Owner: connection layer — budgeted heal, then rethrow as UNAVAILABLE. */
     readonly FATAL: "fatal";
     /** The storage engine itself does not exist in this environment (for example `indexedDB` is an
-     *  undeclared global in Chrome for iOS private tabs and in Lockdown Mode). Never retriable — the
-     *  engine cannot appear mid-session. Owner: the storage layer — degrade
-     *  to the in-memory provider. */
+     *  undeclared global in Chrome for iOS private tabs and in Lockdown Mode), or a FATAL heal budget
+     *  ran out. Never retriable — the engine cannot recover mid-session. Owner: the storage layer —
+     *  degrade to the in-memory provider. */
     readonly UNAVAILABLE: "unavailable";
     /** Unmatched by the active provider. Owner: operation layer — bounded retry, and log the shape so
      *  recurring cases can be promoted into one of the classes above. */

package/dist/storage/errors.js

@@ -26,12 +26,12 @@ const StorageErrorClass = {
     DISK_PRESSURE: 'diskPressure',
     /** Non-serializable payload. Never retriable — the same data will always fail. */
     INVALID_DATA: 'invalidData',
-    /** Backing-store corruption. Owner: connection layer — budgeted heal, then give up. */
+    /** Backing-store corruption. Owner: connection layer — budgeted heal, then rethrow as UNAVAILABLE. */
     FATAL: 'fatal',
     /** The storage engine itself does not exist in this environment (for example `indexedDB` is an
-     *  undeclared global in Chrome for iOS private tabs and in Lockdown Mode). Never retriable — the
-     *  engine cannot appear mid-session. Owner: the storage layer — degrade
-     *  to the in-memory provider. */
+     *  undeclared global in Chrome for iOS private tabs and in Lockdown Mode), or a FATAL heal budget
+     *  ran out. Never retriable — the engine cannot recover mid-session. Owner: the storage layer —
+     *  degrade to the in-memory provider. */
     UNAVAILABLE: 'unavailable',
     /** Unmatched by the active provider. Owner: operation layer — bounded retry, and log the shape so
      *  recurring cases can be promoted into one of the classes above. */

package/dist/storage/index.d.ts

@@ -1,6 +1,7 @@
 import type StorageProvider from './providers/types';
 type Storage = {
     getStorageProvider: () => StorageProvider<unknown>;
+    degradeToMemoryOnly: (error: unknown) => void;
 } & Omit<StorageProvider<unknown>, 'name' | 'store'>;
 declare const storage: Storage;
 export default storage;

package/dist/storage/index.js

@@ -56,6 +56,9 @@ const initPromise = new Promise((resolve) => {
  * Degrade performance by removing the storage provider and only using cache
  */
 function degradePerformance(error) {
+    if (provider === MemoryOnlyProvider_1.default) {
+        return;
+    }
     let causeMessage = '';
     if (error.cause instanceof Error) {
         causeMessage = error.cause.message;
@@ -95,6 +98,7 @@ const storage = {
     getStorageProvider() {
         return provider;
     },
+    degradeToMemoryOnly: (error) => degradePerformance(error instanceof Error ? error : new Error(String(error))),
     /**
      * Classifies a write error using the platform provider's own classifier. Synchronous and pure —
      * never wrapped in tryOrDegradePerformance.
@@ -212,7 +216,12 @@ const storage = {
         if (!InstanceSync_1.default.shouldBeUsed)
             return;
         shouldKeepInstancesSync = true;
-        InstanceSync_1.default.init(onStorageKeysChanged, this);
+        InstanceSync_1.default.init((pairs) => {
+            if (provider === MemoryOnlyProvider_1.default) {
+                return;
+            }
+            onStorageKeysChanged(pairs);
+        }, this);
     },
 };
 exports.default = storage;

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

@@ -1,7 +1,40 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 const errors_1 = require("../../errors");
-const isIndexedDBAvailable_1 = require("./isIndexedDBAvailable");
+const errorMessages_1 = __importStar(require("./errorMessages"));
 /**
  * Classifies an IndexedDB write failure into the shared storage taxonomy (lib/storage/errors.ts).
  * Matching is done on the lowercased error name and message. This is the IndexedDB engine's own
@@ -10,7 +43,11 @@ const isIndexedDBAvailable_1 = require("./isIndexedDBAvailable");
 function classifyIDBError(error) {
     const { name, message } = (0, errors_1.getErrorParts)(error);
     // The engine is absent, not broken e.g. private tabs and Lockdown Mode on WebKit.
-    if (message.includes("can't find variable: indexeddb") || message.includes('indexeddb is not defined') || message.includes(isIndexedDBAvailable_1.INDEXED_DB_UNAVAILABLE_MESSAGE.toLowerCase())) {
+    if (message.includes("can't find variable: indexeddb") || message.includes('indexeddb is not defined') || message.includes(errorMessages_1.default.UNAVAILABLE.toLowerCase())) {
+        return errors_1.StorageErrorClass.UNAVAILABLE;
+    }
+    // Reopen budget spent on FATAL errors, so the store is treated as gone for the rest of the session.
+    if (name === errorMessages_1.IDBErrorName.HEAL_EXHAUSTED.toLowerCase()) {
         return errors_1.StorageErrorClass.UNAVAILABLE;
     }
     // Non-serializable data passed to IDBObjectStore.put — retrying is futile.

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

@@ -40,7 +40,8 @@ const IDB = __importStar(require("idb-keyval"));
 const Logger = __importStar(require("../../../Logger"));
 const errors_1 = require("../../errors");
 const classifyError_1 = __importDefault(require("./classifyError"));
-const isIndexedDBAvailable_1 = __importStar(require("./isIndexedDBAvailable"));
+const errorMessages_1 = __importStar(require("./errorMessages"));
+const isIndexedDBAvailable_1 = __importDefault(require("./isIndexedDBAvailable"));
 const HEAL_ATTEMPTS_MAX = 3;
 // This is a copy of the createStore function from idb-keyval, we need a custom implementation
 // because we need to create the database manually in order to ensure that the store exists before we use it.
@@ -90,7 +91,7 @@ function createStore(dbName, storeName) {
         if (dbp)
             return dbp;
         if (!(0, isIndexedDBAvailable_1.default)()) {
-            return Promise.reject(new Error(isIndexedDBAvailable_1.INDEXED_DB_UNAVAILABLE_MESSAGE));
+            return Promise.reject(new Error(errorMessages_1.default.UNAVAILABLE));
         }
         const request = indexedDB.open(dbName);
         request.onupgradeneeded = () => request.result.createObjectStore(storeName);
@@ -218,12 +219,17 @@ function createStore(dbName, storeName) {
             });
         }
         if (errorClass === errors_1.StorageErrorClass.FATAL) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
             Logger.logAlert('IDB heal: backing store error — heal budget exhausted, giving up', {
                 dbName,
                 storeName,
+                errorMessage,
             });
+            const healExhaustedError = new Error(`${errorMessages_1.default.HEAL_EXHAUSTED}: ${errorMessage}`, { cause: error });
+            healExhaustedError.name = errorMessages_1.IDBErrorName.HEAL_EXHAUSTED;
+            throw healExhaustedError;
         }
-        else if (errorClass === errors_1.StorageErrorClass.UNKNOWN) {
+        if (errorClass === errors_1.StorageErrorClass.UNKNOWN) {
             // UNKNOWN — unexpected at this layer; record it so it's visible. CAPACITY is the
             // expected propagation path (the operation layer owns its logging, and suppresses it
             // entirely once the circuit breaker is open), so we do NOT log it here — doing so was a

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

@@ -0,0 +1,11 @@
+/** Messages of errors thrown by the IndexedDB provider itself. `classifyIDBError` maps `UNAVAILABLE` to `StorageErrorClass.UNAVAILABLE`. */
+declare const IDBErrorMessage: {
+    readonly UNAVAILABLE: "IndexedDB is not available in this environment";
+    readonly HEAL_EXHAUSTED: "IndexedDB heal budget exhausted";
+};
+/** Names of errors thrown by the IndexedDB provider itself. `classifyIDBError` maps `HEAL_EXHAUSTED` to `StorageErrorClass.UNAVAILABLE`. */
+declare const IDBErrorName: {
+    readonly HEAL_EXHAUSTED: "IDBHealExhaustedError";
+};
+export default IDBErrorMessage;
+export { IDBErrorName };

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

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDBErrorName = void 0;
+/** Messages of errors thrown by the IndexedDB provider itself. `classifyIDBError` maps `UNAVAILABLE` to `StorageErrorClass.UNAVAILABLE`. */
+const IDBErrorMessage = {
+    UNAVAILABLE: 'IndexedDB is not available in this environment',
+    HEAL_EXHAUSTED: 'IndexedDB heal budget exhausted',
+};
+/** Names of errors thrown by the IndexedDB provider itself. `classifyIDBError` maps `HEAL_EXHAUSTED` to `StorageErrorClass.UNAVAILABLE`. */
+const IDBErrorName = {
+    HEAL_EXHAUSTED: 'IDBHealExhaustedError',
+};
+exports.IDBErrorName = IDBErrorName;
+exports.default = IDBErrorMessage;

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

@@ -40,7 +40,8 @@ const IDB = __importStar(require("idb-keyval"));
 const utils_1 = __importDefault(require("../../../utils"));
 const createStore_1 = __importDefault(require("./createStore"));
 const classifyError_1 = __importDefault(require("./classifyError"));
-const isIndexedDBAvailable_1 = __importStar(require("./isIndexedDBAvailable"));
+const errorMessages_1 = __importDefault(require("./errorMessages"));
+const isIndexedDBAvailable_1 = __importDefault(require("./isIndexedDBAvailable"));
 const DB_NAME = 'OnyxDB';
 const STORE_NAME = 'keyvaluepairs';
 /**
@@ -71,7 +72,7 @@ const provider = {
      */
     init() {
         if (!(0, isIndexedDBAvailable_1.default)()) {
-            throw new Error(`IDBKeyVal store could not be created: ${isIndexedDBAvailable_1.INDEXED_DB_UNAVAILABLE_MESSAGE}`);
+            throw new Error(`IDBKeyVal store could not be created: ${errorMessages_1.default.UNAVAILABLE}`);
         }
         const newIdbKeyValStore = (0, createStore_1.default)(DB_NAME, STORE_NAME);
         if (newIdbKeyValStore == null) {

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

@@ -1,9 +1,6 @@
-/** Matched by `classifyIDBError` so a guarded failure classifies as UNAVAILABLE like an unguarded one. */
-declare const INDEXED_DB_UNAVAILABLE_MESSAGE = "indexedDB is not available in this environment";
 /**
  * `typeof` instead of `indexedDB === undefined`: on WebKit the global is undeclared in private tabs and
  * Lockdown Mode, so reading it throws a `ReferenceError` instead of evaluating to `undefined`.
  */
 declare function isIndexedDBAvailable(): boolean;
 export default isIndexedDBAvailable;
-export { INDEXED_DB_UNAVAILABLE_MESSAGE };

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

@@ -1,9 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.INDEXED_DB_UNAVAILABLE_MESSAGE = void 0;
-/** Matched by `classifyIDBError` so a guarded failure classifies as UNAVAILABLE like an unguarded one. */
-const INDEXED_DB_UNAVAILABLE_MESSAGE = 'indexedDB is not available in this environment';
-exports.INDEXED_DB_UNAVAILABLE_MESSAGE = INDEXED_DB_UNAVAILABLE_MESSAGE;
 /**
  * `typeof` instead of `indexedDB === undefined`: on WebKit the global is undeclared in private tabs and
  * Lockdown Mode, so reading it throws a `ReferenceError` instead of evaluating to `undefined`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-onyx",
-  "version": "3.0.118",
+  "version": "3.0.120",
   "author": "Expensify, Inc.",
   "homepage": "https://expensify.com",
   "description": "State management for React Native",