[Due for payment 2026-09-10] Remove OnyxUtils.get() from OnyxDerived init (use connectWithoutView)

[tgolen]

Problem

OnyxUtils.get() (imported from the internal deep path react-native-onyx/dist/OnyxUtils) is not a sanctioned way to read Onyx data. The only two supported read APIs are:

1. useOnyx() — for anything in a component's render path.
2. Onyx.connectWithoutView() — for non-render logic that genuinely can't use useOnyx.

Reaching into react-native-onyx/dist/* bypasses the public API and couples us to Onyx internals.

This issue covers src/libs/actions/OnyxDerived/index.ts, which contains one OnyxUtils.get(key) call (as of writing, line 46).

Why connectWithoutView (not useOnyx) here

This is module-level init() logic, not a component — useOnyx() is not applicable. The call performs a one-time hydration read of the stored derived value from disk before wiring up the dependency subscriptions. The sanctioned replacement is a short-lived connectWithoutView read: connect, read the first callback value, then Onyx.disconnect(connection).

Because the connection is short-lived (disconnected after the first callback), it will not recursively re-fire when this same code later writes back to the derived key.

Reference implementation of the short-lived pattern already in the codebase: src/libs/migrations/ConvertGpsPointsTo2DArray.ts.

Proposed change

• Remove the import OnyxUtils from 'react-native-onyx/dist/OnyxUtils'.
• Replace OnyxUtils.get(key).then((storedDerivedValue) => { ... }) with a short-lived Onyx.connectWithoutView read that resolves the stored value, then continues into the existing setup logic.
• Keep all downstream behavior (the dependencyValues wiring, connectWithoutView dependency subscriptions, flush/coalesce logic) unchanged.

Acceptance criteria

• No references to OnyxUtils / react-native-onyx/dist/OnyxUtils remain in this file.
• The initial derived-value hydration uses Onyx.connectWithoutView (short-lived) via the public Onyx import.
• Derived values still restore from disk on init and recompute correctly when dependencies change.

Notes

This is one of several issues removing OnyxUtils.get() across the app. A separate issue will add an ESLint rule to prevent it from being reintroduced.

Upwork Automation - Do Not Edit

• Upwork Job URL: https://www.upwork.com/jobs/~022087946412464986788
• Upwork Job ID: 2087946412464986788
• Last Price Increase: 2026-08-13

Issue Owner

Current Issue Owner: @mallenexpensify

[melvin-bot]

Triggered auto assignment to Contributor-plus team member for initial proposal review - @Ollyws (External)

[melvin-bot]

Job added to Upwork: https://www.upwork.com/jobs/~022087946412464986788

[skrohan5016-coder]

Proposal

Please re-state the problem that we are trying to solve in this issue.

src/libs/actions/OnyxDerived/index.ts performs a one-time startup read with OnyxUtils.get(key), imported from the internal deep path react-native-onyx/dist/OnyxUtils. Runtime code should use the public Onyx API instead, while preserving the current initialization behavior: restore the persisted derived value first, then establish the long-lived dependency subscriptions.

What is the root cause of that problem?

OnyxDerived.init() needs a one-shot, non-React read for every derived key. Since this code runs at module startup outside the React lifecycle, useOnyx() is not applicable, and the existing implementation reached into OnyxUtils.get() as a promise-based shortcut.

The important detail is the ordering around that read. The current .then(...) continuation contains all dependency wiring, so no dependency can complete the initial set and recompute until the persisted derived value has been assigned to derivedValue. Moving those subscriptions outside the hydration callback would introduce a startup race: the first recompute could run with context.currentValue still undefined and overwrite a valid disk-cached derived value.

The replacement must also disconnect after the first callback. Leaving the derived-key connection active would make later writes to that same derived key re-enter the initialization block and install another set of dependency listeners.

What changes do you think we should make in order to solve the problem?

1. Remove the runtime import of react-native-onyx/dist/OnyxUtils from src/libs/actions/OnyxDerived/index.ts.
2. Replace OnyxUtils.get(key).then(...) with a short-lived Onyx.connectWithoutView({key, callback}) read.
3. In the first callback, immediately call Onyx.disconnect(connection) before continuing with initialization.
4. Keep the existing initialization body—including derivedValue restoration, dependency arrays, long-lived dependency subscriptions, coalescing, clear handling, and self-healing logic—inside that one-shot callback. This preserves the existing hydrate-before-subscribe ordering.
5. Follow the established pattern already used by src/libs/migrations/ConvertGpsPointsTo2DArray.ts. The default connection reuse behavior is sufficient: disconnecting this returned connection removes this callback without tearing down other consumers of the same key.

Conceptually:

const connection = Onyx.connectWithoutView({
    key,
    callback: (storedDerivedValue) => {
        Onyx.disconnect(connection);

        let derivedValue = storedDerivedValue;
        // Existing initialization and dependency wiring remains here unchanged.
    },
});

What specific scenarios should we cover in automated tests to prevent reintroducing this issue in the future?

Add focused coverage to the existing OnyxDerived tests for these invariants:

1. Seed a persisted derived value before initializing OnyxDerived and verify that the first compute receives it as context.currentValue, proving hydration still occurs before dependency-driven recomputation.
2. Verify the hydration subscription is one-shot: writing the derived key after initialization must not create another set of dependency subscriptions or cause duplicate recomputations.
3. Keep the existing OnyxDerived and self-healing suites passing to confirm normal recomputation, microtask coalescing, Onyx.clear() handling, and failed-compute recovery are unchanged.

What alternative solutions did you explore? (Optional)

• useOnyx(): not usable because this is non-React startup logic.
• A permanent connectWithoutView() subscription: rejected because writes to the derived key could re-run initialization and duplicate listeners.
• Starting dependency subscriptions before hydration completes: rejected because it changes the current ordering and can overwrite the restored value.
• Adding a new public promise-based getter to react-native-onyx: unnecessary scope for a one-shot read already supported by connectWithoutView().

[tgolen]

@Ollyws Are you OK with that proposal?

[nkdengineer]

Proposal

What is the root cause of that problem?

src/libs/actions/OnyxDerived/index.ts restores the stored derived value with OnyxUtils.get(key), imported from the internal deep path react-native-onyx/dist/OnyxUtils. That is not a sanctioned Onyx read API and couples the derived-value engine to Onyx internals.

This code is not in a React render path, so useOnyx() is not applicable. The read happens during module-level init() before the dependency subscriptions are established, purely to hydrate the last stored derived value from disk and seed derivedValue before recomputes begin. That makes this a non-render, one-shot read, which is exactly the case Onyx.connectWithoutView() is meant to cover.

The subtle requirement is preserving the current bootstrap ordering: restore storedDerivedValue, then continue into the existing dependency wiring, coalescing, and flush logic unchanged. A short-lived connectWithoutView fits that pattern because it can read the first callback value, then immediately disconnect before the later setDerivedValue() writes occur.

What changes do you think we should make in order to solve the problem?

Replace the internal OnyxUtils.get() hydration read with the same short-lived Onyx.connectWithoutView() pattern already used by ConvertGpsPointsTo2DArray.ts.

Concretely:

1. Remove import OnyxUtils from 'react-native-onyx/dist/OnyxUtils'.
2. Replace OnyxUtils.get(key).then((storedDerivedValue) => { ... }) with a small promise wrapper around Onyx.connectWithoutView:
   • connect to key
   • capture the first callback value as storedDerivedValue
   • immediately Onyx.disconnect(connection)
   • continue into the existing setup logic
3. Keep the rest of init() unchanged: restoring derivedValue, establishing dependency subscriptions, deferring writes until all connections initialize, and preserving the current clear/reset and microtask coalescing behavior.

This keeps the behavior the same while moving the initial hydration read onto the public Onyx API.

What alternative solutions did you explore? (Optional)

1. Use useOnyx() instead: rejected because this is module-level initialization logic, not a component or hook render path.
2. Skip the stored-value hydration and always recompute from scratch: rejected because the current code intentionally restores the disk-cached derived value first, which avoids unnecessary churn during startup and preserves the existing bootstrap behavior.

[Ollyws]

@MelvinBot create a draft PR from the proposal outlined in #98607 (comment)

[MelvinBot]

🤖 Draft PR created: #99004

I implemented the proposal from this issue — replacing the internal OnyxUtils.get(key) hydration read in src/libs/actions/OnyxDerived/index.ts with a short-lived Onyx.connectWithoutView read (disconnected after the first callback), following the ConvertGpsPointsTo2DArray.ts pattern.

Acceptance criteria:

• ✅ No references to OnyxUtils / react-native-onyx/dist/OnyxUtils remain in the file (import removed).
• ✅ Initial derived-value hydration now uses Onyx.connectWithoutView (short-lived) via the public Onyx import.
• ✅ Hydrate-before-subscribe ordering and all downstream dependency wiring / flush / coalesce logic are unchanged.

Checks run locally (all pass): typecheck (tsgo), lint, and the OnyxDerived unit suites — OnyxDerivedTest, OnyxDerivedSelfHealTest, CardFeedErrorsDerivedValueTest (69 tests).

Please mark the PR as "Ready for review" when it is ready.

---

view run