perf: skip per-key clone when Onyx.init() hydrates the cache

[WojtekBoman]

Details

Onyx.init() loaded the persisted database into OnyxCache through merge(), which runs fastMerge(existing, value) per key. At init time existing is always undefined, so fastMerge never actually merges anything - it just walks and deep-clones every nested object of every row for no reason. On a heavy account this clone-heavy cache-write phase was measured at ~29% of total Onyx.init() time.

Adds OnyxCache.hydrate(), a bulk-load variant used only by Onyx.init(). Values are stored by reference when safe (utils.needsNormalization() is a read-only, non-allocating check for nested null/undefined and the internal ONYX_INTERNALS__REPLACE_OBJECT_MARK). Falls back to the existing fastMerge path in two cases: the key already has a value in cache (a cross-tab sync listener can race ahead of init and write a key before hydrate() reaches it), or the value itself needs normalizing.

OnyxUtils.ts's initializeWithDefaultKeyStates() now calls cache.hydrate(allDataFromStorage) instead of cache.merge(allDataFromStorage).

merge()'s inline fastMerge options were also extracted into a shared CACHE_MERGE_OPTIONS constant used by both merge() and hydrate()'s fallback, so the cache write paths can't drift apart.

Related Issues

Expensify/App#98553

Linked E/App PR

Automated Tests

tests/unit/onyxCacheTest.tsx covers hydrate() directly and through Onyx.init():

• Equivalence with merge(): identical cache state on an empty cache, and when keys already hold values, across fixtures with nested nulls, nested undefined, the replace-object mark, and plain values.
• Every key is registered, including keys whose stored value is nullish.
• Values are stored by reference when no normalization is needed, and normalized when they carry nested nullish properties.
• Reference stability: a hydrated value that changes nothing keeps the existing reference.
• Init-level: collection members loaded from storage are readable through collection reads, keys written while storage was still being read are merged rather than overwritten, and the resulting cache matches a merge-based init.

Manual Tests

1. Sign in to an account with a reasonably large Onyx database (many reports/reportActions), force-quit and cold-start the app.
   Verify that the app boots normally, the LHN and reports render with the same data as before the change, and no console errors appear.
2. Cold-start the app, open a report with actions containing deleted/optimistic-cleared fields (values that were null on disk).
   Verify that the report renders correctly with those fields absent, matching pre-change behavior.
3. On web, open the app in two browser tabs signed into the same account. In tab A, trigger a write (e.g. send a message) right as tab B is cold-starting/reloading.
   Verify that tab B's cache ends up consistent with tab A's write - i.e. the value isn't clobbered by hydrate()'s bulk load racing the cross-tab sync listener.

Offline tests

1. Put the device in airplane mode, force-quit and cold-start the app.
   Verify that the app boots with the last-persisted cache (same as before this change) and no data is lost or duplicated.
2. While offline, open a report and confirm previously-persisted reportActions/transactions render correctly, then go back online and verify no reconciliation errors occur.

QA Steps

Same as tests.

Author Checklist

• I linked the correct issue in the ### Related Issues section above
• I linked the corresponding Expensify/App PR in the ### Linked E/App PR section above, and verified this change against it (E/App CI passed and manual testing completed)
• I wrote clear testing steps that cover the changes made in this PR
  • I added steps for local testing in the Tests section
  • I tested this PR with a High Traffic account against the staging or production API to ensure there are no regressions (e.g. long loading states that impact usability).
• I included screenshots or videos for tests on all platforms
• I ran the tests on all platforms & verified they passed on:
  • Android / native
  • Android / Chrome
  • iOS / native
  • iOS / Safari
  • MacOS / Chrome / Safari
