Update BaseDataService to accommodate mutations, not just queries by mcmire · Pull Request #9324 · MetaMask/core

mcmire · 2026-06-30T22:03:06Z

Explanation

Currently, BaseDataService has a fetchQuery method which is best used for making read-only requests ("queries" in TanStack Query parlance), but does not work as well for requests that change state on the server side ("mutations"). For instance, it makes sense for queries to be cached and retried, but not so much for mutations.

This commit adds a separate method, executeMutation, which accommodates mutations better. Besides the differences mentioned above, it also uses the mutation cache instead of the query cache.

References

Closes https://consensyssoftware.atlassian.net/browse/WPC-1118.

Manual testing

I've created #10176, which converts AuthenticatedUserStorageService.setAssetsWatchlist to use executeMutation under the hood, and MetaMask/metamask-mobile#36083, which loads those changes into the mobile app. You can check out the mobile branch and run through the manual testing steps there to confirm that executeMutation still exhibits the same basic behavior as fetchQuery.

Checklist

I've updated the test suite for new or updated code as appropriate
I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
I've communicated my changes to consumers by updating changelogs for packages I've changed
I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

Note

Medium Risk
Introduces state-changing server requests and cross-client mutation sync; mistakes in globalId handling or mutation routing could cause wrong UI state, though mutations deliberately skip query-style retries.

Overview
Adds a mutation path alongside existing query support in @metamask/base-data-service and wires it through @metamask/react-data-query.

BaseDataService exposes protected executeMutation (plus exported MutationKey), runs writes through the mutation cache with no retries (circuit breaker only), optional Superstruct validation via processMutationResponse, and an optional globalId in mutation meta for correlating the service client with the UI client. :cacheUpdated payloads now include objectType ("query" | "mutation"), mutation cache subscriptions/dehydration, and destroy() clears mutation GC timers.

createUIQueryClient proxies mutations via mutationKey → messenger actions (trailing globalId), assigns per-mutation UUIDs, syncs service state with hydrateMutations on updated events only (ignoring added/removed that would clobber UI state), and exports useMutation with retries off by default.

^{Reviewed by Cursor Bugbot for commit ac8209b. Bugbot is set up for automated code reviews on this repo. Configure here.}

mcmire · 2026-06-30T22:06:36Z

