react-native-onyx 3.0.116 → 3.0.118

package/dist/PendingWrites.d.ts

@@ -0,0 +1,35 @@
+import type { OnyxKey } from './types';
+/**
+ * Registers an in-flight write under each key it can change, so `scheduleInitialSubscriberNotification`
+ * waits only for the writes relevant to a connecting key. Returns the same promise so callers can wrap a
+ * write's return value inline. The write is deregistered once it settles (success or failure).
+ */
+declare function trackPendingWrite<T>(keys: OnyxKey | OnyxKey[], pendingWrite: Promise<T>): Promise<T>;
+/**
+ * Registers an in-flight write that affects every key (Onyx.clear). Deregistered once it settles.
+ */
+declare function trackPendingGlobalWrite<T>(pendingGlobalWrite: Promise<T>): Promise<T>;
+/**
+ * In-flight writes that can change the value delivered to a subscriber of `key`: writes to the key
+ * itself, writes to any member when `key` is a collection root, and global writes (clear).
+ */
+declare function getPendingWritesForKey(key: OnyxKey): Array<Promise<unknown>>;
+/**
+ * Defer a subscriber's initial notification until the writes relevant to `key` that are in flight this
+ * tick have applied, so it reads post-write cache and dedups against their notifications. The wait is
+ * scoped to `key` and snapshotted after one microtask, so an unrelated or slow write elsewhere cannot
+ * block or postpone this delivery, and writes issued after it do not either.
+ */
+declare function scheduleInitialSubscriberNotification(key: OnyxKey, notify: () => void): void;
+/**
+ * Drop all tracked writes, useful in test environments.
+ */
+declare function clearPendingWrites(): void;
+declare const _default: {
+    trackPendingWrite: typeof trackPendingWrite;
+    trackPendingGlobalWrite: typeof trackPendingGlobalWrite;
+    getPendingWritesForKey: typeof getPendingWritesForKey;
+    scheduleInitialSubscriberNotification: typeof scheduleInitialSubscriberNotification;
+    clearPendingWrites: typeof clearPendingWrites;
+};
+export default _default;

