Add messaging & messaging-internal libraries (#15711)

libs/messaging/README.md

@@ -0,0 +1,5 @@
+# messaging
+
+Owned by: platform
+
+Services for sending and recieving messages from different contexts of the same application.

libs/messaging/eslint.config.mjs

@@ -0,0 +1,3 @@
+import baseConfig from "../../eslint.config.mjs";
+
+export default [...baseConfig];

libs/messaging/jest.config.js

@@ -0,0 +1,10 @@
+module.exports = {
+  displayName: "messaging",
+  preset: "../../jest.preset.js",
+  testEnvironment: "node",
+  transform: {
+    "^.+\\.[tj]s$": ["ts-jest", { tsconfig: "<rootDir>/tsconfig.spec.json" }],
+  },
+  moduleFileExtensions: ["ts", "js", "html"],
+  coverageDirectory: "../../coverage/libs/messaging",
+};

libs/messaging/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@bitwarden/messaging",
+  "version": "0.0.1",
+  "description": "Services for sending and recieving messages from different contexts of the same application.",
+  "private": true,
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "license": "GPL-3.0",
+  "author": "platform"
+}

libs/messaging/project.json

@@ -0,0 +1,33 @@
+{
+  "name": "messaging",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/messaging/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/libs/messaging",
+        "main": "libs/messaging/src/index.ts",
+        "tsConfig": "libs/messaging/tsconfig.lib.json",
+        "assets": ["libs/messaging/*.md"]
+      }
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "outputs": ["{options.outputFile}"],
+      "options": {
+        "lintFilePatterns": ["libs/messaging/**/*.ts"]
+      }
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "options": {
+        "jestConfig": "libs/messaging/jest.config.js"
+      }
+    }
+  }
+}

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;

libs/messaging/tsconfig.eslint.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "files": [],
+  "include": ["src/**/*.ts", "src/**/*.js"],
+  "exclude": ["**/build", "**/dist"]
+}

libs/messaging/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

libs/messaging/tsconfig.lib.json

@@ -0,0 +1,16 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "declaration": true,
+    "types": ["node"]
+  },
+  "include": [
+    "src/**/*.ts",
+    "../messaging-internal/src/subject-message.sender.spec.ts",
+    "../messaging-internal/src/subject-message.sender.ts",
+    "../messaging-internal/src/helpers.spec.ts",
+    "../messaging-internal/src/helpers.ts"
+  ],
+  "exclude": ["jest.config.js", "src/**/*.spec.ts"]
+}

libs/messaging/tsconfig.spec.json

@@ -0,0 +1,17 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "module": "commonjs",
+    "moduleResolution": "node10",
+    "types": ["jest", "node"]
+  },
+  "include": [
+    "jest.config.ts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.d.ts",
+    "../messaging-internal/src/subject-message.sender.spec.ts",
+    "../messaging-internal/src/helpers.spec.ts"
+  ]
+}