react-native-onyx 3.0.112 → 3.0.114

package/API.md

@@ -58,6 +58,11 @@ value will be saved to storage after the default value.</p>
 <dd><p>Sets a collection by replacing all existing collection members with new values.
 Any existing collection members not included in the new data will be removed.</p>
 </dd>
+<dt><a href="#exportState">exportState()</a></dt>
+<dd><p>Returns persisted Onyx key-value pairs as a plain object.
+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>
 </dl>
 
 <a name="init"></a>
@@ -257,3 +262,11 @@ Onyx.setCollection(ONYXKEYS.COLLECTION.REPORT, {
     [`${ONYXKEYS.COLLECTION.REPORT}2`]: report2,
 });
 ```
+<a name="exportState"></a>
+
+## exportState()
+Returns persisted Onyx key-value pairs as a plain object.
+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  

package/README.md

@@ -288,6 +288,10 @@ function signOut() {
 }
 ```
 
+## Export persisted state
+
+`Onyx.exportState()` returns a plain object containing persisted keys and values from the active storage provider. It works on native and web without opening another database connection. The export excludes stale persisted rows for keys that are now RAM-only. Current RAM-only values and writes still in progress are never included. Treat the returned object and its nested values as read-only because some providers return references to their stored values. The result can contain sensitive data; callers should redact it before sharing.
+
 ## Storage Providers
 `Onyx.get`, `Onyx.set`, and the rest of the API accesses the underlying storage
 differently depending on the platform

package/dist/Onyx.d.ts

@@ -1,5 +1,5 @@
 import * as Logger from './Logger';
-import type { CollectionKeyBase, ConnectOptions, InitOptions, OnyxKey, OnyxMergeCollectionInput, OnyxMergeInput, OnyxMultiSetInput, OnyxSetCollectionInput, OnyxSetInput, OnyxUpdate, SetOptions } from './types';
+import type { CollectionKeyBase, ConnectOptions, InitOptions, OnyxKey, OnyxMergeCollectionInput, OnyxMergeInput, OnyxMultiSetInput, OnyxSetCollectionInput, OnyxSetInput, OnyxUpdate, OnyxValue, SetOptions } from './types';
 import type { Connection } from './OnyxConnectionManager';
 /** Initialize the store with actions and listening for storage events */
 declare function init({ keys, initialKeyStates, evictableKeys, shouldSyncMultipleInstances, enableDevTools, skippableCollectionMemberIDs, ramOnlyKeys, snapshotMergeKeys, }: InitOptions): void;
@@ -152,6 +152,12 @@ declare function update<TKey extends OnyxKey>(data: Array<OnyxUpdate<TKey>>): Pr
  * @param collection Object collection keyed by individual collection member keys and values
  */
 declare function setCollection<TKey extends CollectionKeyBase>(collectionKey: TKey, collection: OnyxSetCollectionInput<TKey>): Promise<void>;