+      'mutationKey' | 'mutationFn'
+    >,
+  ): Promise<TData> {
+    const mutationCache = this.#queryClient.getMutationCache();


QueryClient doesn't have a executeMutation method itself. I looked inside of the class, however, and saw that there was a getMutationCache method and followed where that led. This is not how useMutation works, which uses MutationObserver, but I don't know if that really matters. I figured it made more sense to mimic how fetchQuery works. But I'm not very familiar with TanStack Query, so if this is not the way we should be doing things, I'm happy to change this.

I looked into this further and while this is not how useMutation works, it is how MutationObserver works. You can see that here:

https://github.com/TanStack/query/blob/4d8da1e29e97ad5b0c151822d4962849515b4478/packages/query-core/src/mutationObserver.ts#L136

So, we aren't really diverging from TanStack Query as much as I implied before.

FrederikBolding · 2026-07-01T13:36:15Z

+    const mutation = mutationCache.build(this.#queryClient, {
+      ...options,
+      mutationFn: (context) =>
+        this.#policy.execute(() => options.mutationFn(context)),


Hmm, are we safe to apply the policy as-is to mutations?

Just wondering if there could be a problem with accidentally doing double the mutation with retries 🤔

Hmm, good point. We're still making an API request, so I feel like we would still want to have some kind of retry logic. But maybe it needs to be a little different than the logic used for GET requests.

I wonder if the default retry policy for createServicePolicy is too liberal. Right now, if the function you pass to the policy throws any error, then the function will get run again.

In RpcService we only retry connection errors, JSON parse errors, HTTP server errors (5xx), timeout errors, and "connection reset" errors. I wonder if BaseDataService should configure createServicePolicy such that it does the same thing?

Then I would be less worried here, because at that point, either we never make the request, or we do make the request but the server returns a 5xx. And in that case I feel like we ought to assume that the server is well-behaved, i.e. won't attempt to write to a database if it runs into an error. (If the server is not well-behaved, it shouldn't be our fault — the engineer writing the data service should know that and account for it.)

What do you think about that idea?

Improving the defaults to be more "targeted" to BaseDataService makes sense to me. Though I still would be a bit worried that developers configure the service policy mainly for GET requests and don't realize how it may impact a PUT 🤔

I wouldn't expect that most developers would configure the service policy, I would expect them to go with the defaults. But that's a good point. Should we have two kinds of service policies, one for queries and another for mutations? Then if a developer does configure a service policy, it should be more obvious what it's used for, and maybe it will cause them to think about it more critically. Or maybe this is solvable via documentation: we can add an "advanced" section to the tutorial/guide on data services that talks about the service policy, and we can remind the reader to consider non-GET requests when configuring it.

Unsure if a separate service policy or modifications to the default service policy would be preferred. We could consider a default isServiceFailure function that changes depending on the type of request for example? But maybe a separate policy for maximum flexibility is preferred 🤔

Thinking about this some more, I've see realized that it makes more sense to have one policy instead of two. All requests to an API should share one circuit and one counter to keep track of whether the circuit should break. Queries and mutations shouldn't be treated specially. I'll see if I figure out that path tomorrow.

Perhaps it is enough to find a way to disable retrying for mutations?

I guess that approach could work to get this PR merged, and then we could further refine it in another PR if we need to.

I've disabled retrying for mutations by only using the circuit breaker policy to wrap the mutationFn instead of using the circuit breaker and retry policies.

FrederikBolding · 2026-07-09T11:34:52Z

+   * Additionally `retry` and `retryDelay` are not available, retries can be customized using the `servicePolicyOptions`.
+   * @returns The mutation results.
+   */
+  protected async executeMutation<


The mutation cache is separate from the query cache, should we sync it with the UI as well?

E.g. https://github.com/MetaMask/core/blob/main/packages/base-data-service/src/BaseDataService.ts#L145-L152

Ooh good point. Okay I'll make this change.

I've made changes to createUIQueryClient to accommodate mutations.

mcmire · 2026-07-09T21:01:55Z

Moving this PR back to draft. There's still more work to do here in order to properly support mutations.

## Explanation  `createUIQueryClient` takes a messenger that is too broadly typed: it does not require that the actions and events that the messenger can access are actually scoped to the given data services. This was actually causing a type error in `createUIQueryClient.test.ts` — which replicates realistic usage of `createUIQueryClient` — but neither ESLint nor Jest caught it. This commit fixes the `MessengerAdapter` type so the type error goes away and adds a special test file we can run with `tsc` to ensure it doesn't pop up again. ## References  This is blocking MetaMask#9324. https://consensyssoftware.atlassian.net/browse/WPC-1171 ## Checklist - [x] I've updated the test suite for new or updated code as appropriate - [x] I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate - [x] I've communicated my changes to consumers by [updating changelogs for packages I've changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md) - [x] I've introduced [breaking changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md) in this PR and have prepared draft pull requests for clients and consumer packages to resolve them - Extension PR: MetaMask/metamask-extension#44498 - Mobile PR: MetaMask/metamask-mobile#33450  --- > [!NOTE] > **Medium Risk** > Breaking TypeScript contract for `createUIQueryClient` and exported messenger adapter shapes may fail consumer builds until adapters are retyped; runtime query/invalidation behavior is largely unchanged. > > **Overview** > **`createUIQueryClient`** now takes a **readonly** data-service name tuple and a **`MessengerAdapter`** scoped to those names: `call` only accepts `` `${Service}:${string}` `` actions (with `unknown[]` params instead of `Json[]`), and `subscribe` / `unsubscribe` only accept granular `` `:cacheUpdated:${hash}` `` events. Runtime checks use the same name guards; query and invalidation paths no longer cast messenger arguments through `Json`. > > **`@metamask/base-data-service`** publicly exports **`DataServiceActions`** and **`DataServiceEvents`** so consumers can type messengers against data services. > > **Testing / repo hygiene:** `@metamask/react-data-query` adds **tstyche** (`createUIQueryClient.tst.ts`), Jest coverage for adapter proxying and invalidation forwarding, and build excludes `*.tst.ts`. **`yarn.config.cjs`** centralizes **`expectTestScripts`** so workspaces with `test:types` use `test:unit` + tstyche (messenger scripts renamed to match). > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit fa890ae. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>

mcmire · 2026-08-04T04:24:48Z

I just realized that it's probably best if I wait until we upgrade base-data-service to @tanstack/query-core v5. There are some slightly API differences in v5 and I don't want to have to mimic v4 only to then have to migrate to v5 anyway.

mcmire · 2026-08-28T21:53:15Z

Almost done. Working through the tests to make sure that the way we test mutations is very similar to the way we've tested queries.

Currently, `BaseDataService` has a `fetchQuery` method which is best used for making read-only requests ("queries" in TanStack Query parlance), but does not work as well for requests that change state on the server side ("mutations"). For instance, queries are cacheable, but mutations are not. This commit adds a separate method, `executeMutation`, which accommodates mutations better. Its implementation is different from `fetchQuery` as it uses the mutation cache instead of the query cache. Also, retries are disabled.

FrederikBolding · 2026-09-04T09:02:49Z

+          // NOTE: Can't use HttpError from controller-utils due to lint:tsc not
+          // being fully rolled out across the monorepo.


Suggested change

// NOTE: Can't use HttpError from controller-utils due to lint:tsc not

// being fully rolled out across the monorepo.

Nit: personally I would just remove these

Sure, makes sense. Removed here: 9539ca9

FrederikBolding · 2026-09-04T09:04:18Z

  init(): void {
-    this.#loadCache().catch(
+    this.#loadCache().catch((error) =>
      /* istanbul ignore next */


This directive doesn't work now that it has been moved inside the arrow function

Yeah I don't know what I was thinking here. I've fully reverted this change here: 5bae879

FrederikBolding · 2026-09-04T09:06:49Z

 };

+const DATA_SERVICE_MUTATION_DEFAULTS = {
+  retry: false,


How come we don't want staleTime: 0 for mutations?

staleTime isn't an option for useMutation, it's only an option for useQuery and useInfiniteQuery. I think this is because there is no concept of "freshness" or "staleness" for mutations like there is for queries.

The UI query client deduplicated mutations by mutation key alone, which could misroute service :cacheUpdated state onto the wrong UI mutation when multiple mutations shared a key, orphan concurrent mutations, and clobber mutations that used a custom mutationFn. Introduce a UI-generated globalId that uniquely correlates one UI mutation with the service-side mutation it triggers. The UI stores the globalId on the mutation's meta, passes it as the trailing action argument, and matches incoming cache updates strictly by it. executeMutation accepts an optional globalId and echoes it back on the service-side mutation's meta so it rides along in dehydrated payloads.

hydrateMutations, deriveMutationAction, and readGlobalId lived inside createUIQueryClient and were only exercised indirectly through integration tests. Extract them into hydrateMutations.ts and add a dedicated unit test that covers every deriveMutationAction branch, including the previously-untested pending and idle (continue) cases. Remove the integration tests from createUIQueryClient.test.ts that only existed to reach the derive-action logic, keeping one that verifies the full round-trip synchronization between clients.

cursor

Stale Bugbot comment from a previous run.

The globalId used to correlate UI and service mutations was minted inside the defaultMutationOptions override, which runs whenever a mutation's options are defaulted rather than once per mutation. This caused two bugs: - Calling mutate() more than once on the same observer reused the memoized globalId (since mutationFn was already set), so a :cacheUpdated payload could be applied to the wrong cache entry. - Re-defaulting an observer's options (as useMutation does on every render) minted a fresh globalId and, for a pending mutation, replaced the live mutation's meta, detaching it from its in-flight service-side events. Move globalId minting into a mutationCache.build override, which runs exactly once per Mutation instance, and read the id from context.meta in the installed mutationFn instead of a captured variable. Guard the built mutation's setOptions so later option swaps preserve its globalId.

mcmire · 2026-09-10T21:53:51Z

    }
  });

