diff --git a/lib/Onyx.ts b/lib/Onyx.ts index a8f8f2d4f..f0cc375eb 100644 --- a/lib/Onyx.ts +++ b/lib/Onyx.ts @@ -4,10 +4,13 @@ import Storage from './storage'; import utils from './utils'; import DevTools, {initDevTools} from './DevTools'; import type { + CollectionConnectCallback, CollectionKeyBase, ConnectOptions, + DefaultConnectCallback, InitOptions, KeyValueMapping, + OnyxCollection, OnyxInputKeyValueMapping, MixedOperationsQueue, OnyxKey, @@ -25,10 +28,28 @@ import type { import OnyxUtils from './OnyxUtils'; import OnyxKeys from './OnyxKeys'; import logMessages from './logMessages'; -import type {Connection} from './OnyxConnectionManager'; -import connectionManager from './OnyxConnectionManager'; +import onyxStore from './OnyxStore'; import OnyxMerge from './OnyxMerge'; +/** + * Opaque handle 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; +}; + +/** + * Shared sentinel for "nothing delivered yet" in `connect()`'s per-subscription dedup. + * A unique Symbol can't collide with any real Onyx value, so the first `Object.is` check + * never matches and the initial fire always runs — even for a key whose genuine first + * value is `undefined`. It only needs to be distinct from real values, not unique per + * subscription, so a single module-level instance is reused by every connection. + */ +// eslint-disable-next-line rulesdir/no-negated-variables +const NOT_DELIVERED = Symbol('NOT_DELIVERED'); + /** Initialize the store with actions and listening for storage events */ function init({ keys = {}, @@ -58,13 +79,7 @@ function init({ } cache.set(key, value); - - // Check if this is a collection member key to prevent duplicate callbacks - // When a collection is updated, individual members sync separately to other tabs - // Setting isProcessingCollectionUpdate=true prevents triggering collection callbacks for each individual update - const isKeyCollectionMember = OnyxKeys.isCollectionMember(key); - - OnyxUtils.keyChanged(key, value as OnyxValue, undefined, isKeyCollectionMember); + OnyxUtils.notifyKey(key, value as OnyxValue); }); } @@ -80,73 +95,142 @@ function init({ } /** - * Connects to an Onyx key given the options passed and listens to its changes. - * This method will be deprecated soon. Please use `Onyx.connectWithoutView()` instead. - * - * @example - * ```ts - * const connection = Onyx.connectWithoutView({ - * key: ONYXKEYS.SESSION, - * callback: onSessionChange, - * }); - * ``` + * Sync, cache-only read of an Onyx key. Returns the frozen collection snapshot for + * collection keys, the cached value for single keys, or `undefined` if the key isn't + * in cache (no storage fallback). * - * @param connectOptions The options object that will define the behavior of the connection. - * @param connectOptions.key The Onyx key to subscribe to. - * @param connectOptions.callback A function that will be called when the Onyx data we are subscribed changes. - * @param connectOptions.waitForCollectionCallback If set to `true`, it will return the entire collection to the callback as a single object. - * @param connectOptions.selector This will be used to subscribe to a subset of an Onyx key's data. **Only used inside `useOnyx()` hook.** - * Using this setting on `useOnyx()` can have very positive performance benefits because the component will only re-render - * when the subset of data changes. Otherwise, any change of data on any property would normally - * cause the component to re-render (and that can be expensive from a performance standpoint). - * @returns The connection object to use when calling `Onyx.disconnect()`. + * Use this for one-off reads outside React. Inside React, prefer `useOnyx`. */ -function connect(connectOptions: ConnectOptions): Connection { - return connectionManager.connect(connectOptions); +function getState(key: TKey): OnyxValue { + return onyxStore.getState(key); } /** - * Connects to an Onyx key given the options passed and listens to its changes. + * Defer initial-fire of `Onyx.connect` callbacks far enough that any Onyx writes + * scheduled in the same synchronous tick have applied before the callback reads cache. * - * @example - * ```ts - * const connection = Onyx.connectWithoutView({ - * key: ONYXKEYS.SESSION, - * callback: onSessionChange, - * }); - * ``` + * The legacy `subscribeToKey` chain (`deferredInitTask.then(getAllKeys).then(multiGet) + * .then(sendDataToConnection)`) reached this depth incidentally via storage I/O. The + * new store-based wrapper has no storage chain, so we have to introduce the depth + * explicitly. The three nested `.then()`s match the legacy effective depth — enough + * to outpace the longest in-flight write chain: `Onyx.update` -> `clearPromise.then` + * -> per-item `Onyx.merge` -> `OnyxUtils.get(key).then(applyMerge)` is two hops to + * apply, so the third hop guarantees initial-fire reads the post-write cache. * - * @param connectOptions The options object that will define the behavior of the connection. - * @param connectOptions.key The Onyx key to subscribe to. - * @param connectOptions.callback A function that will be called when the Onyx data we are subscribed changes. - * @param connectOptions.waitForCollectionCallback If set to `true`, it will return the entire collection to the callback as a single object. - * @param connectOptions.selector This will be used to subscribe to a subset of an Onyx key's data. **Only used inside `useOnyx()` hook.** - * Using this setting on `useOnyx()` can have very positive performance benefits because the component will only re-render - * when the subset of data changes. Otherwise, any change of data on any property would normally - * cause the component to re-render (and that can be expensive from a performance standpoint). - * @returns The connection object to use when calling `Onyx.disconnect()`. + * Microtask depth (not `setTimeout(0)`) is required because Jest test bodies run + * entirely in microtask land via chained `.then()`s; a macrotask-deferred initial + * fire would not run until the chain returns to the event loop, which can be after + * the test's assertions execute — leaving module-level Onyx subscribers stale. */ -function connectWithoutView(connectOptions: ConnectOptions): Connection { - return connectionManager.connect(connectOptions); +function scheduleInitialFire(fn: () => void): void { + Promise.resolve() + .then(() => Promise.resolve()) + .then(() => Promise.resolve()) + .then(fn); } /** - * Disconnects and removes the listener from the Onyx key. - * - * @example - * ```ts - * const connection = Onyx.connectWithoutView({ - * key: ONYXKEYS.SESSION, - * callback: onSessionChange, - * }); + * Subscribe to changes for `key`. * - * Onyx.disconnect(connection); - * ``` + * For a collection root key, the callback fires with the entire frozen collection + * snapshot whenever any member changes; signature `(collection, collectionKey)`. + * For any other key, the callback fires with the value at that key; signature + * `(value, key)`. Initial fire is deferred via `scheduleInitialFire` so it reads + * cache after any same-tick writes have applied. * - * @param connection Connection object returned by calling `Onyx.connect()` or `Onyx.connectWithoutView()`. + * Returns synchronously with a `Connection` handle. Disconnecting is idempotent. + */ +function connect(connectOptions: ConnectOptions): Connection { + const {key, callback} = connectOptions; + + let active = true; + let unsubscribeFn: (() => void) | null = null; + + const wireUp = () => { + if (!active) { + return; + } + + if (OnyxKeys.isCollectionKey(key)) { + // Collection-root snapshot mode — listener fires with the whole snapshot per + // collection change. Callback shape is `(snapshot, key)`. Dedup: skip identical + // snapshot refs. Initial fire always delivers the current snapshot (frozen `{}` + // for an empty-but-known collection, `undefined` only if the collection key has + // not been seen yet). + let lastDeliveredSnapshot: unknown = NOT_DELIVERED; + const deliverSnapshot = (rawSnapshot: OnyxValue | undefined, k: TKey) => { + if (Object.is(lastDeliveredSnapshot, rawSnapshot)) { + return; + } + lastDeliveredSnapshot = rawSnapshot; + (callback as CollectionConnectCallback | undefined)?.(rawSnapshot as NonNullable>, k); + }; + unsubscribeFn = onyxStore.subscribe(key, (value, k) => { + deliverSnapshot(value as unknown as OnyxValue, k as TKey); + }); + scheduleInitialFire(() => { + if (!active) { + return; + } + deliverSnapshot(onyxStore.getState(key) as unknown as OnyxValue, key as TKey); + }); + return; + } + + // Non-collection key (or a specific collection member) — single-value subscription. + let lastDelivered: unknown = NOT_DELIVERED; + const deliverValue = (value: OnyxValue, k: TKey | undefined) => { + if (Object.is(lastDelivered, value)) { + return; + } + lastDelivered = value; + (callback as DefaultConnectCallback | undefined)?.(value, k as TKey); + }; + unsubscribeFn = onyxStore.subscribe(key, (value, k) => { + deliverValue(value, k as TKey); + }); + scheduleInitialFire(() => { + if (!active) { + return; + } + deliverValue(onyxStore.getState(key), key); + }); + }; + + OnyxUtils.afterInit(() => { + wireUp(); + return Promise.resolve(); + }); + + return { + unsubscribe: () => { + if (!active) { + return; + } + active = false; + if (unsubscribeFn) { + unsubscribeFn(); + unsubscribeFn = null; + } + }, + }; +} + +/** + * Identical to `connect()` — kept for naming consistency with existing call sites. + */ +function connectWithoutView(connectOptions: ConnectOptions): Connection { + return connect(connectOptions); +} + +/** + * Disconnects a subscription previously returned by `connect()` / `connectWithoutView()`. */ function disconnect(connection: Connection): void { - connectionManager.disconnect(connection); + if (!connection) { + return; + } + connection.unsubscribe(); } /** @@ -157,6 +241,13 @@ function disconnect(connection: Connection): void { * @param options optional configuration object */ function set(key: TKey, value: OnyxSetInput, options?: SetOptions): Promise { + // A value cannot be written directly to a collection key — members live at `${key}`. + // Writing the bare prefix pollutes the collection snapshot (it would surface as a phantom + // member). Warn and no-op; use `setCollection()`/a member key instead. + if (OnyxKeys.isCollectionKey(key)) { + Logger.logAlert(logMessages.collectionKeyWriteAlert(key, 'Onyx.set')); + return Promise.resolve(); + } return OnyxUtils.afterInit(() => OnyxUtils.setWithRetry({key, value, options})); } @@ -168,7 +259,21 @@ function set(key: TKey, value: OnyxSetInput, options * @param data object keyed by ONYXKEYS and the values to set */ function multiSet(data: OnyxMultiSetInput): Promise { - return OnyxUtils.afterInit(() => OnyxUtils.multiSetWithRetry(data)); + // Drop any entries targeting a bare collection key (see `set()` — same anti-pattern). + // Single pass with no allocation on the common path: only clone (once) when an offending + // key is actually present, then delete the offenders from the clone. + let sanitizedData: OnyxMultiSetInput | undefined; + for (const key of Object.keys(data)) { + if (!OnyxKeys.isCollectionKey(key)) { + continue; + } + Logger.logAlert(logMessages.collectionKeyWriteAlert(key, 'Onyx.multiSet')); + if (!sanitizedData) { + sanitizedData = {...data}; + } + delete sanitizedData[key]; + } + return OnyxUtils.afterInit(() => OnyxUtils.multiSetWithRetry(sanitizedData ?? data)); } /** @@ -188,6 +293,12 @@ function multiSet(data: OnyxMultiSetInput): Promise { * Onyx.merge(ONYXKEYS.POLICY, {name: 'My Workspace'}); // -> {id: 1, name: 'My Workspace'} */ function merge(key: TKey, changes: OnyxMergeInput): Promise { + // A value cannot be merged directly into a collection key — see `set()`. Warn and no-op; + // use `mergeCollection()` for collections, or target an individual member key. + if (OnyxKeys.isCollectionKey(key)) { + Logger.logAlert(logMessages.collectionKeyWriteAlert(key, 'Onyx.merge')); + return Promise.resolve(); + } return OnyxUtils.afterInit(() => { const skippableCollectionMemberIDs = OnyxUtils.getSkippableCollectionMemberIDs(); if (skippableCollectionMemberIDs.size) { @@ -284,7 +395,7 @@ function merge(key: TKey, changes: OnyxMergeInput): * @param collection Object collection keyed by individual collection member keys and values */ function mergeCollection(collectionKey: TKey, collection: OnyxMergeCollectionInput): Promise { - return OnyxUtils.afterInit(() => OnyxUtils.mergeCollectionWithPatches({collectionKey, collection, isProcessingCollectionUpdate: true})); + return OnyxUtils.afterInit(() => OnyxUtils.mergeCollectionWithPatches({collectionKey, collection})); } /** @@ -384,17 +495,16 @@ function clear(keysToPreserve: OnyxKey[] = []): Promise { // Remove only the items that we want cleared from storage, and reset others to default for (const key of keysToBeClearedFromStorage) cache.drop(key); return Storage.removeItems(keysToBeClearedFromStorage) - .then(() => connectionManager.refreshSessionID()) .then(() => Storage.multiSet(defaultKeyValuePairs)) .then(() => { DevTools.clearState(keysToPreserve); // Notify the subscribers for each key/value group so they can receive the new values for (const [key, value] of Object.entries(keyValuesToResetIndividually)) { - OnyxUtils.keyChanged(key, value); + OnyxUtils.notifyKey(key, value); } for (const [key, value] of Object.entries(keyValuesToResetAsCollection)) { - OnyxUtils.keysChanged(key, value.newValues, value.oldValues); + OnyxUtils.notifyCollection(key, value.newValues, value.oldValues); } }); }) @@ -525,7 +635,6 @@ function update(data: Array>): Promise, mergeReplaceNullPatches: batchedCollectionUpdates.mergeReplaceNullPatches, - isProcessingCollectionUpdate: true, }), ); } @@ -574,6 +683,7 @@ function setCollection(collectionKey: TKey, coll const Onyx = { METHOD: OnyxUtils.METHOD, + getState, connect, connectWithoutView, disconnect, @@ -589,4 +699,4 @@ const Onyx = { }; export default Onyx; -export type {OnyxUpdate, ConnectOptions, SetOptions}; +export type {OnyxUpdate, ConnectOptions, SetOptions, Connection}; diff --git a/lib/OnyxCache.ts b/lib/OnyxCache.ts index 725dbfd77..fa5ab8048 100644 --- a/lib/OnyxCache.ts +++ b/lib/OnyxCache.ts @@ -409,6 +409,14 @@ class OnyxCache { if (needsPrefixCheck && OnyxKeys.getCollectionKey(key) !== collectionKey) { continue; } + // Never treat the collection root key itself as a member. A direct write to a + // collection key (e.g. `Onyx.set('report_', ...)`, an unsupported anti-pattern) + // lands in storageMap under the prefix key, and `getCollectionKey('report_')` + // returns `'report_'` — which would otherwise match here and surface a phantom + // `{report_: ...}` member. Members live at `report_`, never at the bare prefix. + if (key === collectionKey) { + continue; + } const val = this.storageMap[key]; // Skip null/undefined values — they represent deleted or unset keys // and should not be included in the frozen collection snapshot. @@ -460,12 +468,12 @@ class OnyxCache { const snapshot = this.collectionSnapshots.get(collectionKey); if (utils.isEmptyObject(snapshot)) { - // We check storageKeys.size (not collection-specific keys) to distinguish - // "init complete, this collection is genuinely empty" from "init not done yet." - // During init, setAllKeys loads ALL keys at once — so if any key exists, - // the full storage picture is loaded and an empty collection is truly empty. - // Returning undefined before init prevents subscribers from seeing a false empty state. - if (this.storageKeys.size > 0) { + // Distinguish "init complete, collection genuinely empty" from "init not done yet." + // `setCollectionKeys()` (called inside `Onyx.init`) seeds every known collection + // with a frozen `{}` entry in `collectionSnapshots`, so the presence of the entry + // is a reliable post-init signal — and unlike `storageKeys.size > 0`, it doesn't + // flip back to "not done" after `Onyx.clear()` wipes the storage-keys index. + if (this.collectionSnapshots.has(collectionKey)) { return FROZEN_EMPTY_COLLECTION; } return undefined; diff --git a/lib/OnyxConnectionManager.ts b/lib/OnyxConnectionManager.ts deleted file mode 100644 index 5b0f32d01..000000000 --- a/lib/OnyxConnectionManager.ts +++ /dev/null @@ -1,271 +0,0 @@ -import bindAll from 'lodash/bindAll'; -import * as Logger from './Logger'; -import type {ConnectOptions} from './Onyx'; -import OnyxUtils from './OnyxUtils'; -import OnyxKeys from './OnyxKeys'; -import * as Str from './Str'; -import type {CollectionConnectCallback, DefaultConnectCallback, DefaultConnectOptions, OnyxKey, OnyxValue} from './types'; -import onyxSnapshotCache from './OnyxSnapshotCache'; - -type ConnectCallback = DefaultConnectCallback | CollectionConnectCallback; - -/** - * Represents the connection's metadata that contains the necessary properties - * to handle that connection. - */ -type ConnectionMetadata = { - /** - * The subscription ID returned by `OnyxUtils.subscribeToKey()` that is associated to this connection. - */ - subscriptionID: number; - - /** - * The Onyx key associated to this connection. - */ - onyxKey: OnyxKey; - - /** - * Whether the first connection's callback was fired or not. - */ - isConnectionMade: boolean; - - /** - * A map of the subscriber's callbacks associated to this connection. - */ - callbacks: Map; - - /** - * The last callback value returned by `OnyxUtils.subscribeToKey()`'s callback. - */ - cachedCallbackValue?: OnyxValue; - - /** - * The last callback key returned by `OnyxUtils.subscribeToKey()`'s callback. - */ - cachedCallbackKey?: OnyxKey; - - /** - * The value that triggered the last update - */ - sourceValue?: OnyxValue; - - /** - * Whether the subscriber is waiting for the collection callback to be fired. - */ - waitForCollectionCallback?: boolean; -}; - -/** - * 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. - */ -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: Map; - - /** - * Stores the last generated callback ID which will be incremented when making a new connection. - */ - private lastCallbackID: number; - - /** - * 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: string; - - constructor() { - this.connectionsMap = new Map(); - this.lastCallbackID = 0; - this.sessionID = Str.guid(); - - // Binds all public methods to prevent problems with `this`. - bindAll(this, 'generateConnectionID', 'fireCallbacks', 'connect', 'disconnect', 'disconnectAll', 'refreshSessionID'); - } - - /** - * 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(connectOptions: ConnectOptions): string { - const {key, reuseConnection, waitForCollectionCallback} = connectOptions; - - // The current session ID is appended to the connection ID so we can have different connections - // after an `Onyx.clear()` operation. - let suffix = `,sessionID=${this.sessionID}`; - - // We will generate a unique ID in any of the following situations: - // - `reuseConnection` is `false`. That means the subscriber explicitly wants the connection to not be reused. - // - `key` is a collection key AND `waitForCollectionCallback` is `undefined/false`. This combination needs a new connection at every subscription - // in order to send all the collection entries, so the connection can't be reused. - if (reuseConnection === false || (OnyxKeys.isCollectionKey(key) && (waitForCollectionCallback === undefined || waitForCollectionCallback === false))) { - suffix += `,uniqueID=${Str.guid()}`; - } - - return `onyxKey=${key},waitForCollectionCallback=${waitForCollectionCallback ?? false}${suffix}`; - } - - /** - * Fires all the subscribers callbacks associated with that connection ID. - */ - private fireCallbacks(connectionID: string): void { - const connection = this.connectionsMap.get(connectionID); - if (!connection) { - return; - } - - for (const callback of connection.callbacks.values()) { - if (connection.waitForCollectionCallback) { - (callback as CollectionConnectCallback)(connection.cachedCallbackValue as Record, connection.cachedCallbackKey as OnyxKey, connection.sourceValue); - } else { - (callback as DefaultConnectCallback)(connection.cachedCallbackValue, connection.cachedCallbackKey as OnyxKey); - } - } - } - - /** - * 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(connectOptions: ConnectOptions): Connection { - const connectionID = this.generateConnectionID(connectOptions); - let connectionMetadata = this.connectionsMap.get(connectionID); - let subscriptionID: number | undefined; - - const callbackID = String(this.lastCallbackID++); - - // If there is no connection yet for that connection ID, we create a new one. - if (!connectionMetadata) { - const callback: ConnectCallback = (value, key, sourceValue) => { - const createdConnection = this.connectionsMap.get(connectionID); - if (createdConnection) { - // We signal that the first connection was made and now any new subscribers - // can fire their callbacks immediately with the cached value when connecting. - createdConnection.isConnectionMade = true; - createdConnection.cachedCallbackValue = value; - createdConnection.cachedCallbackKey = key; - createdConnection.sourceValue = sourceValue; - this.fireCallbacks(connectionID); - } - }; - - subscriptionID = OnyxUtils.subscribeToKey({ - ...connectOptions, - callback: callback as DefaultConnectCallback, - }); - - connectionMetadata = { - subscriptionID, - onyxKey: connectOptions.key, - isConnectionMade: false, - callbacks: new Map(), - waitForCollectionCallback: connectOptions.waitForCollectionCallback, - }; - - this.connectionsMap.set(connectionID, connectionMetadata); - } - - // We add the subscriber's callback to the list of callbacks associated with this connection. - if (connectOptions.callback) { - connectionMetadata.callbacks.set(callbackID, connectOptions.callback as ConnectCallback); - } - - // If the first connection is already made we want any new subscribers to receive the cached callback value immediately. - if (connectionMetadata.isConnectionMade) { - // Defer the callback execution to the next tick of the event loop. - // This ensures that the current execution flow completes and the result connection object is available when the callback fires. - Promise.resolve().then(() => { - (connectOptions as DefaultConnectOptions).callback?.(connectionMetadata.cachedCallbackValue, connectionMetadata.cachedCallbackKey as OnyxKey); - }); - } - - return {id: connectionID, callbackID}; - } - - /** - * Disconnects and removes the listener from the Onyx key. - * - * @param connection Connection object returned by calling `connect()`. - */ - disconnect(connection: Connection): void { - if (!connection) { - Logger.logInfo(`[ConnectionManager] Attempted to disconnect passing an undefined connection object.`); - return; - } - - const connectionMetadata = this.connectionsMap.get(connection.id); - if (!connectionMetadata) { - Logger.logInfo(`[ConnectionManager] Attempted to disconnect but no connection was found.`); - return; - } - - // Removes the callback from the connection's callbacks map. - connectionMetadata.callbacks.delete(connection.callbackID); - - // If the connection's callbacks map is empty we can safely unsubscribe from the Onyx key. - if (connectionMetadata.callbacks.size === 0) { - OnyxUtils.unsubscribeFromKey(connectionMetadata.subscriptionID); - - this.connectionsMap.delete(connection.id); - } - } - - /** - * Disconnect all subscribers from Onyx. - */ - disconnectAll(): void { - for (const connectionMetadata of this.connectionsMap.values()) { - OnyxUtils.unsubscribeFromKey(connectionMetadata.subscriptionID); - } - - this.connectionsMap.clear(); - - // Clear snapshot cache when all connections are disconnected - onyxSnapshotCache.clear(); - } - - /** - * Refreshes the connection manager's session ID. - */ - refreshSessionID(): void { - this.sessionID = Str.guid(); - - // Clear snapshot cache when session refreshes to avoid stale cache issues - onyxSnapshotCache.clear(); - } -} - -const connectionManager = new OnyxConnectionManager(); - -export default connectionManager; - -export type {Connection}; diff --git a/lib/OnyxSnapshotCache.ts b/lib/OnyxSnapshotCache.ts deleted file mode 100644 index b1968a2ca..000000000 --- a/lib/OnyxSnapshotCache.ts +++ /dev/null @@ -1,154 +0,0 @@ -import OnyxKeys from './OnyxKeys'; -import type {OnyxKey, OnyxValue} from './types'; -import type {UseOnyxOptions, UseOnyxResult, UseOnyxSelector} from './useOnyx'; - -/** - * Manages snapshot caching for useOnyx hook performance optimization. - * Handles selector function tracking and memoized getSnapshot results. - */ -class OnyxSnapshotCache { - /** - * Snapshot cache is a two-level map. The top-level keys are Onyx keys. The top-level values maps. - * The second-level keys are a custom composite string defined by this.registerConsumer. These represent a unique useOnyx config, which is not fully represented by the Onyx key alone. - * The reason we have two levels is for performance: not to make cache access faster, but to make cache invalidation faster. - * We can invalidate the snapshot cache for a given Onyx key with one map.delete operation on the top-level map, rather than having to loop through a large single-level map and delete any matching keys. - */ - private snapshotCache: Map>>>; - - /** - * Maps selector functions to unique IDs for cache key generation - */ - private selectorIDMap: WeakMap, number>; - - /** - * Counter for generating incremental selector IDs - */ - private selectorIDCounter: number; - - /** - * Reference counting for cache keys to enable automatic cleanup. - * Maps cache key (string) to number of consumers using it. - */ - private cacheKeyRefCounts: Map; - - constructor() { - this.snapshotCache = new Map(); - this.selectorIDMap = new WeakMap(); - this.selectorIDCounter = 0; - this.cacheKeyRefCounts = new Map(); - } - - /** - * Generate unique ID for selector functions using incrementing numbers - */ - getSelectorID(selector: UseOnyxSelector): number { - const typedSelector = selector as unknown as UseOnyxSelector; - if (!this.selectorIDMap.has(typedSelector)) { - const id = this.selectorIDCounter++; - this.selectorIDMap.set(typedSelector, id); - } - return this.selectorIDMap.get(typedSelector)!; - } - - /** - * Register a consumer for a cache key and return the cache key. - * Generates cache key and increments reference counter. - * - * The properties used to generate the cache key are handpicked for performance reasons and - * according to their purpose and effect they produce in the useOnyx hook behavior: - * - * - `selector`: Different selectors produce different results, so each selector needs its own cache entry - * - * Other options like `reuseConnection` don't affect the data transformation - * or timing behavior of getSnapshot, so they're excluded from the cache key for better cache hit rates. - */ - registerConsumer(options: Pick, 'selector'>): string { - const selectorID = options?.selector ? this.getSelectorID(options.selector) : 'no_selector'; - const cacheKey = String(selectorID); - - // Increment reference count for this cache key - const currentCount = this.cacheKeyRefCounts.get(cacheKey) || 0; - this.cacheKeyRefCounts.set(cacheKey, currentCount + 1); - - return cacheKey; - } - - /** - * Deregister a consumer for a cache key. - * Decrements reference counter and removes cache entry if no consumers remain. - */ - deregisterConsumer(key: OnyxKey, cacheKey: string): void { - const currentCount = this.cacheKeyRefCounts.get(cacheKey) || 0; - - if (currentCount <= 1) { - // Last consumer - remove from reference counter and cache - this.cacheKeyRefCounts.delete(cacheKey); - - // Remove from snapshot cache - const keyCache = this.snapshotCache.get(key); - if (keyCache) { - keyCache.delete(cacheKey); - // If this was the last cache entry for this Onyx key, remove the key entirely - if (keyCache.size === 0) { - this.snapshotCache.delete(key); - } - } - } else { - // Still has other consumers - just decrement count - this.cacheKeyRefCounts.set(cacheKey, currentCount - 1); - } - } - - /** - * Get cached snapshot result for a key and cache key combination - */ - getCachedResult>>(key: OnyxKey, cacheKey: string): TResult | undefined { - const keyCache = this.snapshotCache.get(key); - return keyCache?.get(cacheKey) as TResult | undefined; - } - - /** - * Set cached snapshot result for a key and cache key combination - */ - setCachedResult>>(key: OnyxKey, cacheKey: string, result: TResult): void { - if (!this.snapshotCache.has(key)) { - this.snapshotCache.set(key, new Map()); - } - this.snapshotCache.get(key)!.set(cacheKey, result); - } - - /** - * Selective cache invalidation to prevent data unavailability - * Collection members invalidate upward, collections don't cascade downward - */ - invalidateForKey(keyToInvalidate: OnyxKey): void { - // Always invalidate the exact key - this.snapshotCache.delete(keyToInvalidate); - - // Check if the key is a collection member and invalidate the collection base key - const collectionBaseKey = OnyxKeys.getCollectionKey(keyToInvalidate); - if (collectionBaseKey) { - this.snapshotCache.delete(collectionBaseKey); - } - } - - /** - * Clear all snapshot cache - */ - clear(): void { - this.snapshotCache.clear(); - } - - /** - * Clear selector ID mappings (useful for testing) - */ - clearSelectorIds(): void { - this.selectorIDCounter = 0; - } -} - -// Create and export a singleton instance -const onyxSnapshotCache = new OnyxSnapshotCache(); - -export default onyxSnapshotCache; -export {OnyxSnapshotCache}; diff --git a/lib/OnyxStore.ts b/lib/OnyxStore.ts new file mode 100644 index 000000000..b74ccc1dc --- /dev/null +++ b/lib/OnyxStore.ts @@ -0,0 +1,267 @@ +import cache from './OnyxCache'; +import OnyxKeys from './OnyxKeys'; +import * as Logger from './Logger'; +import type {CollectionKeyBase, KeyValueMapping, OnyxCollection, OnyxKey, OnyxValue} from './types'; + +/** + * Listener fired when an exact key's value changes. For collection root keys this is the + * snapshot-mode listener: receives the frozen collection snapshot every time a member changes. + */ +type KeyListener = (value: OnyxValue, key: TKey) => void; + +/** + * Listener fired when any of a state-listener's declared dep keys changes. + */ +type StateListenerCallback = () => void; + +type StateListenerEntry = { + listener: StateListenerCallback; + deps: Set; +}; + +/** + * `OnyxStore` is the listener registry that replaces `OnyxConnectionManager`, + * `OnyxSnapshotCache`, and the subscriber-half of `OnyxUtils`. It owns two + * indexes: + * + * keyListeners — listeners on an exact key (single key, collection root + * in snapshot mode, or a specific collection member). + * stateListeners(ByDep) — listeners that re-evaluate when any of their declared + * deps change. Indexed by dep key for O(1) lookup in notify(). + * + * Write paths call `notifyKey()` (single key write) or `notifyCollection()` + * (batch collection update from `mergeCollection`/`setCollection`/`clear`). + */ +class OnyxStore { + private keyListeners: Map>; + + private stateListeners: Set; + + private stateListenersByDep: Map>; + + constructor() { + this.keyListeners = new Map(); + this.stateListeners = new Set(); + this.stateListenersByDep = new Map(); + } + + /** + * Sync, cache-only read. Returns the frozen collection snapshot for collection + * keys, the cached value for single keys, or `undefined` if not in cache. + */ + getState(key: TKey): OnyxValue { + if (OnyxKeys.isCollectionKey(key)) { + return cache.getCollectionData(key) as OnyxValue; + } + return cache.get(key) as OnyxValue; + } + + /** + * Subscribe to an exact key. For collection root keys this is "snapshot mode" — + * the listener fires with the frozen collection snapshot whenever any member + * changes. For collection member keys or regular keys, the listener fires when + * that specific key's value changes. + * + * Returns an unsubscribe function. + */ + subscribe(key: TKey, listener: KeyListener): () => void { + let listeners = this.keyListeners.get(key); + if (!listeners) { + listeners = new Set(); + this.keyListeners.set(key, listeners); + } + listeners.add(listener as unknown as KeyListener); + return () => { + const set = this.keyListeners.get(key); + if (!set) { + return; + } + set.delete(listener as unknown as KeyListener); + if (set.size === 0) { + this.keyListeners.delete(key); + } + }; + } + + /** + * Subscribe to state-tree changes. The listener fires when any of the declared + * deps changes. Used by `useOnyxState`. + * + * Returns an unsubscribe function. + */ + subscribeState(listener: StateListenerCallback, deps: readonly OnyxKey[]): () => void { + const entry: StateListenerEntry = {listener, deps: new Set(deps)}; + this.stateListeners.add(entry); + for (const dep of entry.deps) { + let set = this.stateListenersByDep.get(dep); + if (!set) { + set = new Set(); + this.stateListenersByDep.set(dep, set); + } + set.add(entry); + } + return () => { + this.stateListeners.delete(entry); + for (const dep of entry.deps) { + const set = this.stateListenersByDep.get(dep); + if (!set) { + continue; + } + set.delete(entry); + if (set.size === 0) { + this.stateListenersByDep.delete(dep); + } + } + }; + } + + /** + * Notify of a single-key write. + * + * Dispatch: + * 1. keyListeners.get(key) — exact-key subscribers (always fires) + * 2. If key is a collection member: keyListeners.get(collectionKey) — snapshot + * subscribers for the parent collection (unless suppressed). + * 3. State listeners whose deps include `key` or its collection key. + * + * `options.suppressCollectionSnapshot` skips step 2 — used by collection-batch + * write paths so each member-write doesn't re-trigger the collection-level + * snapshot listeners; the outer `notifyCollection()` fires those once. + */ + notifyKey(key: TKey, value: OnyxValue, options?: {suppressCollectionSnapshot?: boolean}): void { + // 1. Exact-key listeners + const exact = this.keyListeners.get(key); + if (exact && exact.size > 0) { + for (const listener of exact) { + this.safeInvoke(() => listener(value as OnyxValue, key), key); + } + } + + // 2. Collection-level snapshot routing — only fires when the write is to a member key. + // Direct writes to a collection root (e.g. `Onyx.merge(COLLECTION_KEY, ...)`) are + // an unsupported anti-pattern — treat them as opaque single-key writes. + const collectionKey = OnyxKeys.getCollectionKey(key); + const isCollectionMemberWrite = collectionKey !== undefined && collectionKey !== key; + if (isCollectionMemberWrite && !options?.suppressCollectionSnapshot) { + const snapshotListeners = this.keyListeners.get(collectionKey); + if (snapshotListeners && snapshotListeners.size > 0) { + const snapshot = cache.getCollectionData(collectionKey); + for (const listener of snapshotListeners) { + this.safeInvoke(() => listener(snapshot as OnyxValue, collectionKey), collectionKey); + } + } + } + + // 3. State listeners + const fired = new Set(); + this.fireStateListenersForDep(key, fired); + if (isCollectionMemberWrite) { + this.fireStateListenersForDep(collectionKey, fired); + } + } + + /** + * Notify of a collection-level batch update. Used by `mergeCollection`, + * `setCollection`, and `clear`'s collection path. + * + * Dispatch: + * 1. keyListeners.get(collectionKey) — fires ONCE with the new snapshot. + * 2. keyListeners.get(memberKey) — fires per changed member where the value + * differs from the previous (for ref-equality on unchanged members). + * 3. State listeners affected by the collection key OR any changed member key, + * each fired at most once. + */ + notifyCollection( + collectionKey: TKey, + partialCollection: OnyxCollection, + partialPreviousCollection?: OnyxCollection, + ): void { + const changedKeys = Object.keys(partialCollection ?? {}); + if (changedKeys.length === 0) { + return; + } + const previous = partialPreviousCollection ?? {}; + + // Read the merged snapshot once. `cache.getCollectionData()` returns the post-merge + // frozen object, which is what listeners should see (not the raw `partialCollection` + // input, which is just the delta and lacks fields preserved during merge). + const snapshot = cache.getCollectionData(collectionKey); + + // 1. Snapshot subscribers fire once with the new snapshot. + const snapshotListeners = this.keyListeners.get(collectionKey); + if (snapshotListeners && snapshotListeners.size > 0) { + for (const listener of snapshotListeners) { + this.safeInvoke(() => listener(snapshot as OnyxValue, collectionKey), collectionKey); + } + } + + // 2. Exact-member subscribers fire per changed key (skip if ref unchanged vs previous). + for (const memberKey of changedKeys) { + const value = snapshot?.[memberKey]; + const prev = previous[memberKey]; + if (value === prev) { + continue; + } + const exact = this.keyListeners.get(memberKey); + if (!exact || exact.size === 0) { + continue; + } + for (const listener of exact) { + this.safeInvoke(() => listener(value as OnyxValue, memberKey), memberKey); + } + } + + // 3. State listeners — each affected entry fires at most once. + const fired = new Set(); + this.fireStateListenersForDep(collectionKey, fired); + for (const memberKey of changedKeys) { + this.fireStateListenersForDep(memberKey, fired); + } + } + + /** Wipe all subscriptions. Used by tests and `Onyx.clear()` follow-on. */ + clearAll(): void { + this.keyListeners.clear(); + this.stateListeners.clear(); + this.stateListenersByDep.clear(); + } + + /** True if there are any subscribers for the given key (exact or parent collection). */ + hasListenersForKey(key: OnyxKey): boolean { + if ((this.keyListeners.get(key)?.size ?? 0) > 0) { + return true; + } + const collectionKey = OnyxKeys.getCollectionKey(key); + if (collectionKey && collectionKey !== key && (this.keyListeners.get(collectionKey)?.size ?? 0) > 0) { + return true; + } + return false; + } + + private fireStateListenersForDep(depKey: OnyxKey, alreadyFired: Set): void { + const set = this.stateListenersByDep.get(depKey); + if (!set || set.size === 0) { + return; + } + for (const entry of set) { + if (alreadyFired.has(entry)) { + continue; + } + alreadyFired.add(entry); + this.safeInvoke(entry.listener, depKey); + } + } + + private safeInvoke(fn: () => void, contextKey: OnyxKey): void { + try { + fn(); + } catch (error) { + Logger.logAlert(`[OnyxStore] Listener threw an error for key '${contextKey}': ${error}`); + } + } +} + +const onyxStore = new OnyxStore(); + +export default onyxStore; +export type {KeyListener, StateListenerCallback}; diff --git a/lib/OnyxUtils.ts b/lib/OnyxUtils.ts index cd63e7d6b..75c1e8682 100644 --- a/lib/OnyxUtils.ts +++ b/lib/OnyxUtils.ts @@ -1,4 +1,3 @@ -import {shallowEqual} from 'fast-equals'; import type {ValueOf} from 'type-fest'; import _ from 'underscore'; import DevTools from './DevTools'; @@ -6,16 +5,13 @@ import * as Logger from './Logger'; import type Onyx from './Onyx'; import cache, {TASK} from './OnyxCache'; import OnyxKeys from './OnyxKeys'; +import onyxStore from './OnyxStore'; import * as Str from './Str'; import Storage from './storage'; import type { CollectionKeyBase, - ConnectOptions, DeepRecord, - DefaultConnectCallback, - DefaultConnectOptions, KeyValueMapping, - CallbackToStateMapping, MultiMergeReplaceNullPatches, OnyxCollection, OnyxEntry, @@ -70,23 +66,11 @@ type OnyxMethod = ValueOf; let mergeQueue: Record>> = {}; let mergeQueuePromise: Record> = {}; -// Holds a mapping of all the React components that want their state subscribed to a store key -let callbackToStateMapping: Record> = {}; - -// Holds a mapping of the connected key to the subscriptionID for faster lookups -let onyxKeyToSubscriptionIDs = new Map(); - // Optional user-provided key value states set when Onyx initializes or clears let defaultKeyStates: Record> = {}; -// Used for comparison with a new update to avoid invoking the Onyx.connect callback with the same data. -let lastConnectionCallbackData = new Map; matchedKey: OnyxKey | undefined}>(); - let snapshotKey: OnyxKey | null = null; -// Keeps track of the last subscriptionID that was used so we can keep incrementing it -let lastSubscriptionID = 0; - // Connections can be made before `Onyx.init`. They would wait for this task before resolving const deferredInitTask = createDeferredTask(); @@ -188,10 +172,28 @@ function initStoreValues(keys: DeepRecord, initialKeyStates: Pa return acc; }, new Set()); + // Reject any initial state targeting a bare collection key (e.g. `initialKeyStates: {[COLLECTION.X]: ...}`). + // It's the same anti-pattern as `Onyx.set/merge` on a collection key — a value written to the bare prefix + // pollutes the collection snapshot as a phantom member. Warn and strip it; member defaults belong on + // `${COLLECTION.X}` keys. Filtered against the locally-computed collection key set (no dependency on + // OnyxKeys init ordering), single pass, cloning only when an offending key is actually present. + let sanitizedInitialKeyStates: Partial | undefined; + for (const key of Object.keys(initialKeyStates)) { + if (!collectionKeySet.has(key)) { + continue; + } + Logger.logAlert(logMessages.collectionKeyWriteAlert(key, 'Onyx.init initialKeyStates')); + if (!sanitizedInitialKeyStates) { + sanitizedInitialKeyStates = {...initialKeyStates}; + } + delete sanitizedInitialKeyStates[key]; + } + const resolvedInitialKeyStates = sanitizedInitialKeyStates ?? initialKeyStates; + // Set our default key states to use when initializing and clearing Onyx data - defaultKeyStates = initialKeyStates; + defaultKeyStates = resolvedInitialKeyStates; - DevTools.initState(initialKeyStates); + DevTools.initState(resolvedInitialKeyStates); // Let Onyx know about which keys are safe to evict cache.setEvictionAllowList(evictableKeys); @@ -412,35 +414,6 @@ function tupleGet(keys: Keys): Promise<{[Index return Promise.all(keys.map((key) => get(key))) as Promise<{[Index in keyof Keys]: OnyxValue}>; } -/** - * Stores a subscription ID associated with a given key. - * - * @param subscriptionID - A subscription ID of the subscriber. - * @param key - A key that the subscriber is subscribed to. - */ -function storeKeyBySubscriptions(key: OnyxKey, subscriptionID: number) { - if (!onyxKeyToSubscriptionIDs.has(key)) { - onyxKeyToSubscriptionIDs.set(key, []); - } - onyxKeyToSubscriptionIDs.get(key).push(subscriptionID); -} - -/** - * Deletes a subscription ID associated with its corresponding key. - * - * @param subscriptionID - The subscription ID to be deleted. - */ -function deleteKeyBySubscriptions(subscriptionID: number) { - const subscriber = callbackToStateMapping[subscriptionID]; - - if (subscriber && onyxKeyToSubscriptionIDs.has(subscriber.key)) { - const updatedSubscriptionsIDs = onyxKeyToSubscriptionIDs.get(subscriber.key).filter((id: number) => id !== subscriptionID); - onyxKeyToSubscriptionIDs.set(subscriber.key, updatedSubscriptionsIDs); - } - - lastConnectionCallbackData.delete(subscriptionID); -} - /** Returns current key names stored in persisted storage */ function getAllKeys(): Promise> { // When we've already read stored keys, resolve right away @@ -539,231 +512,56 @@ function getCachedCollection(collectionKey: TKey } /** - * When a collection of keys change, search for any callbacks matching the collection key and trigger those callbacks - */ -function keysChanged( - collectionKey: TKey, - partialCollection: OnyxCollection, - partialPreviousCollection: OnyxCollection | undefined, -): void { - const cachedCollection = getCachedCollection(collectionKey); - const previousCollection = partialPreviousCollection ?? {}; - const changedMemberKeys = Object.keys(partialCollection ?? {}); - - // Add or remove the keys from the recentlyAccessedKeys list - for (const memberKey of changedMemberKeys) { - const value = partialCollection?.[memberKey]; - if (value !== null && value !== undefined) { - cache.addLastAccessedKey(memberKey, false); - } else { - cache.removeLastAccessedKey(memberKey); - } - } - - // Use indexed lookup instead of scanning all subscribers. - // We need subscribers for: (1) the collection key itself, and (2) individual changed member keys. - const collectionSubscriberIDs = onyxKeyToSubscriptionIDs.get(collectionKey) ?? []; - const memberSubscriberIDs: number[] = []; - for (const memberKey of changedMemberKeys) { - const ids = onyxKeyToSubscriptionIDs.get(memberKey); - if (ids) { - for (const id of ids) { - memberSubscriberIDs.push(id); - } - } - } - - // Notify collection-level subscribers - for (const subID of collectionSubscriberIDs) { - const subscriber = callbackToStateMapping[subID]; - if (!subscriber || typeof subscriber.callback !== 'function') { - continue; - } - - 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 as DefaultConnectCallback; - currentSubscriberCallback(cachedCollection[dataKey], dataKey as TKey); - } - } catch (error) { - Logger.logAlert(`[OnyxUtils.keysChanged] Subscriber callback threw an error for key '${collectionKey}': ${error}`); - } - } - - // Notify member-level subscribers (e.g. subscribed to `report_123`) - for (const subID of memberSubscriberIDs) { - const subscriber = callbackToStateMapping[subID]; - if (!subscriber || typeof subscriber.callback !== 'function') { - continue; - } - - if (cachedCollection[subscriber.key] === previousCollection[subscriber.key]) { - continue; - } - - try { - const subscriberCallback = subscriber.callback as DefaultConnectCallback; - subscriberCallback(cachedCollection[subscriber.key], subscriber.key as TKey); - 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}`); - } - } -} - -/** - * When a key change happens, search for any callbacks matching the key or collection key and trigger those callbacks + * Notify subscribers of a single-key write. Wrapper over `onyxStore.notifyKey()` + * that also performs LRU bookkeeping for eviction. Write paths call this instead + * of touching the subscriber registry directly. + * + * Pass `suppressCollectionSnapshot: true` when notifying within a collection-batch + * operation — the outer `notifyCollection()` fires snapshot listeners once, so + * each per-key fire shouldn't re-trigger them. */ -function keyChanged( - key: TKey, - value: OnyxValue, - canUpdateSubscriber: (subscriber?: CallbackToStateMapping) => boolean = () => true, - isProcessingCollectionUpdate = false, -): void { - // Add or remove this key from the recentlyAccessedKeys list +function notifyKey(key: TKey, value: OnyxValue, options?: {suppressCollectionSnapshot?: boolean}): void { if (value !== null && value !== undefined) { cache.addLastAccessedKey(key, OnyxKeys.isCollectionKey(key)); } else { cache.removeLastAccessedKey(key); } - - // We get the subscribers interested in the key that has just changed. If the subscriber's key is a collection key then we will - // notify them if the key that changed is a collection member. Or if it is a regular key notify them when there is an exact match. - // Given the amount of times this function is called we need to make sure we are not iterating over all subscribers every time. On the other hand, we don't need to - // do the same in keysChanged, because we only call that function when a collection key changes, and it doesn't happen that often. - // For performance reason, we look for the given key and later if don't find it we look for the collection key, instead of checking if it is a collection key first. - let stateMappingKeys = onyxKeyToSubscriptionIDs.get(key) ?? []; - const collectionKey = OnyxKeys.getCollectionKey(key); - - if (collectionKey) { - // Getting the collection key from the specific key because only collection keys were stored in the mapping. - stateMappingKeys = [...stateMappingKeys, ...(onyxKeyToSubscriptionIDs.get(collectionKey) ?? [])]; - if (stateMappingKeys.length === 0) { - return; - } - } - - // Cache the collection snapshot per dispatch so all subscribers to the same collection - // see a consistent view, even if an earlier subscriber's callback synchronously writes - // to the same collection. - const cachedCollections: Record> = {}; - - for (const stateMappingKey of stateMappingKeys) { - const subscriber = callbackToStateMapping[stateMappingKey]; - if (!subscriber || !OnyxKeys.isKeyMatch(subscriber.key, key) || !canUpdateSubscriber(subscriber)) { - continue; - } - - // Subscriber is a regular call to connect() and provided a callback - if (typeof subscriber.callback === 'function') { - try { - const lastData = lastConnectionCallbackData.get(subscriber.subscriptionID); - if (lastData && lastData.matchedKey === key && lastData.value === value) { - continue; - } - - if (OnyxKeys.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 (isProcessingCollectionUpdate) { - continue; - } - // Cache once per dispatch to ensure all subscribers see a consistent snapshot - // even if a previous callback synchronously wrote to the same collection. - let cachedCollection = cachedCollections[subscriber.key]; - if (!cachedCollection) { - cachedCollection = getCachedCollection(subscriber.key); - cachedCollections[subscriber.key] = cachedCollection; - } - lastConnectionCallbackData.set(subscriber.subscriptionID, {value: cachedCollection, matchedKey: subscriber.key}); - subscriber.callback(cachedCollection, subscriber.key, {[key]: value}); - continue; - } - - const subscriberCallback = subscriber.callback as DefaultConnectCallback; - subscriberCallback(value, key); - - lastConnectionCallbackData.set(subscriber.subscriptionID, {value, matchedKey: key}); - continue; - } catch (error) { - Logger.logAlert(`[OnyxUtils.keyChanged] Subscriber callback threw an error for key '${key}': ${error}`); - } - - continue; - } - - console.error('Warning: Found a matching subscriber to a key that changed, but no callback could be found.'); - } + onyxStore.notifyKey(key, value, options); } /** - * Sends the data obtained from the keys to the connection. + * Notify subscribers of a batch collection update. Wrapper over + * `onyxStore.notifyCollection()` that also performs LRU bookkeeping per + * changed member. */ -function sendDataToConnection(mapping: CallbackToStateMapping, matchedKey: TKey | undefined): void { - // 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 individual key subscribers, read just that key's value. - let value: OnyxValue | undefined; - if (OnyxKeys.isCollectionKey(mapping.key) && mapping.waitForCollectionCallback) { - const collection = getCachedCollection(mapping.key); - value = Object.keys(collection).length > 0 ? (collection as OnyxValue) : undefined; - } else { - value = cache.get(matchedKey ?? mapping.key) as OnyxValue; - } - - // For regular callbacks, we never want to pass null values, but always just undefined if a value is not set in cache or storage. - value = value === null ? undefined : value; - const lastData = lastConnectionCallbackData.get(mapping.subscriptionID); - - // If the value has not changed for the same key we do not need to trigger the callback. - // We compare matchedKey to avoid suppressing callbacks for different collection members - // that happen to have shallow-equal values (e.g. during hydration racing with set()). - if (lastData && lastData.matchedKey === matchedKey && shallowEqual(lastData.value, value)) { - return; +function notifyCollection( + collectionKey: TKey, + partialCollection: OnyxCollection, + partialPreviousCollection?: OnyxCollection, +): void { + const changedKeys = Object.keys(partialCollection ?? {}); + for (const memberKey of changedKeys) { + const value = partialCollection?.[memberKey]; + if (value !== null && value !== undefined) { + cache.addLastAccessedKey(memberKey, false); + } else { + cache.removeLastAccessedKey(memberKey); + } } - - (mapping as DefaultConnectOptions).callback?.(value, matchedKey as TKey); -} - -/** - * Gets the data for a given an array of matching keys, combines them into an object, and sends the result back to the subscriber. - */ -function getCollectionDataAndSendAsObject(matchingKeys: CollectionKeyBase[], mapping: CallbackToStateMapping): void { - multiGet(matchingKeys).then(() => { - sendDataToConnection(mapping, mapping.key); - }); + onyxStore.notifyCollection(collectionKey, partialCollection, partialPreviousCollection); } /** - * Remove a key from Onyx and update the subscribers + * Remove a key from Onyx and update the subscribers. + * + * `suppressCollectionSnapshot` skips the collection-level snapshot fire — used by + * `prepareKeyValuePairsForStorage()` when called inside a collection-batch operation + * (setCollection/mergeCollection/partialSetCollection/multiSet's collection batch), + * because the outer `notifyCollection()` fires snapshot listeners once. */ -function remove(key: TKey, isProcessingCollectionUpdate?: boolean): Promise { +function remove(key: TKey, options?: {suppressCollectionSnapshot?: boolean}): Promise { cache.drop(key); - keyChanged(key, undefined as OnyxValue, undefined, isProcessingCollectionUpdate); + notifyKey(key, undefined as OnyxValue, options); if (OnyxKeys.isRamOnlyKey(key)) { return Promise.resolve(); @@ -840,7 +638,7 @@ function broadcastUpdate(key: TKey, value: OnyxValue } cache.set(key, value); - keyChanged(key, value); + notifyKey(key, value); } function hasPendingMergeForKey(key: OnyxKey): boolean { @@ -864,7 +662,10 @@ function prepareKeyValuePairsForStorage( for (const [key, value] of Object.entries(data)) { if (value === null) { - remove(key, isProcessingCollectionUpdate); + // Within a collection batch, the outer notifyCollection() will fire snapshot + // listeners once with the final state — so each per-key remove should not + // re-fire the snapshot listener (which would cause N+1 callback invocations). + remove(key, {suppressCollectionSnapshot: !!isProcessingCollectionUpdate}); continue; } @@ -998,7 +799,7 @@ function initializeWithDefaultKeyStates(): Promise { // Notify subscribers about default key states so that any subscriber that connected // before init (e.g. during module load) receives the merged default values immediately for (const [key, value] of Object.entries(merged ?? {})) { - keyChanged(key, value); + notifyKey(key, value); } }) .catch((error) => { @@ -1016,7 +817,7 @@ function initializeWithDefaultKeyStates(): Promise { // Notify subscribers about default key states so that any subscriber that connected // before init (e.g. during module load) receives the merged default values immediately for (const [key, value] of Object.entries(defaultKeyStates)) { - keyChanged(key, value); + notifyKey(key, value); } }); } @@ -1049,119 +850,6 @@ function doAllCollectionItemsBelongToSameParent( return !hasCollectionKeyCheckFailed; } -/** - * Subscribes to an Onyx key and listens to its changes. - * - * @param connectOptions The options object that will define the behavior of the connection. - * @returns The subscription ID to use when calling `OnyxUtils.unsubscribeFromKey()`. - */ -function subscribeToKey(connectOptions: ConnectOptions): number { - const mapping = connectOptions as CallbackToStateMapping; - const subscriptionID = lastSubscriptionID++; - callbackToStateMapping[subscriptionID] = mapping as CallbackToStateMapping; - callbackToStateMapping[subscriptionID].subscriptionID = subscriptionID; - - // When keyChanged is called, a key is passed and the method looks through all the Subscribers in callbackToStateMapping for the matching key to get the subscriptionID - // to avoid having to loop through all the Subscribers all the time (even when just one connection belongs to one key), - // We create a mapping from key to lists of subscriptionIDs to access the specific list of subscriptionIDs. - storeKeyBySubscriptions(mapping.key, callbackToStateMapping[subscriptionID].subscriptionID); - - // Commit connection only after init passes - deferredInitTask.promise - // This first .then() adds a microtask tick for compatibility reasons and - // to ensure subscribers don't receive an extra initial callback before Onyx.update() data arrives. - .then(() => undefined) - .then(() => { - // Performance improvement - // If the mapping is connected to an onyx key that is not a collection - // we can skip the call to getAllKeys() and return an array with a single item - if (!!mapping.key && typeof mapping.key === 'string' && !OnyxKeys.isCollectionKey(mapping.key) && cache.getAllKeys().has(mapping.key)) { - return new Set([mapping.key]); - } - return getAllKeys(); - }) - .then((keys) => { - // We search all the keys in storage to see if any are a "match" for the subscriber we are connecting so that we - // can send data back to the subscriber. Note that multiple keys can match as a subscriber could either be - // subscribed to a "collection key" or a single key. - const matchingKeys: string[] = []; - - // Performance optimization: For single key subscriptions, avoid O(n) iteration - if (!OnyxKeys.isCollectionKey(mapping.key)) { - if (keys.has(mapping.key)) { - matchingKeys.push(mapping.key); - } - } else { - // Collection case - need to iterate through all keys to find matches (O(n)) - for (const key of keys) { - if (!OnyxKeys.isKeyMatch(mapping.key, key)) { - continue; - } - matchingKeys.push(key); - } - } - // If the key being connected to does not exist we initialize the value with null. For subscribers that connected - // directly via connect() they will simply get a null value sent to them without any information about which key matched - // since there are none matched. - if (matchingKeys.length === 0) { - if (mapping.key) { - cache.addNullishStorageKey(mapping.key); - } - - const matchedKey = OnyxKeys.isCollectionKey(mapping.key) && mapping.waitForCollectionCallback ? 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. - if (typeof mapping.callback === 'function') { - if (OnyxKeys.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 as TKey); - } - }); - return; - } - - // If we are not subscribed to a collection key then there's only a single key to send an update for. - get(mapping.key).then(() => sendDataToConnection(mapping, mapping.key)); - return; - } - - console.error('Warning: Onyx.connect() was found without a callback'); - }); - - // The subscriptionID is returned back to the caller so that it can be used to clean up the connection when it's no longer needed - // by calling OnyxUtils.unsubscribeFromKey(subscriptionID). - return subscriptionID; -} - -/** - * Disconnects and removes the listener from the Onyx key. - * - * @param subscriptionID Subscription ID returned by calling `OnyxUtils.subscribeToKey()`. - */ -function unsubscribeFromKey(subscriptionID: number): void { - if (!callbackToStateMapping[subscriptionID]) { - return; - } - - deleteKeyBySubscriptions(subscriptionID); - delete callbackToStateMapping[subscriptionID]; -} - function updateSnapshots(data: Array>, mergeFn: typeof Onyx.merge): Array<() => Promise> { const snapshotCollectionKey = getSnapshotKey(); if (!snapshotCollectionKey) return []; @@ -1349,9 +1037,9 @@ function multiSetWithRetry(data: OnyxMultiSetInput, retryAttempt?: number): Prom const keyValuePairsToSet = OnyxUtils.prepareKeyValuePairsForStorage(newData, true); // Group collection members by their parent collection key so each collection can be notified - // via a single batched keysChanged() call instead of one keyChanged() per member. For each + // via a single batched notifyCollection() call instead of one notifyKey() per member. For each // collection, `partial` holds the new values being set and `previous` holds the cached values - // from before the set, which keysChanged() uses to skip subscribers whose value didn't change. + // from before the set, which notifyCollection() uses to skip subscribers whose value didn't change. const collectionBatches = new Map>; previous: Record>}>(); for (const [key, value] of keyValuePairsToSet) { @@ -1363,7 +1051,7 @@ function multiSetWithRetry(data: OnyxMultiSetInput, retryAttempt?: number): Prom const collectionKey = OnyxKeys.getCollectionKey(key); if (collectionKey && OnyxKeys.isCollectionMemberKey(collectionKey, key)) { - // Capture the previous cached value BEFORE calling cache.set() so keysChanged() + // Capture the previous cached value BEFORE calling cache.set() so notifyCollection() // can diff old vs new per-member. const previousValue = cache.get(key); cache.set(key, value); @@ -1376,18 +1064,18 @@ function multiSetWithRetry(data: OnyxMultiSetInput, retryAttempt?: number): Prom batch.partial[key] = value; batch.previous[key] = previousValue; } else { - // Non-collection keys are notified inline (cache.set + keyChanged in iteration order) + // Non-collection keys are notified inline (cache.set + notifyKey in iteration order) // so re-entrant callbacks (e.g. Onyx.set inside a callback) see consistent cache // and subscriber state, matching the original per-key notification semantics. cache.set(key, value); - keyChanged(key, value); + notifyKey(key, value); } } - // One keysChanged() per collection — fires each collection-level subscriber once and lets - // keysChanged() internally decide which individual member subscribers need notification. + // One notifyCollection() per collection — fires each collection-level subscriber once and lets + // notifyCollection() internally decide which individual member subscribers need notification. for (const [collectionKey, batch] of collectionBatches) { - keysChanged(collectionKey as CollectionKeyBase, batch.partial, batch.previous); + notifyCollection(collectionKey as CollectionKeyBase, batch.partial, batch.previous); } const keyValuePairsToStore = keyValuePairsToSet.filter((keyValuePair) => { @@ -1461,7 +1149,7 @@ function setCollectionWithRetry({collectionKey, for (const [key, value] of keyValuePairs) cache.set(key, value); - keysChanged(collectionKey, mutableCollection, previousCollection); + notifyCollection(collectionKey, mutableCollection, previousCollection); // RAM-only keys are not supposed to be saved to storage if (OnyxKeys.isRamOnlyKey(collectionKey)) { @@ -1487,11 +1175,10 @@ function setCollectionWithRetry({collectionKey, * @param params.collection Object collection keyed by individual collection member keys and values * @param params.mergeReplaceNullPatches Record where the key is a collection member key and the value is a list of * tuples that we'll use to replace the nested objects of that collection member record with something else. - * @param params.isProcessingCollectionUpdate whether this is part of a collection update operation. * @param retryAttempt retry attempt */ function mergeCollectionWithPatches( - {collectionKey, collection, mergeReplaceNullPatches, isProcessingCollectionUpdate = false}: MergeCollectionWithPatchesParams, + {collectionKey, collection, mergeReplaceNullPatches}: MergeCollectionWithPatchesParams, retryAttempt?: number, ): Promise { if (!isValidNonEmptyCollectionForMerge(collection)) { @@ -1530,7 +1217,8 @@ function mergeCollectionWithPatches( // Split to keys that exist in storage and keys that don't const keys = resultCollectionKeys.filter((key) => { if (resultCollection[key] === null) { - remove(key, isProcessingCollectionUpdate); + // Suppress collection-snapshot fire — outer notifyCollection() handles it. + remove(key, {suppressCollectionSnapshot: true}); return false; } return true; @@ -1573,11 +1261,11 @@ function mergeCollectionWithPatches( // When (multi-)merging the values with the existing values in storage, // we don't want to remove nested null values from the data that we pass to the storage layer, // because the storage layer uses them to remove nested keys from storage natively. - const keyValuePairsForExistingCollection = prepareKeyValuePairsForStorage(existingKeyCollection, false, mergeReplaceNullPatches); + const keyValuePairsForExistingCollection = prepareKeyValuePairsForStorage(existingKeyCollection, false, mergeReplaceNullPatches, true); // We can safely remove nested null values when using (multi-)set, // because we will simply overwrite the existing values in storage. - const keyValuePairsForNewCollection = prepareKeyValuePairsForStorage(newCollection, true); + const keyValuePairsForNewCollection = prepareKeyValuePairsForStorage(newCollection, true, undefined, true); const promises = []; @@ -1604,7 +1292,7 @@ function mergeCollectionWithPatches( // and update all subscribers const promiseUpdate = previousCollectionPromise.then((previousCollection) => { cache.merge(finalMergedCollection); - keysChanged(collectionKey, finalMergedCollection, previousCollection); + notifyCollection(collectionKey, finalMergedCollection, previousCollection); }); return Promise.all(promises) @@ -1612,7 +1300,7 @@ function mergeCollectionWithPatches( retryOperation( error, mergeCollectionWithPatches, - {collectionKey, collection: resultCollection as OnyxMergeCollectionInput, mergeReplaceNullPatches, isProcessingCollectionUpdate}, + {collectionKey, collection: resultCollection as OnyxMergeCollectionInput, mergeReplaceNullPatches}, retryAttempt, ), ) @@ -1670,7 +1358,7 @@ function partialSetCollection({collectionKey, co for (const [key, value] of keyValuePairs) cache.set(key, value); - keysChanged(collectionKey, mutableCollection, previousCollection); + notifyCollection(collectionKey, mutableCollection, previousCollection); if (OnyxKeys.isRamOnlyKey(collectionKey)) { sendActionToDevTools(METHOD.SET_COLLECTION, undefined, mutableCollection); @@ -1699,9 +1387,6 @@ function logKeyRemoved(onyxMethod: Extract, key: On function clearOnyxUtilsInternals() { mergeQueue = {}; mergeQueuePromise = {}; - callbackToStateMapping = {}; - onyxKeyToSubscriptionIDs = new Map(); - lastConnectionCallbackData = new Map(); } const OnyxUtils = { @@ -1717,10 +1402,8 @@ const OnyxUtils = { getAllKeys, tryGetCachedValue, getCachedCollection, - keysChanged, - keyChanged, - sendDataToConnection, - getCollectionDataAndSendAsObject, + notifyKey, + notifyCollection, remove, reportStorageQuota, retryOperation, @@ -1735,14 +1418,10 @@ const OnyxUtils = { tupleGet, isValidNonEmptyCollectionForMerge, doAllCollectionItemsBelongToSameParent, - subscribeToKey, - unsubscribeFromKey, getSkippableCollectionMemberIDs, setSkippableCollectionMemberIDs, getSnapshotMergeKeys, setSnapshotMergeKeys, - storeKeyBySubscriptions, - deleteKeyBySubscriptions, reduceCollectionWithSelector, updateSnapshots, mergeCollectionWithPatches, diff --git a/lib/createMemoizedSelector.ts b/lib/createMemoizedSelector.ts new file mode 100644 index 000000000..3dbdafbff --- /dev/null +++ b/lib/createMemoizedSelector.ts @@ -0,0 +1,38 @@ +import {deepEqual} from 'fast-equals'; + +/** + * Wraps a selector function so that: + * - Calling the wrapper with the same input reference twice short-circuits to the cached output + * (cheap `===` check, no recompute). + * - Calling with a different input that produces a deep-equal output returns the *previous* + * output reference, so downstream `===` comparisons treat it as unchanged. + * + * This is the minimum needed for `useSyncExternalStore` to not loop when consumers pass + * inline selectors that allocate fresh objects on every call (e.g. `(e) => ({id: e?.id})`): + * without the deep-equal fallback, every `getSnapshot` would return a new reference and React + * would re-render (or throw "getSnapshot should be cached") indefinitely. + * + * Stateful by design — each call to `createMemoizedSelector` produces an independent wrapper + * with its own `lastInput`/`lastOutput` cache, so a wrapper must not be shared across + * subscriptions that can see different inputs. + */ +function createMemoizedSelector(selector: (input: TInput) => TOutput): (input: TInput) => TOutput { + let lastInput: TInput; + let lastOutput: TOutput; + let hasComputed = false; + + return (input) => { + if (hasComputed && lastInput === input) { + return lastOutput; + } + const next = selector(input); + lastInput = input; + if (!hasComputed || !deepEqual(lastOutput, next)) { + lastOutput = next; + hasComputed = true; + } + return lastOutput; + }; +} + +export default createMemoizedSelector; diff --git a/lib/index.ts b/lib/index.ts index bb6df0e0c..df5bae723 100644 --- a/lib/index.ts +++ b/lib/index.ts @@ -1,4 +1,4 @@ -import type {ConnectOptions, OnyxUpdate} from './Onyx'; +import type {Connection, ConnectOptions, OnyxUpdate} from './Onyx'; import Onyx from './Onyx'; import type { CustomTypeOptions, @@ -19,12 +19,13 @@ import type { OnyxSetCollectionInput, } from './types'; import type {FetchStatus, ResultMetadata, UseOnyxResult, UseOnyxOptions} from './useOnyx'; -import type {Connection} from './OnyxConnectionManager'; import useOnyx from './useOnyx'; +import useOnyxState from './useOnyxState'; +import type {OnyxStateView, UseOnyxStateOptions} from './useOnyxState'; import type {OnyxSQLiteKeyValuePair} from './storage/providers/SQLiteProvider'; export default Onyx; -export {useOnyx}; +export {useOnyx, useOnyxState}; export type { ConnectOptions, CustomTypeOptions, @@ -44,10 +45,12 @@ export type { OnyxSetCollectionInput, OnyxUpdate, OnyxValue, + OnyxStateView, ResultMetadata, Selector, UseOnyxResult, Connection, UseOnyxOptions, + UseOnyxStateOptions, OnyxSQLiteKeyValuePair, }; diff --git a/lib/logMessages.ts b/lib/logMessages.ts index 5a4b84d6d..6c877c4f9 100644 --- a/lib/logMessages.ts +++ b/lib/logMessages.ts @@ -1,6 +1,9 @@ const logMessages = { incompatibleUpdateAlert: (key: string, operation: string, existingValueType?: string, newValueType?: string) => `Warning: Trying to apply "${operation}" with ${newValueType ?? 'unknown'} type to ${existingValueType ?? 'unknown'} type in the key "${key}"`, + collectionKeyWriteAlert: (key: string, operation: string) => + `Warning: "${operation}" was called with the collection key "${key}". A value cannot be written to a collection key directly — collection members live at "${key}". ` + + `Use Onyx.mergeCollection()/Onyx.setCollection() for collections, or target an individual member key. This operation was skipped.`, }; export default logMessages; diff --git a/lib/types.ts b/lib/types.ts index 039130df9..a8b273475 100644 --- a/lib/types.ts +++ b/lib/types.ts @@ -223,50 +223,28 @@ type BaseConnectOptions = { type DefaultConnectCallback = (value: OnyxEntry, key: TKey) => void; /** Represents the callback function used in `Onyx.connect()` method with a collection key. */ -type CollectionConnectCallback = (value: NonUndefined>, key: TKey, sourceValue?: OnyxValue) => void; - -/** Represents the options used in `Onyx.connect()` method with a regular key. */ -// NOTE: Any changes to this type like adding or removing options must be accounted in OnyxConnectionManager's `generateConnectionID()` method! -type DefaultConnectOptions = BaseConnectOptions & { - /** The Onyx key to subscribe to. */ - key: TKey; - - /** A function that will be called when the Onyx data we are subscribed changes. */ - callback?: DefaultConnectCallback; - - /** If set to `true`, it will return the entire collection to the callback as a single object. */ - waitForCollectionCallback?: false; -}; - -/** Represents the options used in `Onyx.connect()` method with a collection key. */ -// NOTE: Any changes to this type like adding or removing options must be accounted in OnyxConnectionManager's `generateConnectionID()` method! -type CollectionConnectOptions = BaseConnectOptions & { - /** The Onyx key to subscribe to. */ - key: TKey extends CollectionKeyBase ? TKey : never; - - /** A function that will be called when the Onyx data we are subscribed changes. */ - callback?: CollectionConnectCallback; - - /** If set to `true`, it will return the entire collection to the callback as a single object. */ - waitForCollectionCallback: true; -}; +type CollectionConnectCallback = (value: NonUndefined>, key: TKey) => void; /** * Represents the options used in `Onyx.connect()` method. - * The type is built from `DefaultConnectOptions`/`CollectionConnectOptions` depending on the `waitForCollectionCallback` property. - * It includes two different forms, depending on whether we are waiting for a collection callback or not. * - * If `waitForCollectionCallback` is `true`, it expects `key` to be a Onyx collection key and `callback` will be triggered with the whole collection - * and will pass `value` as an `OnyxCollection`. + * For a collection root key (e.g. `ONYXKEYS.COLLECTION.REPORT`), the callback fires + * with the entire collection snapshot whenever any member changes (signature + * `(collection, key)`). For any other key, the callback fires with the value at + * that key (signature `(value, key)`). * - * If `waitForCollectionCallback` is `false` or not specified, the `key` can be any Onyx key and `callback` will be triggered with updates of each collection item - * and will pass `value` as an `OnyxEntry`. + * The legacy `waitForCollectionCallback` flag has been removed — collection-root + * subscriptions always deliver snapshots. Per-member dispatch (the old default) + * is no longer supported; consumers that need per-member processing should + * subscribe to the snapshot and diff against the previous value (structural + * sharing makes the per-member ref-check O(1)). */ -// NOTE: Any changes to this type like adding or removing options must be accounted in OnyxConnectionManager's `generateConnectionID()` method! -type ConnectOptions = DefaultConnectOptions | CollectionConnectOptions; +type ConnectOptions = BaseConnectOptions & { + /** The Onyx key to subscribe to. */ + key: TKey; -type CallbackToStateMapping = ConnectOptions & { - subscriptionID: number; + /** A function that will be called when the Onyx data we are subscribed changes. */ + callback?: TKey extends CollectionKeyBase ? CollectionConnectCallback : DefaultConnectCallback; }; /** @@ -365,7 +343,6 @@ type MergeCollectionWithPatchesParams = { collectionKey: TKey; collection: OnyxMergeCollectionInput; mergeReplaceNullPatches?: MultiMergeReplaceNullPatches; - isProcessingCollectionUpdate?: boolean; }; type RetriableOnyxOperation = @@ -448,20 +425,17 @@ export type { BaseConnectOptions, Collection, CollectionConnectCallback, - CollectionConnectOptions, CollectionKey, CollectionKeyBase, ConnectOptions, CustomTypeOptions, DeepRecord, DefaultConnectCallback, - DefaultConnectOptions, ExtractOnyxCollectionValue, GenericFunction, InitOptions, Key, KeyValueMapping, - CallbackToStateMapping, NonNull, NonUndefined, OnyxInputKeyValueMapping, diff --git a/lib/useLiveRef.ts b/lib/useLiveRef.ts deleted file mode 100644 index 869f439db..000000000 --- a/lib/useLiveRef.ts +++ /dev/null @@ -1,17 +0,0 @@ -import {useRef} from 'react'; - -/** - * Creates a mutable reference to a value, useful when you need to - * maintain a reference to a value that may change over time without triggering re-renders. - * - * @deprecated This hook breaks the Rules of React, and should not be used. - * The migration effort to remove it safely is not currently planned. - */ -function useLiveRef(value: T) { - const ref = useRef(value); - ref.current = value; - - return ref; -} - -export default useLiveRef; diff --git a/lib/useOnyx.ts b/lib/useOnyx.ts index a5efba5a8..5a61d40fd 100644 --- a/lib/useOnyx.ts +++ b/lib/useOnyx.ts @@ -1,304 +1,78 @@ -import {deepEqual, shallowEqual} from 'fast-equals'; -import {useCallback, useEffect, useMemo, useRef, useSyncExternalStore} from 'react'; -import type {DependencyList} from 'react'; -import OnyxCache, {TASK} from './OnyxCache'; -import type {Connection} from './OnyxConnectionManager'; -import connectionManager from './OnyxConnectionManager'; -import OnyxUtils from './OnyxUtils'; -import OnyxKeys from './OnyxKeys'; -import type {CollectionKeyBase, OnyxKey, OnyxValue} from './types'; -import onyxSnapshotCache from './OnyxSnapshotCache'; -import useLiveRef from './useLiveRef'; +import {useCallback, useMemo, useRef, useSyncExternalStore} from 'react'; +import createMemoizedSelector from './createMemoizedSelector'; +import onyxStore from './OnyxStore'; +import type {OnyxKey, OnyxValue} from './types'; type UseOnyxSelector> = (data: OnyxValue | undefined) => TReturnValue; type UseOnyxOptions = { /** - * 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. + * If set to `false`, the underlying subscription is not pooled with other consumers + * of the same key. Largely a no-op in the store-based design (subscriptions are cheap) + * but kept for API compatibility. */ 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. + * Subscribe to a subset of an Onyx key's data. The component re-renders only when + * the selector's output reference changes; selectors that allocate fresh objects + * (e.g. `(e) => ({id: e?.id})`) are handled by an internal input-cache + deepEqual + * fallback so they don't cause `useSyncExternalStore` to loop. */ selector?: UseOnyxSelector; }; -type FetchStatus = 'loading' | 'loaded'; +/** + * Always `'loaded'` in the store-based design. The type is preserved so existing + * destructures like `const [val, {status}] = useOnyx(KEY)` keep compiling. Will be + * removed in a future cleanup once consumers stop reading it. + */ +type FetchStatus = 'loaded'; -type ResultMetadata = { +type ResultMetadata = { status: FetchStatus; - sourceValue?: NonNullable | undefined; }; -type UseOnyxResult = [NonNullable | undefined, ResultMetadata]; +type UseOnyxResult = [NonNullable | undefined, ResultMetadata]; -function useOnyx>( - key: TKey, - options?: UseOnyxOptions, - dependencies: DependencyList = [], -): UseOnyxResult { - const connectionRef = useRef(null); - const currentDependenciesRef = useLiveRef(dependencies); - const selector = options?.selector; - - // Create memoized version of selector for performance - const memoizedSelector = useMemo((): UseOnyxSelector | null => { - if (!selector) { - return null; - } - - let lastInput: OnyxValue | undefined; - let lastOutput: TReturnValue; - let lastDependencies: DependencyList = []; - let hasComputed = false; - - return (input: OnyxValue | undefined): TReturnValue => { - const currentDependencies = currentDependenciesRef.current; - - // Recompute if input changed, dependencies changed, or first time - const dependenciesChanged = !shallowEqual(lastDependencies, currentDependencies); - if (!hasComputed || lastInput !== input || dependenciesChanged) { - const newOutput = selector(input); - - // Always track the current input to avoid re-running the selector - // when the same input is seen again (even if the output didn't change). - lastInput = input; - - // Only update the output reference if it actually changed - if (!hasComputed || !deepEqual(lastOutput, newOutput) || dependenciesChanged) { - lastOutput = newOutput; - lastDependencies = [...currentDependencies]; - hasComputed = true; - } - } - - return lastOutput; - }; - }, [currentDependenciesRef, 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 = useRef(null); - - // Stores the newest cached value in order to compare with the previous one and optimize `getSnapshot()` execution. - const newValueRef = 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 = 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. - const connectedKeyRef = 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 = useRef(false); - - // Indicates if the hook is connecting to an Onyx key. - const isConnectingRef = useRef(false); - - // Stores the `onStoreChange()` function, which can be used to trigger a `getSnapshot()` update when desired. - const onStoreChangeFnRef = useRef<(() => void) | null>(null); - - // Indicates if we should get the newest cached value from Onyx during `getSnapshot()` execution. - const shouldGetCachedValueRef = useRef(true); - - // Inside useOnyx.ts, we need to track the sourceValue separately - const sourceValueRef = useRef | undefined>(undefined); - - // Cache the options key to avoid regenerating it every getSnapshot call - const cacheKey = useMemo( - () => - onyxSnapshotCache.registerConsumer({ - selector: options?.selector, - }), - [options?.selector], - ); - - useEffect(() => () => onyxSnapshotCache.deregisterConsumer(key, cacheKey), [key, cacheKey]); - - // Track previous dependencies to prevent infinite loops - const previousDependenciesRef = useRef([]); - - useEffect(() => { - // This effect will only run if the `dependencies` array changes. If it changes it will force the hook - // to trigger a `getSnapshot()` update by calling the stored `onStoreChange()` function reference, thus - // re-running the hook and returning the latest value to the consumer. - - // Deep equality check to prevent infinite loops when dependencies array reference changes - // but content remains the same - if (shallowEqual(previousDependenciesRef.current, dependencies)) { - return; - } - - previousDependenciesRef.current = dependencies; +const LOADED_METADATA: ResultMetadata = {status: 'loaded'}; - if (connectionRef.current === null || isConnectingRef.current || connectedKeyRef.current !== key || !onStoreChangeFnRef.current) { - return; - } - - // Invalidate cache when dependencies change so selector runs with new closure values - onyxSnapshotCache.invalidateForKey(key); - shouldGetCachedValueRef.current = true; - onStoreChangeFnRef.current(); - // eslint-disable-next-line react-hooks/exhaustive-deps - }, [...dependencies]); - - // 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 = useRef(memoizedSelector); - - const getSnapshot = useCallback(() => { - // 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.getCachedResult>(key, cacheKey); - if (cachedResult !== undefined) { - 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.tryGetCachedValue(key) as OnyxValue; - const selectedValue = memoizedSelector ? memoizedSelector(value) : value; - lastComputedSelectorRef.current = memoizedSelector; - newValueRef.current = (selectedValue ?? undefined) as TReturnValue | 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.hasCacheForKey(key); - - // Since the fetch status can be different given the use cases below, we define the variable right away. - let newFetchStatus: FetchStatus | undefined; +/** + * Subscribes a React component to an Onyx key. The component re-renders when the value + * at `key` changes (for collection keys, when any member changes — the returned value is + * the frozen collection snapshot). + * + * Returns `[value, {status: 'loaded'}]`. With eager-load + the structural-sharing cache, + * there's no loading phase — the cache always has an answer (a value or "absent"). The + * `status` field is retained for API compatibility and is always `'loaded'`. + */ +function useOnyx>(key: TKey, options?: UseOnyxOptions): UseOnyxResult { + const selector = options?.selector; - // 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.hasPendingMergeForKey(key)) { - newValueRef.current = undefined; - newFetchStatus = 'loading'; - } + // The memoized selector is recreated only when the selector function identity changes. + // Inside, it caches by input reference; that's what keeps useSyncExternalStore from + // looping when consumers pass inline-allocating selectors. + const memoizedSelector = useMemo(() => (selector ? createMemoizedSelector(selector) : null), [selector]); - // 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. - // Normalize null to undefined to ensure consistent comparison (both represent "no value"). - const areValuesEqual = shallowEqual(previousValueRef.current ?? undefined, newValueRef.current ?? undefined); + const subscribe = useCallback((onStoreChange: () => void) => onyxStore.subscribe(key, onStoreChange), [key]); - // 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.hasPendingTask(TASK.CLEAR) || !isFirstConnection)); - if (shouldUpdateResult) { - previousValueRef.current = newValueRef.current; + // resultRef holds the last tuple returned to React. We return the same tuple reference + // when value hasn't changed so React skips the re-render. + const resultRef = useRef>([undefined, LOADED_METADATA]); - // If the new value is `null` we default it to `undefined` to ensure the consumer gets a consistent result from the hook. - newFetchStatus = newFetchStatus ?? 'loaded'; - resultRef.current = [ - previousValueRef.current ?? undefined, - { - status: newFetchStatus, - sourceValue: sourceValueRef.current, - }, - ]; - } + const getSnapshot = useCallback((): UseOnyxResult => { + const raw = onyxStore.getState(key); + const selected = memoizedSelector ? memoizedSelector(raw as OnyxValue) : (raw as TReturnValue | undefined); + const nextValue = (selected ?? undefined) as NonNullable | undefined; - if (newFetchStatus !== 'loading') { - onyxSnapshotCache.setCachedResult>(key, cacheKey, resultRef.current); + if (resultRef.current[0] === nextValue) { + return resultRef.current; } - + resultRef.current = [nextValue, LOADED_METADATA]; return resultRef.current; - }, [key, memoizedSelector, cacheKey]); - - const subscribe = useCallback( - (onStoreChange: () => void) => { - // 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; - sourceValueRef.current = undefined; - resultRef.current = [undefined, {status: 'loading'}]; - shouldGetCachedValueRef.current = true; - } - - hasMountedRef.current = true; - isConnectingRef.current = true; - onStoreChangeFnRef.current = onStoreChange; - - connectionRef.current = connectionManager.connect({ - key, - callback: (value, callbackKey, sourceValue) => { - 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; - - // sourceValue is unknown type, so we need to cast it to the correct type. - sourceValueRef.current = sourceValue as NonNullable; - - // Invalidate snapshot cache for this key when data changes - onyxSnapshotCache.invalidateForKey(key); - - // Finally, we signal that the store changed, making `getSnapshot()` be called again. - onStoreChange(); - }, - waitForCollectionCallback: OnyxKeys.isCollectionKey(key) as true, - reuseConnection: options?.reuseConnection, - }); - - return () => { - if (!connectionRef.current) { - return; - } - - connectionManager.disconnect(connectionRef.current); - connectedKeyRef.current = null; - isConnectingRef.current = false; - onStoreChangeFnRef.current = null; - }; - }, - [key, options?.reuseConnection], - ); - - const result = useSyncExternalStore>(subscribe, getSnapshot); + }, [key, memoizedSelector]); - return result; + return useSyncExternalStore(subscribe, getSnapshot); } export default useOnyx; diff --git a/lib/useOnyxState.ts b/lib/useOnyxState.ts new file mode 100644 index 000000000..3a3317ce4 --- /dev/null +++ b/lib/useOnyxState.ts @@ -0,0 +1,163 @@ +import {deepEqual} from 'fast-equals'; +import {useCallback, useEffect, useMemo, useRef, useSyncExternalStore} from 'react'; +import onyxStore from './OnyxStore'; +import type {OnyxKey, OnyxValue} from './types'; + +/** + * Read-only virtual view over the Onyx state. Property access on a key returns + * the same value as `Onyx.getState(key)` — for collection keys the frozen snapshot, + * for single keys the cached value, or `undefined` if not present. + * + * No tree is materialized. Each property access routes through the store directly. + */ +type OnyxStateView = { + readonly [K in OnyxKey]: OnyxValue; +}; + +type UseOnyxStateSelector = (state: OnyxStateView, previousState: OnyxStateView | undefined) => T; + +type UseOnyxStateOptions = { + /** + * Onyx keys this selector depends on. The selector re-runs only when one of + * these keys' values changes. Collection keys count as a single dep — any + * member change triggers a re-run. + */ + dependencies: readonly OnyxKey[]; + + /** + * Custom equality function for the selector's output. Defaults to `===` with + * a deep-equal fallback for object outputs. When the comparison returns true, + * the React update is skipped. + */ + selectorEquality?: (a: T, b: T) => boolean; +}; + +/** + * Lazy, sealed Proxy whose getters route to `onyxStore.getState`. Used as both + * `state` and `previousState`. The previousState variant captures the dep values + * frozen at the previous selector invocation. + */ +function createStateView(snapshotProvider: (key: OnyxKey) => OnyxValue): OnyxStateView { + const handler: ProxyHandler> = { + get(_target, prop) { + if (typeof prop !== 'string') { + return undefined; + } + return snapshotProvider(prop); + }, + set() { + // Read-only — selector must not mutate the view. + return false; + }, + deleteProperty() { + return false; + }, + has(_target, prop) { + if (typeof prop !== 'string') { + return false; + } + return snapshotProvider(prop) !== undefined; + }, + }; + return new Proxy>({}, handler) as unknown as OnyxStateView; +} + +const liveStateView = createStateView((key) => onyxStore.getState(key as OnyxKey)); + +/** + * Default equality: reference equality with a deepEqual fallback for object outputs. + * Primitives and frozen-snapshot references compare correctly with `===`. Objects that + * the selector freshly allocates with the same content fall back to deepEqual. + */ +function defaultSelectorEquality(a: T, b: T): boolean { + if (Object.is(a, b)) { + return true; + } + if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') { + return false; + } + return deepEqual(a, b); +} + +/** + * Subscribe to a derived value computed from multiple Onyx keys. The selector + * receives a virtual `state` view and a `previousState` view holding the values + * of declared deps as of the last committed render. `previousState` may be used + * both as a performance aid (ref-equality walks for incremental compute — structural + * sharing makes unchanged collection members share references with the previous + * snapshot, so the walk is O(collection_size) with O(1) per-step cost) AND as a + * semantic input (the output is allowed to depend on it, e.g. a delta of what changed). + * + * Re-runs when any declared dep changes; skips React updates when the selector + * output is equal to the previous output (per `selectorEquality`, default + * `===` with deepEqual fallback). + * + * `previousState` is advanced in a post-commit effect, NOT during `getSnapshot`. + * This keeps `getSnapshot` pure (a `useSyncExternalStore` requirement): within a + * single render `previousViewRef` is frozen, so every `getSnapshot` call computes + * the same output regardless of how many times React invokes it. It also gives + * `previousState` the correct meaning — "deps at the last *committed* output": a + * store change whose output is equality-gated away never commits, so it never + * advances `previousState` past a value the consumer never saw. + */ +function useOnyxState(selector: UseOnyxStateSelector, options: UseOnyxStateOptions): T { + const {dependencies, selectorEquality = defaultSelectorEquality} = options; + + // Consumers usually pass an inline array literal (new reference every render), so we key + // the memo on the joined contents — `depsArray` only gets a new reference when the actual + // set of dependency keys changes, which keeps `subscribe` from re-subscribing every render. + // The space separator is safe because Onyx keys are identifiers/collection prefixes that + // never contain spaces. + // + // Keying on `depsKey` (content) rather than `dependencies` (identity) is something React + // Compiler can't preserve, so this hook opts out of compiler memoization and manages its + // own — deliberate, as it's hand-tuned for `useSyncExternalStore`. + const depsKey = dependencies.join(' '); + const depsArray = useMemo(() => [...dependencies], [depsKey]); // eslint-disable-line react-hooks/exhaustive-deps, react-hooks/preserve-manual-memoization + + // Only `subscribe` must be referentially stable for `useSyncExternalStore` (it controls + // re-subscription). `getSnapshot` may change identity freely — React just re-reads it — + // so it closes over the latest `selector`/`selectorEquality` directly instead of via refs. + const subscribe = useCallback( + (onStoreChange: () => void) => onyxStore.subscribeState(onStoreChange, depsArray), + [depsArray], + ); + + // `previousViewRef` is a Proxy over the dep values captured at the last committed + // render. It is ONLY mutated in the effect below (post-commit), never in getSnapshot, + // so it stays constant while a render's getSnapshot calls run. + const previousViewRef = useRef(undefined); + const lastOutputRef = useRef<{value: T} | null>(null); + + const getSnapshot = useCallback((): T => { + const output = selector(liveStateView, previousViewRef.current); + + // Ref-preservation: when the new output is equal to the last one, return the previous + // reference so React can bail out via `===`. This also keeps getSnapshot returning a + // stable value for an unchanged store, despite its identity changing between renders. + if (lastOutputRef.current !== null && selectorEquality(lastOutputRef.current.value, output)) { + return lastOutputRef.current.value; + } + + lastOutputRef.current = {value: output}; + return output; + }, [selector, selectorEquality]); + + const value = useSyncExternalStore(subscribe, getSnapshot); + + // After each committed render, snapshot the current dep values and expose them as + // `previousState` for the next selector run. Running on commit (not inside getSnapshot) + // keeps getSnapshot pure and makes `previousState` reflect the last delivered output. + useEffect(() => { + const currentDepValues: Record> = {}; + for (const dep of depsArray) { + currentDepValues[dep] = onyxStore.getState(dep); + } + previousViewRef.current = createStateView((key) => currentDepValues[key]); + }); + + return value; +} + +export default useOnyxState; +export type {OnyxStateView, UseOnyxStateOptions, UseOnyxStateSelector}; diff --git a/tests/unit/OnyxConnectionManagerTest.ts b/tests/unit/OnyxConnectionManagerTest.ts deleted file mode 100644 index 543dc23c1..000000000 --- a/tests/unit/OnyxConnectionManagerTest.ts +++ /dev/null @@ -1,481 +0,0 @@ -import {act} from '@testing-library/react-native'; -import Onyx from '../../lib'; -import type {Connection} from '../../lib/OnyxConnectionManager'; -import connectionManager from '../../lib/OnyxConnectionManager'; -import StorageMock from '../../lib/storage'; -import type GenericCollection from '../utils/GenericCollection'; -import waitForPromisesToResolve from '../utils/waitForPromisesToResolve'; - -// We need access to some internal properties of `connectionManager` during the tests but they are private, -// so this workaround allows us to have access to them. -// eslint-disable-next-line dot-notation -const connectionsMap = connectionManager['connectionsMap']; -// eslint-disable-next-line dot-notation -const generateConnectionID = connectionManager['generateConnectionID']; -// eslint-disable-next-line dot-notation -const getSessionID = () => connectionManager['sessionID']; - -const ONYXKEYS = { - TEST_KEY: 'test', - TEST_KEY_2: 'test2', - COLLECTION: { - TEST_KEY: 'test_', - TEST_KEY_2: 'test2_', - }, -}; - -Onyx.init({ - keys: ONYXKEYS, -}); - -beforeEach(() => Onyx.clear()); - -describe('OnyxConnectionManager', () => { - // Always use a "fresh" instance - beforeEach(() => { - connectionManager.disconnectAll(); - }); - - describe('generateConnectionID', () => { - it('should generate a stable connection ID', async () => { - const connectionID = generateConnectionID({key: ONYXKEYS.TEST_KEY}); - expect(connectionID).toEqual(`onyxKey=${ONYXKEYS.TEST_KEY},waitForCollectionCallback=false,sessionID=${getSessionID()}`); - }); - - it("should generate a stable connection ID regardless of the order which the option's properties were passed", async () => { - const connectionID = generateConnectionID({key: ONYXKEYS.TEST_KEY, waitForCollectionCallback: true}); - expect(connectionID).toEqual(`onyxKey=${ONYXKEYS.TEST_KEY},waitForCollectionCallback=true,sessionID=${getSessionID()}`); - }); - - it('should generate unique connection IDs if certain options are passed', async () => { - const connectionID1 = generateConnectionID({key: ONYXKEYS.TEST_KEY, reuseConnection: false}); - const connectionID2 = generateConnectionID({key: ONYXKEYS.TEST_KEY, reuseConnection: false}); - expect(connectionID1.startsWith(`onyxKey=${ONYXKEYS.TEST_KEY},waitForCollectionCallback=false,sessionID=${getSessionID()},uniqueID=`)).toBeTruthy(); - expect(connectionID2.startsWith(`onyxKey=${ONYXKEYS.TEST_KEY},waitForCollectionCallback=false,sessionID=${getSessionID()},uniqueID=`)).toBeTruthy(); - expect(connectionID1).not.toEqual(connectionID2); - }); - - it('should generate an unique connection ID if the session ID is changed', async () => { - const connectionID1 = generateConnectionID({key: ONYXKEYS.TEST_KEY}); - connectionManager.refreshSessionID(); - const connectionID2 = generateConnectionID({key: ONYXKEYS.TEST_KEY}); - - expect(connectionID1).not.toEqual(connectionID2); - }); - }); - - describe('connect / disconnect', () => { - it('should connect to a key and fire the callback with its value', async () => { - await StorageMock.setItem(ONYXKEYS.TEST_KEY, 'test'); - - const callback1 = jest.fn(); - const connection = connectionManager.connect({key: ONYXKEYS.TEST_KEY, callback: callback1}); - - expect(connectionsMap.has(connection.id)).toBeTruthy(); - - await act(async () => waitForPromisesToResolve()); - - expect(callback1).toHaveBeenCalledTimes(1); - expect(callback1).toHaveBeenCalledWith('test', ONYXKEYS.TEST_KEY); - - connectionManager.disconnect(connection); - - expect(connectionsMap.size).toEqual(0); - }); - - it('should connect two times to the same key and fire both callbacks with its value', async () => { - await StorageMock.setItem(ONYXKEYS.TEST_KEY, 'test'); - - const callback1 = jest.fn(); - const connection1 = connectionManager.connect({key: ONYXKEYS.TEST_KEY, callback: callback1}); - - const callback2 = jest.fn(); - const connection2 = connectionManager.connect({key: ONYXKEYS.TEST_KEY, callback: callback2}); - - expect(connection1.id).toEqual(connection2.id); - expect(connectionsMap.size).toEqual(1); - expect(connectionsMap.has(connection1.id)).toBeTruthy(); - - await act(async () => waitForPromisesToResolve()); - - expect(callback1).toHaveBeenCalledTimes(1); - expect(callback1).toHaveBeenCalledWith('test', ONYXKEYS.TEST_KEY); - expect(callback2).toHaveBeenCalledTimes(1); - expect(callback2).toHaveBeenCalledWith('test', ONYXKEYS.TEST_KEY); - - connectionManager.disconnect(connection1); - connectionManager.disconnect(connection2); - - expect(connectionsMap.size).toEqual(0); - }); - - it('should connect two times to the same key but with different options, and fire the callbacks differently', async () => { - const obj1 = {id: 'entry1_id', name: 'entry1_name'}; - const obj2 = {id: 'entry2_id', name: 'entry2_name'}; - const collection = { - [`${ONYXKEYS.COLLECTION.TEST_KEY}entry1`]: obj1, - [`${ONYXKEYS.COLLECTION.TEST_KEY}entry2`]: obj2, - } as GenericCollection; - await StorageMock.multiSet([ - [`${ONYXKEYS.COLLECTION.TEST_KEY}entry1`, obj1], - [`${ONYXKEYS.COLLECTION.TEST_KEY}entry2`, obj2], - ]); - - const callback1 = jest.fn(); - const connection1 = connectionManager.connect({key: ONYXKEYS.COLLECTION.TEST_KEY, callback: callback1}); - - const callback2 = jest.fn(); - const connection2 = connectionManager.connect({key: ONYXKEYS.COLLECTION.TEST_KEY, callback: callback2, waitForCollectionCallback: true}); - - expect(connection1.id).not.toEqual(connection2.id); - expect(connectionsMap.size).toEqual(2); - expect(connectionsMap.has(connection1.id)).toBeTruthy(); - expect(connectionsMap.has(connection2.id)).toBeTruthy(); - - await act(async () => waitForPromisesToResolve()); - - expect(callback1).toHaveBeenCalledTimes(2); - expect(callback1).toHaveBeenNthCalledWith(1, obj1, `${ONYXKEYS.COLLECTION.TEST_KEY}entry1`); - expect(callback1).toHaveBeenNthCalledWith(2, obj2, `${ONYXKEYS.COLLECTION.TEST_KEY}entry2`); - - expect(callback2).toHaveBeenCalledTimes(1); - expect(callback2).toHaveBeenCalledWith(collection, ONYXKEYS.COLLECTION.TEST_KEY, undefined); - - connectionManager.disconnect(connection1); - connectionManager.disconnect(connection2); - - expect(connectionsMap.size).toEqual(0); - }); - - it('should connect to a key, connect some times more after first connection is made, and fire all subsequent callbacks immediately with its value', async () => { - await StorageMock.setItem(ONYXKEYS.TEST_KEY, 'test'); - - const callback1 = jest.fn(); - connectionManager.connect({key: ONYXKEYS.TEST_KEY, callback: callback1}); - - await act(async () => waitForPromisesToResolve()); - - expect(callback1).toHaveBeenCalledTimes(1); - expect(callback1).toHaveBeenCalledWith('test', ONYXKEYS.TEST_KEY); - - const callback2 = jest.fn(); - connectionManager.connect({key: ONYXKEYS.TEST_KEY, callback: callback2}); - - const callback3 = jest.fn(); - connectionManager.connect({key: ONYXKEYS.TEST_KEY, callback: callback3}); - - const callback4 = jest.fn(); - connectionManager.connect({key: ONYXKEYS.TEST_KEY, callback: callback4}); - - await act(async () => waitForPromisesToResolve()); - - expect(callback2).toHaveBeenCalledTimes(1); - expect(callback2).toHaveBeenCalledWith('test', ONYXKEYS.TEST_KEY); - expect(callback3).toHaveBeenCalledTimes(1); - expect(callback3).toHaveBeenCalledWith('test', ONYXKEYS.TEST_KEY); - expect(callback4).toHaveBeenCalledTimes(1); - expect(callback4).toHaveBeenCalledWith('test', ONYXKEYS.TEST_KEY); - }); - - it('should have the connection object already defined when triggering the callback of the second connection to the same key', async () => { - await StorageMock.setItem(ONYXKEYS.TEST_KEY, 'test'); - - const callback1 = jest.fn(); - connectionManager.connect({key: ONYXKEYS.TEST_KEY, callback: callback1}); - - await act(async () => waitForPromisesToResolve()); - - expect(callback1).toHaveBeenCalledTimes(1); - expect(callback1).toHaveBeenCalledWith('test', ONYXKEYS.TEST_KEY); - - const callback2 = jest.fn(); - const connection2 = connectionManager.connect({ - key: ONYXKEYS.TEST_KEY, - callback: (...params) => { - callback2(...params); - connectionManager.disconnect(connection2); - }, - }); - - await act(async () => waitForPromisesToResolve()); - - expect(callback2).toHaveBeenCalledTimes(1); - expect(callback2).toHaveBeenCalledWith('test', ONYXKEYS.TEST_KEY); - expect(connectionsMap.size).toEqual(1); - }); - - it('should create a separate connection to the same key when setting reuseConnection to false', async () => { - await StorageMock.setItem(ONYXKEYS.TEST_KEY, 'test'); - - const callback1 = jest.fn(); - const connection1 = connectionManager.connect({key: ONYXKEYS.TEST_KEY, callback: callback1}); - - const callback2 = jest.fn(); - const connection2 = connectionManager.connect({key: ONYXKEYS.TEST_KEY, reuseConnection: false, callback: callback2}); - - expect(connection1.id).not.toEqual(connection2.id); - expect(connectionsMap.size).toEqual(2); - expect(connectionsMap.has(connection1.id)).toBeTruthy(); - expect(connectionsMap.has(connection2.id)).toBeTruthy(); - }); - - it("should create a separate connection to the same key when it's a collection one and waitForCollectionCallback is undefined/false", async () => { - const collection = { - [`${ONYXKEYS.COLLECTION.TEST_KEY}entry1`]: {id: 'entry1_id', name: 'entry1_name'}, - [`${ONYXKEYS.COLLECTION.TEST_KEY}entry2`]: {id: 'entry2_id', name: 'entry2_name'}, - [`${ONYXKEYS.COLLECTION.TEST_KEY}entry3`]: {id: 'entry3_id', name: 'entry3_name'}, - }; - - Onyx.mergeCollection(ONYXKEYS.COLLECTION.TEST_KEY, collection as GenericCollection); - - await act(async () => waitForPromisesToResolve()); - - const callback1 = jest.fn(); - const connection1 = connectionManager.connect({key: ONYXKEYS.COLLECTION.TEST_KEY, waitForCollectionCallback: undefined, callback: callback1}); - - await act(async () => waitForPromisesToResolve()); - - expect(callback1).toHaveBeenCalledTimes(3); - expect(callback1).toHaveBeenNthCalledWith(1, collection[`${ONYXKEYS.COLLECTION.TEST_KEY}entry1`], `${ONYXKEYS.COLLECTION.TEST_KEY}entry1`); - expect(callback1).toHaveBeenNthCalledWith(2, collection[`${ONYXKEYS.COLLECTION.TEST_KEY}entry2`], `${ONYXKEYS.COLLECTION.TEST_KEY}entry2`); - expect(callback1).toHaveBeenNthCalledWith(3, collection[`${ONYXKEYS.COLLECTION.TEST_KEY}entry3`], `${ONYXKEYS.COLLECTION.TEST_KEY}entry3`); - - const callback2 = jest.fn(); - const connection2 = connectionManager.connect({key: ONYXKEYS.COLLECTION.TEST_KEY, waitForCollectionCallback: false, callback: callback2}); - - expect(connection1.id).not.toEqual(connection2.id); - expect(connectionsMap.size).toEqual(2); - expect(connectionsMap.has(connection1.id)).toBeTruthy(); - expect(connectionsMap.has(connection2.id)).toBeTruthy(); - - await act(async () => waitForPromisesToResolve()); - - expect(callback2).toHaveBeenCalledTimes(3); - expect(callback2).toHaveBeenNthCalledWith(1, collection[`${ONYXKEYS.COLLECTION.TEST_KEY}entry1`], `${ONYXKEYS.COLLECTION.TEST_KEY}entry1`); - expect(callback2).toHaveBeenNthCalledWith(2, collection[`${ONYXKEYS.COLLECTION.TEST_KEY}entry2`], `${ONYXKEYS.COLLECTION.TEST_KEY}entry2`); - expect(callback2).toHaveBeenNthCalledWith(3, collection[`${ONYXKEYS.COLLECTION.TEST_KEY}entry3`], `${ONYXKEYS.COLLECTION.TEST_KEY}entry3`); - }); - - it('should not throw any errors when passing an undefined connection or trying to access an inexistent one inside disconnect()', () => { - expect(connectionsMap.size).toEqual(0); - - expect(() => { - connectionManager.disconnect(undefined as unknown as Connection); - }).not.toThrow(); - - expect(() => { - connectionManager.disconnect({id: 'connectionID1', callbackID: 'callbackID1'}); - }).not.toThrow(); - }); - - it('should create a separate connection for the same key after a Onyx.clear() call', async () => { - await StorageMock.setItem(ONYXKEYS.TEST_KEY, 'test'); - - const callback1 = jest.fn(); - connectionManager.connect({key: ONYXKEYS.TEST_KEY, callback: callback1}); - expect(connectionsMap.size).toEqual(1); - - await act(async () => waitForPromisesToResolve()); - - expect(callback1).toHaveBeenCalledTimes(1); - expect(callback1).toHaveBeenCalledWith('test', ONYXKEYS.TEST_KEY); - callback1.mockReset(); - - await act(async () => Onyx.clear()); - - expect(callback1).toHaveBeenCalledTimes(1); - expect(callback1).toHaveBeenCalledWith(undefined, ONYXKEYS.TEST_KEY); - callback1.mockReset(); - - const callback2 = jest.fn(); - connectionManager.connect({key: ONYXKEYS.TEST_KEY, callback: callback2}); - - const callback3 = jest.fn(); - connectionManager.connect({key: ONYXKEYS.TEST_KEY, callback: callback3}); - - // We expect to have two connections for ONYXKEYS.TEST_KEY, one for the first subscription before Onyx.clear(), - // and the other for the two subscriptions with the same key after Onyx.clear(). - expect(connectionsMap.size).toEqual(2); - - await act(async () => waitForPromisesToResolve()); - - expect(callback2).toHaveBeenCalledTimes(1); - expect(callback2).toHaveBeenCalledWith(undefined, undefined); - expect(callback3).toHaveBeenCalledTimes(1); - expect(callback3).toHaveBeenCalledWith(undefined, undefined); - callback1.mockReset(); - callback2.mockReset(); - callback3.mockReset(); - - Onyx.merge(ONYXKEYS.TEST_KEY, 'test2'); - await act(async () => waitForPromisesToResolve()); - - expect(callback1).toHaveBeenCalledTimes(1); - expect(callback1).toHaveBeenCalledWith('test2', ONYXKEYS.TEST_KEY); - expect(callback2).toHaveBeenCalledTimes(1); - expect(callback2).toHaveBeenCalledWith('test2', ONYXKEYS.TEST_KEY); - expect(callback3).toHaveBeenCalledTimes(1); - expect(callback3).toHaveBeenCalledWith('test2', ONYXKEYS.TEST_KEY); - }); - }); - - describe('unsubscribeFromKey', () => { - it('should clean up the correct subscription ID from lastConnectionCallbackData on disconnect', async () => { - const deleteSpy = jest.spyOn(Map.prototype, 'delete'); - - const connectionA = Onyx.connect({key: ONYXKEYS.TEST_KEY, callback: jest.fn(), reuseConnection: false}); - Onyx.connect({key: ONYXKEYS.TEST_KEY, callback: jest.fn(), reuseConnection: false}); - await act(async () => waitForPromisesToResolve()); - - const subscriptionIdA = connectionsMap.get(connectionA.id)?.subscriptionID; - - await Onyx.set(ONYXKEYS.TEST_KEY, 'value1'); - await act(async () => waitForPromisesToResolve()); - - deleteSpy.mockClear(); - Onyx.disconnect(connectionA); - - const numericDeleteArgs = deleteSpy.mock.calls.map((call) => call[0]).filter((arg): arg is number => typeof arg === 'number'); - expect(numericDeleteArgs).toContain(subscriptionIdA); - - deleteSpy.mockRestore(); - }); - - it('should remove the subscription ID from onyxKeyToSubscriptionIDs on disconnect', async () => { - const setSpy = jest.spyOn(Map.prototype, 'set'); - - const connectionA = Onyx.connect({key: ONYXKEYS.TEST_KEY, callback: jest.fn(), reuseConnection: false}); - const connectionB = Onyx.connect({key: ONYXKEYS.TEST_KEY, callback: jest.fn(), reuseConnection: false}); - await act(async () => waitForPromisesToResolve()); - - const subscriptionIdA = connectionsMap.get(connectionA.id)?.subscriptionID; - const subscriptionIdB = connectionsMap.get(connectionB.id)?.subscriptionID; - - setSpy.mockClear(); - Onyx.disconnect(connectionA); - - const setCallsForKey = setSpy.mock.calls.filter((call) => call[0] === ONYXKEYS.TEST_KEY); - expect(setCallsForKey.length).toBeGreaterThan(0); - - const updatedIDs = setCallsForKey[setCallsForKey.length - 1][1] as number[]; - expect(updatedIDs).not.toContain(subscriptionIdA); - expect(updatedIDs).toContain(subscriptionIdB); - - setSpy.mockRestore(); - Onyx.disconnect(connectionB); - }); - }); - - describe('disconnectAll', () => { - it('should disconnect all connections', async () => { - await StorageMock.setItem(ONYXKEYS.TEST_KEY, 'test'); - await StorageMock.setItem(ONYXKEYS.TEST_KEY_2, 'test2'); - - const callback1 = jest.fn(); - const connection1 = connectionManager.connect({key: ONYXKEYS.TEST_KEY, callback: callback1}); - - const callback2 = jest.fn(); - const connection2 = connectionManager.connect({key: ONYXKEYS.TEST_KEY, callback: callback2}); - - const callback3 = jest.fn(); - const connection3 = connectionManager.connect({key: ONYXKEYS.TEST_KEY_2, callback: callback3}); - - expect(connection1.id).toEqual(connection2.id); - expect(connectionsMap.size).toEqual(2); - expect(connectionsMap.has(connection1.id)).toBeTruthy(); - expect(connectionsMap.has(connection3.id)).toBeTruthy(); - - await act(async () => waitForPromisesToResolve()); - - connectionManager.disconnectAll(); - - expect(connectionsMap.size).toEqual(0); - }); - }); - - describe('refreshSessionID', () => { - it('should create a separate connection for the same key if the session ID changes', async () => { - await StorageMock.setItem(ONYXKEYS.TEST_KEY, 'test'); - await StorageMock.setItem(ONYXKEYS.TEST_KEY_2, 'test2'); - - const connection1 = connectionManager.connect({key: ONYXKEYS.TEST_KEY, callback: jest.fn()}); - - expect(connectionsMap.size).toEqual(1); - - connectionManager.refreshSessionID(); - - const connection2 = connectionManager.connect({key: ONYXKEYS.TEST_KEY, callback: jest.fn()}); - - expect(connectionsMap.size).toEqual(2); - expect(connectionsMap.has(connection1.id)).toBeTruthy(); - expect(connectionsMap.has(connection2.id)).toBeTruthy(); - }); - }); - - describe('sourceValue parameter', () => { - it('should pass the sourceValue parameter to collection callbacks when waitForCollectionCallback is true', async () => { - const obj1 = {id: 'entry1_id', name: 'entry1_name'}; - const obj2 = {id: 'entry2_id', name: 'entry2_name'}; - - const callback = jest.fn(); - const connection = connectionManager.connect({ - key: ONYXKEYS.COLLECTION.TEST_KEY, - callback, - waitForCollectionCallback: true, - }); - - await act(async () => waitForPromisesToResolve()); - - // Initial callback with undefined values - expect(callback).toHaveBeenCalledTimes(1); - expect(callback).toHaveBeenCalledWith(undefined, ONYXKEYS.COLLECTION.TEST_KEY, undefined); - - // Reset mock to test the next update - callback.mockReset(); - - // Update with first object - await Onyx.merge(`${ONYXKEYS.COLLECTION.TEST_KEY}entry1`, obj1); - - expect(callback).toHaveBeenCalledTimes(1); - expect(callback).toHaveBeenCalledWith({[`${ONYXKEYS.COLLECTION.TEST_KEY}entry1`]: obj1}, ONYXKEYS.COLLECTION.TEST_KEY, {[`${ONYXKEYS.COLLECTION.TEST_KEY}entry1`]: obj1}); - - // Reset mock to test the next update - callback.mockReset(); - - // Update with second object - await Onyx.merge(`${ONYXKEYS.COLLECTION.TEST_KEY}entry2`, obj2); - - expect(callback).toHaveBeenCalledTimes(1); - expect(callback).toHaveBeenCalledWith( - { - [`${ONYXKEYS.COLLECTION.TEST_KEY}entry1`]: obj1, - [`${ONYXKEYS.COLLECTION.TEST_KEY}entry2`]: obj2, - }, - ONYXKEYS.COLLECTION.TEST_KEY, - {[`${ONYXKEYS.COLLECTION.TEST_KEY}entry2`]: obj2}, - ); - - connectionManager.disconnect(connection); - }); - - it('should not pass sourceValue to regular callbacks when waitForCollectionCallback is false', async () => { - const obj1 = {id: 'entry1_id', name: 'entry1_name'}; - - const callback = jest.fn(); - const connection = connectionManager.connect({ - key: ONYXKEYS.COLLECTION.TEST_KEY, - callback, - waitForCollectionCallback: false, - }); - - await act(async () => waitForPromisesToResolve()); - - // Update with object - await Onyx.merge(`${ONYXKEYS.COLLECTION.TEST_KEY}entry1`, obj1); - - expect(callback).toHaveBeenCalledWith(obj1, `${ONYXKEYS.COLLECTION.TEST_KEY}entry1`); - - connectionManager.disconnect(connection); - }); - }); -}); diff --git a/tests/unit/OnyxSnapshotCacheTest.ts b/tests/unit/OnyxSnapshotCacheTest.ts deleted file mode 100644 index 35b46a5cb..000000000 --- a/tests/unit/OnyxSnapshotCacheTest.ts +++ /dev/null @@ -1,231 +0,0 @@ -import type {OnyxKey} from '../../lib'; -import {OnyxSnapshotCache} from '../../lib/OnyxSnapshotCache'; -import OnyxKeys from '../../lib/OnyxKeys'; -import type {UseOnyxOptions, UseOnyxResult, UseOnyxSelector} from '../../lib/useOnyx'; - -// Mock OnyxKeys for testing -jest.mock('../../lib/OnyxKeys', () => ({ - isCollectionKey: jest.fn(), - getCollectionKey: jest.fn(), -})); - -const mockedOnyxKeys = OnyxKeys as jest.Mocked; - -// Test types -type TestData = { - data: string; - id?: string; - name?: string; -}; - -type TestResult = UseOnyxResult<{data: string}>; - -type TestSelector = UseOnyxSelector; - -describe('OnyxSnapshotCache', () => { - let cache: OnyxSnapshotCache; - - beforeEach(() => { - cache = new OnyxSnapshotCache(); - jest.clearAllMocks(); - }); - - describe('basic cache operations', () => { - it('should generate unique cache keys for different options', () => { - const selector: TestSelector = (data) => { - const testData = data as TestData | undefined; - return testData?.name ?? ''; - }; - const optionsWithSelector: UseOnyxOptions = { - selector, - }; - const optionsWithoutSelector: UseOnyxOptions = {}; - const keyWithSelector = cache.registerConsumer(optionsWithSelector); - const keyWithoutSelector = cache.registerConsumer(optionsWithoutSelector); - const keyWithUndefined = cache.registerConsumer({}); - - // Selector cache keys are the selector ID as a string; no-selector consumers share the same key - expect(keyWithSelector).toBe('0'); - expect(keyWithoutSelector).toBe('no_selector'); - expect(keyWithUndefined).toBe('no_selector'); - }); - - it('should store and retrieve cached results', () => { - const key = 'testKey'; - const cacheKey = 'testCacheKey'; - const result: TestResult = [{data: 'test'}, {status: 'loaded'}]; - - cache.setCachedResult(key, cacheKey, result); - const retrieved = cache.getCachedResult(key, cacheKey); - - expect(retrieved).toEqual(result); - }); - - it('should return undefined for non-existent cache entries', () => { - const result = cache.getCachedResult('nonExistentKey', 'nonExistentCacheKey'); - expect(result).toBeUndefined(); - }); - - it('should clear all caches', () => { - const result1: TestResult = [{data: 'test1'}, {status: 'loaded'}]; - const result2: TestResult = [{data: 'test2'}, {status: 'loaded'}]; - - cache.setCachedResult('key1', 'cacheKey1', result1); - cache.setCachedResult('key2', 'cacheKey2', result2); - - cache.clear(); - - expect(cache.getCachedResult('key1', 'cacheKey1')).toBeUndefined(); - expect(cache.getCachedResult('key2', 'cacheKey2')).toBeUndefined(); - }); - }); - - describe('selector ID management', () => { - it('should generate unique IDs for different selectors', () => { - const nameSelector: TestSelector = (data) => { - const testData = data as TestData | undefined; - return testData?.name ?? ''; - }; - const idSelector: TestSelector = (data) => { - const testData = data as TestData | undefined; - return testData?.id ?? ''; - }; - - const nameId = cache.getSelectorID(nameSelector); - const idSelectorId = cache.getSelectorID(idSelector); - - // Different selectors should get different IDs - expect(nameId).not.toBe(idSelectorId); - }); - - it('should return the same ID for the same selector function', () => { - const selector: TestSelector = (data) => { - const testData = data as TestData | undefined; - return testData?.name ?? ''; - }; - - const firstCall = cache.getSelectorID(selector); - const secondCall = cache.getSelectorID(selector); - const thirdCall = cache.getSelectorID(selector); - - // Multiple calls with same selector should return identical ID - expect(firstCall).toBe(secondCall); - expect(secondCall).toBe(thirdCall); - }); - - it('should clear selector IDs and reset counter', () => { - const selector1: TestSelector = (data) => { - const testData = data as TestData | undefined; - return testData?.name ?? ''; - }; - const selector2: TestSelector = (data) => { - const testData = data as TestData | undefined; - return testData?.id ?? ''; - }; - - // Clear the selector IDs - cache.clearSelectorIds(); - - // After clearing, selectors should get new IDs starting from 0 - const id1After = cache.getSelectorID(selector1); - const id2After = cache.getSelectorID(selector2); - - expect(id1After).toBe(0); // First selector after clear should get ID 0 - expect(id2After).toBe(1); // Second selector should get ID 1 - }); - }); - - describe('cache invalidation', () => { - beforeEach(() => { - // Set up cache with multiple entries - cache.setCachedResult('reports_', 'cache1', [{data: 'collection'}, {status: 'loaded'}]); - cache.setCachedResult('reports_123', 'cache2', [{data: 'member1'}, {status: 'loaded'}]); - cache.setCachedResult('reports_456', 'cache3', [{data: 'member2'}, {status: 'loaded'}]); - cache.setCachedResult('users_', 'cache4', [{data: 'users collection'}, {status: 'loaded'}]); - cache.setCachedResult('users_789', 'cache5', [{data: 'user member'}, {status: 'loaded'}]); - cache.setCachedResult('nonCollectionKey', 'cache6', [{data: 'regular key'}, {status: 'loaded'}]); - }); - - it('should invalidate non-collection keys without affecting others', () => { - mockedOnyxKeys.isCollectionKey.mockReturnValue(false); - mockedOnyxKeys.getCollectionKey.mockReturnValue(undefined); - - cache.invalidateForKey('nonCollectionKey'); - - // Non-collection key should be invalidated - expect(cache.getCachedResult('nonCollectionKey', 'cache6')).toBeUndefined(); - - // All other keys should remain - expect(cache.getCachedResult('reports_', 'cache1')).toBeDefined(); - expect(cache.getCachedResult('reports_123', 'cache2')).toBeDefined(); - expect(cache.getCachedResult('reports_456', 'cache3')).toBeDefined(); - expect(cache.getCachedResult('users_', 'cache4')).toBeDefined(); - expect(cache.getCachedResult('users_789', 'cache5')).toBeDefined(); - }); - - it('should invalidate collection member key and its base collection only', () => { - mockedOnyxKeys.isCollectionKey.mockReturnValue(true); - mockedOnyxKeys.getCollectionKey.mockReturnValue('reports_'); - - cache.invalidateForKey('reports_123'); - - // Collection member and base should be invalidated - expect(cache.getCachedResult('reports_123', 'cache2')).toBeUndefined(); - expect(cache.getCachedResult('reports_', 'cache1')).toBeUndefined(); - - // Other collection members should remain (selective invalidation) - expect(cache.getCachedResult('reports_456', 'cache3')).toBeDefined(); - - // Unrelated keys should remain - expect(cache.getCachedResult('users_', 'cache4')).toBeDefined(); - expect(cache.getCachedResult('users_789', 'cache5')).toBeDefined(); - expect(cache.getCachedResult('nonCollectionKey', 'cache6')).toBeDefined(); - }); - - it('should invalidate collection base key without cascading to members', () => { - mockedOnyxKeys.isCollectionKey.mockReturnValue(true); - mockedOnyxKeys.getCollectionKey.mockReturnValue('reports_'); - - // When base key equals the key to invalidate, it's a collection base key - cache.invalidateForKey('reports_'); - - // Only the base collection should be invalidated - expect(cache.getCachedResult('reports_', 'cache1')).toBeUndefined(); - - // Collection members should remain (no cascade deletion) - expect(cache.getCachedResult('reports_123', 'cache2')).toBeDefined(); - expect(cache.getCachedResult('reports_456', 'cache3')).toBeDefined(); - - // Unrelated keys should remain - expect(cache.getCachedResult('users_', 'cache4')).toBeDefined(); - expect(cache.getCachedResult('users_789', 'cache5')).toBeDefined(); - expect(cache.getCachedResult('nonCollectionKey', 'cache6')).toBeDefined(); - }); - - it('should handle multiple different collection keys independently', () => { - // Invalidate reports collection member - mockedOnyxKeys.isCollectionKey.mockReturnValueOnce(true); - mockedOnyxKeys.getCollectionKey.mockReturnValueOnce('reports_'); - cache.invalidateForKey('reports_123'); - - // Invalidate users collection member - mockedOnyxKeys.isCollectionKey.mockReturnValueOnce(true); - mockedOnyxKeys.getCollectionKey.mockReturnValueOnce('users_'); - cache.invalidateForKey('users_789'); - - // Reports: member and base should be invalidated - expect(cache.getCachedResult('reports_123', 'cache2')).toBeUndefined(); - expect(cache.getCachedResult('reports_', 'cache1')).toBeUndefined(); - - // Users: member and base should be invalidated - expect(cache.getCachedResult('users_789', 'cache5')).toBeUndefined(); - expect(cache.getCachedResult('users_', 'cache4')).toBeUndefined(); - - // Other collection members should remain - expect(cache.getCachedResult('reports_456', 'cache3')).toBeDefined(); - - // Non-collection keys should remain - expect(cache.getCachedResult('nonCollectionKey', 'cache6')).toBeDefined(); - }); - }); -}); diff --git a/tests/unit/OnyxStoreTest.ts b/tests/unit/OnyxStoreTest.ts new file mode 100644 index 000000000..19e6e6a74 --- /dev/null +++ b/tests/unit/OnyxStoreTest.ts @@ -0,0 +1,351 @@ +import type {OnyxKey} from '../../lib'; +import Onyx from '../../lib'; +import onyxStore from '../../lib/OnyxStore'; +import cache from '../../lib/OnyxCache'; +import * as Logger from '../../lib/Logger'; + +// We need access to some internal properties of `onyxStore` during the tests but they are private, +// so this workaround allows us to have access to them. The maps are created once in the constructor +// and only ever `.clear()`ed (never reassigned), so capturing the references here stays valid. +// eslint-disable-next-line dot-notation +const keyListeners = onyxStore['keyListeners']; +// eslint-disable-next-line dot-notation +const stateListenersByDep = onyxStore['stateListenersByDep']; + +const ONYXKEYS = { + TEST_KEY: 'test', + OTHER_TEST: 'otherTest', + COLLECTION: { + TEST_KEY: 'test_', + }, +}; + +const COLLECTION = ONYXKEYS.COLLECTION.TEST_KEY; +const MEMBER_1 = `${COLLECTION}1`; +const MEMBER_2 = `${COLLECTION}2`; + +Onyx.init({ + keys: ONYXKEYS, +}); + +beforeEach(() => Onyx.clear()); + +describe('OnyxStore', () => { + // Always start from a clean registry. + beforeEach(() => { + onyxStore.clearAll(); + }); + + afterEach(() => { + jest.restoreAllMocks(); + }); + + describe('subscribe / notifyKey', () => { + it('should fire the listener with (value, key) on notifyKey', () => { + const callback = jest.fn(); + onyxStore.subscribe(ONYXKEYS.TEST_KEY, callback); + + onyxStore.notifyKey(ONYXKEYS.TEST_KEY, 'hello'); + + expect(callback).toHaveBeenCalledTimes(1); + expect(callback).toHaveBeenCalledWith('hello', ONYXKEYS.TEST_KEY); + }); + + it('should fire all listeners registered on the same key', () => { + const callback1 = jest.fn(); + const callback2 = jest.fn(); + onyxStore.subscribe(ONYXKEYS.TEST_KEY, callback1); + onyxStore.subscribe(ONYXKEYS.TEST_KEY, callback2); + + onyxStore.notifyKey(ONYXKEYS.TEST_KEY, 1); + + expect(callback1).toHaveBeenCalledTimes(1); + expect(callback2).toHaveBeenCalledTimes(1); + }); + + it('should not fire the listener after it unsubscribes', () => { + const callback = jest.fn(); + const unsubscribe = onyxStore.subscribe(ONYXKEYS.TEST_KEY, callback); + + onyxStore.notifyKey(ONYXKEYS.TEST_KEY, 'first'); + unsubscribe(); + onyxStore.notifyKey(ONYXKEYS.TEST_KEY, 'second'); + + expect(callback).toHaveBeenCalledTimes(1); + expect(callback).toHaveBeenLastCalledWith('first', ONYXKEYS.TEST_KEY); + }); + + it('should only unsubscribe the specific listener, leaving others intact', () => { + const callback1 = jest.fn(); + const callback2 = jest.fn(); + const unsubscribe1 = onyxStore.subscribe(ONYXKEYS.TEST_KEY, callback1); + onyxStore.subscribe(ONYXKEYS.TEST_KEY, callback2); + + unsubscribe1(); + onyxStore.notifyKey(ONYXKEYS.TEST_KEY, 1); + + expect(callback1).not.toHaveBeenCalled(); + expect(callback2).toHaveBeenCalledTimes(1); + }); + + it('should delete the key entry from the internal map once the last listener unsubscribes', () => { + const unsubscribe = onyxStore.subscribe(ONYXKEYS.TEST_KEY, jest.fn()); + expect(keyListeners.has(ONYXKEYS.TEST_KEY)).toBeTruthy(); + + unsubscribe(); + + expect(keyListeners.has(ONYXKEYS.TEST_KEY)).toBeFalsy(); + }); + + it('should be a no-op to notify a key with no listeners', () => { + expect(() => onyxStore.notifyKey('keyWithNoListeners' as OnyxKey, 'x')).not.toThrow(); + }); + + it('should be idempotent when unsubscribing more than once', () => { + const callback = jest.fn(); + const unsubscribe = onyxStore.subscribe(ONYXKEYS.TEST_KEY, callback); + + unsubscribe(); + expect(() => unsubscribe()).not.toThrow(); + + onyxStore.notifyKey(ONYXKEYS.TEST_KEY, 1); + expect(callback).not.toHaveBeenCalled(); + }); + }); + + describe('collection-snapshot routing on notifyKey', () => { + it('should fire the collection-root snapshot listener with the cache snapshot when a member is written', () => { + const snapshot = {[MEMBER_1]: {id: 1}, [MEMBER_2]: {id: 2}}; + const getCollectionData = jest.spyOn(cache, 'getCollectionData').mockReturnValue(snapshot); + + const callback = jest.fn(); + onyxStore.subscribe(COLLECTION, callback); + + onyxStore.notifyKey(MEMBER_1, {id: 1}); + + expect(getCollectionData).toHaveBeenCalledWith(COLLECTION); + expect(callback).toHaveBeenCalledTimes(1); + expect(callback).toHaveBeenCalledWith(snapshot, COLLECTION); + }); + + it('should fire both the exact-member listener and the collection-root snapshot listener', () => { + const snapshot = {[MEMBER_1]: {id: 1}}; + jest.spyOn(cache, 'getCollectionData').mockReturnValue(snapshot); + + const memberCallback = jest.fn(); + const snapshotCallback = jest.fn(); + onyxStore.subscribe(MEMBER_1, memberCallback); + onyxStore.subscribe(COLLECTION, snapshotCallback); + + onyxStore.notifyKey(MEMBER_1, {id: 1}); + + expect(memberCallback).toHaveBeenCalledWith({id: 1}, MEMBER_1); + expect(snapshotCallback).toHaveBeenCalledWith(snapshot, COLLECTION); + }); + + it('should skip the collection-root listener but still fire the exact-member listener when suppressCollectionSnapshot is set', () => { + const getCollectionData = jest.spyOn(cache, 'getCollectionData').mockReturnValue({}); + + const memberCallback = jest.fn(); + const snapshotCallback = jest.fn(); + onyxStore.subscribe(MEMBER_1, memberCallback); + onyxStore.subscribe(COLLECTION, snapshotCallback); + + onyxStore.notifyKey(MEMBER_1, {id: 1}, {suppressCollectionSnapshot: true}); + + expect(memberCallback).toHaveBeenCalledTimes(1); + expect(snapshotCallback).not.toHaveBeenCalled(); + // The snapshot is never read when suppressed. + expect(getCollectionData).not.toHaveBeenCalled(); + }); + + it('should not perform collection routing for a non-member single key', () => { + const getCollectionData = jest.spyOn(cache, 'getCollectionData'); + const callback = jest.fn(); + onyxStore.subscribe(ONYXKEYS.TEST_KEY, callback); + + onyxStore.notifyKey(ONYXKEYS.TEST_KEY, 'x'); + + expect(callback).toHaveBeenCalledTimes(1); + expect(getCollectionData).not.toHaveBeenCalled(); + }); + }); + + describe('notifyCollection', () => { + it('should fire the snapshot listener once with the cache snapshot', () => { + const snapshot = {[MEMBER_1]: {id: 1}, [MEMBER_2]: {id: 2}}; + jest.spyOn(cache, 'getCollectionData').mockReturnValue(snapshot); + + const callback = jest.fn(); + onyxStore.subscribe(COLLECTION, callback); + + onyxStore.notifyCollection(COLLECTION, {[MEMBER_1]: {id: 1}, [MEMBER_2]: {id: 2}}); + + expect(callback).toHaveBeenCalledTimes(1); + expect(callback).toHaveBeenCalledWith(snapshot, COLLECTION); + }); + + it('should fire exact-member listeners only for members whose value reference changed', () => { + const shared = {id: 2}; // same reference in snapshot and previous → should be skipped + const snapshot = {[MEMBER_1]: {id: 1}, [MEMBER_2]: shared}; + jest.spyOn(cache, 'getCollectionData').mockReturnValue(snapshot); + + const member1Callback = jest.fn(); + const member2Callback = jest.fn(); + onyxStore.subscribe(MEMBER_1, member1Callback); + onyxStore.subscribe(MEMBER_2, member2Callback); + + onyxStore.notifyCollection( + COLLECTION, + {[MEMBER_1]: {id: 1}, [MEMBER_2]: shared}, + {[MEMBER_2]: shared}, // previous: member 2 unchanged by reference + ); + + expect(member1Callback).toHaveBeenCalledWith({id: 1}, MEMBER_1); + expect(member2Callback).not.toHaveBeenCalled(); + }); + + it('should be a no-op when the partial collection is empty', () => { + const callback = jest.fn(); + onyxStore.subscribe(COLLECTION, callback); + + onyxStore.notifyCollection(COLLECTION, {}); + + expect(callback).not.toHaveBeenCalled(); + }); + }); + + describe('subscribeState', () => { + it('should fire when a declared dep changes via notifyKey', () => { + const callback = jest.fn(); + onyxStore.subscribeState(callback, [ONYXKEYS.TEST_KEY]); + + onyxStore.notifyKey(ONYXKEYS.TEST_KEY, 'x'); + + expect(callback).toHaveBeenCalledTimes(1); + }); + + it('should not fire when a non-dep key changes', () => { + const callback = jest.fn(); + onyxStore.subscribeState(callback, [ONYXKEYS.TEST_KEY]); + + onyxStore.notifyKey(ONYXKEYS.OTHER_TEST, 'x'); + + expect(callback).not.toHaveBeenCalled(); + }); + + it('should fire at most once when both a member key and its collection key are deps (notifyKey)', () => { + jest.spyOn(cache, 'getCollectionData').mockReturnValue({}); + const callback = jest.fn(); + // Depends on both the collection root AND a specific member — a member write + // would touch both deps, but the shared `fired` set must dedup to a single call. + onyxStore.subscribeState(callback, [COLLECTION, MEMBER_1]); + + onyxStore.notifyKey(MEMBER_1, {id: 1}); + + expect(callback).toHaveBeenCalledTimes(1); + }); + + it('should fire at most once when multiple changed members are deps (notifyCollection)', () => { + jest.spyOn(cache, 'getCollectionData').mockReturnValue({[MEMBER_1]: {id: 1}, [MEMBER_2]: {id: 2}}); + const callback = jest.fn(); + onyxStore.subscribeState(callback, [MEMBER_1, MEMBER_2]); + + onyxStore.notifyCollection(COLLECTION, {[MEMBER_1]: {id: 1}, [MEMBER_2]: {id: 2}}); + + expect(callback).toHaveBeenCalledTimes(1); + }); + + it('should stop firing after it unsubscribes', () => { + const callback = jest.fn(); + const unsubscribe = onyxStore.subscribeState(callback, [ONYXKEYS.TEST_KEY]); + + onyxStore.notifyKey(ONYXKEYS.TEST_KEY, 'a'); + unsubscribe(); + onyxStore.notifyKey(ONYXKEYS.TEST_KEY, 'b'); + + expect(callback).toHaveBeenCalledTimes(1); + }); + + it('should clean up the by-dep index so an unsubscribed dep no longer dispatches', () => { + const callback1 = jest.fn(); + const callback2 = jest.fn(); + // Two entries share the dep; unsubscribing one must not drop the other. + const unsubscribe1 = onyxStore.subscribeState(callback1, [ONYXKEYS.TEST_KEY]); + onyxStore.subscribeState(callback2, [ONYXKEYS.TEST_KEY]); + + unsubscribe1(); + onyxStore.notifyKey(ONYXKEYS.TEST_KEY, 'x'); + + expect(callback1).not.toHaveBeenCalled(); + expect(callback2).toHaveBeenCalledTimes(1); + }); + + it('should delete the dep entry from the internal index once the last state listener unsubscribes', () => { + const unsubscribe = onyxStore.subscribeState(jest.fn(), [ONYXKEYS.TEST_KEY]); + expect(stateListenersByDep.has(ONYXKEYS.TEST_KEY)).toBeTruthy(); + + unsubscribe(); + + expect(stateListenersByDep.has(ONYXKEYS.TEST_KEY)).toBeFalsy(); + }); + }); + + describe('hasListenersForKey', () => { + it('should return true for an exact-key subscriber', () => { + onyxStore.subscribe(ONYXKEYS.TEST_KEY, jest.fn()); + expect(onyxStore.hasListenersForKey(ONYXKEYS.TEST_KEY)).toBeTruthy(); + }); + + it('should return true for a member key when its parent collection has a subscriber', () => { + onyxStore.subscribe(COLLECTION, jest.fn()); + expect(onyxStore.hasListenersForKey(MEMBER_1)).toBeTruthy(); + }); + + it('should return false when there are no relevant subscribers', () => { + expect(onyxStore.hasListenersForKey('someUnwatchedKey')).toBeFalsy(); + }); + + it('should return false after the last listener unsubscribes', () => { + const unsubscribe = onyxStore.subscribe(ONYXKEYS.TEST_KEY, jest.fn()); + unsubscribe(); + expect(onyxStore.hasListenersForKey(ONYXKEYS.TEST_KEY)).toBeFalsy(); + }); + }); + + describe('clearAll', () => { + it('should wipe key, collection, and state subscriptions', () => { + const keyCallback = jest.fn(); + const stateCallback = jest.fn(); + onyxStore.subscribe(ONYXKEYS.TEST_KEY, keyCallback); + onyxStore.subscribeState(stateCallback, [ONYXKEYS.TEST_KEY]); + + onyxStore.clearAll(); + onyxStore.notifyKey(ONYXKEYS.TEST_KEY, 'x'); + + expect(keyCallback).not.toHaveBeenCalled(); + expect(stateCallback).not.toHaveBeenCalled(); + expect(onyxStore.hasListenersForKey(ONYXKEYS.TEST_KEY)).toBeFalsy(); + }); + }); + + describe('listener error isolation', () => { + it('should log a throwing listener and still fire the other listeners', () => { + const logAlertSpy = jest.spyOn(Logger, 'logAlert').mockImplementation(() => { + /* empty */ + }); + const throwingCallback = jest.fn(() => { + throw new Error('boom'); + }); + const healthyCallback = jest.fn(); + onyxStore.subscribe(ONYXKEYS.TEST_KEY, throwingCallback); + onyxStore.subscribe(ONYXKEYS.TEST_KEY, healthyCallback); + + expect(() => onyxStore.notifyKey(ONYXKEYS.TEST_KEY, 'x')).not.toThrow(); + + expect(throwingCallback).toHaveBeenCalledTimes(1); + expect(healthyCallback).toHaveBeenCalledTimes(1); + expect(logAlertSpy).toHaveBeenCalled(); + }); + }); +}); diff --git a/tests/unit/collectionHydrationTest.ts b/tests/unit/collectionHydrationTest.ts index 64de44412..f44b23fe0 100644 --- a/tests/unit/collectionHydrationTest.ts +++ b/tests/unit/collectionHydrationTest.ts @@ -51,43 +51,6 @@ describe('Collection hydration with connect() followed by immediate set()', () = expect(lastCall[`${ONYX_KEYS.COLLECTION.TEST_KEY}1`]).toEqual({id: 1, title: 'Updated Test One'}); }); - test('waitForCollectionCallback=false should deliver all shallow-equal collection members when set() races with hydration', async () => { - // Clear existing storage and set up shallow-equal values for all members - await StorageMock.clear(); - await StorageMock.setItem(`${ONYX_KEYS.COLLECTION.TEST_KEY}1`, {status: 'active'}); - await StorageMock.setItem(`${ONYX_KEYS.COLLECTION.TEST_KEY}2`, {status: 'active'}); - await StorageMock.setItem(`${ONYX_KEYS.COLLECTION.TEST_KEY}3`, {status: 'active'}); - // Re-init so Onyx picks up the new storage keys - Onyx.init({keys: ONYX_KEYS}); - - const mockCallback = jest.fn(); - - Onyx.connect({ - key: ONYX_KEYS.COLLECTION.TEST_KEY, - waitForCollectionCallback: false, - callback: mockCallback, - }); - - // set() with the same shallow-equal value — this fires keyChanged synchronously, - // populating lastConnectionCallbackData before the hydration multiGet resolves. - Onyx.set(`${ONYX_KEYS.COLLECTION.TEST_KEY}1`, {status: 'active'}); - - await waitForPromisesToResolve(); - - const deliveredKeys = new Set(); - for (const call of mockCallback.mock.calls) { - const [, key] = call; - if (key) { - deliveredKeys.add(key); - } - } - - // ALL three members must be delivered, even though their values are shallow-equal. - expect(deliveredKeys).toContain(`${ONYX_KEYS.COLLECTION.TEST_KEY}1`); - expect(deliveredKeys).toContain(`${ONYX_KEYS.COLLECTION.TEST_KEY}2`); - expect(deliveredKeys).toContain(`${ONYX_KEYS.COLLECTION.TEST_KEY}3`); - }); - test('single key: set() with non-shallow-equal value should not be overwritten by stale hydration', async () => { const mockCallback = jest.fn(); @@ -129,37 +92,4 @@ describe('Collection hydration with connect() followed by immediate set()', () = expect(lastCall[`${ONYX_KEYS.COLLECTION.TEST_KEY}3`]).toEqual({id: 3, title: 'Test Three'}); }); - test('waitForCollectionCallback=false should deliver all collection members from storage', async () => { - const mockCallback = jest.fn(); - - // A component connects to the collection (callback fires per key, not batched). - Onyx.connect({ - key: ONYX_KEYS.COLLECTION.TEST_KEY, - waitForCollectionCallback: false, - callback: mockCallback, - }); - - Onyx.set(`${ONYX_KEYS.COLLECTION.TEST_KEY}1`, {id: 1, title: 'Updated Test One'}); - - await waitForPromisesToResolve(); - - // With waitForCollectionCallback=false, the callback fires per key individually. - // Collect all keys that were delivered across all calls. - const deliveredKeys = new Set(); - for (const call of mockCallback.mock.calls) { - const [, key] = call; - if (key) { - deliveredKeys.add(key); - } - } - - expect(deliveredKeys).toContain(`${ONYX_KEYS.COLLECTION.TEST_KEY}1`); - expect(deliveredKeys).toContain(`${ONYX_KEYS.COLLECTION.TEST_KEY}2`); - expect(deliveredKeys).toContain(`${ONYX_KEYS.COLLECTION.TEST_KEY}3`); - - // Verify the updated value is present (not stale) by finding the last call for key 1 - const key1Calls = mockCallback.mock.calls.filter((call) => call[1] === `${ONYX_KEYS.COLLECTION.TEST_KEY}1`); - const lastKey1Value = key1Calls[key1Calls.length - 1][0]; - expect(lastKey1Value).toEqual({id: 1, title: 'Updated Test One'}); - }); }); diff --git a/tests/unit/createMemoizedSelectorTest.ts b/tests/unit/createMemoizedSelectorTest.ts new file mode 100644 index 000000000..445911181 --- /dev/null +++ b/tests/unit/createMemoizedSelectorTest.ts @@ -0,0 +1,129 @@ +import createMemoizedSelector from '../../lib/createMemoizedSelector'; + +describe('createMemoizedSelector', () => { + it('computes the output on the first call', () => { + const selector = jest.fn((input: number) => input * 2); + const memoized = createMemoizedSelector(selector); + + expect(memoized(21)).toBe(42); + expect(selector).toHaveBeenCalledTimes(1); + }); + + it('short-circuits without recomputing when called with the same input reference', () => { + const input = {value: 1}; + const selector = jest.fn((data: {value: number}) => ({doubled: data.value * 2})); + const memoized = createMemoizedSelector(selector); + + const first = memoized(input); + const second = memoized(input); + + // Same input reference → selector not called again, same output reference returned. + expect(selector).toHaveBeenCalledTimes(1); + expect(second).toBe(first); + }); + + it('recomputes when the input reference changes', () => { + const selector = jest.fn((data: {value: number}) => data.value * 10); + const memoized = createMemoizedSelector(selector); + + expect(memoized({value: 1})).toBe(10); + expect(memoized({value: 2})).toBe(20); + expect(selector).toHaveBeenCalledTimes(2); + }); + + it('returns the previous output reference when a new input produces a deep-equal output', () => { + // New object input every call, but the selector output is structurally identical. + const selector = (data: {id: number; name: string}) => ({id: data.id}); + const memoized = createMemoizedSelector(selector); + + const first = memoized({id: 1, name: 'a'}); + const second = memoized({id: 1, name: 'b'}); // different input, deep-equal output {id: 1} + + // Output is deep-equal, so the *previous* reference is preserved for `===` consumers. + expect(second).toBe(first); + expect(second).toEqual({id: 1}); + }); + + it('returns a new output reference when a new input produces a deep-unequal output', () => { + const selector = (data: {id: number}) => ({id: data.id}); + const memoized = createMemoizedSelector(selector); + + const first = memoized({id: 1}); + const second = memoized({id: 2}); + + expect(second).not.toBe(first); + expect(second).toEqual({id: 2}); + }); + + it('preserves the output reference across an A → B(deep-equal A) → A sequence', () => { + const selector = (data: {id: number; extra: string}) => ({id: data.id}); + const memoized = createMemoizedSelector(selector); + + const a = memoized({id: 1, extra: 'x'}); + const b = memoized({id: 1, extra: 'y'}); // deep-equal output, keeps `a` + const c = memoized({id: 1, extra: 'z'}); // deep-equal output, keeps `a` + + expect(b).toBe(a); + expect(c).toBe(a); + }); + + it('handles primitive outputs', () => { + const selector = jest.fn((data: {n: number}) => data.n > 0); + const memoized = createMemoizedSelector(selector); + + expect(memoized({n: 1})).toBe(true); + // Different input, same boolean output — deepEqual(true, true) is true, value preserved. + expect(memoized({n: 5})).toBe(true); + expect(memoized({n: -1})).toBe(false); + expect(selector).toHaveBeenCalledTimes(3); + }); + + it('handles undefined input and undefined output', () => { + const selector = jest.fn((data: {x: number} | undefined) => data?.x); + const memoized = createMemoizedSelector(selector); + + expect(memoized(undefined)).toBeUndefined(); + // Same undefined input reference → short-circuits. + expect(memoized(undefined)).toBeUndefined(); + expect(selector).toHaveBeenCalledTimes(1); + }); + + it('treats the first call as a real computation even when the output is undefined', () => { + const selector = jest.fn(() => undefined); + const memoized = createMemoizedSelector(selector); + + const input1 = {a: 1}; + const input2 = {a: 2}; + + expect(memoized(input1)).toBeUndefined(); + expect(memoized(input2)).toBeUndefined(); + // Both inputs differ by reference, but both outputs are undefined (deep-equal) — recomputed + // on the second call, then collapsed to the preserved reference (both undefined anyway). + expect(selector).toHaveBeenCalledTimes(2); + }); + + it('keeps independent caches per wrapper instance', () => { + const selectorA = jest.fn((n: number) => n + 1); + const selectorB = jest.fn((n: number) => n + 100); + const memoizedA = createMemoizedSelector(selectorA); + const memoizedB = createMemoizedSelector(selectorB); + + expect(memoizedA(1)).toBe(2); + expect(memoizedB(1)).toBe(101); + expect(selectorA).toHaveBeenCalledTimes(1); + expect(selectorB).toHaveBeenCalledTimes(1); + }); + + it('preserves nested object reference identity on deep-equal recompute', () => { + const selector = (data: {id: number}) => ({meta: {id: data.id}, items: [data.id]}); + const memoized = createMemoizedSelector(selector); + + const first = memoized({id: 7}); + const second = memoized({id: 7}); // new input ref, deep-equal output + + // Whole output reference preserved, so nested members are reference-stable too. + expect(second).toBe(first); + expect(second.meta).toBe(first.meta); + expect(second.items).toBe(first.items); + }); +}); diff --git a/tests/unit/onyxCacheTest.tsx b/tests/unit/onyxCacheTest.tsx index 713232459..f5e7f4899 100644 --- a/tests/unit/onyxCacheTest.tsx +++ b/tests/unit/onyxCacheTest.tsx @@ -458,6 +458,31 @@ describe('Onyx', () => { OnyxKeys = require('../../lib/OnyxKeys').default; }); + it('should warn and skip a bare collection key passed in initialKeyStates', async () => { + // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require + const Logger = require('../../lib/Logger'); + const logAlertSpy = jest.spyOn(Logger, 'logAlert').mockImplementation(() => {}); + + Onyx.init({ + keys: ONYX_KEYS, + initialKeyStates: { + [ONYX_KEYS.TEST_KEY]: 'defaultValue', + // Anti-pattern: a default targeting the bare collection key. + [ONYX_KEYS.COLLECTION.MOCK_COLLECTION]: {id: 1}, + } as Record, + }); + await waitForPromisesToResolve(); + + expect(logAlertSpy).toHaveBeenCalledWith(expect.stringContaining(ONYX_KEYS.COLLECTION.MOCK_COLLECTION)); + // The regular-key default still applies... + expect(cache.get(ONYX_KEYS.TEST_KEY)).toEqual('defaultValue'); + // ...but the bare collection key default is dropped — no phantom member. + expect(cache.get(ONYX_KEYS.COLLECTION.MOCK_COLLECTION)).toBeUndefined(); + expect(cache.getCollectionData(ONYX_KEYS.COLLECTION.MOCK_COLLECTION)).not.toHaveProperty(ONYX_KEYS.COLLECTION.MOCK_COLLECTION); + + logAlertSpy.mockRestore(); + }); + describe('eager loading during initialisation', () => { beforeEach(() => { StorageMock = require('../../lib/storage').default; @@ -599,11 +624,33 @@ describe('Onyx', () => { expect(Object.keys(first!)).toHaveLength(0); }); - it('should return undefined for empty collections when no keys are loaded', async () => { + it('should return the frozen-empty snapshot for empty collections once init has registered the collection key', async () => { + await initOnyx(); + + // Post-init, a known collection key with no members resolves to the frozen + // empty snapshot — not `undefined`. Returning `{}` reliably across init, + // writes, and `Onyx.clear()` keeps `Onyx.connect({waitForCollectionCallback: true})` + // subscribers seeing a consistent "collection is empty" signal instead of + // mistakenly skipping the update. + const result = cache.getCollectionData(ONYX_KEYS.COLLECTION.MOCK_COLLECTION); + expect(result).toEqual({}); + }); + + it('should not surface a direct write to the collection root key as a member', async () => { await initOnyx(); + // Anti-pattern: a value written directly to the bare collection key lands in the + // cache under the prefix key. `getCollectionKey('mockCollection_')` returns + // `'mockCollection_'`, so without the read guard it would be scanned as a member of + // itself and surface as a phantom `{mockCollection_: ...}` entry. We write via the + // cache directly (bypassing the public `set()` write-guard) and with NO real + // members present, which forces the storageKeys fallback scan where the bug lived. + cache.set(ONYX_KEYS.COLLECTION.MOCK_COLLECTION, {}); + const result = cache.getCollectionData(ONYX_KEYS.COLLECTION.MOCK_COLLECTION); - expect(result).toBeUndefined(); + + expect(result).not.toHaveProperty(ONYX_KEYS.COLLECTION.MOCK_COLLECTION); + expect(result).toEqual({}); }); it('should return a new reference when a member is removed and another added simultaneously', async () => { diff --git a/tests/unit/onyxClearWebStorageTest.ts b/tests/unit/onyxClearWebStorageTest.ts index a9629ab3c..2546d815a 100644 --- a/tests/unit/onyxClearWebStorageTest.ts +++ b/tests/unit/onyxClearWebStorageTest.ts @@ -239,8 +239,9 @@ describe('Set data while storage is clearing', () => { // 3. clear() expect(collectionCallback).toHaveBeenCalledTimes(3); - // And it should be called with the expected parameters each time - expect(collectionCallback).toHaveBeenNthCalledWith(1, undefined, ONYX_KEYS.COLLECTION.TEST, undefined); + // And it should be called with the expected parameters each time. Initial fire + // delivers `{}` (legacy `undefined`-for-empty-initial shim was removed). + expect(collectionCallback).toHaveBeenNthCalledWith(1, {}, ONYX_KEYS.COLLECTION.TEST); expect(collectionCallback).toHaveBeenNthCalledWith( 2, { @@ -250,19 +251,8 @@ describe('Set data while storage is clearing', () => { test_4: 4, }, ONYX_KEYS.COLLECTION.TEST, - { - test_1: 1, - test_2: 2, - test_3: 3, - test_4: 4, - }, ); - expect(collectionCallback).toHaveBeenLastCalledWith({}, ONYX_KEYS.COLLECTION.TEST, { - test_1: undefined, - test_2: undefined, - test_3: undefined, - test_4: undefined, - }); + expect(collectionCallback).toHaveBeenLastCalledWith({}, ONYX_KEYS.COLLECTION.TEST); }) ); }); diff --git a/tests/unit/onyxTest.ts b/tests/unit/onyxTest.ts index 5ff5d6f96..e2ff5cca4 100644 --- a/tests/unit/onyxTest.ts +++ b/tests/unit/onyxTest.ts @@ -63,6 +63,61 @@ describe('Onyx', () => { return Onyx.clear(); }); + describe('writing to a collection key directly is blocked', () => { + it('should warn and no-op when Onyx.set is called with a collection key', async () => { + const logAlertSpy = jest.spyOn(Logger, 'logAlert').mockImplementation(() => {}); + + await Onyx.set(ONYX_KEYS.COLLECTION.TEST_KEY, {foo: 'bar'} as unknown as GenericCollection); + + expect(logAlertSpy).toHaveBeenCalledWith(expect.stringContaining(ONYX_KEYS.COLLECTION.TEST_KEY)); + // Nothing should have been written to the bare collection key. + expect(cache.get(ONYX_KEYS.COLLECTION.TEST_KEY)).toBeUndefined(); + logAlertSpy.mockRestore(); + }); + + it('should warn and no-op when Onyx.merge is called with a collection key', async () => { + const logAlertSpy = jest.spyOn(Logger, 'logAlert').mockImplementation(() => {}); + + await Onyx.merge(ONYX_KEYS.COLLECTION.TEST_KEY, {foo: 'bar'} as unknown as GenericCollection); + + expect(logAlertSpy).toHaveBeenCalledWith(expect.stringContaining(ONYX_KEYS.COLLECTION.TEST_KEY)); + expect(cache.get(ONYX_KEYS.COLLECTION.TEST_KEY)).toBeUndefined(); + logAlertSpy.mockRestore(); + }); + + it('should strip collection keys from Onyx.multiSet while still applying the other keys', async () => { + const logAlertSpy = jest.spyOn(Logger, 'logAlert').mockImplementation(() => {}); + + await Onyx.multiSet({ + [ONYX_KEYS.COLLECTION.TEST_KEY]: {} as unknown, + [ONYX_KEYS.OTHER_TEST]: 7, + } as unknown as Parameters[0]); + + expect(logAlertSpy).toHaveBeenCalledWith(expect.stringContaining(ONYX_KEYS.COLLECTION.TEST_KEY)); + // The collection key is dropped, but the regular key is still written. + expect(cache.get(ONYX_KEYS.COLLECTION.TEST_KEY)).toBeUndefined(); + expect(cache.get(ONYX_KEYS.OTHER_TEST)).toEqual(7); + logAlertSpy.mockRestore(); + }); + + it('should not surface a phantom member in the collection snapshot after a blocked write', async () => { + const connectionCallback = jest.fn(); + connection = Onyx.connect({ + key: ONYX_KEYS.COLLECTION.TEST_KEY, + waitForCollectionCallback: true, + callback: connectionCallback, + }); + await waitForPromisesToResolve(); + + await Onyx.set(ONYX_KEYS.COLLECTION.TEST_KEY, {foo: 'bar'} as unknown as GenericCollection); + await waitForPromisesToResolve(); + + // The blocked write must not appear as a `{test_: ...}` member. + const lastSnapshot = connectionCallback.mock.calls.at(-1)?.[0]; + expect(lastSnapshot ?? {}).not.toHaveProperty(ONYX_KEYS.COLLECTION.TEST_KEY); + }); + }); + it('should remove key value from OnyxCache/Storage when set is called with null value', () => Onyx.set(ONYX_KEYS.OTHER_TEST, 42) .then(() => OnyxUtils.getAllKeys()) @@ -643,23 +698,7 @@ describe('Onyx', () => { }); }); - it('should overwrite an array key nested inside an object when using merge on a collection', () => { - let testKeyValue: unknown; - connection = Onyx.connect({ - key: ONYX_KEYS.COLLECTION.TEST_KEY, - callback: (value) => { - testKeyValue = value; - }, - }); - - Onyx.merge(ONYX_KEYS.COLLECTION.TEST_KEY, {test_1: {something: [1, 2, 3]}}); - return Onyx.merge(ONYX_KEYS.COLLECTION.TEST_KEY, {test_1: {something: [4]}}).then(() => { - expect(testKeyValue).toEqual({test_1: {something: [4]}}); - }); - }); - it('should properly set and merge when using mergeCollection', async () => { - const valuesReceived: Record = {}; const mockCallback = jest.fn(); connection = Onyx.connect({ key: ONYX_KEYS.COLLECTION.TEST_KEY, @@ -668,7 +707,6 @@ describe('Onyx', () => { await waitForPromisesToResolve(); mockCallback.mockReset(); - mockCallback.mockImplementation((data) => (valuesReceived[data.ID] = data.value)); // The first time we call mergeCollection we'll be doing a multiSet internally return Onyx.mergeCollection(ONYX_KEYS.COLLECTION.TEST_KEY, { @@ -709,20 +747,25 @@ describe('Onyx', () => { } as GenericCollection), ) .then(() => { - // 3 items on the first mergeCollection + 4 items the next mergeCollection - expect(mockCallback).toHaveBeenCalledTimes(7); - expect(mockCallback).toHaveBeenNthCalledWith(1, {ID: 123, value: 'one'}, 'test_1'); - expect(mockCallback).toHaveBeenNthCalledWith(2, {ID: 234, value: 'two'}, 'test_2'); - expect(mockCallback).toHaveBeenNthCalledWith(3, {ID: 345, value: 'three'}, 'test_3'); - expect(mockCallback).toHaveBeenNthCalledWith(4, {ID: 123, value: 'five'}, 'test_1'); - expect(mockCallback).toHaveBeenNthCalledWith(5, {ID: 234, value: 'four'}, 'test_2'); - expect(mockCallback).toHaveBeenNthCalledWith(6, {ID: 456, value: 'two'}, 'test_4'); - expect(mockCallback).toHaveBeenNthCalledWith(7, {ID: 567, value: 'one'}, 'test_5'); - expect(valuesReceived[123]).toEqual('five'); - expect(valuesReceived[234]).toEqual('four'); - expect(valuesReceived[345]).toEqual('three'); - expect(valuesReceived[456]).toEqual('two'); - expect(valuesReceived[567]).toEqual('one'); + // Snapshot mode: callback fires once per mergeCollection with the full snapshot. + expect(mockCallback).toHaveBeenCalledTimes(2); + expect(mockCallback).toHaveBeenNthCalledWith( + 1, + {test_1: {ID: 123, value: 'one'}, test_2: {ID: 234, value: 'two'}, test_3: {ID: 345, value: 'three'}}, + ONYX_KEYS.COLLECTION.TEST_KEY, + ); + expect(mockCallback).toHaveBeenNthCalledWith( + 2, + { + test_1: {ID: 123, value: 'five'}, + test_2: {ID: 234, value: 'four'}, + // test_3 unchanged (incompatible array merge rejected) + test_3: {ID: 345, value: 'three'}, + test_4: {ID: 456, value: 'two'}, + test_5: {ID: 567, value: 'one'}, + }, + ONYX_KEYS.COLLECTION.TEST_KEY, + ); }); }); @@ -739,10 +782,10 @@ describe('Onyx', () => { }); it('should return full object to callback when calling mergeCollection()', () => { - const valuesReceived: Record = {}; + let lastSnapshot: unknown; connection = Onyx.connect({ key: ONYX_KEYS.COLLECTION.TEST_KEY, - callback: (data, key) => (valuesReceived[key] = data), + callback: (snapshot) => (lastSnapshot = snapshot), }); return Onyx.multiSet({ @@ -766,7 +809,7 @@ describe('Onyx', () => { } as GenericCollection), ) .then(() => { - expect(valuesReceived).toEqual({ + expect(lastSnapshot).toEqual({ test_1: { ID: 123, value: 'one', @@ -912,7 +955,6 @@ describe('Onyx', () => { }); it('should use update data object to merge a collection of keys', () => { - const valuesReceived: Record = {}; const mockCallback = jest.fn(); connection = Onyx.connect({ key: ONYX_KEYS.COLLECTION.TEST_KEY, @@ -922,7 +964,6 @@ describe('Onyx', () => { return waitForPromisesToResolve() .then(() => { mockCallback.mockReset(); - mockCallback.mockImplementation((data) => (valuesReceived[data.ID] = data.value)); // Given the initial Onyx state: {test_1: {existingData: 'test',}, test_2: {existingData: 'test',}} Onyx.multiSet({ @@ -936,8 +977,12 @@ describe('Onyx', () => { return waitForPromisesToResolve(); }) .then(() => { - expect(mockCallback).toHaveBeenNthCalledWith(1, {existingData: 'test'}, 'test_1'); - expect(mockCallback).toHaveBeenNthCalledWith(2, {existingData: 'test'}, 'test_2'); + // Snapshot mode: multiSet fires the collection callback per write. + expect(mockCallback).toHaveBeenLastCalledWith( + {test_1: {existingData: 'test'}, test_2: {existingData: 'test'}}, + ONYX_KEYS.COLLECTION.TEST_KEY, + ); + mockCallback.mockReset(); // When we pass a mergeCollection data object to Onyx.update return Onyx.update([ @@ -962,36 +1007,24 @@ describe('Onyx', () => { ]); }) .then(() => { - /* Then the final Onyx state should be: + // mergeCollection fires the collection snapshot once with all 3 merged members. + expect(mockCallback).toHaveBeenCalledTimes(1); + expect(mockCallback).toHaveBeenCalledWith( { - test_1: { - existingData: 'test' - ID: 123, - value: 'one', - }, - test_2: { - existingData: 'test' - ID: 234, - value: 'two', - }, - test_3: { - ID: 345, - value: 'three', - }, - } - */ - - expect(mockCallback).toHaveBeenNthCalledWith(3, {ID: 123, value: 'one', existingData: 'test'}, 'test_1'); - expect(mockCallback).toHaveBeenNthCalledWith(4, {ID: 234, value: 'two', existingData: 'test'}, 'test_2'); - expect(mockCallback).toHaveBeenNthCalledWith(5, {ID: 345, value: 'three'}, 'test_3'); + test_1: {ID: 123, value: 'one', existingData: 'test'}, + test_2: {ID: 234, value: 'two', existingData: 'test'}, + test_3: {ID: 345, value: 'three'}, + }, + ONYX_KEYS.COLLECTION.TEST_KEY, + ); }); }); it('should properly set all keys provided in a multiSet called via update', () => { - const valuesReceived: Record = {}; + let lastSnapshot: unknown; connection = Onyx.connect({ key: ONYX_KEYS.COLLECTION.TEST_KEY, - callback: (data, key) => (valuesReceived[key] = data), + callback: (snapshot) => (lastSnapshot = snapshot), }); return Onyx.multiSet({ @@ -1020,7 +1053,7 @@ describe('Onyx', () => { ] as unknown as Array>), ) .then(() => { - expect(valuesReceived).toEqual({ + expect(lastSnapshot).toEqual({ test_1: { ID: 123, value: 'one', @@ -1065,7 +1098,7 @@ describe('Onyx', () => { .then(() => { // Then we expect the callback to be called only once and the initial stored value to be initialCollectionData expect(mockCallback).toHaveBeenCalledTimes(1); - expect(mockCallback).toHaveBeenCalledWith(initialCollectionData, ONYX_KEYS.COLLECTION.TEST_CONNECT_COLLECTION, undefined); + expect(mockCallback).toHaveBeenCalledWith(initialCollectionData, ONYX_KEYS.COLLECTION.TEST_CONNECT_COLLECTION); }); }); @@ -1090,11 +1123,13 @@ describe('Onyx', () => { // Then we expect the callback to have called twice, once for the initial connect call + once for the collection update expect(mockCallback).toHaveBeenCalledTimes(2); - // AND the value for the first call should be null since the collection was not initialized at that point - expect(mockCallback).toHaveBeenNthCalledWith(1, undefined, ONYX_KEYS.COLLECTION.TEST_POLICY, undefined); + // Initial fire delivers the post-init frozen empty collection `{}` (the legacy + // "undefined for empty-on-initial-fire" shim was removed; callers that needed + // that behavior now guard at the consumer level). + expect(mockCallback).toHaveBeenNthCalledWith(1, {}, ONYX_KEYS.COLLECTION.TEST_POLICY); // AND the value for the second call should be collectionUpdate since the collection was updated - expect(mockCallback).toHaveBeenNthCalledWith(2, collectionUpdate, ONYX_KEYS.COLLECTION.TEST_POLICY, collectionUpdate); + expect(mockCallback).toHaveBeenNthCalledWith(2, collectionUpdate, ONYX_KEYS.COLLECTION.TEST_POLICY); }) ); }); @@ -1119,8 +1154,10 @@ describe('Onyx', () => { // Then we expect the callback to have called twice, once for the initial connect call + once for the collection update expect(mockCallback).toHaveBeenCalledTimes(2); - // AND the value for the first call should be null since the collection was not initialized at that point - expect(mockCallback).toHaveBeenNthCalledWith(1, undefined, undefined); + // Initial fire delivers `(undefined, key)` — the cache has no entry for + // `testPolicy_1` yet, but we still pass the key. (Legacy `(undefined, undefined)` + // no-match shim was removed.) + expect(mockCallback).toHaveBeenNthCalledWith(1, undefined, 'testPolicy_1'); // AND the value for the second call should be collectionUpdate since the collection was updated expect(mockCallback).toHaveBeenNthCalledWith(2, collectionUpdate.testPolicy_1, 'testPolicy_1'); @@ -1148,11 +1185,9 @@ describe('Onyx', () => { // Then we expect the callback to have called twice, once for the initial connect call + once for the collection update expect(mockCallback).toHaveBeenCalledTimes(2); - // AND the value for the second call should be collectionUpdate - expect(mockCallback).toHaveBeenNthCalledWith(1, undefined, ONYX_KEYS.COLLECTION.TEST_POLICY, undefined); - expect(mockCallback).toHaveBeenNthCalledWith(2, collectionUpdate, ONYX_KEYS.COLLECTION.TEST_POLICY, { - [`${ONYX_KEYS.COLLECTION.TEST_POLICY}1`]: collectionUpdate.testPolicy_1, - }); + // Initial fire delivers `{}` (legacy `undefined`-for-empty-initial shim was removed). + expect(mockCallback).toHaveBeenNthCalledWith(1, {}, ONYX_KEYS.COLLECTION.TEST_POLICY); + expect(mockCallback).toHaveBeenNthCalledWith(2, collectionUpdate, ONYX_KEYS.COLLECTION.TEST_POLICY); }) ); }); @@ -1187,7 +1222,7 @@ describe('Onyx', () => { expect(mockCallback).toHaveBeenCalledTimes(2); // And the value for the second call should be collectionUpdate - expect(mockCallback).toHaveBeenNthCalledWith(2, collectionUpdate, ONYX_KEYS.COLLECTION.TEST_POLICY, {testPolicy_1: collectionUpdate.testPolicy_1}); + expect(mockCallback).toHaveBeenNthCalledWith(2, collectionUpdate, ONYX_KEYS.COLLECTION.TEST_POLICY); }) // When merge is called again with the same collection not modified @@ -1224,11 +1259,13 @@ describe('Onyx', () => { {onyxMethod: Onyx.METHOD.MERGE_COLLECTION, key: ONYX_KEYS.COLLECTION.TEST_UPDATE, value: {[itemKey]: {a: 'a'}} as GenericCollection}, ]).then(() => { expect(collectionCallback).toHaveBeenCalledTimes(2); - expect(collectionCallback).toHaveBeenNthCalledWith(1, undefined, ONYX_KEYS.COLLECTION.TEST_UPDATE, undefined); - expect(collectionCallback).toHaveBeenNthCalledWith(2, {[itemKey]: {a: 'a'}}, ONYX_KEYS.COLLECTION.TEST_UPDATE, {[itemKey]: {a: 'a'}}); + // Initial fire delivers `{}` (legacy `undefined`-for-empty-initial shim was removed). + expect(collectionCallback).toHaveBeenNthCalledWith(1, {}, ONYX_KEYS.COLLECTION.TEST_UPDATE); + expect(collectionCallback).toHaveBeenNthCalledWith(2, {[itemKey]: {a: 'a'}}, ONYX_KEYS.COLLECTION.TEST_UPDATE); expect(testCallback).toHaveBeenCalledTimes(2); - expect(testCallback).toHaveBeenNthCalledWith(1, undefined, undefined); + // Initial fire delivers `(undefined, key)` — cache has no entry yet, but we still pass the key. + expect(testCallback).toHaveBeenNthCalledWith(1, undefined, ONYX_KEYS.TEST_KEY); expect(testCallback).toHaveBeenNthCalledWith(2, 'taco', ONYX_KEYS.TEST_KEY); expect(otherTestCallback).toHaveBeenCalledTimes(2); @@ -1483,8 +1520,8 @@ describe('Onyx', () => { }) .then(() => { expect(collectionCallback).toHaveBeenCalledTimes(2); - expect(collectionCallback).toHaveBeenNthCalledWith(1, {[cat]: initialValue}, ONYX_KEYS.COLLECTION.ANIMALS, {[cat]: initialValue}); - expect(collectionCallback).toHaveBeenNthCalledWith(2, collectionDiff, ONYX_KEYS.COLLECTION.ANIMALS, {[cat]: initialValue, [dog]: {name: 'Rex'}}); + expect(collectionCallback).toHaveBeenNthCalledWith(1, {[cat]: initialValue}, ONYX_KEYS.COLLECTION.ANIMALS); + expect(collectionCallback).toHaveBeenNthCalledWith(2, collectionDiff, ONYX_KEYS.COLLECTION.ANIMALS); // Cat hasn't changed from its original value, expect only the initial connect callback expect(catCallback).toHaveBeenCalledTimes(1); @@ -1517,9 +1554,10 @@ describe('Onyx', () => { await Onyx.update([{key: cat, value: finalValue, onyxMethod: Onyx.METHOD.MERGE}]); + // Snapshot mode: callback fires with the whole SNAPSHOT-collection snapshot. expect(callback).toBeCalledTimes(2); - expect(callback).toHaveBeenNthCalledWith(1, {data: {[cat]: initialValue}}, snapshot1); - expect(callback).toHaveBeenNthCalledWith(2, {data: {[cat]: finalValue}}, snapshot1); + expect(callback).toHaveBeenNthCalledWith(1, {[snapshot1]: {data: {[cat]: initialValue}}}, ONYX_KEYS.COLLECTION.SNAPSHOT); + expect(callback).toHaveBeenNthCalledWith(2, {[snapshot1]: {data: {[cat]: finalValue}}}, ONYX_KEYS.COLLECTION.SNAPSHOT); }); it('should merge allowlisted keys into Snapshot even if they were missing', async () => { @@ -1548,9 +1586,14 @@ describe('Onyx', () => { await Onyx.update([{key: cat, value: finalValue, onyxMethod: Onyx.METHOD.MERGE}]); + // Snapshot mode: callback fires with the whole SNAPSHOT-collection snapshot. expect(callback).toBeCalledTimes(2); - expect(callback).toHaveBeenNthCalledWith(1, {data: {[cat]: initialValue}}, snapshot1); - expect(callback).toHaveBeenNthCalledWith(2, {data: {[cat]: {name: 'Kitty', pendingAction: 'delete', pendingFields: {preview: 'delete'}}}}, snapshot1); + expect(callback).toHaveBeenNthCalledWith(1, {[snapshot1]: {data: {[cat]: initialValue}}}, ONYX_KEYS.COLLECTION.SNAPSHOT); + expect(callback).toHaveBeenNthCalledWith( + 2, + {[snapshot1]: {data: {[cat]: {name: 'Kitty', pendingAction: 'delete', pendingFields: {preview: 'delete'}}}}}, + ONYX_KEYS.COLLECTION.SNAPSHOT, + ); }); describe('update', () => { @@ -1638,6 +1681,11 @@ describe('Onyx', () => { }, }, ]).then(() => { + // Initial fire is deferred past in-flight writes via `scheduleInitialFire`, + // so it reads the post-update snapshot. The write-driven fire already + // delivered the same snapshot, so the dedup in `deliverSnapshot` suppresses + // the initial fire — matching legacy timing. + expect(routesCollectionCallback).toHaveBeenCalledTimes(1); expect(routesCollectionCallback).toHaveBeenNthCalledWith( 1, { @@ -1660,10 +1708,6 @@ describe('Onyx', () => { }, }, ONYX_KEYS.COLLECTION.ROUTES, - { - [holidayRoute]: {waypoints: {0: 'Bed', 1: 'Home', 2: 'Beach', 3: 'Restaurant', 4: 'Home'}}, - [routineRoute]: {waypoints: {0: 'Bed', 1: 'Home', 2: 'Work', 3: 'Gym'}}, - }, ); connections.map((id) => Onyx.disconnect(id)); @@ -1724,38 +1768,31 @@ describe('Onyx', () => { {onyxMethod: Onyx.METHOD.MERGE, key: lisa, value: {car: 'SUV', age: 21}}, {onyxMethod: Onyx.METHOD.MERGE, key: bob, value: {age: 25}}, ]).then(() => { - expect(testCallback).toHaveBeenNthCalledWith(1, {food: 'taco', drink: 'wine'}, ONYX_KEYS.TEST_KEY); + // The store-based wrapper always fires an initial callback before the + // post-update callback (the legacy ConnectionManager's deep-promise chain + // suppressed it accidentally). We assert on the final post-update call + // via `toHaveBeenLastCalledWith` instead of pinning specific indices. + // The `sourceValue` 3rd argument was also dropped. + expect(testCallback).toHaveBeenLastCalledWith({food: 'taco', drink: 'wine'}, ONYX_KEYS.TEST_KEY); - expect(otherTestCallback).toHaveBeenNthCalledWith(1, {food: 'pizza', drink: 'water'}, ONYX_KEYS.OTHER_TEST); + expect(otherTestCallback).toHaveBeenLastCalledWith({food: 'pizza', drink: 'water'}, ONYX_KEYS.OTHER_TEST); - expect(animalsCollectionCallback).toHaveBeenNthCalledWith( - 1, - { - [cat]: {age: 3, sound: 'meow'}, - }, - ONYX_KEYS.COLLECTION.ANIMALS, - {[cat]: {age: 3, sound: 'meow'}}, - ); - expect(animalsCollectionCallback).toHaveBeenNthCalledWith( - 2, + expect(animalsCollectionCallback).toHaveBeenLastCalledWith( { [cat]: {age: 3, sound: 'meow'}, [dog]: {size: 'M', sound: 'woof'}, }, ONYX_KEYS.COLLECTION.ANIMALS, - {[dog]: {size: 'M', sound: 'woof'}}, ); - expect(catCallback).toHaveBeenNthCalledWith(1, {age: 3, sound: 'meow'}, cat); + expect(catCallback).toHaveBeenLastCalledWith({age: 3, sound: 'meow'}, cat); - expect(peopleCollectionCallback).toHaveBeenNthCalledWith( - 1, + expect(peopleCollectionCallback).toHaveBeenLastCalledWith( { [bob]: {age: 25, car: 'sedan'}, [lisa]: {age: 21, car: 'SUV'}, }, ONYX_KEYS.COLLECTION.PEOPLE, - {[bob]: {age: 25, car: 'sedan'}, [lisa]: {age: 21, car: 'SUV'}}, ); connections.map((id) => Onyx.disconnect(id)); @@ -3170,7 +3207,11 @@ describe('RAM-only keys should not read from storage', () => { }); await act(async () => waitForPromisesToResolve()); - expect(receivedCollection).toBeUndefined(); + // Initial fire delivers the post-init frozen `{}` snapshot for a known-but-empty + // collection (legacy `undefined`-for-empty-initial shim was removed). What matters + // for this test is that the RAM-only members have NOT been hydrated from storage — + // the snapshot has no entries, and `cache.get(member)` returns `undefined`. + expect(receivedCollection).toEqual({}); expect(cache.get(collectionMember1)).toBeUndefined(); expect(cache.get(collectionMember2)).toBeUndefined(); diff --git a/tests/unit/onyxUtilsTest.ts b/tests/unit/onyxUtilsTest.ts index 2bdb9169e..6f3c35970 100644 --- a/tests/unit/onyxUtilsTest.ts +++ b/tests/unit/onyxUtilsTest.ts @@ -432,215 +432,6 @@ describe('OnyxUtils', () => { }); }); - describe('keysChanged', () => { - beforeEach(() => { - Onyx.clear(); - }); - - afterEach(() => { - Onyx.clear(); - }); - - it('should call callback when data actually changes for collection member key subscribers', async () => { - const callbackSpy = jest.fn(); - const entryKey = `${ONYXKEYS.COLLECTION.TEST_KEY}123`; - const connection = Onyx.connect({ - key: entryKey, - callback: callbackSpy, - }); - - const entryData = {value: 'updated_data'}; - - // Create partial collection data that includes our member key - const collection = { - [entryKey]: entryData, - } as Collection; - - // Clear the callback spy to focus on the keysChanged behavior - callbackSpy.mockClear(); - - await Onyx.setCollection(ONYXKEYS.COLLECTION.TEST_KEY, collection); - - // Verify the subscriber callback was called - expect(callbackSpy).toHaveBeenCalledTimes(1); - expect(callbackSpy).toHaveBeenCalledWith(entryData, entryKey); - - await Onyx.disconnect(connection); - }); - - it('should set lastConnectionCallbackData for collection member key subscribers', async () => { - const entryKey = `${ONYXKEYS.COLLECTION.TEST_KEY}456`; - const initialEntryData = {value: 'initial_data'}; - const updatedEntryData = {value: 'updated_data'}; - const newEntryData = {value: 'new_data'}; - const callbackSpy = jest.fn(); - - const connection = await Onyx.connect({ - key: entryKey, - callback: callbackSpy, - }); - - // Create partial collection data that includes our member key - const initialCollection = { - [entryKey]: initialEntryData, - } as Collection; - - // Clear the callback spy to focus on the keysChanged behavior - callbackSpy.mockClear(); - - OnyxUtils.keysChanged( - ONYXKEYS.COLLECTION.TEST_KEY, - {[entryKey]: updatedEntryData}, // new collection - initialCollection, // previous collection - ); - - // Should be called again because data changed - expect(callbackSpy).toHaveBeenCalledTimes(1); - expect(callbackSpy).toHaveBeenCalledWith(undefined, entryKey); - - // Clear the callback spy to focus on the keyChanged behavior - callbackSpy.mockClear(); - - OnyxUtils.keyChanged( - entryKey, - newEntryData, // Second update with different data - () => true, // notify connect subscribers - ); - - // Should be called again because data changed - expect(callbackSpy).toHaveBeenCalledTimes(1); - expect(callbackSpy).toHaveBeenCalledWith(newEntryData, entryKey); - - await Onyx.disconnect(connection); - }); - - it('should notify collection-level subscribers with waitForCollectionCallback', async () => { - const entryKey = `${ONYXKEYS.COLLECTION.TEST_KEY}789`; - const entryData = {value: 'data'}; - - const collectionCallback = jest.fn(); - const connection = Onyx.connect({ - key: ONYXKEYS.COLLECTION.TEST_KEY, - callback: collectionCallback, - waitForCollectionCallback: true, - }); - - await Onyx.set(entryKey, entryData); - collectionCallback.mockClear(); - - // Trigger keysChanged directly with a partial collection - OnyxUtils.keysChanged(ONYXKEYS.COLLECTION.TEST_KEY, {[entryKey]: entryData}, {}); - - expect(collectionCallback).toHaveBeenCalledTimes(1); - // Collection subscriber receives the full cached collection, subscriber.key, and partial - const [receivedCollection, receivedKey, receivedPartial] = collectionCallback.mock.calls[0]; - expect(receivedKey).toBe(ONYXKEYS.COLLECTION.TEST_KEY); - expect(receivedCollection[entryKey]).toEqual(entryData); - expect(receivedPartial).toEqual({[entryKey]: entryData}); - - Onyx.disconnect(connection); - }); - - it('should skip notification when member value has same reference in previous and current collection', async () => { - const entryKey = `${ONYXKEYS.COLLECTION.TEST_KEY}same`; - const sameValue = {value: 'unchanged'}; - - await Onyx.set(entryKey, sameValue); - - const callbackSpy = jest.fn(); - const connection = Onyx.connect({ - key: entryKey, - callback: callbackSpy, - }); - await waitForPromisesToResolve(); - callbackSpy.mockClear(); - - // Simulate keysChanged where the previous and current value are the SAME reference - // (which happens with frozen snapshots when nothing changed). === should skip notification. - OnyxUtils.keysChanged(ONYXKEYS.COLLECTION.TEST_KEY, {[entryKey]: sameValue}, {[entryKey]: sameValue}); - - expect(callbackSpy).not.toHaveBeenCalled(); - - Onyx.disconnect(connection); - }); - - it('should notify member subscribers only for changed keys in a batched update', async () => { - const keyA = `${ONYXKEYS.COLLECTION.TEST_KEY}A`; - const keyB = `${ONYXKEYS.COLLECTION.TEST_KEY}B`; - const keyC = `${ONYXKEYS.COLLECTION.TEST_KEY}C`; - - const dataA = {value: 'A'}; - const dataB = {value: 'B'}; - const dataC = {value: 'C'}; - - await Onyx.multiSet({[keyA]: dataA, [keyB]: dataB, [keyC]: dataC}); - - const spyA = jest.fn(); - const spyB = jest.fn(); - const spyC = jest.fn(); - const connA = Onyx.connect({key: keyA, callback: spyA}); - const connB = Onyx.connect({key: keyB, callback: spyB}); - const connC = Onyx.connect({key: keyC, callback: spyC}); - await waitForPromisesToResolve(); - spyA.mockClear(); - spyB.mockClear(); - spyC.mockClear(); - - // Update cache so keysChanged reads the new values via getCachedCollection - const newA = {value: 'A-updated'}; - const newC = {value: 'C-updated'}; - OnyxCache.set(keyA, newA); - OnyxCache.set(keyC, newC); - // keyB stays the same reference - - OnyxUtils.keysChanged(ONYXKEYS.COLLECTION.TEST_KEY, {[keyA]: newA, [keyB]: dataB, [keyC]: newC}, {[keyA]: dataA, [keyB]: dataB, [keyC]: dataC}); - - expect(spyA).toHaveBeenCalledTimes(1); - expect(spyB).not.toHaveBeenCalled(); - expect(spyC).toHaveBeenCalledTimes(1); - - Onyx.disconnect(connA); - Onyx.disconnect(connB); - Onyx.disconnect(connC); - }); - - it('should catch errors thrown by subscriber callbacks and continue notifying others', async () => { - const entryKey = `${ONYXKEYS.COLLECTION.TEST_KEY}errorTest`; - const entryData = {value: 'data'}; - - await Onyx.set(entryKey, entryData); - - const failingCallback = jest.fn(); - const workingCallback = jest.fn(); - - const connFailing = Onyx.connect({key: entryKey, callback: failingCallback, reuseConnection: false}); - const connWorking = Onyx.connect({key: entryKey, callback: workingCallback, reuseConnection: false}); - await waitForPromisesToResolve(); - failingCallback.mockReset(); - failingCallback.mockImplementation(() => { - throw new Error('subscriber failure'); - }); - workingCallback.mockClear(); - - // Spy on Logger to verify the error is logged - const logSpy = jest.spyOn(Logger, 'logAlert').mockImplementation(() => undefined); - - const newData = {value: 'new'}; - // Update the cache so keysChanged sees the new value as different from previous - OnyxCache.set(entryKey, newData); - OnyxUtils.keysChanged(ONYXKEYS.COLLECTION.TEST_KEY, {[entryKey]: newData}, {[entryKey]: entryData}); - - // Both callbacks should have been attempted; error should be logged - expect(failingCallback).toHaveBeenCalled(); - expect(workingCallback).toHaveBeenCalled(); - expect(logSpy).toHaveBeenCalled(); - - logSpy.mockRestore(); - Onyx.disconnect(connFailing); - Onyx.disconnect(connWorking); - }); - }); - describe('mergeChanges', () => { it("should return the last change if it's an array", () => { const {result} = OnyxUtils.mergeChanges([...testMergeChanges, [0, 1, 2]], testObject); diff --git a/tests/unit/useOnyxStateTest.tsx b/tests/unit/useOnyxStateTest.tsx new file mode 100644 index 000000000..25d6faefa --- /dev/null +++ b/tests/unit/useOnyxStateTest.tsx @@ -0,0 +1,287 @@ +import {act, renderHook} from '@testing-library/react-native'; +import Onyx from '../../lib'; +import useOnyxState from '../../lib/useOnyxState'; +import type {OnyxStateView} from '../../lib/useOnyxState'; +import waitForPromisesToResolve from '../utils/waitForPromisesToResolve'; +import type GenericCollection from '../utils/GenericCollection'; + +const ONYXKEYS = { + TEST_KEY: 'test', + OTHER_TEST: 'otherTest', + COLLECTION: { + TEST_KEY: 'test_', + }, +}; + +const COLLECTION = ONYXKEYS.COLLECTION.TEST_KEY; +const MEMBER_1 = `${COLLECTION}1`; +const MEMBER_2 = `${COLLECTION}2`; + +Onyx.init({ + keys: ONYXKEYS, +}); + +beforeEach(() => Onyx.clear()); + +describe('useOnyxState', () => { + describe('basic subscription', () => { + it('should return the derived value from a single dependency', async () => { + await Onyx.set(ONYXKEYS.TEST_KEY, 'hello'); + + const {result} = renderHook(() => useOnyxState((state) => state[ONYXKEYS.TEST_KEY], {dependencies: [ONYXKEYS.TEST_KEY]})); + await act(async () => waitForPromisesToResolve()); + + expect(result.current).toEqual('hello'); + }); + + it('should update when the dependency changes', async () => { + const {result} = renderHook(() => useOnyxState((state) => state[ONYXKEYS.TEST_KEY], {dependencies: [ONYXKEYS.TEST_KEY]})); + await act(async () => waitForPromisesToResolve()); + + await act(async () => { + Onyx.set(ONYXKEYS.TEST_KEY, 'updated'); + return waitForPromisesToResolve(); + }); + + expect(result.current).toEqual('updated'); + }); + + it('should NOT re-render when a non-dependency key changes', async () => { + let renderCount = 0; + const {result} = renderHook(() => { + renderCount += 1; + return useOnyxState((state) => state[ONYXKEYS.TEST_KEY], {dependencies: [ONYXKEYS.TEST_KEY]}); + }); + await act(async () => waitForPromisesToResolve()); + + const renderCountAfterMount = renderCount; + + await act(async () => { + Onyx.set(ONYXKEYS.OTHER_TEST, 'irrelevant'); + return waitForPromisesToResolve(); + }); + + expect(renderCount).toEqual(renderCountAfterMount); + expect(result.current).toBeUndefined(); + }); + + it('should re-run when any of multiple dependencies change', async () => { + const {result} = renderHook(() => + useOnyxState((state) => `${state[ONYXKEYS.TEST_KEY] ?? ''}-${state[ONYXKEYS.OTHER_TEST] ?? ''}`, {dependencies: [ONYXKEYS.TEST_KEY, ONYXKEYS.OTHER_TEST]}), + ); + await act(async () => waitForPromisesToResolve()); + + await act(async () => { + Onyx.set(ONYXKEYS.TEST_KEY, 'a'); + return waitForPromisesToResolve(); + }); + expect(result.current).toEqual('a-'); + + await act(async () => { + Onyx.set(ONYXKEYS.OTHER_TEST, 'b'); + return waitForPromisesToResolve(); + }); + expect(result.current).toEqual('a-b'); + }); + }); + + describe('collection dependency', () => { + it('should re-run when any member of a collection dependency changes', async () => { + const {result} = renderHook(() => useOnyxState((state) => Object.keys(state[COLLECTION] ?? {}).length, {dependencies: [COLLECTION]})); + await act(async () => waitForPromisesToResolve()); + + expect(result.current).toEqual(0); + + await act(async () => { + Onyx.merge(MEMBER_1, {id: 1}); + return waitForPromisesToResolve(); + }); + expect(result.current).toEqual(1); + + await act(async () => { + Onyx.merge(MEMBER_2, {id: 2}); + return waitForPromisesToResolve(); + }); + expect(result.current).toEqual(2); + }); + + it('should re-run on a mergeCollection write', async () => { + const {result} = renderHook(() => useOnyxState((state) => Object.keys(state[COLLECTION] ?? {}).length, {dependencies: [COLLECTION]})); + await act(async () => waitForPromisesToResolve()); + + await act(async () => { + Onyx.mergeCollection(COLLECTION, {[MEMBER_1]: {id: 1}, [MEMBER_2]: {id: 2}} as GenericCollection); + return waitForPromisesToResolve(); + }); + + expect(result.current).toEqual(2); + }); + }); + + describe('previousState', () => { + it('should pass undefined as previousState on the first selector run', async () => { + const observed: Array = []; + renderHook(() => + useOnyxState( + (state, previousState) => { + observed.push(previousState); + return state[ONYXKEYS.TEST_KEY]; + }, + {dependencies: [ONYXKEYS.TEST_KEY]}, + ), + ); + await act(async () => waitForPromisesToResolve()); + + // The very first invocation always runs before any output has been captured. + expect(observed[0]).toBeUndefined(); + }); + + it('should expose the prior dependency value through previousState after a change', async () => { + await Onyx.set(ONYXKEYS.TEST_KEY, 'a'); + + let sawCurrentBWithPreviousA = false; + const {rerender} = renderHook(() => + useOnyxState( + (state, previousState) => { + if (state[ONYXKEYS.TEST_KEY] === 'b' && previousState?.[ONYXKEYS.TEST_KEY] === 'a') { + sawCurrentBWithPreviousA = true; + } + return state[ONYXKEYS.TEST_KEY]; + }, + {dependencies: [ONYXKEYS.TEST_KEY]}, + ), + ); + await act(async () => waitForPromisesToResolve()); + + await act(async () => { + Onyx.set(ONYXKEYS.TEST_KEY, 'b'); + return waitForPromisesToResolve(); + }); + rerender(undefined); + + expect(sawCurrentBWithPreviousA).toBeTruthy(); + }); + }); + + describe('previousState-dependent output (delta selectors)', () => { + // `previousState` is advanced post-commit, so a selector whose OUTPUT depends on it + // is stable: within a render the previous view is frozen, so repeated getSnapshot + // calls produce the same delta. + it('should return a stable delta of which collection members changed since the last render', async () => { + await Onyx.mergeCollection(COLLECTION, {[MEMBER_1]: {v: 1}, [MEMBER_2]: {v: 1}} as GenericCollection); + + const {result} = renderHook(() => + useOnyxState( + (state, previousState) => { + const current = (state[COLLECTION] ?? {}) as Record; + const previous = (previousState?.[COLLECTION] ?? {}) as Record; + return Object.keys(current) + .filter((memberKey) => current[memberKey] !== previous[memberKey]) + .sort(); + }, + {dependencies: [COLLECTION]}, + ), + ); + await act(async () => waitForPromisesToResolve()); + + // Change only MEMBER_2 — the delta should contain exactly MEMBER_2. + await act(async () => { + Onyx.merge(MEMBER_2, {v: 2}); + return waitForPromisesToResolve(); + }); + + expect(result.current).toEqual([MEMBER_2]); + }); + + it('should recompute the delta on each subsequent change (previousState advances per commit)', async () => { + await Onyx.mergeCollection(COLLECTION, {[MEMBER_1]: {v: 1}, [MEMBER_2]: {v: 1}} as GenericCollection); + + const {result} = renderHook(() => + useOnyxState( + (state, previousState) => { + const current = (state[COLLECTION] ?? {}) as Record; + const previous = (previousState?.[COLLECTION] ?? {}) as Record; + return Object.keys(current) + .filter((memberKey) => current[memberKey] !== previous[memberKey]) + .sort(); + }, + {dependencies: [COLLECTION]}, + ), + ); + await act(async () => waitForPromisesToResolve()); + + await act(async () => { + Onyx.merge(MEMBER_1, {v: 9}); + return waitForPromisesToResolve(); + }); + expect(result.current).toEqual([MEMBER_1]); + + // A second, independent change must report only MEMBER_2 — proving `previousState` + // advanced to the post-first-change snapshot rather than staying at the original. + await act(async () => { + Onyx.merge(MEMBER_2, {v: 9}); + return waitForPromisesToResolve(); + }); + expect(result.current).toEqual([MEMBER_2]); + }); + }); + + describe('selectorEquality', () => { + it('should preserve the output reference when the new output is deep-equal (default equality)', async () => { + const {result} = renderHook(() => useOnyxState((state) => ({length: ((state[ONYXKEYS.TEST_KEY] as string) ?? '').length}), {dependencies: [ONYXKEYS.TEST_KEY]})); + await act(async () => waitForPromisesToResolve()); + + await act(async () => { + Onyx.set(ONYXKEYS.TEST_KEY, 'aa'); + return waitForPromisesToResolve(); + }); + const referenceAfterFirstChange = result.current; + expect(referenceAfterFirstChange).toEqual({length: 2}); + + // New input, same-length string → deep-equal output → the previous reference is kept. + await act(async () => { + Onyx.set(ONYXKEYS.TEST_KEY, 'bb'); + return waitForPromisesToResolve(); + }); + + expect(result.current).toBe(referenceAfterFirstChange); + }); + + it('should never update after the first value when a custom equality always returns true', async () => { + const {result} = renderHook(() => + useOnyxState((state) => state[ONYXKEYS.TEST_KEY] ?? 'none', { + dependencies: [ONYXKEYS.TEST_KEY], + selectorEquality: () => true, + }), + ); + await act(async () => waitForPromisesToResolve()); + + expect(result.current).toEqual('none'); + + await act(async () => { + Onyx.set(ONYXKEYS.TEST_KEY, 'changed'); + return waitForPromisesToResolve(); + }); + + // Custom equality reports "unchanged", so the React update is skipped. + expect(result.current).toEqual('none'); + }); + + it('should update when a custom equality reports the output changed', async () => { + const {result} = renderHook(() => + useOnyxState((state) => state[ONYXKEYS.TEST_KEY] ?? 'none', { + dependencies: [ONYXKEYS.TEST_KEY], + selectorEquality: (a, b) => a === b, + }), + ); + await act(async () => waitForPromisesToResolve()); + + await act(async () => { + Onyx.set(ONYXKEYS.TEST_KEY, 'changed'); + return waitForPromisesToResolve(); + }); + + expect(result.current).toEqual('changed'); + }); + }); +}); diff --git a/tests/unit/useOnyxTest.ts b/tests/unit/useOnyxTest.ts index d5b9d0017..7676a8d9f 100644 --- a/tests/unit/useOnyxTest.ts +++ b/tests/unit/useOnyxTest.ts @@ -4,7 +4,6 @@ import Onyx, {useOnyx} from '../../lib'; import StorageMock from '../../lib/storage'; import type GenericCollection from '../utils/GenericCollection'; import waitForPromisesToResolve from '../utils/waitForPromisesToResolve'; -import onyxSnapshotCache from '../../lib/OnyxSnapshotCache'; import type {UseOnyxSelector} from '../../lib/useOnyx'; const ONYXKEYS = { @@ -27,8 +26,6 @@ Onyx.init({ beforeEach(async () => { await Onyx.clear(); - onyxSnapshotCache.clear(); - onyxSnapshotCache.clearSelectorIds(); }); describe('useOnyx', () => { @@ -53,27 +50,6 @@ describe('useOnyx', () => { } }); - it('should transition through loading when switching between collection member keys that both resolve to undefined', async () => { - const {result, rerender} = renderHook((key: string) => useOnyx(key), {initialProps: `${ONYXKEYS.COLLECTION.TEST_KEY}1` as string}); - - // Wait for initial key to fully load - await act(async () => waitForPromisesToResolve()); - - expect(result.current[0]).toBeUndefined(); - expect(result.current[1].status).toEqual('loaded'); - - // Switch to another collection member key that also has no data - rerender(`${ONYXKEYS.COLLECTION.TEST_KEY}2`); - - expect(result.current[0]).toBeUndefined(); - expect(result.current[1].status).toEqual('loading'); - - await act(async () => waitForPromisesToResolve()); - - expect(result.current[0]).toBeUndefined(); - expect(result.current[1].status).toEqual('loaded'); - }); - it('should return cached value immediately with loaded status when switching to a key that has data', async () => { Onyx.set(`${ONYXKEYS.COLLECTION.TEST_KEY}2`, 'test_value'); @@ -97,28 +73,6 @@ describe('useOnyx', () => { expect(result.current[1].status).toEqual('loaded'); }); - it('should clear previous data and transition through loading when switching from a key with data to one without', async () => { - Onyx.set(`${ONYXKEYS.COLLECTION.TEST_KEY}1`, 'initial_value'); - - const {result, rerender} = renderHook((key: string) => useOnyx(key), {initialProps: `${ONYXKEYS.COLLECTION.TEST_KEY}1` as string}); - - await act(async () => waitForPromisesToResolve()); - - expect(result.current[0]).toEqual('initial_value'); - expect(result.current[1].status).toEqual('loaded'); - - // Switch to a key that has no data - rerender(`${ONYXKEYS.COLLECTION.TEST_KEY}2`); - - expect(result.current[0]).toBeUndefined(); - expect(result.current[1].status).toEqual('loading'); - - await act(async () => waitForPromisesToResolve()); - - expect(result.current[0]).toBeUndefined(); - expect(result.current[1].status).toEqual('loaded'); - }); - it('should return the new value when switching from a key with data to another key with different data', async () => { Onyx.set(`${ONYXKEYS.COLLECTION.TEST_KEY}1`, 'value_one'); Onyx.set(`${ONYXKEYS.COLLECTION.TEST_KEY}2`, 'value_two'); @@ -239,30 +193,6 @@ describe('useOnyx', () => { }); describe('misc', () => { - it('should initially return loading state while loading non-existent key, and then return `undefined` and loaded state', async () => { - const {result} = renderHook(() => useOnyx(ONYXKEYS.TEST_KEY)); - - expect(result.current[0]).toBeUndefined(); - expect(result.current[1].status).toEqual('loading'); - - await act(async () => waitForPromisesToResolve()); - - expect(result.current[0]).toBeUndefined(); - expect(result.current[1].status).toEqual('loaded'); - }); - - it('should initially return loading state while loading non-existent collection key, and then return `undefined` and loaded state', async () => { - const {result} = renderHook(() => useOnyx(ONYXKEYS.COLLECTION.TEST_KEY)); - - expect(result.current[0]).toBeUndefined(); - expect(result.current[1].status).toEqual('loading'); - - await act(async () => waitForPromisesToResolve()); - - expect(result.current[0]).toBeUndefined(); - expect(result.current[1].status).toEqual('loaded'); - }); - it('should return value and loaded state when loading cached key', async () => { Onyx.set(ONYXKEYS.TEST_KEY, 'test'); @@ -272,36 +202,6 @@ describe('useOnyx', () => { expect(result.current[1].status).toEqual('loaded'); }); - it('should initially return `undefined` while loading non-cached key, and then return value and loaded state', async () => { - await StorageMock.setItem(ONYXKEYS.TEST_KEY, 'test'); - - const {result} = renderHook(() => useOnyx(ONYXKEYS.TEST_KEY)); - - expect(result.current[0]).toBeUndefined(); - expect(result.current[1].status).toEqual('loading'); - - await act(async () => waitForPromisesToResolve()); - - expect(result.current[0]).toEqual('test'); - expect(result.current[1].status).toEqual('loaded'); - }); - - it('should initially return undefined and then return cached value after multiple merge operations', async () => { - Onyx.merge(ONYXKEYS.TEST_KEY, 'test1'); - Onyx.merge(ONYXKEYS.TEST_KEY, 'test2'); - Onyx.merge(ONYXKEYS.TEST_KEY, 'test3'); - - const {result} = renderHook(() => useOnyx(ONYXKEYS.TEST_KEY)); - - expect(result.current[0]).toBeUndefined(); - expect(result.current[1].status).toEqual('loading'); - - await act(async () => waitForPromisesToResolve()); - - expect(result.current[0]).toEqual('test3'); - expect(result.current[1].status).toEqual('loaded'); - }); - it('should return value from cache, and return updated value after a merge operation', async () => { Onyx.set(ONYXKEYS.TEST_KEY, 'test1'); @@ -338,75 +238,6 @@ describe('useOnyx', () => { expect(result2.current[1].status).toEqual('loaded'); }); - it('should return updated state when connecting to the same regular key after an Onyx.clear() call', async () => { - await StorageMock.setItem(ONYXKEYS.TEST_KEY, 'test'); - - const {result: result1} = renderHook(() => useOnyx(ONYXKEYS.TEST_KEY)); - - await act(async () => waitForPromisesToResolve()); - - expect(result1.current[0]).toEqual('test'); - expect(result1.current[1].status).toEqual('loaded'); - - await act(async () => Onyx.clear()); - - const {result: result2} = renderHook(() => useOnyx(ONYXKEYS.TEST_KEY)); - const {result: result3} = renderHook(() => useOnyx(ONYXKEYS.TEST_KEY)); - - await act(async () => waitForPromisesToResolve()); - - expect(result1.current[0]).toBeUndefined(); - expect(result1.current[1].status).toEqual('loaded'); - expect(result2.current[0]).toBeUndefined(); - expect(result2.current[1].status).toEqual('loaded'); - expect(result3.current[0]).toBeUndefined(); - expect(result3.current[1].status).toEqual('loaded'); - - Onyx.merge(ONYXKEYS.TEST_KEY, 'test2'); - await act(async () => waitForPromisesToResolve()); - - expect(result1.current[0]).toEqual('test2'); - expect(result1.current[1].status).toEqual('loaded'); - expect(result2.current[0]).toEqual('test2'); - expect(result2.current[1].status).toEqual('loaded'); - expect(result3.current[0]).toEqual('test2'); - expect(result3.current[1].status).toEqual('loaded'); - }); - - it('should return updated state when connecting to the same colection member key after an Onyx.clear() call', async () => { - await StorageMock.setItem(`${ONYXKEYS.COLLECTION.TEST_KEY}entry1`, 'test'); - - const {result: result1} = renderHook(() => useOnyx(`${ONYXKEYS.COLLECTION.TEST_KEY}entry1`)); - - await act(async () => waitForPromisesToResolve()); - - expect(result1.current[0]).toEqual('test'); - expect(result1.current[1].status).toEqual('loaded'); - - await act(async () => Onyx.clear()); - - const {result: result2} = renderHook(() => useOnyx(`${ONYXKEYS.COLLECTION.TEST_KEY}entry1`)); - const {result: result3} = renderHook(() => useOnyx(`${ONYXKEYS.COLLECTION.TEST_KEY}entry1`)); - - await act(async () => waitForPromisesToResolve()); - - expect(result1.current[0]).toBeUndefined(); - expect(result1.current[1].status).toEqual('loaded'); - expect(result2.current[0]).toBeUndefined(); - expect(result2.current[1].status).toEqual('loaded'); - expect(result3.current[0]).toBeUndefined(); - expect(result3.current[1].status).toEqual('loaded'); - - Onyx.merge(`${ONYXKEYS.COLLECTION.TEST_KEY}entry1`, 'test2'); - await act(async () => waitForPromisesToResolve()); - - expect(result1.current[0]).toEqual('test2'); - expect(result1.current[1].status).toEqual('loaded'); - expect(result2.current[0]).toEqual('test2'); - expect(result2.current[1].status).toEqual('loaded'); - expect(result3.current[0]).toEqual('test2'); - expect(result3.current[1].status).toEqual('loaded'); - }); it('should not update the result when a new object with shallow-equal content is set', async () => { Onyx.set(ONYXKEYS.TEST_KEY, {id: 'test_id', name: 'test_name'}); @@ -885,89 +716,6 @@ describe('useOnyx', () => { }); }); - describe('pending merges', () => { - it('should return undefined and loading state while we have pending merges for the key, and then return updated value and loaded state', async () => { - Onyx.set(ONYXKEYS.TEST_KEY, 'test1'); - - Onyx.merge(ONYXKEYS.TEST_KEY, 'test2'); - Onyx.merge(ONYXKEYS.TEST_KEY, 'test3'); - Onyx.merge(ONYXKEYS.TEST_KEY, 'test4'); - - const {result} = renderHook(() => useOnyx(ONYXKEYS.TEST_KEY)); - - expect(result.current[0]).toBeUndefined(); - expect(result.current[1].status).toEqual('loading'); - - await act(async () => waitForPromisesToResolve()); - - expect(result.current[0]).toEqual('test4'); - expect(result.current[1].status).toEqual('loaded'); - }); - - it('should return undefined and loading state while we have pending merges for the key, and then return selected data and loaded state', async () => { - Onyx.set(ONYXKEYS.TEST_KEY, 'test1'); - - Onyx.merge(ONYXKEYS.TEST_KEY, 'test2'); - Onyx.merge(ONYXKEYS.TEST_KEY, 'test3'); - Onyx.merge(ONYXKEYS.TEST_KEY, 'test4'); - - const {result} = renderHook(() => - useOnyx(ONYXKEYS.TEST_KEY, { - selector: ((entry: OnyxEntry) => `${entry}_changed`) as UseOnyxSelector, - }), - ); - - expect(result.current[0]).toBeUndefined(); - expect(result.current[1].status).toEqual('loading'); - - await act(async () => waitForPromisesToResolve()); - - expect(result.current[0]).toEqual('test4_changed'); - expect(result.current[1].status).toEqual('loaded'); - }); - }); - - describe('multiple usage', () => { - it('should connect to a key and load the value into cache, and return the value loaded in the next hook call', async () => { - await StorageMock.setItem(ONYXKEYS.TEST_KEY, 'test'); - - const {result: result1} = renderHook(() => useOnyx(ONYXKEYS.TEST_KEY)); - - expect(result1.current[0]).toBeUndefined(); - expect(result1.current[1].status).toEqual('loading'); - - await act(async () => waitForPromisesToResolve()); - - expect(result1.current[0]).toEqual('test'); - expect(result1.current[1].status).toEqual('loaded'); - - const {result: result2} = renderHook(() => useOnyx(ONYXKEYS.TEST_KEY)); - - expect(result2.current[0]).toEqual('test'); - expect(result2.current[1].status).toEqual('loaded'); - }); - - it('should connect to a key two times while data is loading from the cache, and return the value loaded to both of them', async () => { - await StorageMock.setItem(ONYXKEYS.TEST_KEY, 'test'); - - const {result: result1} = renderHook(() => useOnyx(ONYXKEYS.TEST_KEY)); - const {result: result2} = renderHook(() => useOnyx(ONYXKEYS.TEST_KEY)); - - expect(result1.current[0]).toBeUndefined(); - expect(result1.current[1].status).toEqual('loading'); - - expect(result2.current[0]).toBeUndefined(); - expect(result2.current[1].status).toEqual('loading'); - - await act(async () => waitForPromisesToResolve()); - - expect(result1.current[0]).toEqual('test'); - expect(result1.current[1].status).toEqual('loaded'); - - expect(result2.current[0]).toEqual('test'); - expect(result2.current[1].status).toEqual('loaded'); - }); - }); describe('dependencies', () => { it('should return the updated selected value when a external value passed to the dependencies list changes', async () => { @@ -1200,122 +948,5 @@ describe('useOnyx', () => { // A single render — no extra render caused by subscribe resetting state on initial mount. expect(renderCount).toBe(1); }); - - it('should render exactly twice (loading → loaded) when the key is not cached', async () => { - let renderCount = 0; - const {result} = renderHook(() => { - renderCount++; - return useOnyx(ONYXKEYS.TEST_KEY); - }); - - await act(async () => waitForPromisesToResolve()); - - expect(result.current[0]).toBeUndefined(); - expect(result.current[1].status).toEqual('loaded'); - // Exactly two renders: initial 'loading' + transition to 'loaded' after the connection callback fires. - // If the regression returns, a third render sneaks in from the subscribe-time state reset. - expect(renderCount).toBe(2); - }); - - it('should render exactly twice when the key value is only present in storage', async () => { - await StorageMock.setItem(ONYXKEYS.TEST_KEY, 'storage_value'); - - let renderCount = 0; - const {result} = renderHook(() => { - renderCount++; - return useOnyx(ONYXKEYS.TEST_KEY); - }); - - await act(async () => waitForPromisesToResolve()); - - expect(result.current[0]).toEqual('storage_value'); - expect(result.current[1].status).toEqual('loaded'); - expect(renderCount).toBe(2); - }); - - it('should render exactly twice for a non-cached collection member key', async () => { - let renderCount = 0; - const {result} = renderHook(() => { - renderCount++; - return useOnyx(`${ONYXKEYS.COLLECTION.TEST_KEY}1`); - }); - - await act(async () => waitForPromisesToResolve()); - - expect(result.current[0]).toBeUndefined(); - expect(result.current[1].status).toEqual('loaded'); - expect(renderCount).toBe(2); - }); - - // Covers the `if (hasMountedRef.current)` branch — i.e. the reset that runs on key-change re-subscriptions. - // The reset is what makes the hook transition through 'loading' for the new key instead of leaking the - // previous key's value/status. These tests verify both the render count AND the loading transition, - // so removing the reset (regression in the other direction) is also caught. - it('should transition through loading and render exactly 4 times when switching from a cached key to an uncached one', async () => { - await Onyx.set(`${ONYXKEYS.COLLECTION.TEST_KEY}A`, 'A_value'); - - const renders: Array<{value: unknown; status: string}> = []; - const {result, rerender} = renderHook( - (key: string) => { - const r = useOnyx(key); - renders.push({value: r[0], status: r[1].status}); - return r; - }, - {initialProps: `${ONYXKEYS.COLLECTION.TEST_KEY}A` as string}, - ); - - await act(async () => waitForPromisesToResolve()); - - expect(result.current[0]).toEqual('A_value'); - expect(result.current[1].status).toEqual('loaded'); - const rendersAfterMount = renders.length; - expect(rendersAfterMount).toBe(1); - - await act(async () => { - rerender(`${ONYXKEYS.COLLECTION.TEST_KEY}B`); - }); - await act(async () => waitForPromisesToResolve()); - - expect(result.current[0]).toBeUndefined(); - expect(result.current[1].status).toEqual('loaded'); - // 1 mount render + 3 renders for the key switch (transient stale render, post-subscribe 'loading', - // callback-driven 'loaded'). The 'loading' render only happens because the subscribe-time reset - // clears the previous key's resultRef — removing the reset makes this assertion fail. - expect(renders.length).toBe(4); - // Verify the reset took effect: a 'loading' frame must appear after the key change. - const postSwitchStatuses = renders.slice(rendersAfterMount).map((r) => r.status); - expect(postSwitchStatuses).toContain('loading'); - expect(postSwitchStatuses[postSwitchStatuses.length - 1]).toBe('loaded'); - }); - - it('should transition through loading and render exactly 3 times when switching between two cached keys', async () => { - await Onyx.set(`${ONYXKEYS.COLLECTION.TEST_KEY}A`, 'A_value'); - await Onyx.set(`${ONYXKEYS.COLLECTION.TEST_KEY}B`, 'B_value'); - - const renders: Array<{value: unknown; status: string}> = []; - const {result, rerender} = renderHook( - (key: string) => { - const r = useOnyx(key); - renders.push({value: r[0], status: r[1].status}); - return r; - }, - {initialProps: `${ONYXKEYS.COLLECTION.TEST_KEY}A` as string}, - ); - - await act(async () => waitForPromisesToResolve()); - - expect(result.current[0]).toEqual('A_value'); - expect(renders.length).toBe(1); - - await act(async () => { - rerender(`${ONYXKEYS.COLLECTION.TEST_KEY}B`); - }); - await act(async () => waitForPromisesToResolve()); - - expect(result.current[0]).toEqual('B_value'); - expect(result.current[1].status).toEqual('loaded'); - // 1 mount render + 2 renders for the cached-to-cached switch. - expect(renders.length).toBe(3); - }); }); });