+/**
+ * Returns persisted Onyx key-value pairs as a plain object.
+ * 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.
+ */
+declare function exportState(): Promise<Record<OnyxKey, OnyxValue<OnyxKey>>>;
 declare const Onyx: {
     METHOD: {
         readonly SET: "set";
@@ -171,6 +177,7 @@ declare const Onyx: {
     setCollection: typeof setCollection;
     update: typeof update;
     clear: typeof clear;
+    exportState: typeof exportState;
     init: typeof init;
     registerLogger: typeof Logger.registerLogger;
 };

package/dist/Onyx.js

@@ -554,6 +554,23 @@ function update(data) {
 function setCollection(collectionKey, collection) {
     return OnyxUtils_1.default.afterInit(() => OnyxUtils_1.default.setCollectionWithRetry({ collectionKey, collection }));
 }
+/**
+ * Returns persisted Onyx key-value pairs as a plain object.
+ * 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.
+ */
+function exportState() {
+    return OnyxUtils_1.default.afterInit(() => storage_1.default.getAll().then((entries) => {
+        const state = {};
+        for (const [key, value] of entries) {
+            if (OnyxKeys_1.default.isRamOnlyKey(key)) {
+                continue;
+            }
+            state[key] = value;
+        }
+        return state;
+    }));
+}
 const Onyx = {
     METHOD: OnyxUtils_1.default.METHOD,
     connect,
@@ -566,6 +583,7 @@ const Onyx = {
     setCollection,
     update,
     clear,
+    exportState,
     init,
     registerLogger: Logger.registerLogger,
 };

package/dist/OnyxUtils.d.ts

@@ -153,6 +153,8 @@ declare function reportStorageQuota(error?: Error): Promise<void>;
  * - 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.
  * - 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

@@ -668,6 +668,8 @@ function reportStorageQuota(error) {
  * - 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.
  * - 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.
  */
@@ -704,6 +706,12 @@ function retryOperation(error, onyxMethod, defaultParams, retryAttempt, inFlight
         Logger.logInfo(`Storage operation skipped retry; ${errorClass} errors are handled by the connection layer. Error: ${error}. onyxMethod: ${onyxMethod.name}.`);
         return Promise.resolve();
     }
+    // UNAVAILABLE: there is no storage engine in this environment. The storage layer has already swapped
+    // in the in-memory provider, so the write's data is not lost.
+    if (errorClass === errors_1.StorageErrorClass.UNAVAILABLE) {
+        Logger.logInfo(`Storage operation skipped retry; the storage engine is unavailable and the storage layer has degraded to memory-only. Error: ${error}. onyxMethod: ${onyxMethod.name}.`);
+        return Promise.resolve();
+    }
     if (nextRetryAttempt > MAX_STORAGE_OPERATION_RETRY_ATTEMPTS) {
         Logger.logAlert(`Storage operation failed after ${MAX_STORAGE_OPERATION_RETRY_ATTEMPTS} retries. Error: ${error}. onyxMethod: ${onyxMethod.name}.`);
         return Promise.resolve();

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

@@ -6,6 +6,7 @@ declare const StorageMock: {
         readonly DISK_PRESSURE: "diskPressure";
         readonly INVALID_DATA: "invalidData";
         readonly FATAL: "fatal";
+        readonly UNAVAILABLE: "unavailable";
         readonly UNKNOWN: "unknown";
     }>, [error: unknown], any>;
     getStorageProvider: jest.Mock<import("../providers/types").default<{

package/dist/storage/errors.d.ts

@@ -4,8 +4,9 @@
  * provider's `classifyError`). This module deliberately holds NO string matchers: it is the common
  * taxonomy the two reacting layers agree on, while the per-engine knowledge lives with the engine.
  *
- * - the connection layer (`createStore`) recovers TRANSIENT and FATAL errors by reopening the DB, and
- * - the operation layer (`OnyxUtils.retryOperation`) recovers CAPACITY by eviction and retries UNKNOWN.
+ * - the connection layer (`createStore`) recovers TRANSIENT and FATAL errors by reopening the DB,
+ * - the operation layer (`OnyxUtils.retryOperation`) recovers CAPACITY by eviction and retries UNKNOWN, and
+ * - the storage layer (`lib/storage/index.ts`) reacts to UNAVAILABLE by degrading to memory-only.
  *
  * This module has no Onyx dependencies (and no engine dependencies) so it can live in the storage
  * layer, and be imported by every provider, without creating an import cycle.
@@ -23,6 +24,11 @@ declare const StorageErrorClass: {
     readonly INVALID_DATA: "invalidData";
     /** Backing-store corruption. Owner: connection layer — budgeted heal, then give up. */
     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. */
+    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. */
     readonly UNKNOWN: "unknown";

package/dist/storage/errors.js

@@ -8,8 +8,9 @@ exports.getErrorParts = getErrorParts;
  * provider's `classifyError`). This module deliberately holds NO string matchers: it is the common
  * taxonomy the two reacting layers agree on, while the per-engine knowledge lives with the engine.
  *
- * - the connection layer (`createStore`) recovers TRANSIENT and FATAL errors by reopening the DB, and
- * - the operation layer (`OnyxUtils.retryOperation`) recovers CAPACITY by eviction and retries UNKNOWN.
+ * - the connection layer (`createStore`) recovers TRANSIENT and FATAL errors by reopening the DB,
+ * - the operation layer (`OnyxUtils.retryOperation`) recovers CAPACITY by eviction and retries UNKNOWN, and
+ * - the storage layer (`lib/storage/index.ts`) reacts to UNAVAILABLE by degrading to memory-only.
  *
  * This module has no Onyx dependencies (and no engine dependencies) so it can live in the storage
  * layer, and be imported by every provider, without creating an import cycle.
@@ -27,6 +28,11 @@ const StorageErrorClass = {
     INVALID_DATA: 'invalidData',
     /** Backing-store corruption. Owner: connection layer — budgeted heal, then give up. */
     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. */
+    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. */
     UNKNOWN: 'unknown',

package/dist/storage/index.js

@@ -40,7 +40,13 @@ const Logger = __importStar(require("../Logger"));
 const platforms_1 = __importDefault(require("./platforms"));
 const InstanceSync_1 = __importDefault(require("./InstanceSync"));
 const MemoryOnlyProvider_1 = __importDefault(require("./providers/MemoryOnlyProvider"));
+const errors_1 = require("./errors");
 let provider = platforms_1.default;
+/**
+ * Held separately from `provider` so `degradePerformance` swapping it for `MemoryOnlyProvider`
+ * doesn't erase the class of the error that caused the swap.
+ */
+const classifyStorageError = provider.classifyError;
 let shouldKeepInstancesSync = false;
 let finishInitalization;
 const initPromise = new Promise((resolve) => {
@@ -61,6 +67,13 @@ function degradePerformance(error) {
     console.error(error);
     provider = MemoryOnlyProvider_1.default;
 }
+/**
+ * Whether an error means the storage engine itself is unusable, which is what justifies dropping it.
+ */
+function shouldDegradeOn(error) {
+    // catch the error if DB connection can not be established/DB can not be created
+    return error instanceof Error && (error.message.includes('IDBKeyVal store could not be created') || classifyStorageError(error) === errors_1.StorageErrorClass.UNAVAILABLE);
+}
 /**
  * Runs a piece of code and degrades performance if certain errors are thrown
  */
@@ -69,8 +82,7 @@ function tryOrDegradePerformance(fn, waitForInitialization = true) {
     return initialization
         .then(() => fn())
         .catch((error) => {
-        // catch the error if DB connection can not be established/DB can not be created
-        if (error instanceof Error && error.message.includes('IDBKeyVal store could not be created')) {
+        if (shouldDegradeOn(error)) {
             degradePerformance(error);
         }
         return Promise.reject(error);
@@ -84,17 +96,22 @@ const storage = {
         return provider;
     },
     /**
-     * Classifies a write error using the active provider's own classifier. Synchronous and pure —
+     * Classifies a write error using the platform provider's own classifier. Synchronous and pure —
      * never wrapped in tryOrDegradePerformance.
      */
-    classifyError: (error) => provider.classifyError(error),
+    classifyError: (error) => classifyStorageError(error),
     /**
      * Initializes all providers in the list of storage providers
      * and enables fallback providers if necessary
+     *
+     * The rejection is consumed here: an unconsumed one would fire the app's global unhandled-rejection handler.
      */
     init() {
-        tryOrDegradePerformance(provider.init, false).finally(() => {
+        tryOrDegradePerformance(provider.init, false).then(finishInitalization, (error) => {
             finishInitalization();
+            if (!shouldDegradeOn(error)) {
+                Logger.logAlert(`Storage initialization failed. Original error: ${error instanceof Error ? error.message : String(error)}`);
+            }
         });
     },
     /**

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const errors_1 = require("../../errors");
+const isIndexedDBAvailable_1 = require("./isIndexedDBAvailable");
 /**
  * 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
@@ -8,6 +9,10 @@ const errors_1 = require("../../errors");
  */
 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())) {
+        return errors_1.StorageErrorClass.UNAVAILABLE;
+    }
     // Non-serializable data passed to IDBObjectStore.put — retrying is futile.
     if (message.includes("failed to execute 'put' on 'idbobjectstore'")) {
         return errors_1.StorageErrorClass.INVALID_DATA;

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

@@ -40,6 +40,7 @@ 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 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.
@@ -88,6 +89,9 @@ function createStore(dbName, storeName) {
     const getDB = () => {
         if (dbp)
             return dbp;
+        if (!(0, isIndexedDBAvailable_1.default)()) {
+            return Promise.reject(new Error(isIndexedDBAvailable_1.INDEXED_DB_UNAVAILABLE_MESSAGE));
+        }
         const request = indexedDB.open(dbName);
         request.onupgradeneeded = () => request.result.createObjectStore(storeName);
         return cacheOpenPromise(IDB.promisifyRequest(request));
@@ -181,6 +185,8 @@ function createStore(dbName, storeName) {
     //   Mirrors Dexie's PR1398_maxLoop pattern: https://github.com/dexie/Dexie.js/blob/master/src/functions/temp-transaction.ts
     // - CAPACITY / UNKNOWN are NOT the connection layer's responsibility — propagate to the operation
     //   layer (OnyxUtils.retryOperation) without retrying here, to avoid compounding retries.
+    // - UNAVAILABLE (no IndexedDB engine at all) is nobody's to recover — propagate so the storage
+    //   layer can degrade to memory-only once.
     // Note: concurrent store() calls share the heal budget. Under overlapping failures each caller
     // decrements independently, so the budget may drain faster than one-per-incident. This is
     // acceptable — same as Dexie's approach — and the budget resets on any success.

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

@@ -40,6 +40,7 @@ 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 DB_NAME = 'OnyxDB';
 const STORE_NAME = 'keyvaluepairs';
 /**
@@ -69,6 +70,9 @@ const provider = {
      * Initializes the storage provider
      */
     init() {
+        if (!(0, isIndexedDBAvailable_1.default)()) {
+            throw new Error(`IDBKeyVal store could not be created: ${isIndexedDBAvailable_1.INDEXED_DB_UNAVAILABLE_MESSAGE}`);
+        }
         const newIdbKeyValStore = (0, createStore_1.default)(DB_NAME, STORE_NAME);
         if (newIdbKeyValStore == null) {
             throw Error('IDBKeyVal store could not be created');

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

@@ -0,0 +1,9 @@
+/** 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

@@ -0,0 +1,14 @@
+"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`.
+ */
+function isIndexedDBAvailable() {
+    return typeof indexedDB !== 'undefined' && indexedDB !== null;
+}
+exports.default = isIndexedDBAvailable;

package/package.json

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