package/dist/PendingWrites.js

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const OnyxKeys_1 = __importDefault(require("./OnyxKeys"));
+// In-flight writes tracked per affected key, so a subscriber's initial notification waits only for
+// writes that can change its own value, never for unrelated (or slow) writes elsewhere.
+const pendingWritesByKey = new Map();
+// In-flight writes that affect every key (Onyx.clear). Any initial notification waits for these.
+const pendingGlobalWrites = new Set();
+/**
+ * Registers an in-flight write under each key it can change, so `scheduleInitialSubscriberNotification`
+ * waits only for the writes relevant to a connecting key. Returns the same promise so callers can wrap a
+ * write's return value inline. The write is deregistered once it settles (success or failure).
+ */
+function trackPendingWrite(keys, pendingWrite) {
+    // Drop nullish keys (e.g. a keyless `clear` item) so they never reach `getPendingWritesForKey`'s scan.
+    const keyList = (Array.isArray(keys) ? keys : [keys]).filter((key) => typeof key === 'string');
+    for (const key of keyList) {
+        let pendingWritesForKey = pendingWritesByKey.get(key);
+        if (!pendingWritesForKey) {
+            pendingWritesForKey = new Set();
+            pendingWritesByKey.set(key, pendingWritesForKey);
+        }
+        pendingWritesForKey.add(pendingWrite);
+    }
+    const deregister = () => {
+        for (const key of keyList) {
+            const pendingWritesForKey = pendingWritesByKey.get(key);
+            if (!pendingWritesForKey) {
+                continue;
+            }
+            pendingWritesForKey.delete(pendingWrite);
+            if (pendingWritesForKey.size === 0) {
+                pendingWritesByKey.delete(key);
+            }
+        }
+    };
+    pendingWrite.then(deregister, deregister);
+    return pendingWrite;
+}
+/**
+ * Registers an in-flight write that affects every key (Onyx.clear). Deregistered once it settles.
+ */
+function trackPendingGlobalWrite(pendingGlobalWrite) {
+    pendingGlobalWrites.add(pendingGlobalWrite);
+    const deregister = () => pendingGlobalWrites.delete(pendingGlobalWrite);
+    pendingGlobalWrite.then(deregister, deregister);
+    return pendingGlobalWrite;
+}
+/**
+ * In-flight writes that can change the value delivered to a subscriber of `key`: writes to the key
+ * itself, writes to any member when `key` is a collection root, and global writes (clear).
+ */
+function getPendingWritesForKey(key) {
+    const promises = [...pendingGlobalWrites];
+    const own = pendingWritesByKey.get(key);
+    if (own) {
+        promises.push(...own);
+    }
+    if (OnyxKeys_1.default.isCollectionKey(key)) {
+        for (const [writeKey, pendingWritesForKey] of pendingWritesByKey) {
+            // Membership resolves by longest match, as `notifyKey`/`notifyCollection` do, so a write to a
+            // more specific collection (`test_level_last_1`) is not treated as a member of a shorter one
+            // (`test_level_`) and cannot delay its subscribers.
+            if (writeKey !== key && OnyxKeys_1.default.getCollectionKey(writeKey) === key) {
+                promises.push(...pendingWritesForKey);
+            }
+        }
+    }
+    return promises;
+}
+/**
+ * Defer a subscriber's initial notification until the writes relevant to `key` that are in flight this
+ * tick have applied, so it reads post-write cache and dedups against their notifications. The wait is
+ * scoped to `key` and snapshotted after one microtask, so an unrelated or slow write elsewhere cannot
+ * block or postpone this delivery, and writes issued after it do not either.
+ */
+function scheduleInitialSubscriberNotification(key, notify) {
+    Promise.resolve().then(() => {
+        const relevant = getPendingWritesForKey(key);
+        if (relevant.length === 0) {
+            notify();
+            return;
+        }
+        Promise.all(relevant.map((pendingWrite) => pendingWrite.catch(() => undefined))).then(notify);
+    });
+}
+/**
+ * Drop all tracked writes, useful in test environments.
+ */
+function clearPendingWrites() {
+    pendingWritesByKey.clear();
+    pendingGlobalWrites.clear();
+}
+exports.default = {
+    trackPendingWrite,
+    trackPendingGlobalWrite,
+    getPendingWritesForKey,
+    scheduleInitialSubscriberNotification,
+    clearPendingWrites,
+};

package/dist/index.d.ts

@@ -1,8 +1,7 @@
-import type { ConnectOptions, OnyxUpdate } from './Onyx';
+import type { Connection, ConnectOptions, OnyxUpdate } from './Onyx';
 import Onyx from './Onyx';
 import type { CustomTypeOptions, KeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxValue, Selector, OnyxInputValue, OnyxCollectionInputValue, OnyxInput, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput, OnyxSetCollectionInput } from './types';
 import type { FetchStatus, ResultMetadata, UseOnyxResult, UseOnyxOptions } from './useOnyx';
-import type { Connection } from './OnyxConnectionManager';
 import useOnyx from './useOnyx';
 import type { OnyxSQLiteKeyValuePair } from './storage/providers/SQLiteProvider';
 export default Onyx;

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

