WIP

Author: Gudahtt

packages/base-controller/src/Messenger.ts

@@ -89,7 +89,7 @@ export type NamespacedName<Namespace extends string = string> =
 type DelegatedMessenger<
   Action extends ActionConstraint,
   Event extends EventConstraint,
-  Namespace extends string,
+  Namespace extends string = string,
 > = Pick<
   Messenger<Action, Event, Namespace>,
   | 'publishDelegated'
@@ -121,15 +121,21 @@ export class Messenger<
 
   readonly #events = new Map<Event['type'], EventSubscriptionMap<Event>>();
 
-  readonly #delegatedEventSubscriptions = new Map<
+  /**
+   * The set of messengers we've delegated events to, by event type.
+   */
+  readonly #subscriptionDelegationTargets = new Map<
     Event['type'],
     Map<
       DelegatedMessenger<Action, Event>,
       ExtractEventHandler<Event, Event['type']>
     >
   >();
 
-  readonly #delegatedActionHandlers = new Map<
+  /**
+   * The set of messengers we've delegated actions to, by action type.
+   */
+  readonly #actionDelegationTargets = new Map<
     Action['type'],
     Set<DelegatedMessenger<Action, Event>>
   >();
@@ -172,7 +178,6 @@ export class Messenger<
    * @throws Will throw when a handler has been registered for this action type already.
    * @template ActionType - A type union of Action type strings.
    */
-
   registerActionHandler<
     ActionType extends Action['type'] & NamespacedName<Namespace>,
   >(actionType: ActionType, handler: ActionHandler<Action, ActionType>) {
@@ -260,14 +265,14 @@ export class Messenger<
     actionType: ActionType,
   ) {
     this.#actions.delete(actionType);
-    const delegatedMessengers = this.#delegatedActionHandlers.get(actionType);
-    if (!delegatedMessengers) {
+    const delegationTargets = this.#actionDelegationTargets.get(actionType);
+    if (!delegationTargets) {
       return;
     }
-    for (const messenger of delegatedMessengers) {
+    for (const messenger of delegationTargets) {
       messenger.unregisterDelegatedActionHandler(actionType);
     }
-    this.#delegatedActionHandlers.delete(actionType);
+    this.#actionDelegationTargets.delete(actionType);
   }
 
   /**
@@ -317,7 +322,49 @@ export class Messenger<
    * @param args.eventType - The event type to register a payload for.
    * @param args.getPayload - A function for retrieving the event payload.
    */
-  registerInitialEventPayload<EventType extends Event['type']>({
+  registerInitialEventPayload<
+    EventType extends Event['type'] & NamespacedName<Namespace>,
+  >({
+    eventType,
+    getPayload,
+  }: {
+    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 '${
+          this.#namespace
+        }:'`,
+      );
+    }
+    this.#registerInitialEventPayload({ eventType, getPayload });
+  }
+
+  /**
+   * Register a function for getting the initial payload for a delegated event.
+   *
+   * This is used for events that represent a state change, where the payload is the state.
+   * Registering a function for getting the payload allows event selectors to have a point of
+   * comparison the first time state changes.
+   *
+   * @deprecated Do not call this directly, instead use the `delegate` method.
+   * @param args - The arguments to this function
+   * @param args.eventType - The event type to register a payload for.
+   * @param args.getPayload - A function for retrieving the event payload.
+   */
+  registerDelegatedInitialEventPayload<EventType extends Event['type']>({
+    eventType,
+    getPayload,
+  }: {
+    eventType: EventType;
+    getPayload: () => ExtractEventPayload<Event, EventType>;
+  }) {
+    this.#registerInitialEventPayload({ eventType, getPayload });
+  }
+
+  #registerInitialEventPayload<EventType extends Event['type']>({
     eventType,
     getPayload,
   }: {
@@ -341,6 +388,40 @@ export class Messenger<
    * @template EventType - A type union of Event type strings.
    */
   publish<EventType extends Event['type']>(
+    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}:'`,
+      );
+    }
+    this.#publish(eventType, ...payload);
+  }
+
+  /**
+   * Publish a delegated event.
+   *
+   * Publishes the given payload to all subscribers of the given event type.
+   *
+   * Note that this method should never throw directly. Any errors from
+   * subscribers are captured and re-thrown in a timeout handler.
+   *
+   * @deprecated Do not call this directly, instead use the `delegate` method.
+   * @param eventType - The event type. This is a unique identifier for this event.
+   * @param payload - The event payload. The type of the parameters for each event handler must
+   * match the type of this payload.
+   * @template EventType - A type union of Event type strings.
+   */
+  publishDelegated<EventType extends Event['type']>(
+    eventType: EventType,
+    ...payload: ExtractEventPayload<Event, EventType>
+  ) {
+    this.#publish(eventType, ...payload);
+  }
+
+  #publish<EventType extends Event['type']>(
     eventType: EventType,
     ...payload: ExtractEventPayload<Event, EventType>
   ) {
@@ -483,63 +564,79 @@ export class Messenger<
   }
 
   /**
-   * Get a restricted messenger
-   *
-   * Returns a wrapper around the messenger instance that restricts access to actions and events.
-   * The provided allowlists grant the ability to call the listed actions and subscribe to the
-   * listed events. The "name" provided grants ownership of any actions and events under that
-   * namespace. Ownership allows registering actions and publishing events, as well as
-   * unregistering actions and clearing event subscriptions.
-   *
-   * @param options - Messenger options.
-   * @param options.name - The name of the thing this messenger will be handed to (e.g. the
-   * controller name). This grants "ownership" of actions and events under this namespace to the
-   * restricted messenger returned.
-   * @param options.allowedActions - The list of actions that this restricted messenger should be
-   * allowed to call.
-   * @param options.allowedEvents - The list of events that this restricted messenger should be
-   * allowed to subscribe to.
-   * @template Namespace - The namespace for this messenger. Typically this is the name of the
-   * module that this messenger has been created for. The authority to publish events and register
-   * actions under this namespace is granted to this restricted messenger instance.
-   * @template AllowedAction - A type union of the 'type' string for any allowed actions.
-   * This must not include internal actions that are in the messenger's namespace.
-   * @template AllowedEvent - A type union of the 'type' string for any allowed events.
-   * This must not include internal events that are in the messenger's namespace.
-   * @returns The restricted messenger.
+   * Delegate actions and/or events to another messenger.
+   *
+   * @param args - Arguments.
+   * @param args.actions - The action types to delegate.
+   * @param args.events - The event types to delegate.
+   * @param args.messenger - The messenger to delegate to.
    */
