Block `QueryClient` API surface in UI
- Dominant language
- TypeScript
- Stars
- 413
- Forks
- 308
- Avg merge
- 1d 4h
- Merged PRs (30d)
- 253
Description
**File:** `packages/react-data-query/src/createUIQueryClient.ts`
**Size:** M | **Hours:** 6–10
---
## Problem
Under ADR 0020 Option A, two messenger-routed proxies and the `OmitKeyof` wrapper hooks enforce that the background owns data-service-keyed cache entries: the [proxy `queryFn`](https://github.com/MetaMask/core/blob/f07ef66f2e1fa3a23a33d2ae6ec4fc0f99f1c73a/packages/react-data-query/src/createUIQueryClient.ts#L245-L262), and since [#9324 (Update BaseDataService to accommodate mutations)](https://github.com/MetaMask/core/pull/9324) the [`defaultMutationOptions` shadow](https://github.com/MetaMask/core/blob/f07ef66f2e1fa3a23a33d2ae6ec4fc0f99f1c73a/packages/react-data-query/src/createUIQueryClient.ts#L423-L456) that injects a `mutationFn`. None of them covers the `QueryClient` instance surface. UI code with a handle on `queryClient` (via `ui/contexts/query-client.ts` or `useQueryClient()`) can call instance methods that bypass the proxy or cross the ownership boundary without warning.
**No longer dormant.** [`DATA_SERVICES`](https://github.com/MetaMask/metamask-extension/blob/main/shared/constants/data-services.ts) on `metamask-extension` main holds `MoneyAccountBalanceService` and `MoneyAccountApiDataService`, so the guards below are on a live path rather than a preemptive one.
### The options-resolution path is a second surface
Every method below is a `QueryClient` **instance method**. A shadow on the instance cannot reach a bypass supplied through per-call **options**, and both proxies can be overridden that way:
- `queryFn` — the proxy is a client default, so an explicit `queryFn` on a `useQuery` call wins. `OmitKeyof` strips it from the wrapper's type, which is a compile-time strip with no runtime check.
- `mutationFn` — [`defaultedOptions.mutationFn ??=`](https://github.com/MetaMask/core/blob/f07ef66f2e1fa3a23a33d2ae6ec4fc0f99f1c73a/packages/react-data-query/src/createUIQueryClient.ts#L436) is a nullish-assign, so a caller-supplied `mutationFn` on a data-service `mutationKey` wins and the write never reaches the service.
Whether that override is intended is an open design question rather than a settled hole: the query-side escape hatch was deliberate, and the mutation side mirrors it. Either way it is not closed by shadowing instance methods, so it needs its own decision and its own guard.
---
## Solution
Mirror the existing [`invalidateQueries` shadow](https://github.com/MetaMask/core/blob/f07ef66f2e1fa3a23a33d2ae6ec4fc0f99f1c73a/packages/react-data-query/src/createUIQueryClient.ts#L397-L421). For each method below, shadow on the returned client and throw a descriptive error if the query key matches a registered data-service prefix. Non-data-service keys pass through unchanged. Note there are now two shadows on the returned client, `invalidateQueries` and `defaultMutationOptions`, so the guards compose with them rather than replacing them.
Methods to guard:
- `setQueryDefaults` — per-key cache-policy override; ADR 0020 moves cache policy to the service layer
- `setMutationDefaults` — data-service mutations exist as of [#9324 (mutations in BaseDataService)](https://github.com/MetaMask/core/pull/9324), so this is now live rather than preemptive
- `setDefaultOptions` — block only when `options.queries.queryFn` or `options.mutations.mutationFn` is set
- `prefetchQuery` / `prefetchInfiniteQuery` — pending policy decision on whether UI-side prefetch is in scope; block until decided
- `fetchQuery` / `fetchInfiniteQuery` — same
- `setQueryData` / `setQueriesData` — block; replacement implementation tracked separately (see Dependencies)
- `ensureQueryData` / `ensureInfiniteQueryData` — block; replacement implementation tracked separately (see Dependencies)
- `getMutationCache` / `resumePausedMutations` / `isMutating` — mutation-side twins, needed since [#9324 (mutations in BaseDataService)](https://github.com/MetaMask/core/pull/9324)
---
## Acceptance Criteria
- [ ] All methods above throw on data-service keys with a descriptive error citing the data service as cache owner and referencing ADR 0020
- [ ] A caller-supplied `queryFn` or `mutationFn` on a data-service key is decided one way or the other, and whichever way it goes is enforced at runtime rather than only in the wrapper's types
- [ ] `setDefaultOptions` only throws when `options.queries.queryFn` or `options.mutations.mutationFn` is set; other client-wide tuning unaffected
- [ ] Non-data-service keys pass through for all methods (Option C hooks unaffected)
- [ ] `invalidateQueries` and `defaultMutationOptions` shadows, wrapper hooks, and `hydrate`-based cache-sync continue to work
- [ ] Unit tests per method: data-service key throws, non-data-service key passes, error message correct
- [ ] Regression tests for Option C consumers (`useHistoricalPrices`, `activity-v2/hooks`, `useMerklRewards`) still pass
---
## Dependencies
**Depends on:** [MetaMask/metamask-extension#41183](https://github.com/MetaMask/metamask-extension/pull/41183) *(merged)*
**Dependents:** [MetaMask/metamask-extension#41977](https://github.com/MetaMask/metamask-extension/issues/41977)
**Follow-up epic (Layer 2 + replacements):** [#8531 (Expose replacement implementations of `QueryClient` APIs in UI)](https://github.com/MetaMask/core/issues/8531)
**Widened by:** [#9324 (Update BaseDataService to accommodate mutations)](https://github.com/MetaMask/core/pull/9324) — adds the mutation proxy and the mutation-side instance methods
Contributor guide
No contributing guide indexed for this repository
Research direction
Start in packages/react-data-query/src/createUIQueryClient.ts, reading the existing invalidateQueries and defaultMutationOptions shadows and the wrapper hooks. Decide how per-call queryFn and mutationFn overrides should behave, then add guards for the listed QueryClient methods while preserving non-data-service keys. Add per-method unit tests for throwing and pass-through behavior, plus the named Option C regression tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, frontend
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100