Add messaging & messaging-internal libraries (#15711)

libs/messaging/src/index.ts

@@ -0,0 +1,4 @@
+export { MessageListener } from "./message.listener";
+export { MessageSender } from "./message.sender";
+export { Message, CommandDefinition } from "./types";
+export { isExternalMessage, EXTERNAL_SOURCE_TAG } from "./is-external-message";

libs/messaging/src/is-external-message.ts

@@ -0,0 +1,5 @@
+export const EXTERNAL_SOURCE_TAG = Symbol("externalSource");
+
+export const isExternalMessage = (message: Record<PropertyKey, unknown>) => {
+  return message?.[EXTERNAL_SOURCE_TAG] === true;
+};

libs/messaging/src/message.listener.spec.ts

@@ -0,0 +1,43 @@
+import { bufferCount, firstValueFrom, Subject } from "rxjs";
+
+import { MessageListener } from "./message.listener";
+import { Message, CommandDefinition } from "./types";
+
+describe("MessageListener", () => {
+  const subject = new Subject<Message<{ test: number }>>();
+  const sut = new MessageListener(subject.asObservable());
+
+  const testCommandDefinition = new CommandDefinition<{ test: number }>("myCommand");
+
+  describe("allMessages$", () => {
+    it("runs on all nexts", async () => {
+      const emissionsPromise = firstValueFrom(sut.allMessages$.pipe(bufferCount(2)));
+
+      subject.next({ command: "command1", test: 1 });
+      subject.next({ command: "command2", test: 2 });
+
+      const emissions = await emissionsPromise;
+
+      expect(emissions[0]).toEqual({ command: "command1", test: 1 });
+      expect(emissions[1]).toEqual({ command: "command2", test: 2 });
+    });
+  });
+
+  describe("messages$", () => {
+    it("runs on only my commands", async () => {
+      const emissionsPromise = firstValueFrom(
+        sut.messages$(testCommandDefinition).pipe(bufferCount(2)),
+      );
+
+      subject.next({ command: "notMyCommand", test: 1 });
+      subject.next({ command: "myCommand", test: 2 });
+      subject.next({ command: "myCommand", test: 3 });
+      subject.next({ command: "notMyCommand", test: 4 });
+
+      const emissions = await emissionsPromise;
+
+      expect(emissions[0]).toEqual({ command: "myCommand", test: 2 });
+      expect(emissions[1]).toEqual({ command: "myCommand", test: 3 });
+    });
+  });
+});

libs/messaging/src/message.listener.ts

@@ -0,0 +1,43 @@
+import { EMPTY, Observable, filter } from "rxjs";
+
+import { Message, CommandDefinition } from "./types";
+
+/**
+ * A class that allows for listening to messages coming through the application,
+ * allows for listening of all messages or just the messages you care about.
+ *
+ * @note Consider NOT using messaging at all if you can. State Providers offer an observable stream of
+ * data that is persisted. This can serve messages that might have been used to notify of settings changes
+ * or vault data changes and those observables should be preferred over messaging.
+ */
+export class MessageListener {
+  constructor(private readonly messageStream: Observable<Message<Record<string, unknown>>>) {}
+
+  /**
+   * A stream of all messages sent through the application. It does not contain type information for the
+   * other properties on the messages. You are encouraged to instead subscribe to an individual message
+   * through {@link messages$}.
+   */
+  allMessages$ = this.messageStream;
+
+  /**
+   * Creates an observable stream filtered to just the command given via the {@link CommandDefinition} and typed
+   * to the generic contained in the CommandDefinition. Be careful using this method unless all your messages are being
+   * sent through `MessageSender.send`, if that isn't the case you should have lower confidence in the message
+   * payload being the expected type.
+   *
+   * @param commandDefinition The CommandDefinition containing the information about the message type you care about.
+   */
+  messages$<T extends Record<string, unknown>>(
+    commandDefinition: CommandDefinition<T>,
+  ): Observable<T> {
+    return this.allMessages$.pipe(
+      filter((msg) => msg?.command === commandDefinition.command),
+    ) as Observable<T>;
+  }
+
+  /**
+   * A helper property for returning a MessageListener that will never emit any messages and will immediately complete.
+   */
+  static readonly EMPTY = new MessageListener(EMPTY);
+}

libs/messaging/src/message.sender.ts

@@ -0,0 +1,65 @@
+import { CommandDefinition } from "./types";
+
+class MultiMessageSender implements MessageSender {
+  constructor(private readonly innerMessageSenders: MessageSender[]) {}
+
+  send<T extends Record<string, unknown>>(
+    commandDefinition: string | CommandDefinition<T>,
+    payload: Record<string, unknown> | T = {},
+  ): void {
+    for (const messageSender of this.innerMessageSenders) {
+      messageSender.send(commandDefinition, payload);
+    }
+  }
+}
+
+export abstract class MessageSender {
+  /**
+   * A method for sending messages in a type safe manner. The passed in command definition
+   * will require you to provide a compatible type in the payload parameter.
+   *
+   * @example
+   * const MY_COMMAND = new CommandDefinition<{ test: number }>("myCommand");
+   *
+   * this.messageSender.send(MY_COMMAND, { test: 14 });
+   *
+   * @param commandDefinition
+   * @param payload
+   */
+  abstract send<T extends Record<string, unknown>>(
+    commandDefinition: CommandDefinition<T>,
+    payload: T,
+  ): void;
+
+  /**
+   * A legacy method for sending messages in a non-type safe way.
+   *
+   * @remarks Consider defining a {@link CommandDefinition} and passing that in for the first parameter to
+   * get compilation errors when defining an incompatible payload.
+   *
+   * @param command The string based command of your message.
+   * @param payload Extra contextual information regarding the message. Be aware that this payload may
+   *   be serialized and lose all prototype information.
+   */
+  abstract send(command: string, payload?: Record<string, unknown>): void;
+
+  /** Implementation of the other two overloads, read their docs instead. */
+  abstract send<T extends Record<string, unknown>>(
+    commandDefinition: CommandDefinition<T> | string,
+    payload: T | Record<string, unknown>,
+  ): void;
+
+  /**
+   * A helper method for combine multiple {@link MessageSender}'s.
+   * @param messageSenders The message senders that should be combined.
+   * @returns A message sender that will relay all messages to the given message senders.
+   */
+  static combine(...messageSenders: MessageSender[]) {
+    return new MultiMessageSender(messageSenders);
+  }
+
+  /**
+   * A helper property for creating a {@link MessageSender} that sends to nowhere.
+   */
+  static readonly EMPTY: MessageSender = new MultiMessageSender([]);
+}

libs/messaging/src/messaging.spec.ts

@@ -0,0 +1,8 @@
+import * as lib from "./index";
+
+describe("messaging", () => {
+  // This test will fail until something is exported from index.ts
+  it("should work", () => {
+    expect(lib).toBeDefined();
+  });
+});

libs/messaging/src/types.ts

@@ -0,0 +1,15 @@
+// FIXME: Update this file to be type safe and remove this and next line
+// @ts-strict-ignore
+declare const tag: unique symbol;
+
+/**
+ * A class for defining information about a message, this is helpful
+ * alonside `MessageSender` and `MessageListener` for providing a type
+ * safe(-ish) way of sending and receiving messages.
+ */
+export class CommandDefinition<T extends Record<string, unknown>> {
+  [tag]: T;
+  constructor(readonly command: string) {}
+}
+
+export type Message<T extends Record<string, unknown>> = { command: string } & T;