-  getRestricted<
-    Namespace extends string,
-    AllowedAction extends NotNamespacedBy<Namespace, Action['type']> = never,
-    AllowedEvent extends NotNamespacedBy<Namespace, Event['type']> = never,
-  >({
-    name,
-    allowedActions,
-    allowedEvents,
+  delegate<DelegatedAction extends Action, DelegatedEvent extends Event>({
+    actions = [],
+    events = [],
+    messenger,
   }: {
-    name: Namespace;
-    allowedActions: NotNamespacedBy<
-      Namespace,
-      Extract<Action['type'], AllowedAction>
-    >[];
-    allowedEvents: NotNamespacedBy<
-      Namespace,
-      Extract<Event['type'], AllowedEvent>
-    >[];
-  }): RestrictedMessenger<
-    Namespace,
-    | NarrowToNamespace<Action, Namespace>
-    | NarrowToAllowed<Action, AllowedAction>,
-    NarrowToNamespace<Event, Namespace> | NarrowToAllowed<Event, AllowedEvent>,
-    AllowedAction,
-    AllowedEvent
-  > {
-    return new RestrictedMessenger({
-      messenger: this,
-      name,
-      allowedActions,
-      allowedEvents,
-    });
+    actions?: DelegatedAction['type'][];
+    events?: DelegatedEvent['type'][];
+    messenger: DelegatedMessenger<DelegatedAction, DelegatedEvent>;
+  }) {
+    for (const actionType of actions) {
+      const delegatedActionHandler = (
+        ...args: ExtractActionParameters<DelegatedAction, typeof actionType>
+      ) => {
+        // TODO: Explain cast
+        const actionHandler = this.#actions.get(actionType) as
+          | ActionHandler<DelegatedAction, typeof actionType>
+          | undefined;
+        if (!actionHandler) {
+          throw new Error(
+            `Cannot call '${actionType}', action not registered.`,
+          );
+        }
+        return actionHandler(...args);
+      };
+      let delegationTargets = this.#actionDelegationTargets.get(actionType);
+      if (!delegationTargets) {
+        delegationTargets = new Set<DelegatedMessenger<Action, Event>>();
+        this.#actionDelegationTargets.set(actionType, delegationTargets);
+      }
+      delegationTargets.add(messenger);
+
+      messenger.registerDelegatedActionHandler(
+        actionType,
+        delegatedActionHandler,
+      );
+    }
+    for (const eventType of events) {
+      const untypedSubscriber = (
+        ...payload: ExtractEventPayload<DelegatedEvent, typeof eventType>
+      ) => {
+        messenger.publishDelegated(eventType, ...payload);
+      };
+      // TODO: Explain cast
+      const subscriber = untypedSubscriber as ExtractEventHandler<
+        DelegatedEvent,
+        typeof eventType
+      >;
+      let delegatedEventSubscriptions =
+        this.#delegatedEventSubscriptions.get(eventType);
+      if (!delegatedEventSubscriptions) {
+        delegatedEventSubscriptions = new Map();
+        this.#delegatedEventSubscriptions.set(
+          eventType,
+          delegatedEventSubscriptions,
+        );
+      }
+      delegatedEventSubscriptions.set(messenger, subscriber);
+      const getPayload = this.#initialEventPayloadGetters.get(eventType);
+      if (getPayload) {
+        messenger.registerDelegatedInitialEventPayload({
+          eventType,
+          getPayload,
+        });
+      }
+      this.subscribe(eventType, subscriber);
+    }
   }
 
   /**