Migrate SampleGasPriceService to BaseDataService (#8343)

## Explanation

<!--
Thanks for your contribution! Take a moment to answer these questions so
that reviewers have the information they need to properly understand
your changes:

* What is the current state of things and why does it need to change?
* What is the solution your changes offer and how does it work?
* Are there any changes whose purpose might not obvious to those
unfamiliar with the domain?
* If your primary goal was to update one package but you found you had
to update another one along the way, why did you do so?
* If you had to upgrade a dependency, why did you do so?
-->

With the release of `@metamask/base-data-service`, the
`SampleGasPricesService` class needs to be updated so that new data
services follow our best practices.

## References

<!--
Are there any issues that this pull request is tied to?
Are there other links that reviewers should consult to understand these
changes better?
Are there client or consumer pull requests to adopt any breaking
changes?

For example:

* Fixes #12345
* Related to #67890
-->

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

## 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)
- [ ] 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

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Introduces breaking API changes (service inheritance and removed
`onRetry`/`onBreak`/`onDegraded`) and changes request behavior to be
query-cached/deduplicated, which could affect consumers and error/retry
semantics.
> 
> **Overview**
> Migrates `SampleGasPricesService` to extend
`@metamask/base-data-service`’s `BaseDataService`, switching
`fetchGasPrices` to use `fetchQuery` (TanStack Query) so API calls are
**cached and deduplicated** and adding optional `queryClientConfig` for
cache/client tuning.
> 
> Adds new messenger surface area for cache management/observability
(`:invalidateQueries` action plus `cacheUpdated` events), exports the
new types from `src/index.ts`, and updates tests accordingly while
removing the previous `onRetry`/`onBreak`/`onDegraded` hooks. Dependency
and TS project references are updated to include
`@metamask/base-data-service`, `@tanstack/query-core`, and
`@metamask/superstruct` (used for response validation).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
3a60272. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: mcmire

packages/sample-controllers/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add actions and events for accessing and interacting with the new query cache for `SampleGasPricesService` ([#8343](https://github.com/MetaMask/core/pull/8343))
+  - New actions and events are:
+    - `SampleGasPricesServiceInvalidateQueriesAction`
+    - `SampleGasPricesServiceCacheUpdatedEvent`
+    - `SampleGasPricesServiceGranularCacheUpdatedEvent`
+  - Additionally, the actions are available within `SampleGasPricesServiceActions` and the events are available within `SampleGasPricesServiceEvents`
+- Add optional `queryClientConfig` constructor argument which can be used to configure the underlying TanStack Query client ([#8343](https://github.com/MetaMask/core/pull/8343))
+- Add `destroy` method to `BaseDataService` ([#8343](https://github.com/MetaMask/core/pull/8343))
+
+### Changed
+
+- **BREAKING:** `SampleGasPricesService` now inherits from `BaseDataService` from `@metamask/base-data-service` ([#8343](https://github.com/MetaMask/core/pull/8343))
+- Update `SampleGasPricesService.fetchGasPrices` (and messenger action) so requests to API will be cached and/or deduplicated ([#8343](https://github.com/MetaMask/core/pull/8343))
+- Add new dependencies ([#8343](https://github.com/MetaMask/core/pull/8343))
+  - Add `@metamask/base-data-service` ^0.1.1
+  - Add `@tanstack/query-core` ^4.43.0
+  - Add `@metamask/superstruct` ^3.2.1
+
+### Removed
+
+- **BREAKING:** Remove `onRetry`, `onBreak`, and `onDegraded` ([#8343](https://github.com/MetaMask/core/pull/8343))
+  - You are free to implement these methods in your "real" service class if you need them, but we no longer require you to do so.
+
 ## [4.0.4]
 
 ### Changed

packages/sample-controllers/package.json

@@ -49,9 +49,12 @@
   },
   "dependencies": {
     "@metamask/base-controller": "^9.0.1",
+    "@metamask/base-data-service": "^0.1.1",
     "@metamask/messenger": "^1.0.0",
     "@metamask/network-controller": "^30.0.1",
-    "@metamask/utils": "^11.9.0"
+    "@metamask/superstruct": "^3.1.0",
+    "@metamask/utils": "^11.9.0",
+    "@tanstack/query-core": "^4.43.0"
   },
   "devDependencies": {
     "@metamask/auto-changelog": "^3.4.4",

packages/sample-controllers/src/index.ts

@@ -1,5 +1,8 @@
 export type {
+  SampleGasPricesServiceInvalidateQueriesAction,
   SampleGasPricesServiceActions,
+  SampleGasPricesServiceCacheUpdatedEvent,
+  SampleGasPricesServiceGranularCacheUpdatedEvent,
   SampleGasPricesServiceEvents,
   SampleGasPricesServiceMessenger,
 } from './sample-gas-prices-service/sample-gas-prices-service';

packages/sample-controllers/src/sample-gas-prices-service/sample-gas-prices-service.test.ts

@@ -1,4 +1,4 @@
-import { HttpError } from '@metamask/controller-utils';
+import { DEFAULT_MAX_RETRIES } from '@metamask/controller-utils';
 import { Messenger, MOCK_ANY_NAMESPACE } from '@metamask/messenger';
 import type {
   MockAnyNamespace,
@@ -11,14 +11,6 @@ import type { SampleGasPricesServiceMessenger } from './sample-gas-prices-servic
 import { SampleGasPricesService } from './sample-gas-prices-service';
 
 describe('SampleGasPricesService', () => {
-  beforeEach(() => {
-    jest.useFakeTimers({ doNotFake: ['nextTick', 'queueMicrotask'] });
-  });
-
-  afterEach(() => {
-    jest.useRealTimers();
-  });
-
   describe('SampleGasPricesService:fetchGasPrices', () => {
     it('returns the low, average, and high gas prices from the API', async () => {
       nock('https://api.example.com')
@@ -31,7 +23,7 @@ describe('SampleGasPricesService', () => {
             high: 15,
           },
         });
-      const { rootMessenger } = getService();
+      const { rootMessenger } = createService();
 
       const gasPricesResponse = await rootMessenger.call(
         'SampleGasPricesService:fetchGasPrices',
@@ -45,6 +37,19 @@ describe('SampleGasPricesService', () => {
       });
     });
 
+    it('throws if the API returns a non-200 status', async () => {
+      nock('https://api.example.com')
+        .get('/gas-prices')
+        .query({ chainId: 'eip155:1' })
+        .times(DEFAULT_MAX_RETRIES + 1)
+        .reply(500);
+      const { rootMessenger } = createService();
+
+      await expect(
+        rootMessenger.call('SampleGasPricesService:fetchGasPrices', '0x1'),
+      ).rejects.toThrow("Gas prices API failed with status '500'");
+    });
+
     it.each([
       'not an object',
       { missing: 'data' },
@@ -62,202 +67,13 @@ describe('SampleGasPricesService', () => {
           .get('/gas-prices')
           .query({ chainId: 'eip155:1' })
           .reply(200, JSON.stringify(response));
-        const { rootMessenger } = getService();
+        const { rootMessenger } = createService();
 
         await expect(
           rootMessenger.call('SampleGasPricesService:fetchGasPrices', '0x1'),
         ).rejects.toThrow('Malformed response received from gas prices API');
       },
     );
-
-    it('calls onDegraded listeners if the request takes longer than 5 seconds to resolve', async () => {
-      nock('https://api.example.com')
-        .get('/gas-prices')
-        .query({ chainId: 'eip155:1' })
-        .reply(200, () => {
-          jest.advanceTimersByTime(6000);
-          return {
-            data: {
-              low: 5,
-              average: 10,
-              high: 15,
-            },
-          };
-        });
-      const { service, rootMessenger } = getService();
-      const onDegradedListener = jest.fn();
-      service.onDegraded(onDegradedListener);
-
-      await rootMessenger.call('SampleGasPricesService:fetchGasPrices', '0x1');
-
-      expect(onDegradedListener).toHaveBeenCalled();
-    });
-
-    it('allows the degradedThreshold to be changed', async () => {
-      nock('https://api.example.com')
-        .get('/gas-prices')
-        .query({ chainId: 'eip155:1' })
-        .reply(200, () => {
-          jest.advanceTimersByTime(1000);
-          return {
-            data: {
-              low: 5,
-              average: 10,
-              high: 15,
-            },
-          };
-        });
-      const { service, rootMessenger } = getService({
-        options: {
-          policyOptions: { degradedThreshold: 500 },
-        },
-      });
-      const onDegradedListener = jest.fn();
-      service.onDegraded(onDegradedListener);
-
-      await rootMessenger.call('SampleGasPricesService:fetchGasPrices', '0x1');
-
-      expect(onDegradedListener).toHaveBeenCalled();
-    });
-
-    it('attempts a request that responds with non-200 up to 4 times, throwing if it never succeeds', async () => {
-      nock('https://api.example.com')
-        .get('/gas-prices')
-        .query({ chainId: 'eip155:1' })
-        .times(4)
-        .reply(500);
-      const { service, rootMessenger } = getService();
-      service.onRetry(() => {
-        jest.advanceTimersToNextTimerAsync().catch(console.error);
-      });
-
-      await expect(
-        rootMessenger.call('SampleGasPricesService:fetchGasPrices', '0x1'),
-      ).rejects.toThrow(
-        "Fetching 'https://api.example.com/gas-prices?chainId=eip155%3A1' failed with status '500'",
-      );
-    });
-
-    it('calls onDegraded listeners when the maximum number of retries is exceeded', async () => {
-      nock('https://api.example.com')
-        .get('/gas-prices')
-        .query({ chainId: 'eip155:1' })
-        .times(4)
-        .reply(500);
-      const { service, rootMessenger } = getService();
-      service.onRetry(() => {
-        jest.advanceTimersToNextTimerAsync().catch(console.error);
-      });
-      const onDegradedListener = jest.fn();
-      service.onDegraded(onDegradedListener);
-
-      await expect(
-        rootMessenger.call('SampleGasPricesService:fetchGasPrices', '0x1'),
-      ).rejects.toThrow(
-        "Fetching 'https://api.example.com/gas-prices?chainId=eip155%3A1' failed with status '500'",
-      );
-      expect(onDegradedListener).toHaveBeenCalled();
-    });
-
-    it('intercepts requests and throws a circuit break error after the 4th failed attempt, running onBreak listeners', async () => {
-      nock('https://api.example.com')
-        .get('/gas-prices')
-        .query({ chainId: 'eip155:1' })
-        .times(12)
-        .reply(500);
-      const { service, rootMessenger } = getService();
-      service.onRetry(() => {
-        jest.advanceTimersToNextTimerAsync().catch(console.error);
-      });
-      const onBreakListener = jest.fn();
-      service.onBreak(onBreakListener);
-
-      // Should make 4 requests
-      await expect(
-        rootMessenger.call('SampleGasPricesService:fetchGasPrices', '0x1'),
-      ).rejects.toThrow(
-        "Fetching 'https://api.example.com/gas-prices?chainId=eip155%3A1' failed with status '500'",
-      );
-      // Should make 4 requests
-      await expect(
-        rootMessenger.call('SampleGasPricesService:fetchGasPrices', '0x1'),
-      ).rejects.toThrow(
-        "Fetching 'https://api.example.com/gas-prices?chainId=eip155%3A1' failed with status '500'",
-      );
-      // Should make 4 requests
-      await expect(
-        rootMessenger.call('SampleGasPricesService:fetchGasPrices', '0x1'),
-      ).rejects.toThrow(
-        "Fetching 'https://api.example.com/gas-prices?chainId=eip155%3A1' failed with status '500'",
-      );
-      // Should not make an additional request (we only mocked 12 requests
-      // above)
-      await expect(
-        rootMessenger.call('SampleGasPricesService:fetchGasPrices', '0x1'),
-      ).rejects.toThrow(
-        'Execution prevented because the circuit breaker is open',
-      );
-      expect(onBreakListener).toHaveBeenCalledWith({
-        error: new HttpError(
-          500,
-          "Fetching 'https://api.example.com/gas-prices?chainId=eip155%3A1' failed with status '500'",
-        ),
-      });
-    });
-
-    it('resumes requests after the circuit break duration passes, returning the API response if the request ultimately succeeds', async () => {
-      const circuitBreakDuration = 5_000;
-      nock('https://api.example.com')
-        .get('/gas-prices')
-        .query({ chainId: 'eip155:1' })
-        .times(12)
-        .reply(500)
-        .get('/gas-prices')
-        .query({ chainId: 'eip155:1' })
-        .reply(200, {
-          data: {
-            low: 5,
-            average: 10,
-            high: 15,
-          },
-        });
-      const { service, rootMessenger } = getService({
-        options: {
-          policyOptions: { circuitBreakDuration },
-        },
-      });
-      service.onRetry(() => {
-        jest.advanceTimersToNextTimerAsync().catch(console.error);
-      });
-
-      await expect(
-        rootMessenger.call('SampleGasPricesService:fetchGasPrices', '0x1'),
-      ).rejects.toThrow(
-        "Fetching 'https://api.example.com/gas-prices?chainId=eip155%3A1' failed with status '500'",
-      );
-      await expect(
-        rootMessenger.call('SampleGasPricesService:fetchGasPrices', '0x1'),
-      ).rejects.toThrow(
-        "Fetching 'https://api.example.com/gas-prices?chainId=eip155%3A1' failed with status '500'",
-      );
-      await expect(
-        rootMessenger.call('SampleGasPricesService:fetchGasPrices', '0x1'),
-      ).rejects.toThrow(
-        "Fetching 'https://api.example.com/gas-prices?chainId=eip155%3A1' failed with status '500'",
-      );
-      await expect(
-        rootMessenger.call('SampleGasPricesService:fetchGasPrices', '0x1'),
-      ).rejects.toThrow(
-        'Execution prevented because the circuit breaker is open',
-      );
-      await jest.advanceTimersByTimeAsync(circuitBreakDuration);
-      const gasPricesResponse = await service.fetchGasPrices('0x1');
-      expect(gasPricesResponse).toStrictEqual({
-        low: 5,
-        average: 10,
-        high: 15,
-      });
-    });
   });
 
   describe('fetchGasPrices', () => {
@@ -272,7 +88,7 @@ describe('SampleGasPricesService', () => {
             high: 15,
           },
         });
-      const { service } = getService();
+      const { service } = createService();
 
       const gasPricesResponse = await service.fetchGasPrices('0x1');
 
@@ -301,7 +117,7 @@ type RootMessenger = Messenger<
  *
  * @returns The root messenger.
  */
-function getRootMessenger(): RootMessenger {
+function createRootMessenger(): RootMessenger {
   return new Messenger({ namespace: MOCK_ANY_NAMESPACE });
 }
 
@@ -312,7 +128,7 @@ function getRootMessenger(): RootMessenger {
  * events required by the controller's messenger.
  * @returns The service-specific messenger.
  */
-function getMessenger(
+function createServiceMessenger(
   rootMessenger: RootMessenger,
 ): SampleGasPricesServiceMessenger {
   return new Messenger({
@@ -330,7 +146,7 @@ function getMessenger(
  * `messenger`).
  * @returns The new service, root messenger, and service messenger.
  */
-function getService({
+function createService({
   options = {},
 }: {
   options?: Partial<ConstructorParameters<typeof SampleGasPricesService>[0]>;
@@ -339,10 +155,9 @@ function getService({
   rootMessenger: RootMessenger;
   messenger: SampleGasPricesServiceMessenger;
 } {
-  const rootMessenger = getRootMessenger();
-  const messenger = getMessenger(rootMessenger);
+  const rootMessenger = createRootMessenger();
+  const messenger = createServiceMessenger(rootMessenger);
   const service = new SampleGasPricesService({
-    fetch,
     messenger,
     ...options,
   });