@@ -31,6 +31,10 @@ function classifyIDBError(error) {
     if (message.includes('internal error opening backing store')) {
         return errors_1.StorageErrorClass.FATAL;
     }
+    // Chromium persistence failure with no cause attached, recovered by a fresh connection.
+    if (name === 'unknownerror' && message === 'internal error.') {
+        return errors_1.StorageErrorClass.FATAL;
+    }
     // Transient connection/transport failures — the cached connection is stale and a reopen fixes it:
     // - InvalidStateError: connection closed between getDB() resolving and db.transaction().
     // - AbortError: write transaction aborted (connection close / versionchange / sibling abort).

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

@@ -209,6 +209,7 @@ function createStore(dbName, storeName) {
             Logger.logInfo(`IDB heal: backing store error detected — dropping cached connection and reopening (${healAttemptsRemaining} attempts left)`, {
                 dbName,
                 storeName,
+                errorMessage: error instanceof Error ? error.message : String(error),
             });
             dbp = undefined;
             return executeTransaction(txMode, callback).then((result) => {

package/dist/types.d.ts

@@ -176,14 +176,6 @@ type NullishObjectDeep<ObjectType extends object> = {
  * the object of collection keys/values specified in the second parameter of the method.
  */
 type Collection<TKey extends CollectionKeyBase, TValue> = Record<`${TKey}${string}`, TValue>;
-/** Represents the base options used in `Onyx.connect()` method. */
-type BaseConnectOptions = {
-    /**
-     * If set to `false`, the connection won't be reused between other subscribers that are listening to the same Onyx key
-     * with the same connect configurations.
-     */
-    reuseConnection?: boolean;
-};
 /** Represents the callback function used in `Onyx.connect()` method with a regular key. */
 type DefaultConnectCallback<TKey extends OnyxKey> = (value: OnyxEntry<KeyValueMapping[TKey]>, key: TKey) => void;
 /** Represents the callback function used in `Onyx.connect()` method with a collection key. */
@@ -196,15 +188,12 @@ type CollectionConnectCallback<TKey extends OnyxKey> = (value: NonUndefined<Onyx
  * `(collection, key)`). For any other key, the callback fires with the value at
  * that key (signature `(value, key)`).
  */
-type ConnectOptions<TKey extends OnyxKey> = BaseConnectOptions & {
+type ConnectOptions<TKey extends OnyxKey> = {
     /** The Onyx key to subscribe to. */
     key: TKey;
     /** A function that will be called when the Onyx data we are subscribed changes. */
     callback?: (value: TKey extends CollectionKeyBase ? NonUndefined<OnyxCollection<KeyValueMapping[TKey]>> : OnyxEntry<KeyValueMapping[TKey]>, key: TKey) => void;
 };
-type CallbackToStateMapping<TKey extends OnyxKey> = ConnectOptions<TKey> & {
-    subscriptionID: number;
-};
 /**
  * Represents a single Onyx input value, that can be either `TOnyxValue` or `null` if the key should be deleted.
  * This type is used for data passed to Onyx e.g. in `Onyx.merge` and `Onyx.set`.
@@ -362,4 +351,12 @@ type MixedOperationsQueue = {
     mergeReplaceNullPatches: MultiMergeReplaceNullPatches;
     set: OnyxInputKeyValueMapping;
 };
-export type { BaseConnectOptions, Collection, CollectionConnectCallback, CollectionKey, CollectionKeyBase, ConnectOptions, CustomTypeOptions, DeepRecord, DefaultConnectCallback, ExtractOnyxCollectionValue, GenericFunction, InitOptions, Key, KeyValueMapping, CallbackToStateMapping, NonNull, NonUndefined, OnyxInputKeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxInputValue, OnyxCollectionInputValue, OnyxInput, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput, OnyxSetCollectionInput, OnyxMethod, OnyxMethodMap, OnyxUpdate, OnyxValue, Selector, SetOptions, SetParams, SetCollectionParams, MergeCollectionWithPatchesParams, MultiMergeReplaceNullPatches, MixedOperationsQueue, RetriableOnyxOperation, };
+/**
+ * Represents a connection to an Onyx key, returned by `Onyx.connect()`/`Onyx.connectWithoutView()`.
+ * Pass it to `Onyx.disconnect()` to stop receiving callbacks for this subscription.
+ */
+type Connection = {
+    /** Unsubscribe this connection. Idempotent. */
+    unsubscribe: () => void;
+};
+export type { Connection, Collection, CollectionConnectCallback, CollectionKey, CollectionKeyBase, ConnectOptions, CustomTypeOptions, DeepRecord, DefaultConnectCallback, ExtractOnyxCollectionValue, GenericFunction, InitOptions, Key, KeyValueMapping, NonNull, NonUndefined, OnyxInputKeyValueMapping, NullishDeep, OnyxCollection, OnyxEntry, OnyxKey, OnyxInputValue, OnyxCollectionInputValue, OnyxInput, OnyxSetInput, OnyxMultiSetInput, OnyxMergeInput, OnyxMergeCollectionInput, OnyxSetCollectionInput, OnyxMethod, OnyxMethodMap, OnyxUpdate, OnyxValue, Selector, SetOptions, SetParams, SetCollectionParams, MergeCollectionWithPatchesParams, MultiMergeReplaceNullPatches, MixedOperationsQueue, RetriableOnyxOperation, };

package/dist/useOnyx.d.ts

@@ -2,24 +2,25 @@ import type { OnyxKey, OnyxValue } from './types';
 type UseOnyxSelector<TKey extends OnyxKey, TReturnValue = OnyxValue<TKey>> = (data: OnyxValue<TKey> | undefined) => TReturnValue;
 type UseOnyxOptions<TKey extends OnyxKey, TReturnValue> = {
     /**
-     * If set to `false`, the connection won't be reused between other subscribers that are listening to the same Onyx key
-     * with the same connect configurations.
-     */
-    reuseConnection?: boolean;
-    /**
-     * This will be used to subscribe to a subset of an Onyx key's data.
-     * 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).
-     * @see `useOnyx` cannot return `null` and so selector will replace `null` with `undefined` to maintain compatibility.
+     * Select a subset of the key's data. Re-renders only when the selector's output changes by deep
+     * equality, so an inline selector that allocates fresh objects/arrays each render is safe.
      */
     selector?: UseOnyxSelector<TKey, TReturnValue>;
 };
+/**
+ * `loading` while the key's first value is still on its way: `Onyx.init` hasn't hydrated the cache yet,
+ * or nothing is cached and a merge is in flight. `loaded` otherwise.
+ */
 type FetchStatus = 'loading' | 'loaded';
 type ResultMetadata = {
     status: FetchStatus;
 };
 type UseOnyxResult<TValue> = [NonNullable<TValue> | undefined, ResultMetadata];
+/**
+ * Subscribes a component to an Onyx key, re-rendering when the value changes (for a collection key,
+ * when any member changes; the value is the frozen collection object). Returns `[value, {status}]`,
+ * `status` `loading` until the key's first value can be known.
+ */
 declare function useOnyx<TKey extends OnyxKey, TReturnValue = OnyxValue<TKey>>(key: TKey, options?: UseOnyxOptions<TKey, TReturnValue>): UseOnyxResult<TReturnValue>;
 export default useOnyx;
 export type { FetchStatus, ResultMetadata, UseOnyxResult, UseOnyxOptions, UseOnyxSelector };

package/dist/useOnyx.js

@@ -1,209 +1,84 @@
 "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;
-    };
-})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const fast_equals_1 = require("fast-equals");
 const react_1 = require("react");
-const createMemoizedSelector_1 = __importDefault(require("./createMemoizedSelector"));
-const OnyxCache_1 = __importStar(require("./OnyxCache"));
-const OnyxConnectionManager_1 = __importDefault(require("./OnyxConnectionManager"));
+const with_selector_1 = require("use-sync-external-store/with-selector");
+const OnyxCache_1 = __importDefault(require("./OnyxCache"));
+const OnyxSubscriptionManager_1 = __importDefault(require("./OnyxSubscriptionManager"));
 const OnyxUtils_1 = __importDefault(require("./OnyxUtils"));
-const OnyxSnapshotCache_1 = __importDefault(require("./OnyxSnapshotCache"));
-const memoizedShallowEqual_1 = __importDefault(require("./memoizedShallowEqual"));
+function isOnyxInitialised() {
+    return OnyxUtils_1.default.getDeferredInitTask().isResolved;
+}
+/**
+ * What can be said about a key's value, as a single value so that init finishing re-renders a
+ * subscriber even when its key has no value and nothing else about it changed.
+ */
+const AVAILABILITY = {
+    /** `Onyx.init` hasn't hydrated the cache yet, so nothing can be said about the key. */
+    UNKNOWN: 0,
+    /** The cache is hydrated and the key has no value. */
+    ABSENT: 1,
+    /** The cache is hydrated and the key has a value. */
+    PRESENT: 2,
+};
+function getAvailability(key) {
+    if (!isOnyxInitialised()) {
+        return AVAILABILITY.UNKNOWN;
+    }
+    return OnyxCache_1.default.hasCacheForKey(key) ? AVAILABILITY.PRESENT : AVAILABILITY.ABSENT;
+}
+/**
+ * Subscribes a component to an Onyx key, re-rendering when the value changes (for a collection key,
+ * when any member changes; the value is the frozen collection object). Returns `[value, {status}]`,
+ * `status` `loading` until the key's first value can be known.
+ */
 function useOnyx(key, options) {
-    const connectionRef = (0, react_1.useRef)(null);
     const selector = options === null || options === void 0 ? void 0 : options.selector;
-    // Create memoized version of selector for performance. It caches by input reference
-    // with a deepEqual fallback on the output to keep the returned reference stable.
-    const memoizedSelector = (0, react_1.useMemo)(() => {
-        if (!selector) {
-            return null;
-        }
-        return (0, createMemoizedSelector_1.default)(selector);
-    }, [selector]);
-    // Stores the previous cached value as it's necessary to compare with the new value in `getSnapshot()`.
-    // We initialize it to `null` to simulate that we don't have any value from cache yet.
-    const previousValueRef = (0, react_1.useRef)(null);
-    // Stores the newest cached value in order to compare with the previous one and optimize `getSnapshot()` execution.
-    const newValueRef = (0, react_1.useRef)(null);
-    // Stores the previously result returned by the hook, containing the data from cache and the fetch status.
-    // We initialize it to `undefined` and `loading` fetch status to simulate the initial result when the hook is loading from the cache.
-    const resultRef = (0, react_1.useRef)([
-        undefined,
-        {
-            status: 'loading',
-        },
-    ]);
-    // Tracks which key has completed its first Onyx connection callback. When this doesn't match the
-    // current key, getSnapshot() treats the hook as being in its "first connection" state for that key.
-    // This is key-aware by design: when the key changes, connectedKeyRef still holds the old key (or null
-    // after cleanup), so the hook automatically enters first-connection mode for the new key without any
-    // explicit reset logic — eliminating the race condition where cleanup could clobber a boolean flag.
+    // First-render marker for the loading gate below.
     const connectedKeyRef = (0, react_1.useRef)(null);
-    // Tracks whether the hook has completed its initial mount subscription.
-    // Unlike connectedKeyRef (which gets nulled by cleanup), this persists across re-subscriptions.
-    const hasMountedRef = (0, react_1.useRef)(false);
-    // Indicates if the hook is connecting to an Onyx key.
-    const isConnectingRef = (0, react_1.useRef)(false);
-    // Stores the `onStoreChange()` function, which can be used to trigger a `getSnapshot()` update when desired.
-    const onStoreChangeFnRef = (0, react_1.useRef)(null);
-    // Indicates if we should get the newest cached value from Onyx during `getSnapshot()` execution.
-    const shouldGetCachedValueRef = (0, react_1.useRef)(true);
-    // Cache the options key to avoid regenerating it every getSnapshot call
-    const cacheKey = (0, react_1.useMemo)(() => OnyxSnapshotCache_1.default.registerConsumer(key, {
-        selector: options === null || options === void 0 ? void 0 : options.selector,
-    }), [key, options === null || options === void 0 ? void 0 : options.selector]);
-    (0, react_1.useEffect)(() => () => OnyxSnapshotCache_1.default.deregisterConsumer(key, cacheKey), [key, cacheKey]);
-    // Tracks the last memoizedSelector reference that getSnapshot() has computed with.
-    // When the selector changes, this mismatch forces getSnapshot() to re-evaluate
-    // even if all other conditions (isFirstConnection, shouldGetCachedValue, key) are false.
-    const lastComputedSelectorRef = (0, react_1.useRef)(memoizedSelector);
-    const getSnapshot = (0, react_1.useCallback)(() => {
-        var _a, _b, _c;
-        // Check if we have any cache for this Onyx key
-        // Don't use cache during active data updates (when shouldGetCachedValueRef is true)
-        const isFirstConnection = connectedKeyRef.current !== key;
-        if (!shouldGetCachedValueRef.current) {
-            const cachedResult = OnyxSnapshotCache_1.default.getCachedResult(key, cacheKey);
-            if (cachedResult !== undefined) {
-                // The slot is shared by all subscribers of the same (key, selector) pair, so it can hold a content-equal
-                // result computed by another subscriber. Keep our own result then, otherwise we would needlessly change
-                // this hook's result identity and re-render its consumer.
-                if (cachedResult !== resultRef.current && (0, memoizedShallowEqual_1.default)(cachedResult[0], resultRef.current[0]) && cachedResult[1].status === resultRef.current[1].status) {
-                    return resultRef.current;
-                }
-                resultRef.current = cachedResult;
-                return cachedResult;
-            }
-        }
-        // We get the value from cache while the first connection to Onyx is being made or if the key has changed,
-        // so we can return any cached value right away. For the case where the key has changed, If we don't return the cached value right away, then the UI will show the incorrect (previous) value for a brief period which looks like a UI glitch to the user. After the connection is made, we only
-        // update `newValueRef` when `Onyx.connect()` callback is fired.
-        const hasSelectorChanged = lastComputedSelectorRef.current !== memoizedSelector;
-        if (isFirstConnection || shouldGetCachedValueRef.current || hasSelectorChanged) {
-            // Gets the value from cache and maps it with selector. It changes `null` to `undefined` for `useOnyx` compatibility.
-            const value = OnyxUtils_1.default.tryGetCachedValue(key);
-            const selectedValue = memoizedSelector ? memoizedSelector(value) : value;
-            lastComputedSelectorRef.current = memoizedSelector;
-            newValueRef.current = (selectedValue !== null && selectedValue !== void 0 ? selectedValue : undefined);
-            // We set this flag to `false` again since we don't want to get the newest cached value every time `getSnapshot()` is executed,
-            // and only when `Onyx.connect()` callback is fired.
-            shouldGetCachedValueRef.current = false;
-        }
-        const hasCacheForKey = OnyxCache_1.default.hasCacheForKey(key);
-        // Since the fetch status can be different given the use cases below, we define the variable right away.
-        let newFetchStatus;
-        // If we have pending merge operations for the key during the first connection, we set the new value to `undefined`
-        // and fetch status to `loading` to simulate that it is still being loaded until we have the most updated data.
-        if (isFirstConnection && OnyxUtils_1.default.hasPendingMergeForKey(key)) {
-            newValueRef.current = undefined;
-            newFetchStatus = 'loading';
-        }
-        // shallowEqual checks === first (O(1) for frozen snapshots and stable selector references),
-        // then falls back to comparing top-level properties for individual keys that may have
-        // new references with equivalent content. The comparison is memoized by object identity
-        // (see `memoizedShallowEqual`) so N hooks comparing the same two cache objects pay for
-        // one walk in total instead of one walk each.
-        // Normalize null to undefined to ensure consistent comparison (both represent "no value").
-        const areValuesEqual = (0, memoizedShallowEqual_1.default)((_a = previousValueRef.current) !== null && _a !== void 0 ? _a : undefined, (_b = newValueRef.current) !== null && _b !== void 0 ? _b : undefined);
-        // We update the cached value and the result in the following conditions:
-        // We will update the cached value and the result in any of the following situations:
-        // - The previously cached value is different from the new value.
-        // - The previously cached value is `null` (not set from cache yet) and we have cache for this key
-        //   OR we have a pending `Onyx.clear()` task (if `Onyx.clear()` is running cache might not be available anymore
-        //   OR the subscriber is triggered (the value is gotten from the storage)
-        //   so we update the cached value/result right away in order to prevent infinite loading state issues).
-        const shouldUpdateResult = !areValuesEqual || (previousValueRef.current === null && (hasCacheForKey || OnyxCache_1.default.hasPendingTask(OnyxCache_1.TASK.CLEAR) || !isFirstConnection));
-        if (shouldUpdateResult) {
-            previousValueRef.current = newValueRef.current;
-            // If the new value is `null` we default it to `undefined` to ensure the consumer gets a consistent result from the hook.
-            newFetchStatus = newFetchStatus !== null && newFetchStatus !== void 0 ? newFetchStatus : 'loaded';
-            resultRef.current = [
-                (_c = previousValueRef.current) !== null && _c !== void 0 ? _c : undefined,
-                {
-                    status: newFetchStatus,
-                },
-            ];
-        }
-        if (newFetchStatus !== 'loading') {
-            OnyxSnapshotCache_1.default.setCachedResult(key, cacheKey, resultRef.current);
-        }
-        return resultRef.current;
-    }, [key, memoizedSelector, cacheKey]);
     const subscribe = (0, react_1.useCallback)((onStoreChange) => {
-        // Reset internal state so the hook properly transitions through loading
-        // for the new key instead of preserving stale state from the previous one.
-        // Only reset when the key has actually changed (not on initial mount).
-        if (hasMountedRef.current) {
-            previousValueRef.current = null;
-            newValueRef.current = null;
-            resultRef.current = [undefined, { status: 'loading' }];
-            shouldGetCachedValueRef.current = true;
-        }
-        hasMountedRef.current = true;
-        isConnectingRef.current = true;
-        onStoreChangeFnRef.current = onStoreChange;
-        connectionRef.current = OnyxConnectionManager_1.default.connect({
-            key,
-            callback: () => {
-                isConnectingRef.current = false;
-                onStoreChangeFnRef.current = onStoreChange;
-                // Signals that the first connection was made for this key, so some logics
-                // in `getSnapshot()` won't be executed anymore.
-                connectedKeyRef.current = key;
-                // Signals that we want to get the newest cached value again in `getSnapshot()`.
-                shouldGetCachedValueRef.current = true;
-                // Invalidate snapshot cache for this key when data changes
-                OnyxSnapshotCache_1.default.invalidateForKey(key);
-                // Finally, we signal that the store changed, making `getSnapshot()` be called again.
+        const unsubscribe = OnyxSubscriptionManager_1.default.subscribe(key, onStoreChange);
+        // `Onyx.init` hydrates the cache without notifying anyone, so a subscriber that mounted
+        // before it finished would never hear about the stored value. Re-read once init lands.
+        let isActive = true;
+        if (!isOnyxInitialised()) {
+            OnyxUtils_1.default.getDeferredInitTask().promise.then(() => {
+                if (!isActive) {
+                    return;
+                }
                 onStoreChange();
-            },
-            reuseConnection: options === null || options === void 0 ? void 0 : options.reuseConnection,
-        });
+            });
+        }
         return () => {
-            if (!connectionRef.current) {
-                return;
-            }
-            OnyxConnectionManager_1.default.disconnect(connectionRef.current);
-            connectedKeyRef.current = null;
-            isConnectingRef.current = false;
-            onStoreChangeFnRef.current = null;
+            isActive = false;
+            unsubscribe();
         };
-    }, [key, options === null || options === void 0 ? void 0 : options.reuseConnection]);
-    const result = (0, react_1.useSyncExternalStore)(subscribe, getSnapshot);
-    return result;
+    }, [key]);
+    const getSnapshot = (0, react_1.useCallback)(() => OnyxSubscriptionManager_1.default.getState(key), [key]);
+    const select = (0, react_1.useCallback)((data) => { var _a; return (_a = (selector ? selector(data) : data)) !== null && _a !== void 0 ? _a : undefined; }, [selector]);
+    // Deep-equal only with a selector (its output may be freshly allocated); raw values are ref-stable.
+    const isEqual = selector ? fast_equals_1.deepEqual : undefined;
+    const value = (0, with_selector_1.useSyncExternalStoreWithSelector)(subscribe, getSnapshot, undefined, select, isEqual);
+    // Reactive availability, so the first value landing re-renders even when the selector output is unchanged.
+    const availability = (0, react_1.useSyncExternalStore)(subscribe, () => getAvailability(key));
+    const isCached = availability === AVAILABILITY.PRESENT;
+    // Loading while a first value is still on its way: init hasn't hydrated yet, or nothing is cached
+    // and a merge is in flight.
+    // eslint-disable-next-line react-hooks/refs
+    const isLoading = !isOnyxInitialised() || (connectedKeyRef.current !== key && !isCached && OnyxUtils_1.default.hasPendingMergeForKey(key));
+    const loadingStatus = isLoading ? 'loading' : 'loaded';
+    // Only advance the marker once a value exists, so an unrelated re-render can't end loading early.
+    (0, react_1.useEffect)(() => {
+        if (!isCached) {
+            return;
+        }
+        connectedKeyRef.current = key;
+    }, [isCached, key]);
+    // Blank the value while loading: the pending merge isn't in cache yet.
+    const result = isLoading ? undefined : value;
+    return (0, react_1.useMemo)(() => [result, { status: loadingStatus }], [result, loadingStatus]);
 }
 exports.default = useOnyx;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-onyx",
-  "version": "3.0.116",
+  "version": "3.0.118",
   "author": "Expensify, Inc.",
   "homepage": "https://expensify.com",
   "description": "State management for React Native",
@@ -49,7 +49,8 @@
     "lodash.clone": "^4.5.0",
     "lodash.pick": "^4.4.0",
     "lodash.transform": "^4.6.0",
-    "underscore": "^1.13.6"
+    "underscore": "^1.13.6",
+    "use-sync-external-store": "^1.6.0"
   },
   "devDependencies": {
     "@actions/core": "^1.10.1",
@@ -70,6 +71,7 @@
     "@types/react": "^18.2.14",
     "@types/react-native": "^0.70.0",
     "@types/underscore": "^1.11.15",
+    "@types/use-sync-external-store": "^1.5.0",
     "@typescript-eslint/eslint-plugin": "^8.51.0",
     "@typescript-eslint/parser": "^8.51.0",
     "@vercel/ncc": "0.38.1",

package/dist/OnyxConnectionManager.d.ts

@@ -1,78 +0,0 @@
-import type { ConnectOptions } from './Onyx';
-import type { OnyxKey } from './types';
-/**
- * Represents the connection object returned by `Onyx.connect()`.
- */
-type Connection = {
-    /**
-     * The ID used to identify this particular connection.
-     */
-    id: string;
-    /**
-     * The ID of the subscriber's callback that is associated to this connection.
-     */
-    callbackID: string;
-};
-/**
- * Manages Onyx connections of `Onyx.connect()` and `useOnyx()` subscribers.
- */
-declare class OnyxConnectionManager {
-    /**
-     * A map where the key is the connection ID generated inside `connect()` and the value is the metadata of that connection.
-     */
-    private connectionsMap;
-    /**
-     * Stores the last generated callback ID which will be incremented when making a new connection.
-     */
-    private lastCallbackID;
-    /**
-     * Stores the last generated session ID for the connection manager. The current session ID
-     * is appended to the connection IDs and it's used to create new different connections for the same key
-     * when `refreshSessionID()` is called.
-     *
-     * When calling `Onyx.clear()` after a logout operation some connections might remain active as they
-     * aren't tied to the React's lifecycle e.g. `Onyx.connect()` usage, causing infinite loading state issues to new `useOnyx()` subscribers
-     * that are connecting to the same key as we didn't populate the cache again because we are still reusing such connections.
-     *
-     * To elimitate this problem, the session ID must be refreshed during the `Onyx.clear()` call (by using `refreshSessionID()`)
-     * in order to create fresh connections when new subscribers connect to the same keys again, allowing them
-     * to use the cache system correctly and avoid the mentioned issues in `useOnyx()`.
-     */
-    private sessionID;
-    constructor();
-    /**
-     * Generates a connection ID based on the `connectOptions` object passed to the function.
-     *
-     * The properties used to generate the ID are handpicked for performance reasons and
-     * according to their purpose and effect they produce in the Onyx connection.
-     */
-    private generateConnectionID;
-    /**
-     * Fires all the subscribers callbacks associated with that connection ID.
-     */
-    private fireCallbacks;
-    /**
-     * Connects to an Onyx key given the options passed and listens to its changes.
-     *
-     * @param connectOptions The options object that will define the behavior of the connection.
-     * @returns The connection object to use when calling `disconnect()`.
-     */
-    connect<TKey extends OnyxKey>(connectOptions: ConnectOptions<TKey>): Connection;
-    /**
-     * Disconnects and removes the listener from the Onyx key.
-     *
-     * @param connection Connection object returned by calling `connect()`.
-     */
-    disconnect(connection: Connection): void;
-    /**
-     * Disconnect all subscribers from Onyx.
-     */
-    disconnectAll(): void;
-    /**
-     * Refreshes the connection manager's session ID.
-     */
-    refreshSessionID(): void;
-}
-declare const connectionManager: OnyxConnectionManager;
-export default connectionManager;
-export type { Connection };