feat(base-data-service): Support persisting the cache by FrederikBolding · Pull Request #9445 · MetaMask/core

FrederikBolding · 2026-07-09T12:18:50Z

Explanation

Add support for cache persistence, which can be enabled by configuring persistenceConfig. Persistence is achieved using StorageService and debounced to not cause too many writes. Rehydration of the cache happens on init, while expired or invalid data is discarded. Any errors with persistence are logged, but ultimately ignored, due to the reduced importance of the data persisted.

This approach of storing the dehydrated state is similar to how @tanstack/query-persist-client-core works.

References

https://consensyssoftware.atlassian.net/browse/WPC-1128

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
Touches shared data-layer caching and storage I/O; stale or rehydrated cache could affect offline/API behavior, though persistence is opt-in and errors are non-fatal.

Overview
Adds optional TanStack Query cache persistence to BaseDataService via a new constructor persistenceConfig (maxAge, optional writeDelay / maxWriteDelay). When enabled, successful query cache entries are dehydrated and written through messenger actions to @metamask/storage-service under key cache, with lodash debounced writes after cache add/update/remove and removeItem when the cache is empty.

Introduces init() to rehydrate from storage on startup; entries older than maxAge are dropped and removed. Persistence is off unless persistenceConfig is set; storage failures are swallowed (logged via captureException). destroy() now cancels pending debounced writes.

The package gains dependencies on @metamask/storage-service and lodash, exports PersistenceConfiguration, and includes broad persistence tests. README dependency graph and changelog are updated.

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

## Explanation Separated out for review from MetaMask#9445, since it is needed for multiple PRs. Makes it easier to write tests for `BaseDataService` going forward. ## References N/A ## 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 - [ ] 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) - [ ] 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

FrederikBolding · 2026-07-15T08:54:14Z

+            (error) => this.#messenger.captureException?.(error),
+          );
+        },
+        this.#persistConfig.debounce ?? inMilliseconds(10, Duration.Second),


Open to suggestions for defaults here

Seems fine. Could consider shortening to 5 seconds if this is too slow in practice. But even 10 seconds doesn't seem bad.

Since they are non-critical writes, my thinking was starting higher and tweaking later, but 🤷‍♂️

cursor · 2026-07-15T09:09:45Z

+    this.#rehydrateCache().catch(
+      /* istanbul ignore next */
+      (error) => this.#messenger.captureException?.(error),
+    );


init does not await rehydration

Medium Severity

init() starts #rehydrateCache but returns immediately without a Promise, so callers cannot await completion. Fetches issued right after init() may run before persisted data is hydrated and can hit the network even when valid cached data exists.

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

I don't think we want to wait for this anywhere, so this was intended 🤔

Why don't we want to wait?

I was thinking this would be similar to controllers providing a fire and forget init function to do setup.

I don't think we would want to block anywhere in the clients to wait for loading these persisted caches 🤔

Yeah I guess the question is, if cache persistence is not fully initialized will this prevent the data service from functioning correctly or would it cause adverse effects? It sounds like it would not, but just want to make sure.

It shouldn't, it just means that we may have to refetch queries. Similarly to if fetching the cache fails for whatever reason.

Okay, that's what I thought. Yeah I guess that's not so bad.

mcmire · 2026-07-15T13:32:20Z

+    this.#rehydrateCache().catch(
+      /* istanbul ignore next */
+      (error) => this.#messenger.captureException?.(error),
+    );


Why don't we want to wait?

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

There are 3 total unresolved issues (including 1 from previous review).

^{❌ 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 43b812d. Configure here.}

mcmire

LGTM!

FrederikBolding mentioned this pull request Jul 14, 2026

test(base-data-service): Use fake timers #9496

Merged

4 tasks

FrederikBolding force-pushed the fb/base-data-service-persistence branch from ceae8cf to 7412c82 Compare July 14, 2026 13:19

FrederikBolding commented Jul 15, 2026

View reviewed changes

FrederikBolding marked this pull request as ready for review July 15, 2026 09:07

FrederikBolding requested a review from a team as a code owner July 15, 2026 09:07

FrederikBolding temporarily deployed to default-branch July 15, 2026 09:07 — with GitHub Actions Inactive

cursor Bot reviewed Jul 15, 2026

View reviewed changes

Mrtenz reviewed Jul 15, 2026

View reviewed changes

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

FrederikBolding requested a review from Mrtenz July 15, 2026 09:30

Mrtenz reviewed Jul 15, 2026

View reviewed changes

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

Mrtenz reviewed Jul 15, 2026

View reviewed changes

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

FrederikBolding requested a review from Mrtenz July 15, 2026 09:48

Mrtenz reviewed Jul 15, 2026

View reviewed changes

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

FrederikBolding requested a review from Mrtenz July 15, 2026 11:28

mcmire reviewed Jul 15, 2026

View reviewed changes

FrederikBolding force-pushed the fb/base-data-service-persistence branch from f0e55be to 43b812d Compare July 15, 2026 14:40

FrederikBolding requested a review from mcmire July 15, 2026 14:40

cursor Bot reviewed Jul 15, 2026

View reviewed changes

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

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

FrederikBolding added 11 commits July 15, 2026 16:54

feat(base-data-service): Support persisting the cache

4a8c3ee

Add debounce

ec5e0b4

Update README

0039665

Fix build

fa7739a

Add test for StorageService failure

b6058e3

Add remaining tests

c264385

Simplify

e34c40c

Make debounce configurable

56f331d

Add CHANGELOG entry

09f9829

Fix lint

869f361

Export STORAGE_SERVICE_KEY

9f241d7

FrederikBolding added 8 commits July 15, 2026 16:54

Add more JSDoc

6aa6bbd

Export PersistenceConfiguration

2bfff42

Address more comments

4bca6a5

Clear the cache if it is expired or empty

c7da4a1

Fix lint

e36492a

Explicit shouldDehydrateQuery

1d8b962

Address PR comments

240399a

Rename persistence options

79adfe5

FrederikBolding force-pushed the fb/base-data-service-persistence branch from 43b812d to 79adfe5 Compare July 15, 2026 14:54

mcmire approved these changes Jul 15, 2026

View reviewed changes

FrederikBolding added this pull request to the merge queue Jul 15, 2026

Merged via the queue into main with commit 146712f Jul 15, 2026
426 checks passed

FrederikBolding deleted the fb/base-data-service-persistence branch July 15, 2026 15:08

Uh oh!

Uh oh!

Conversation

FrederikBolding commented Jul 9, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explanation

References

Checklist

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!

Uh oh!

cursor Bot Jul 15, 2026

Choose a reason for hiding this comment

init does not await rehydration

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mcmire left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

FrederikBolding commented Jul 9, 2026 •

edited by cursor Bot

Loading