• I verified there are no console errors (if there's a console error not related to the PR, report it or open an issue for it to be fixed)
• I followed proper code patterns (see Reviewing the code)
  • I verified that any callback methods that were added or modified are named for what the method does and never what callback they handle (i.e. toggleReport and not onIconClick)
  • I verified that the left part of a conditional rendering a React component is a boolean and NOT a string, e.g. myBool && <MyComponent />.
  • I verified that comments were added to code that is not self explanatory
  • I verified that any new or modified comments were clear, correct English, and explained "why" the code was doing something instead of only explaining "what" the code was doing.
  • I verified proper file naming conventions were followed for any new files or renamed files. All non-platform specific files are named after what they export and are not named "index.js". All platform-specific files are named for the platform the code supports as outlined in the README.
  • I verified the JSDocs style guidelines (in STYLE.md) were followed
• If a new code pattern is added I verified it was agreed to be used by multiple Expensify engineers
• I followed the guidelines as stated in the Review Guidelines
• I tested other components that can be impacted by my changes (i.e. if the PR modifies a shared library or component like Avatar, I verified the components using Avatar are working as expected)
• I verified all code is DRY (the PR doesn't include any logic written more than once, with the exception of tests)
• I verified any variables that can be defined as constants (ie. in CONST.js or at the top of the file that uses the constant) are defined as such
• I verified that if a function's arguments changed that all usages have also been updated correctly
• If a new component is created I verified that:
  • A similar component doesn't exist in the codebase
  • All props are defined accurately and each prop has a /** comment above it */
  • The file is named correctly
  • The component has a clear name that is non-ambiguous and the purpose of the component can be inferred from the name alone
  • The only data being stored in the state is data necessary for rendering and nothing else
  • If we are not using the full Onyx data that we loaded, I've added the proper selector in order to ensure the component only re-renders when the data it is using changes
  • For Class Components, any internal methods passed to components event handlers are bound to this properly so there are no scoping issues (i.e. for onClick={this.submit} the method this.submit should be bound to this in the constructor)
  • Any internal methods bound to this are necessary to be bound (i.e. avoid this.submit = this.submit.bind(this); if this.submit is never passed to a component event handler like onClick)
  • All JSX used for rendering exists in the render method
  • The component has the minimum amount of code necessary for its purpose, and it is broken down into smaller components in order to separate concerns and functions
• If any new file was added I verified that:
  • The file has a description of what it does and/or why is needed at the top of the file if the code is not self explanatory
• If the PR modifies a generic component, I tested and verified that those changes do not break usages of that component in the rest of the App (i.e. if a shared library or component like Avatar is modified, I verified that Avatar is working as expected in all cases)
• If the main branch was merged into this PR after a review, I tested again and verified the outcome was still expected according to the Test steps.
• I have checked off every checkbox in the PR author checklist, including those that don't apply to this PR.

Screenshots/Videos

Android: Native

Android: mWeb Chrome

iOS: Native

iOS: mWeb Safari

MacOS: Chrome / Safari

Screen.Recording.2026-08-14.at.15.07.49.mov

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[WojtekBoman]

I have read the CLA Document and I hereby sign the CLA

[collectioneur]

LGTM! 🚀

[mkhutornyi]

NAB comments:

[mkhutornyi]

This race fallback cannot detect a cross-tab deletion that landed before hydrate, so a stale row is resurrected.
cache.set(key, null) erases both storageMap[key] and the nullishStorageKeys marker, leaving hydrate no way to tell "never written" from "just deleted".
Same as the old merge() behavior (not a regression), but this new comment and the PR body claim the fallback makes the init race safe — it only does for non-null writes.

Suggested additional comment:

// Note: this only covers non-null writes. A `cache.set(key, null)` that lands before hydrate
// clears the nullish marker too, so a deletion racing init is still undone — same as before.

[mkhutornyi]

hydrate(null) is guarded but not covered by this test.
Worth one more line given the guard was added in 51d14dd specifically for it.

[mkhutornyi]

Regression test cases

1. Cold start with existing data (the main path)

1. Sign in and let the app fully load (open a few chats, a workspace, and Search).
2. Force-quit the app (swipe away on mobile, close the tab/browser on web).
3. Relaunch.
4. Verify the LHN renders the same report list as before the restart, in the same order.
5. Open a report that was open before — verify all messages, avatars, and unread indicators are identical.
6. Open Settings → Workspaces — verify categories, tags, and members are present.
7. Verify no "empty state" or skeleton flashes and then fills in for data that was already on disk.

Why: cache.hydrate() replaces setAllKeys() + cache.merge() for the entire eager load. A key registration failure shows up here as missing LHN rows or an empty workspace list.

2. Collections render fully

1. From the cold-start state above, verify the LHN report list, the workspace member list, and a report's transaction list all show every row.
2. Pull to refresh / navigate away and back — verify nothing appears or disappears.

Why: hydrate() now registers collection member keys via addKey() and marks collections dirty itself. A miss here means a collection snapshot is built from an incomplete index — the symptom is some members rendering, not zero.

3. Values with removed properties survive the restart

1. Set a workspace description, then clear it. Do the same for an optional profile field (e.g. pronouns).
2. Force-quit and relaunch.
3. Verify the cleared fields are still empty and no null leaks into the UI as the literal string "null" or a blank row that shouldn't exist.

Why: hydrate() skips normalization entirely for values that pass needsNormalization(), and only deep-cleans the ones that don't. This is the scenario where a value carrying nested nulls is stored raw.

4. Offline data after restart

1. Create an expense, then go offline before it finishes syncing.
2. Force-quit and relaunch while still offline.
3. Verify the pending expense is still visible with its offline styling.
4. Go back online — verify it syncs and the pending styling clears.

Why: exercises hydrate against optimistic data written by the previous session, including pendingAction fields.

5. Multi-tab race (web only — highest-risk scenario)

1. Open the app in two browser tabs and let both load.
2. In Tab A, send a message in a chat.
3. Immediately hard-refresh Tab B (Cmd+Shift+R) so its startup storage read overlaps the cross-tab broadcast.
4. Verify Tab B shows the new message and the chat is in the right LHN position.
5. Repeat 3–4 times — the timing window is narrow.
6. Now the inverse: in Tab A delete a message, and immediately hard-refresh Tab B.
7. Verify the deleted message does not reappear in Tab B.

Why: the existing !== undefined fallback inside hydrate() exists specifically for this race. Steps 6–7 cover a known pre-existing gap — if the deleted message does briefly reappear, that reproduces on main too and is not caused by this PR. Worth capturing on video either way.

6. Fresh install / empty storage

1. Uninstall (or clear site data) and reinstall.
2. Launch before signing in — verify the sign-in page renders normally, no crash, no hang on the splash screen.
3. Sign in and verify normal loading.

Why: hydrate({}) on an empty payload no longer resets the key index. Confirms nothing depends on that reset.

7. Sign out / sign in / switch accounts

1. Sign out, then sign in as a different account.
2. Verify none of the previous account's chats, workspaces, or avatars appear.
3. Force-quit and relaunch — verify still clean.

Why: Onyx.clear() interacts with the key index, and the index is no longer replaced wholesale at init.

8. Performance verification (this is the PR's actual goal)

1. On a release build with a large account (many reports/transactions), measure time from launch to first LHN paint.
2. Compare against a build on main with the same account and the same storage state — run each 5 times and take the median.
3. Verify the branch is not slower; a measurable improvement on large accounts is the expected result.

A Sentry span or a console.time around Onyx.init()'s resolution both work; use whichever the perf setup already tracks.

Platforms

Run 1–4 and 6–7 on iOS, Android, and web (different storage providers: SQLite vs IndexedDB, and only SQLite batches the whole table through one JSON.parse). Scenario 5 is web only. Scenario 8 on iOS and Android release builds.

[roryabraham]

Code LGTM but we should link an App PR to help the Onyx merge queue go smoother.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Can't wait for the next one!

Reviewed commit: 25cf1cb277

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".