feat: Add Messenger parant parameter

Add the `parent` constructor parameter to the `Messenger` class for
automatic delegation of all capabilities under that messenger's
namespace. This significantly reduces boilerplate, making the messenger
easier to use in a similar manner to how the old `RestrictedMessenger`
class wored.

See this ADR PR for details: MetaMask/decisions#53

Author: Gudahtt

packages/messenger/CHANGELOG.md

@@ -14,13 +14,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - These allow delegating or revoking capabilities (actions or events) from one `Messenger` instance to another.
   - This allows passing capabilities through chains of messengers of arbitrary length
   - See this ADR for details: https://github.com/MetaMask/decisions/blob/main/decisions/core/0012-messenger-delegation.md
+- Add `parent` constructor parameter to `Messenger` ([#6142](https://github.com/MetaMask/core/pull/6142))
+  - All capabilities registered under this messenger's namespace are delegated to the parent automatically. This is similar to how the `RestrictedMessenger` would automatically delegate all capabilities to the messenger it was created from.
 
 ### Changed
 
 - **BREAKING:** Add `Namespace` type parameter and required `namespace` constructor parameter ([#6132](https://github.com/MetaMask/core/pull/6132))
   - All published events and registered actions should fall under the given namespace. Typically the namespace is the controller or service name. This is the equivalent to the `Namespace` parameter from the old `RestrictedMessenger` class.
 - **BREAKING:** Remove `RestrictedMessenger` class ([#6132](https://github.com/MetaMask/core/pull/6132))
-  - Existing `RestrictedMessenger` instances should be replaced with a `Messenger`. We can now use the same class everywhere, passing capabilities using `delegate`.
+  - Existing `RestrictedMessenger` instances should be replaced with a `Messenger` with the `parent` constructor parameter set to the global messenger. We can now use the same class everywhere, passing capabilities using `delegate`.
   - See this ADR for details: https://github.com/MetaMask/decisions/blob/main/decisions/core/0012-messenger-delegation.md
 
 [Unreleased]: https://github.com/MetaMask/core/

packages/messenger/src/Messenger.test.ts

@@ -26,6 +26,28 @@ describe('Messenger', () => {
     expect(count).toBe(1);
   });
 
+  it('automatically delegates actions to parent upon registration', () => {
+    type CountAction = {
+      type: 'Fixture:count';
+      handler: (increment: number) => void;
+    };
+    const parentMessenger = new Messenger<'Parent', CountAction, never>({
+      namespace: 'Parent',
+    });
+    const messenger = new Messenger<'Fixture', CountAction, never>({
+      namespace: 'Fixture',
+      parent: parentMessenger,
+    });
+
+    let count = 0;
+    messenger.registerActionHandler('Fixture:count', (increment: number) => {
+      count += increment;
+    });
+    parentMessenger.call('Fixture:count', 1);
+
+    expect(count).toBe(1);
+  });
+
   it('should allow registering and calling multiple different action handlers', () => {
     // These 'Other' types are included to demonstrate that messenger generics can indeed be unions
     // of actions and events from different modules.
@@ -225,6 +247,24 @@ describe('Messenger', () => {
     expect(handler.callCount).toBe(1);
   });
 
+  it('automatically delegates events to parent upon first publish', () => {
+    type MessageEvent = { type: 'Fixture:message'; payload: [string] };
+    const parentMessenger = new Messenger<'Parent', never, MessageEvent>({
+      namespace: 'Parent',
+    });
+    const messenger = new Messenger<'Fixture', never, MessageEvent>({
+      namespace: 'Fixture',
+      parent: parentMessenger,
+    });
+
+    const handler = sinon.stub();
+    parentMessenger.subscribe('Fixture:message', handler);
+    messenger.publish('Fixture:message', 'hello');
+
+    expect(handler.calledWithExactly('hello')).toBe(true);
+    expect(handler.callCount).toBe(1);
+  });
+
   it('should allow publishing multiple different events to subscriber', () => {
     type MessageEvent =
       | { type: 'Fixture:message'; payload: [string] }
@@ -513,6 +553,42 @@ describe('Messenger', () => {
     });
   });
 
+  it('automatically delegates to parent when an initial payload is registered', () => {
+    const state = {
+      propA: 1,
+      propB: 1,
+    };
+    type MessageEvent = {
+      type: 'Fixture:complexMessage';
+      payload: [typeof state];
+    };
+    const parentMessenger = new Messenger<'Parent', never, MessageEvent>({
+      namespace: 'Parent',
+    });
+    const messenger = new Messenger<'Fixture', never, MessageEvent>({
+      namespace: 'Fixture',
+      parent: parentMessenger,
+    });
+    const handler = sinon.stub();
+
+    messenger.registerInitialEventPayload({
+      eventType: 'Fixture:complexMessage',
+      getPayload: () => [state],
+    });
+
+    parentMessenger.subscribe(
+      'Fixture:complexMessage',
+      handler,
+      (obj) => obj.propA,
+    );
+    messenger.publish('Fixture:complexMessage', state);
+    expect(handler.callCount).toBe(0);
+    state.propA += 1;
+    messenger.publish('Fixture:complexMessage', state);
+    expect(handler.getCall(0)?.args).toStrictEqual([2, 1]);
+    expect(handler.callCount).toBe(1);
+  });
+
   it('should publish event to many subscribers with the same selector', () => {
     type MessageEvent = {
       type: 'Fixture:complexMessage';
@@ -1080,6 +1156,27 @@ describe('Messenger', () => {
   });
 
   describe('revoke', () => {
+    it('throws when attempting to revoke from parent', () => {
+      type ExampleEvent = {
+        type: 'Source:event';
+        payload: ['test'];
+      };
+      const parentMessenger = new Messenger<'Parent', never, ExampleEvent>({
+        namespace: 'Parent',
+      });
+      const sourceMessenger = new Messenger<'Source', never, ExampleEvent>({
+        namespace: 'Source',
+        parent: parentMessenger,
+      });
+
+      expect(() =>
+        sourceMessenger.revoke({
+          messenger: parentMessenger,
+          events: ['Source:event'],
+        }),
+      ).toThrow('Cannot revoke from parent');
+    });
+
     it('allows revoking a delegated event', () => {
       type ExampleEvent = {
         type: 'Source:event';

packages/messenger/src/Messenger.ts

@@ -134,12 +134,22 @@ export class Messenger<
 > {
   readonly #namespace: Namespace;
 
+  /**
+   * The parent messenger. All actions/events under this namespace are automatically delegated to
+   * the parent messenger.
+   */
+  readonly #parent?: Messenger<
+    string,
+    Action | ActionConstraint,
+    Event | EventConstraint
+  >;
+
   readonly #actions = new Map<Action['type'], Action['handler']>();
 
   readonly #events = new Map<Event['type'], EventSubscriptionMap<Event>>();
 
   /**
-   * The set of messengers we've delegated events to and their event handlers, by event type.
+   * The set of messengers we've delegated events to, by event type.
    */
   readonly #subscriptionDelegationTargets = new Map<
     Event['type'],
@@ -178,11 +188,26 @@ export class Messenger<
   /**
    * Construct a messenger.
    *
+   * If a parent messenger is given, all actions and events under this messenger's namespace will
+   * be delegated to the parent automatically.
+   *
    * @param args - Constructor arguments
    * @param args.namespace - The messenger namespace.
+   * @param args.parent - The parent messenger.
    */
-  constructor({ namespace }: { namespace: Namespace }) {
+  constructor({
+    namespace,
+    parent,
+  }: {
+    namespace: Namespace;
+    parent?: Messenger<
+      string,
+      Action | ActionConstraint,
+      Event | EventConstraint
+    >;
+  }) {
     this.#namespace = namespace;
+    this.#parent = parent;
   }
 
   /**
@@ -208,6 +233,9 @@ export class Messenger<
       );
     }
     this.#registerActionHandler(actionType, handler);
+    if (this.#parent) {
+      this.delegate({ actions: [actionType], messenger: this.#parent });
+    }
   }
 
   /**
@@ -381,6 +409,12 @@ export class Messenger<
         }:'`,
       );
     }
+    if (
+      this.#parent &&
+      !this.#subscriptionDelegationTargets.get(eventType)?.has(this.#parent)
+    ) {
+      this.delegate({ events: [eventType], messenger: this.#parent });
+    }
     this.#registerInitialEventPayload({ eventType, getPayload });
   }
 
@@ -447,6 +481,12 @@ export class Messenger<
         `Only allowed publishing events prefixed by '${this.#namespace}:'`,
       );
     }
+    if (
+      this.#parent &&
+      !this.#subscriptionDelegationTargets.get(eventType)?.has(this.#parent)
+    ) {
+      this.delegate({ events: [eventType], messenger: this.#parent });
+    }
     this.#publish(eventType, ...payload);
   }
 
@@ -710,6 +750,9 @@ export class Messenger<
     events?: readonly DelegatedEvent['type'][];
     messenger: DelegatedMessenger<DelegatedAction, DelegatedEvent>;
   }) {
+    if (messenger === this.#parent) {
+      throw new Error('Cannot revoke from parent');
+    }
     for (const actionType of actions) {
       const delegationTargets = this.#actionDelegationTargets.get(actionType);
       if (!delegationTargets || !delegationTargets.has(messenger)) {