feat: Migrate controller guidelines and examples to new Messenger

Migrate the controller guidelines and the `sample-controllers` package
to the `next` export of the `@metamask/base-controller` package and the
new `Messenger` class from `@metamask/messenger`.

Author: Gudahtt

docs/controller-guidelines.md

@@ -78,7 +78,7 @@ Next we'll define the messenger. We give the messenger a namespace, and we expos
 ```typescript
 // (top of file)
 
-import type { RestrictedMessenger } from '@metamask/base-controller';
+import type { Messenger } from '@metamask/base-controller';
 
 const SERVICE_NAME = 'GasPricesService';
 

docs/data-services.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **BREAKING:** Migrate to new `Messenger` class ([#6335](https://github.com/MetaMask/core/pull/6335))
 - Bump `@metamask/utils` from `^11.2.0` to `^11.4.2` ([#6054](https://github.com/MetaMask/core/pull/6054))
 - Bump `@metamask/base-controller` from `^8.0.1` to `^8.1.0` ([#6284](https://github.com/MetaMask/core/pull/6284))
 

packages/sample-controllers/CHANGELOG.md

@@ -48,6 +48,7 @@
   },
   "dependencies": {
     "@metamask/base-controller": "^8.1.0",
+    "@metamask/messenger": "^0.0.0",
     "@metamask/utils": "^11.4.2"
   },
   "devDependencies": {

packages/sample-controllers/package.json

@@ -1,16 +1,12 @@
-import { Messenger } from '@metamask/base-controller';
-import { SampleGasPricesController } from '@metamask/sample-controllers';
-import type { SampleGasPricesControllerMessenger } from '@metamask/sample-controllers';
-
 import {
-  getDefaultNetworkControllerState,
-  type NetworkControllerGetStateAction,
-} from './network-controller-types';
+  Messenger,
+  type MessengerActions,
+  type MessengerEvents,
+} from '@metamask/messenger';
+
 import type { SampleAbstractGasPricesService } from './sample-gas-prices-service';
-import type {
-  ExtractAvailableAction,
-  ExtractAvailableEvent,
-} from '../../base-controller/tests/helpers';
+import { SampleGasPricesController } from '@metamask/sample-controllers';
+import type { SampleGasPricesControllerMessenger } from '@metamask/sample-controllers';
 
 describe('SampleGasPricesController', () => {
   describe('constructor', () => {
@@ -66,14 +62,8 @@ describe('SampleGasPricesController', () => {
         average: 10,
         high: 15,
       });
-      const rootMessenger = getRootMessenger({
-        networkControllerGetStateActionHandler: () => ({
-          ...getDefaultNetworkControllerState(),
-          chainId: '0x42',
-        }),
-      });
       const controller = new SampleGasPricesController({
-        messenger: getMessenger(rootMessenger),
+        messenger: getMessenger(),
         gasPricesService,
       });
 
@@ -94,56 +84,29 @@ describe('SampleGasPricesController', () => {
 });
 
 /**
- * The union of actions that the root messenger allows.
- */
-type RootAction = ExtractAvailableAction<SampleGasPricesControllerMessenger>;
-
-/**
- * The union of events that the root messenger allows.
+ * The union of all SampleGasPricesController actions.
  */
-type RootEvent = ExtractAvailableEvent<SampleGasPricesControllerMessenger>;
+type AllSampleGasPricesControllerActions =
+  MessengerActions<SampleGasPricesControllerMessenger>;
 
 /**
- * Constructs the unrestricted messenger. This can be used to call actions and
- * publish events within the tests for this controller.
- *
- * @param args - The arguments to this function.
- * @param args.networkControllerGetStateActionHandler - Used to mock the
- * `NetworkController:getState` action on the messenger.
- * @returns The unrestricted messenger suited for SampleGasPricesController.
+ * The union of all SampleGasPricesController events.
  */
-function getRootMessenger({
-  networkControllerGetStateActionHandler = jest
-    .fn<
-      ReturnType<NetworkControllerGetStateAction['handler']>,
-      Parameters<NetworkControllerGetStateAction['handler']>
-    >()
-    .mockReturnValue(getDefaultNetworkControllerState()),
-}: {
-  networkControllerGetStateActionHandler?: NetworkControllerGetStateAction['handler'];
-} = {}): Messenger<RootAction, RootEvent> {
-  const rootMessenger = new Messenger<RootAction, RootEvent>();
-  rootMessenger.registerActionHandler(
-    'NetworkController:getState',
-    networkControllerGetStateActionHandler,
-  );
-  return rootMessenger;
-}
+type AllSampleGasPricesControllerEvents =
+  MessengerEvents<SampleGasPricesControllerMessenger>;
 
 /**
- * Constructs the messenger which is restricted to relevant SampleGasPricesController
- * actions and events.
+ * Constructs the SampleGasPricesController messenger.
  *
- * @param rootMessenger - The root messenger to restrict.
- * @returns The restricted messenger.
+ * @returns The SampleGasPricesController messenger.
  */
-function getMessenger(
-  rootMessenger = getRootMessenger(),
-): SampleGasPricesControllerMessenger {
-  return rootMessenger.getRestricted({
-    name: 'SampleGasPricesController',
-    allowedActions: ['NetworkController:getState'],
-    allowedEvents: [],
+function getMessenger(): SampleGasPricesControllerMessenger {
+  return new Messenger<
+    'SampleGasPricesController',
+    AllSampleGasPricesControllerActions,
+    AllSampleGasPricesControllerEvents
+  >({
+    namespace: 'SampleGasPricesController',
   });
 }
 

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

@@ -1,10 +1,10 @@
 import type {
   ControllerGetStateAction,
   ControllerStateChangeEvent,
-  RestrictedMessenger,
   StateMetadata,
-} from '@metamask/base-controller';
-import { BaseController } from '@metamask/base-controller';
+} from '@metamask/base-controller/next';
+import { BaseController } from '@metamask/base-controller/next';
+import type { Messenger } from '@metamask/messenger';
 import type { Hex } from '@metamask/utils';
 
 import type { NetworkControllerGetStateAction } from './network-controller-types';
@@ -123,12 +123,10 @@ type AllowedEvents = never;
  * The messenger which is restricted to actions and events accessed by
  * {@link SampleGasPricesController}.
  */
-export type SampleGasPricesControllerMessenger = RestrictedMessenger<
+export type SampleGasPricesControllerMessenger = Messenger<
   typeof controllerName,
   SampleGasPricesControllerActions | AllowedActions,
-  SampleGasPricesControllerEvents | AllowedEvents,
-  AllowedActions['type'],
-  AllowedEvents['type']
+  SampleGasPricesControllerEvents | AllowedEvents
 >;
 
 /**

packages/sample-controllers/src/sample-gas-prices-controller.ts

@@ -1,11 +1,11 @@
-import { Messenger } from '@metamask/base-controller';
+import {
+  Messenger,
+  type MessengerActions,
+  type MessengerEvents,
+} from '@metamask/messenger';
 
 import type { SamplePetnamesControllerMessenger } from './sample-petnames-controller';
 import { SamplePetnamesController } from './sample-petnames-controller';
-import type {
-  ExtractAvailableAction,
-  ExtractAvailableEvent,
-} from '../../base-controller/tests/helpers';
 import { PROTOTYPE_POLLUTION_BLOCKLIST } from '../../controller-utils/src/util';
 
 describe('SamplePetnamesController', () => {
@@ -143,38 +143,28 @@ describe('SamplePetnamesController', () => {
 });
 
 /**
- * The union of actions that the root messenger allows.
+ * The union of all SamplePetnamesController actions.
  */
-type RootAction = ExtractAvailableAction<SamplePetnamesControllerMessenger>;
+type AllSamplePetnamesControllerActions =
+  MessengerActions<SamplePetnamesControllerMessenger>;
 
 /**
- * The union of events that the root messenger allows.
+ * The union of all SamplePetnamesController events.
  */
-type RootEvent = ExtractAvailableEvent<SamplePetnamesControllerMessenger>;
+type AllSamplePetnamesControllerEvents =
+  MessengerEvents<SamplePetnamesControllerMessenger>;
 
 /**
- * Constructs the unrestricted messenger. This can be used to call actions and
- * publish events within the tests for this controller.
+ * Constructs the SamplePetnamesController messenger.
  *
- * @returns The unrestricted messenger suited for SamplePetnamesController.
+ * @returns The SamplePetnamesController messenger.
  */
-function getRootMessenger(): Messenger<RootAction, RootEvent> {
-  return new Messenger<RootAction, RootEvent>();
-}
-
-/**
- * Constructs the messenger which is restricted to relevant SamplePetnamesController
- * actions and events.
- *
- * @param rootMessenger - The root messenger to restrict.
- * @returns The restricted messenger.
- */
-function getMessenger(
-  rootMessenger = getRootMessenger(),
-): SamplePetnamesControllerMessenger {
-  return rootMessenger.getRestricted({
-    name: 'SamplePetnamesController',
-    allowedActions: [],
-    allowedEvents: [],
+function getMessenger(): SamplePetnamesControllerMessenger {
+  return new Messenger<
+    'SamplePetnamesController',
+    AllSamplePetnamesControllerActions,
+    AllSamplePetnamesControllerEvents
+  >({
+    namespace: 'SamplePetnamesController',
   });
 }

packages/sample-controllers/src/sample-petnames-controller.test.ts

@@ -1,11 +1,11 @@
 import type {
   ControllerGetStateAction,
   ControllerStateChangeEvent,
-  RestrictedMessenger,
   StateMetadata,
-} from '@metamask/base-controller';
-import { BaseController } from '@metamask/base-controller';
+} from '@metamask/base-controller/next';
+import { BaseController } from '@metamask/base-controller/next';
 import { isSafeDynamicKey } from '@metamask/controller-utils';
+import type { Messenger } from '@metamask/messenger';
 import type { Hex } from '@metamask/utils';
 
 // === GENERAL ===
@@ -92,12 +92,10 @@ type AllowedEvents = never;
  * The messenger which is restricted to actions and events accessed by
  * {@link SamplePetnamesController}.
  */
-export type SamplePetnamesControllerMessenger = RestrictedMessenger<
+export type SamplePetnamesControllerMessenger = Messenger<
   typeof controllerName,
   SamplePetnamesControllerActions | AllowedActions,
-  SamplePetnamesControllerEvents | AllowedEvents,
-  AllowedActions['type'],
-  AllowedEvents['type']
+  SamplePetnamesControllerEvents | AllowedEvents
 >;
 
 /**

packages/sample-controllers/src/sample-petnames-controller.ts

@@ -7,6 +7,7 @@
   },
   "references": [
     { "path": "../../packages/base-controller/tsconfig.build.json" },
+    { "path": "../../packages/messenger/tsconfig.build.json" },
     { "path": "../../packages/network-controller/tsconfig.build.json" }
   ],
   "include": ["../../types", "./src"]

packages/sample-controllers/tsconfig.build.json

@@ -6,6 +6,7 @@
   "references": [
     { "path": "../../packages/base-controller" },
     { "path": "../../packages/controller-utils" },
+    { "path": "../../packages/messenger" },
     { "path": "../../packages/network-controller" }
   ],
   "include": ["../../types", "./src"],