+  const mutationCache = client.getMutationCache();


To be honest, this is getting a little messy and I am curious whether it would make sense to subclass QueryClient rather than patch it like this. I've done my best to follow the existing conventions here but we may want to investigate a cleanup in a future PR.

mcmire · 2026-09-10T21:55:11Z

@@ -1,7 +1,14 @@
-import { QueryKey } from '@metamask/base-data-service';
+/**


This comment was already present, I just moved it up so it's more clear it's applicable to the whole file.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fe79ca0. Configure here.}

The mutation cache listener hydrated every non-'removed' :cacheUpdated event, including 'added'. A data service emits 'added' when it first builds a mutation, while it is still 'idle' with no result, so hydrating it overwrote (and wiped the result of) a UI mutation that had already settled. Sync only 'updated' events, which are the ones that carry a meaningful mutation state. Also restore the two-argument form of the 'globalId' assert in the data-service mutationFn. It had regressed to assert('...message...'), which passes the message as the (always-truthy) condition, so it never threw and never narrowed 'globalId' to a string.

mcmire · 2026-09-11T15:17:09Z

@FrederikBolding When you get back, I've made some changes to this PR in response to feedback from you, Jongsun, and Cursor. It's ready for review again.

mcmire force-pushed the add-execute-mutation branch from 7e277f0 to 603d673 Compare June 30, 2026 22:07

mcmire commented Jun 30, 2026

View reviewed changes

mcmire marked this pull request as ready for review June 30, 2026 22:14

mcmire requested a review from a team as a code owner June 30, 2026 22:14

mcmire temporarily deployed to default-branch June 30, 2026 22:14 — with GitHub Actions Inactive

cursor Bot reviewed Jun 30, 2026

View reviewed changes

Comment thread packages/base-data-service/tests/mocks.ts Outdated

Comment thread packages/base-data-service/src/BaseDataService.ts Outdated

FrederikBolding reviewed Jul 1, 2026

View reviewed changes

FrederikBolding reviewed Jul 9, 2026

View reviewed changes

mcmire marked this pull request as draft July 9, 2026 21:01

mcmire mentioned this pull request Jul 10, 2026

Constrain MessengerAdapter to match given data services #9475

Merged

4 tasks

mcmire changed the base branch from main to fix-messenger-adapter-type July 27, 2026 18:16

Base automatically changed from fix-messenger-adapter-type to main July 30, 2026 22:21

mcmire force-pushed the add-execute-mutation branch from 5ce00ba to ec84edc Compare August 4, 2026 04:23

mcmire force-pushed the add-execute-mutation branch from ec84edc to e9cba53 Compare August 28, 2026 20:41

mcmire changed the base branch from main to enable-typechecking-for-react-data-query August 28, 2026 20:42

Base automatically changed from enable-typechecking-for-react-data-query to main September 2, 2026 13:42

mcmire force-pushed the add-execute-mutation branch 6 times, most recently from 9162ced to 4c370ee Compare September 2, 2026 19:18

mcmire force-pushed the add-execute-mutation branch from 4c370ee to eb74071 Compare September 2, 2026 19:30

mcmire added 2 commits September 2, 2026 13:43

Add missing comment

ea44597

Remove 100% test coverage

00baf1c

Export useMutation

f07ef66

FrederikBolding reviewed Sep 4, 2026

View reviewed changes

mcmire added 4 commits September 4, 2026 11:12

Fully revert 'istanbul ignore' lines

5bae879

Wrap comment

e2b7230

Simplify check in mutation cache subscription handler

10b5928

Remove extraneous comments

9539ca9

MajorLift mentioned this pull request Sep 4, 2026

Block QueryClient API surface in UI #8530

Open

7 tasks

mcmire added 4 commits September 4, 2026 13:00

Refactor the conditional into processMutationResponse

2473a50

Clean up

b7639a8

cursor Bot reviewed Sep 4, 2026

View reviewed changes

Comment thread packages/react-data-query/src/createUIQueryClient.ts

mcmire added 2 commits September 4, 2026 16:31

Clean up 2

80dc628

Clean up 3

6381ab9

This was referenced Sep 10, 2026

[DON'T MERGE] Apply executeMutation pattern across some data services for testing #10176

Draft

[DON'T MERGE] Bump authenticated-user-storage to use mutations for persisting watchlist MetaMask/metamask-mobile#36083

Draft

mcmire added 4 commits September 10, 2026 13:10

Use Struct<TMutationFnData> instead of Struct<any>

b0c3b8d

Add a caveat about setQueryData

4e37555

Merge branch 'main' into add-execute-mutation

fe79ca0

mcmire commented Sep 10, 2026

View reviewed changes

cursor Bot reviewed Sep 10, 2026

View reviewed changes

Comment thread packages/react-data-query/src/createUIQueryClient.ts

mcmire added 5 commits September 11, 2026 08:45

Fix assert

17dcc25

Merge branch 'main' into add-execute-mutation

5eb3b29

Update changelog

09b7d0f

Bump uuid to 9.0.1

ac8209b

		// NOTE: Can't use HttpError from controller-utils due to lint:tsc not
		// being fully rolled out across the monorepo.

		@@ -1,7 +1,14 @@
		import { QueryKey } from '@metamask/base-data-service';
		/**

Uh oh!

Uh oh!

Conversation

mcmire commented Jun 30, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explanation

References

Manual testing

Checklist

Uh oh!

mcmire Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcmire Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcmire Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FrederikBolding Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcmire Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FrederikBolding Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcmire Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcmire commented Jul 9, 2026

Uh oh!

mcmire commented Aug 4, 2026

Uh oh!

mcmire commented Aug 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcmire commented Jun 30, 2026 •

edited by cursor Bot

Loading

mcmire Jun 30, 2026 •

edited

Loading

mcmire Sep 2, 2026 •

edited

Loading

mcmire Jul 1, 2026 •

edited

Loading

FrederikBolding Jul 2, 2026 •

edited

Loading

mcmire Jul 2, 2026 •

edited

Loading

FrederikBolding Jul 6, 2026 •

edited

Loading

mcmire Jul 9, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading