Merge pull request #195 from podium-lib/bridge-client

feat: listen to and send messages over the Podium JSON RPC bridge if present

Author: tor0405

README.md

@@ -1,6 +1,9 @@
 # @podium/browser
 
-This is a client-side library designed to send and receive messages between different podlets in a layout.
+This is a client-side library designed to:
+
+-   send and receive messages between different podlets in a layout.
+-   send and receive messages between web and native in a webview.
 
 ## Usage
 
@@ -40,6 +43,36 @@ messageBus.subscribe('search', 'query', (event) => {
 });
 ```
 
+### Send messages between web and native
+
+To send messages between web and native the [`@podium/bridge`](https://github.com/podium-lib/bridge) must be in the document. Typically you include this once in your layout so podlets can assume it's present.
+
+The API is similar as sending messages between podlets. This way you can notify both other podlets and any native code using the same API.
+
+```js
+import { MessageBus } from '@podium/browser';
+
+const messageBus = new MessageBus();
+
+// notify of a logout
+messageBus.publish('system', 'authentication', null);
+```
+
+The `channel` and `topic` parameters are combined to form the JSON RPC 2.0 `"method"` property. In the example above the channel `system` and topic `authentication` are combined to the method `"system/authentication"`.
+
+To listen to messages coming in from native:
+
+```js
+import { MessageBus } from '@podium/browser';
+
+const messageBus = new MessageBus();
+
+// listen to the `"system/authentication"` message coming from native
+messageBus.subscribe('system', 'authentication', (event) => {
+    console.log(event.payload);
+});
+```
+
 ## API
 
 ### MessageBus

package.json

@@ -39,6 +39,7 @@
     "types": "tsc --declaration --emitDeclarationOnly"
   },
   "dependencies": {
+    "@podium/bridge": "^1.2.2",
     "eventemitter3": "4.0.7"
   },
   "devDependencies": {
@@ -57,6 +58,7 @@
     "eslint-config-prettier": "9.1.0",
     "eslint-plugin-prettier": "5.1.3",
     "globals": "15.0.0",
+    "jsdom": "24.0.0",
     "prettier": "3.2.5",
     "rollup": "4.15.0",
     "tap": "18.7.2"

src/MessageBus.js

@@ -14,17 +14,20 @@ function getGlobalThis() {
 }
 
 /**
- * @returns {{ ee: EventEmitter; sink: Sink; }}
+ * @returns {{ ee: EventEmitter; sink: Sink; bridge?: import("@podium/bridge").PodiumBridge }}
  */
 function getGlobalObjects() {
     let objs = getGlobalThis()['@podium'];
     if (!objs) {
         objs = {};
+        getGlobalThis()['@podium'] = objs;
+    }
+    if (!objs.ee) {
         objs.ee = new EventEmitter();
+    }
+    if (!objs.sink) {
         objs.sink = new Sink();
-        getGlobalThis()['@podium'] = objs;
     }
-
     return objs;
 }
 
@@ -35,9 +38,10 @@ function getGlobalObjects() {
 
 export default class MessageBus {
     constructor() {
-        const { ee, sink } = getGlobalObjects();
+        const { ee, sink, bridge } = getGlobalObjects();
         this.ee = ee;
         this.sink = sink;
+        this.bridge = bridge;
     }
 
     /**
@@ -78,9 +82,35 @@ export default class MessageBus {
         const event = new Event(channel, topic, payload);
         this.ee.emit(event.toKey(), event);
         this.sink.push(event);
+        if (this.bridge) {
+            /** @type {T | T[]} */
+            let params = payload;
+
+            if (typeof payload !== 'undefined') {
+                // JSON RPC 2.0 requires that params is either an object or an array. Wrap primitives in an an array.
+                const isPrimitive =
+                    typeof params === 'string' ||
+                    typeof params === 'boolean' ||
+                    typeof params === 'number';
+                if (isPrimitive) {
+                    params = [payload];
+                }
+            }
+
+            this.bridge.notification({
+                method: `${channel}/${topic}`,
+                params,
+            });
+        }
         return event;
     }
 
+    /**
+     * Saves a reference to the event handlers that wrap the API for @podium/bridge, so we can unsubscribe later.
+     * @type {Map<MessageHandler<any>, import('@podium/bridge').EventHandler<any>>}
+     */
+    #bridgeMap = new Map();
+
     /**
      * Subscribe to messages for a channel and topic.
      *
@@ -98,6 +128,28 @@ export default class MessageBus {
      * ```
      */
     subscribe(channel, topic, listener) {
+        if (this.bridge) {
+            // If there's a bridge, add a listener for the channel and topic there
+            // and translate incoming messages to a @podium/browser Event for the
+            // same API surface in userland.
+
+            /** @type {import('@podium/bridge').EventHandler<T>} */
+            const bridgeListener = (message) => {
+                const request =
+                    /** @type {import("@podium/bridge").RpcRequest<T>} */ (
+                    message
+                );
+
+                const event = new Event(channel, topic, request.params);
+                this.sink.push(event);
+                listener(event);
+            };
+            this.bridge.on(`${channel}/${topic}`, bridgeListener);
+
+            // Save a reference to the bridgeListener so we can unsubscribe later.
+            this.#bridgeMap.set(listener, bridgeListener);
+        }
+
         this.ee.on(toKey(channel, topic), listener);
     }
 
