feat: Allow disabling namespace checks

Messenger namespace checks can now be disabled by using the
`DISABLE_NAMESPACE` namespace constructor parameter, and setting the
`Namespace` type parameter to `string`. This makes it much easier to
mock messengers in unit tests.

Author: Gudahtt

packages/messenger/src/Messenger.test.ts

@@ -1,7 +1,7 @@
 import type { Patch } from 'immer';
 import sinon from 'sinon';
 
-import { Messenger } from './Messenger';
+import { Messenger, DISABLE_NAMESPACE } from './Messenger';
 
 describe('Messenger', () => {
   afterEach(() => {
@@ -27,6 +27,24 @@ describe('Messenger', () => {
       expect(count).toBe(1);
     });
 
+    it('allows registering and calling an action handler for a different namespace using DISABLE_NAMESPACE', () => {
+      type CountAction = {
+        type: 'Fixture:count';
+        handler: (increment: number) => void;
+      };
+      const messenger = new Messenger<string, CountAction, never>({
+        namespace: DISABLE_NAMESPACE,
+      });
+
+      let count = 0;
+      messenger.registerActionHandler('Fixture:count', (increment: number) => {
+        count += increment;
+      });
+      messenger.call('Fixture:count', 1);
+
+      expect(count).toBe(1);
+    });
+
     it('automatically delegates actions to parent upon registration', () => {
       type CountAction = {
         type: 'Fixture:count';
@@ -168,6 +186,67 @@ describe('Messenger', () => {
       }).toThrow('A handler for Fixture:ping has not been registered');
     });
 
+    it('throws when registering an action handler for a different namespace', () => {
+      type CountAction = {
+        type: 'Fixture:count';
+        handler: (increment: number) => void;
+      };
+      const messenger = new Messenger<'Different', CountAction, never>({
+        namespace: 'Different',
+      });
+
+      expect(() =>
+        // @ts-expect-error Intentionally invalid parameter
+        messenger.registerActionHandler('Fixture:count', jest.fn()),
+      ).toThrow(
+        `Only allowed registering action handlers prefixed by 'Different:'`,
+      );
+    });
+
+    it('throws when unregistering an action handler for a different namespace', () => {
+      type CountAction = {
+        type: 'Source:count';
+        handler: (increment: number) => void;
+      };
+      const sourceMessenger = new Messenger<'Source', CountAction, never>({
+        namespace: 'Source',
+      });
+      const messenger = new Messenger<'Destination', CountAction, never>({
+        namespace: 'Destination',
+      });
+      sourceMessenger.delegate({ actions: ['Source:count'], messenger });
+
+      expect(() =>
+        // @ts-expect-error Intentionally invalid parameter
+        messenger.unregisterActionHandler('Source:count'),
+      ).toThrow(
+        `Only allowed unregistering action handlers prefixed by 'Destination:'`,
+      );
+    });
+
+    it('throws when calling an action from a different namespace that has been unregistered using DISABLE_NAMESPACE', () => {
+      type PingAction = { type: 'Fixture:ping'; handler: () => void };
+      const messenger = new Messenger<string, PingAction, never>({
+        namespace: DISABLE_NAMESPACE,
+      });
+
+      expect(() => {
+        messenger.call('Fixture:ping');
+      }).toThrow('A handler for Fixture:ping has not been registered');
+
+      let pingCount = 0;
+      messenger.registerActionHandler('Fixture:ping', () => {
+        pingCount += 1;
+      });
+
+      messenger.unregisterActionHandler('Fixture:ping');
+
+      expect(() => {
+        messenger.call('Fixture:ping');
+      }).toThrow('A handler for Fixture:ping has not been registered');
+      expect(pingCount).toBe(0);
+    });
+
     it('throws when calling an action that has been unregistered', () => {
       type PingAction = { type: 'Fixture:ping'; handler: () => void };
       const messenger = new Messenger<'Fixture', PingAction, never>({
@@ -259,6 +338,20 @@ describe('Messenger', () => {
       expect(handler.callCount).toBe(1);
     });
 
+    it('publishes event from different namespace using DISABLE_NAMESPACE', () => {
+      type MessageEvent = { type: 'Fixture:message'; payload: [string] };
+      const messenger = new Messenger<string, never, MessageEvent>({
+        namespace: DISABLE_NAMESPACE,
+      });
+
+      const handler = sinon.stub();
+      messenger.subscribe('Fixture:message', handler);
+      messenger.publish('Fixture:message', 'hello');
+
+      expect(handler.calledWithExactly('hello')).toBe(true);
+      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>({
@@ -428,6 +521,66 @@ describe('Messenger', () => {
       });
     });
 
+    describe('on first state change with an initial payload function from another namespace registered (using DISABLE_NAMESPACE)', () => {
+      it('publishes event if selected payload differs', () => {
+        const state = {
+          propA: 1,
+          propB: 1,
+        };
+        type MessageEvent = {
+          type: 'Fixture:complexMessage';
+          payload: [typeof state];
+        };
+        const messenger = new Messenger<string, never, MessageEvent>({
+          namespace: DISABLE_NAMESPACE,
+        });
+        messenger.registerInitialEventPayload({
+          eventType: 'Fixture:complexMessage',
+          getPayload: () => [state],
+        });
+        const handler = sinon.stub();
+        messenger.subscribe(
+          'Fixture:complexMessage',
+          handler,
+          (obj) => obj.propA,
+        );
+
+        state.propA += 1;
+        messenger.publish('Fixture:complexMessage', state);
+
+        expect(handler.getCall(0)?.args).toStrictEqual([2, 1]);
+        expect(handler.callCount).toBe(1);
+      });
+
+      it('does not publish event if selected payload is the same', () => {
+        const state = {
+          propA: 1,
+          propB: 1,
+        };
+        type MessageEvent = {
+          type: 'Fixture:complexMessage';
+          payload: [typeof state];
+        };
+        const messenger = new Messenger<string, never, MessageEvent>({
+          namespace: DISABLE_NAMESPACE,
+        });
+        messenger.registerInitialEventPayload({
+          eventType: 'Fixture:complexMessage',
+          getPayload: () => [state],
+        });
+        const handler = sinon.stub();
+        messenger.subscribe(
+          'Fixture:complexMessage',
+          handler,
+          (obj) => obj.propA,
+        );
+
+        messenger.publish('Fixture:complexMessage', state);
+
+        expect(handler.callCount).toBe(0);
+      });
+    });
+
     describe('on first state change without an initial payload function registered', () => {
       it('publishes event if selected payload differs', () => {
         const state = {
@@ -727,6 +880,42 @@ describe('Messenger', () => {
       expect(stub.callCount).toBe(0);
     });
 
+    it('throws when publishing an event from another namespace', () => {
+      type MessageEvent = { type: 'Fixture:message'; payload: [string] };
+      const messenger = new Messenger<'Other', never, MessageEvent>({
+        namespace: 'Other',
+      });
+      const handler = jest.fn();
+      messenger.subscribe('Fixture:message', handler);
+
+      // @ts-expect-error Intentionally invalid parameter
+      expect(() => messenger.publish('Fixture:message', 'hello')).toThrow(
+        `Only allowed publishing events prefixed by 'Other:'`,
+      );
+      expect(handler).not.toHaveBeenCalled();
+    });
+
+    it('throws when registering an initial event payload from another namespace', () => {
+      type MessageEvent = {
+        type: 'Fixture:complexMessage';
+        payload: [null];
+      };
+      const messenger = new Messenger<'Other', never, MessageEvent>({
+        namespace: 'Other',
+      });
+
+      expect(() =>
+        messenger.registerInitialEventPayload({
+          // @ts-expect-error Intentionally invalid parameter
+          eventType: 'Fixture:complexMessage',
+          // @ts-expect-error Intentionally invalid parameter
+          getPayload: () => [null],
+        }),
+      ).toThrow(
+        `Only allowed registering initial payloads for events prefixed by 'Other:'`,
+      );
+    });
+
     it('throws when unsubscribing when there are no subscriptions', () => {
       type MessageEvent = { type: 'Fixture:message'; payload: [string] };
       const messenger = new Messenger<'Fixture', never, MessageEvent>({

packages/messenger/src/Messenger.ts

@@ -94,6 +94,15 @@ export type MessengerEvents<
     ? Event
     : never;
 
+/**
+ * Messenger namespace checks can be disabled by using this as the `namespace` constructor
+ * parameter, and using `string` as the Namespace type parameter.
+ *
+ * This is useful for mocking a variety of different actions/events in unit tests. Please do not
+ * use this in production code.
+ */
+export const DISABLE_NAMESPACE = 'DISABLE_NAMESPACE';
+
 /**
  * Metadata for a single event subscription.
  *
@@ -278,7 +287,6 @@ export class Messenger<
   registerActionHandler<
     ActionType extends Action['type'] & NamespacedName<Namespace>,
   >(actionType: ActionType, handler: ActionHandler<Action, ActionType>) {
-    /* istanbul ignore if */ // Branch unreachable with valid types
     if (!this.#isInCurrentNamespace(actionType)) {
       throw new Error(
         `Only allowed registering action handlers prefixed by '${
@@ -341,7 +349,6 @@ export class Messenger<
   unregisterActionHandler<
     ActionType extends Action['type'] & NamespacedName<Namespace>,
   >(actionType: ActionType) {
-    /* istanbul ignore if */ // Branch unreachable with valid types
     if (!this.#isInCurrentNamespace(actionType)) {
       throw new Error(
         `Only allowed unregistering action handlers prefixed by '${
@@ -419,7 +426,6 @@ export class Messenger<
     eventType: EventType;
     getPayload: () => ExtractEventPayload<Event, EventType>;
   }) {
-    /* istanbul ignore if */ // Branch unreachable with valid types
     if (!this.#isInCurrentNamespace(eventType)) {
       throw new Error(
         `Only allowed registering initial payloads for events prefixed by '${
@@ -478,7 +484,6 @@ export class Messenger<
     eventType: EventType & NamespacedName<Namespace>,
     ...payload: ExtractEventPayload<Event, EventType>
   ) {
-    /* istanbul ignore if */ // Branch unreachable with valid types
     if (!this.#isInCurrentNamespace(eventType)) {
       throw new Error(
         `Only allowed publishing events prefixed by '${this.#namespace}:'`,
@@ -985,10 +990,15 @@ export class Messenger<
   /**
    * Determine whether the given name is within the current namespace.
    *
+   * If the current namespace is DISABLE_NAMESPACE, this check always returns true.
+   *
    * @param name - The name to check
    * @returns Whether the name is within the current namespace
    */
   #isInCurrentNamespace(name: string): name is NamespacedName<Namespace> {
-    return name.startsWith(`${this.#namespace}:`);
+    return (
+      this.#namespace === DISABLE_NAMESPACE ||
+      name.startsWith(`${this.#namespace}:`)
+    );
   }
 }

packages/messenger/src/index.test.ts

@@ -4,6 +4,7 @@ describe('@metamask/messenger', () => {
   it('has expected JavaScript exports', () => {
     expect(Object.keys(allExports)).toMatchInlineSnapshot(`
       Array [
+        "DISABLE_NAMESPACE",
         "Messenger",
       ]
     `);

packages/messenger/src/index.ts

@@ -14,4 +14,4 @@ export type {
   NotNamespacedBy,
   NamespacedName,
 } from './Messenger';
-export { Messenger } from './Messenger';
+export { DISABLE_NAMESPACE, Messenger } from './Messenger';