@@ -123,5 +175,12 @@ export default class MessageBus {
      */
     unsubscribe(channel, topic, listener) {
         this.ee.off(toKey(channel, topic), listener);
+
+        if (this.bridge) {
+            const bridgeListener = this.#bridgeMap.get(listener);
+            if (bridgeListener) {
+                this.bridge.off(`${channel}/${topic}`, bridgeListener);
+            }
+        }
     }
 }

test/Bridge.test.js

@@ -0,0 +1,102 @@
+import tap from 'tap';
+import { JSDOM } from 'jsdom';
+
+const html = /* html */ `<!doctype html>
+<html>
+    <head>
+        <meta charset="utf-8">
+    </head>
+    <body></body>
+</html>`;
+const dom = new JSDOM(html);
+globalThis.window = dom.window;
+
+const { PodiumBridge } = await import('@podium/bridge');
+const { default: MessageBus } = await import('../src/MessageBus.js');
+
+/** @type {import('../src/MessageBus.js').default} */
+let bus;
+
+tap.beforeEach(() => {
+    // Unregister listeners and clear the global between tests for a clean slate
+    if (globalThis.window['@podium']?.bridge) {
+        /** @type {import('@podium/bridge').PodiumBridge} */
+        const bridge = globalThis.window['@podium'].bridge;
+        bridge.destroy();
+    }
+
+    globalThis.window['@podium'] = {};
+    globalThis.window['@podium'].bridge = new PodiumBridge();
+    bus = new MessageBus();
+});
+
+tap.test('bridge.on() - should invoke subscribed messagebus listener', (t) => {
+    t.ok(
+        globalThis.window['@podium'].bridge,
+        'Expected the Podium bridge to be globally available',
+    );
+
+    const payload = { a: 'b' };
+    bus.subscribe('foo', 'bar', (event) => {
+        t.equal(event.payload, payload);
+        t.end();
+    });
+
+    const rpcRequest = {
+        method: 'foo/bar',
+        params: payload,
+        jsonrpc: '2.0',
+    };
+
+    globalThis.window.dispatchEvent(
+        new globalThis.window.CustomEvent('rpcbridge', {
+            detail: rpcRequest,
+        }),
+    );
+});
+
+tap.test('unsubscribe() - should remove subscribed listener', (t) => {
+    t.ok(
+        globalThis.window['@podium'].bridge,
+        'Expected the Podium bridge to be globally available',
+    );
+
+    const payload = { a: 'b' };
+    let count = 0;
+    const listener = (event) => {
+        t.equal(event.payload, payload);
+        count += 1;
+    };
+
+    bus.subscribe('foo', 'bar', listener);
+
+    const rpcRequest = {
+        method: 'foo/bar',
+        params: payload,
+        jsonrpc: '2.0',
+    };
+
+    globalThis.window.dispatchEvent(
+        new globalThis.window.CustomEvent('rpcbridge', {
+            detail: rpcRequest,
+        }),
+    );
+    globalThis.window.dispatchEvent(
+        new globalThis.window.CustomEvent('rpcbridge', {
+            detail: rpcRequest,
+        }),
+    );
+
+    t.equal(count, 2);
+
+    bus.unsubscribe('foo', 'bar', listener);
+
+    globalThis.window.dispatchEvent(
+        new globalThis.window.CustomEvent('rpcbridge', {
+            detail: rpcRequest,
+        }),
+    );
+
+    t.equal(count, 2);
+    t.end();
+});