Added messaging library (#331)

* Added messaging library as an example to document
* better docs and examples

---------

Co-authored-by: Shane Osbourne <[email protected]>

Author: shakyShane

package-lock.json

@@ -38,7 +38,8 @@
   },
   "type": "module",
   "workspaces": [
-    "packages/special-pages"
+    "packages/special-pages",
+    "packages/messaging"
   ],
   "dependencies": {
     "seedrandom": "^3.0.5",

package.json

@@ -0,0 +1,157 @@
+/**
+ * @module Messaging
+ * @category Libraries
+ * @description
+ *
+ * An abstraction for communications between JavaScript and host platforms.
+ *
+ * 1) First you construct your platform-specific configuration (eg: {@link WebkitMessagingConfig})
+ * 2) Then use that to get an instance of the Messaging utility which allows
+ * you to send and receive data in a unified way
+ * 3) Each platform implements {@link MessagingTransport} along with its own Configuration
+ *     - For example, to learn what configuration is required for Webkit, see: {@link WebkitMessagingConfig}
+ *     - Or, to learn about how messages are sent and received in Webkit, see {@link WebkitMessagingTransport}
+ *
+ * @example Webkit Messaging
+ *
+ * ```javascript
+ * [[include:packages/messaging/lib/examples/webkit.example.js]]```
+ *
+ * @example Windows Messaging
+ *
+ * ```javascript
+ * [[include:packages/messaging/lib/examples/windows.example.js]]```
+ */
+import { WindowsMessagingConfig, WindowsMessagingTransport, WindowsInteropMethods } from './lib/windows.js'
+import { WebkitMessagingConfig, WebkitMessagingTransport } from './lib/webkit.js'
+
+/**
+ * @implements {MessagingTransport}
+ */
+export class Messaging {
+    /**
+     * @param {WebkitMessagingConfig | WindowsMessagingConfig} config
+     */
+    constructor (config) {
+        this.transport = getTransport(config)
+    }
+
+    /**
+     * Send a 'fire-and-forget' message.
+     * @throws {MissingHandler}
+     *
+     * @example
+     *
+     * ```ts
+     * const messaging = new Messaging(config)
+     * messaging.notify("foo", {bar: "baz"})
+     * ```
+     * @param {string} name
+     * @param {Record<string, any>} [data]
+     */
+    notify (name, data = {}) {
+        this.transport.notify(name, data)
+    }
+
+    /**
+     * Send a request, and wait for a response
+     * @throws {MissingHandler}
+     *
+     * @example
+     * ```
+     * const messaging = new Messaging(config)
+     * const response = await messaging.request("foo", {bar: "baz"})
+     * ```
+     *
+     * @param {string} name
+     * @param {Record<string, any>} [data]
+     * @return {Promise<any>}
+     */
+    request (name, data = {}) {
+        return this.transport.request(name, data)
+    }
+
+    /**
+     * @param {string} name
+     * @param {(value: unknown) => void} callback
+     * @return {() => void}
+     */
+    subscribe (name, callback) {
+        return this.transport.subscribe(name, callback)
+    }
+}
+
+/**
+ * @interface
+ */
+export class MessagingTransport {
+    /**
+     * @param {string} name
+     * @param {Record<string, any>} [data]
+     * @returns {void}
+     */
+    // @ts-ignore - ignoring a no-unused ts error, this is only an interface.
+    notify (name, data = {}) {
+        throw new Error("must implement 'notify'")
+    }
+
+    /**
+     * @param {string} name
+     * @param {Record<string, any>} [data]
+     * @param {{signal?: AbortSignal}} [options]
+     * @return {Promise<any>}
+     */
+    // @ts-ignore - ignoring a no-unused ts error, this is only an interface.
+    request (name, data = {}, options = {}) {
+        throw new Error('must implement')
+    }
+
+    /**
+     * @param {string} name
+     * @param {(value: unknown) => void} callback
+     * @return {() => void}
+     */
+    // @ts-ignore - ignoring a no-unused ts error, this is only an interface.
+    subscribe (name, callback) {
+        throw new Error('must implement')
+    }
+}
+
+/**
+ * @param {WebkitMessagingConfig | WindowsMessagingConfig} config
+ * @returns {MessagingTransport}
+ */
+function getTransport (config) {
+    if (config instanceof WebkitMessagingConfig) {
+        return new WebkitMessagingTransport(config)
+    }
+    if (config instanceof WindowsMessagingConfig) {
+        return new WindowsMessagingTransport(config)
+    }
+    throw new Error('unreachable')
+}
+
+/**
+ * Thrown when a handler cannot be found
+ */
+export class MissingHandler extends Error {
+    /**
+     * @param {string} message
+     * @param {string} handlerName
+     */
+    constructor (message, handlerName) {
+        super(message)
+        this.handlerName = handlerName
+    }
+}
+
+/**
+ * Some re-exports for convenience
+ */
+export {
+    WebkitMessagingConfig,
+    WebkitMessagingTransport,
+    WindowsMessagingConfig,
+    WindowsMessagingTransport,
+    WindowsInteropMethods
+}

packages/messaging/index.js

@@ -0,0 +1,23 @@
+import { Messaging, WebkitMessagingConfig } from '../../index.js'
+
+/**
+ * Webkit messaging involves calling methods on `window.webkit.messageHandlers`.
+ *
+ * For catalina support we support encryption which is the bulk of this configuration
+ */
+const config = new WebkitMessagingConfig({
+  hasModernWebkitAPI: true,
+  secret: 'SECRET',
+  webkitMessageHandlerNames: ['helloWorld', 'sendPixel'],
+})
+
+/**
+ * Send notifications!
+ */
+const messaging = new Messaging(config)
+messaging.notify('sendPixel')
+
+/**
+ * Or request some data
+ */
+messaging.request('helloWorld', { foo: 'bar' }).then(console.log).catch(console.error)

packages/messaging/lib/examples/webkit.example.js

@@ -0,0 +1,44 @@
+import { WindowsMessagingConfig } from '../windows.js'
+import { Messaging } from '../../index.js'
+
+/**
+ * These 3 required methods that get assigned by the Native side.
+ */
+// @ts-ignore
+const windowsInteropPostMessage = window.chrome.webview.postMessage
+// @ts-ignore
+const windowsInteropAddEventListener = window.chrome.webview.addEventListener
+// @ts-ignore
+const windowsInteropRemoveEventListener = window.chrome.webview.removeEventListener
+
+/**
+ * With those methods available in the same lexical scope, we can then create
+ * our WindowsMessagingConfig
+ */
+const config = new WindowsMessagingConfig({
+  featureName: 'ExamplePage',
+  methods: {
+    postMessage: windowsInteropPostMessage,
+    addEventListener: windowsInteropAddEventListener,
+    removeEventListener: windowsInteropRemoveEventListener,
+  },
+})
+
+/**
+ * And then send notifications!
+ */
+const messaging = new Messaging(config)
+messaging.notify('helloWorld')
+
+/**
+ * Or request some data
+ */
+messaging.request('getData', { foo: 'bar' }).then(console.log).catch(console.error)
+
+/**
+ * Or subscribe for push messages
+ */
+const unsubscribe = messaging.subscribe('getData', (data) => console.log(data))
+
+// later
+unsubscribe()

packages/messaging/lib/examples/windows.example.js

@@ -0,0 +1,16 @@
+interface UnstableWebkit {
+  messageHandlers: Record<
+    string,
+    {
+      postMessage?: (...args: unknown[]) => void
+    }
+  >
+}
+
+interface Window {
+  webkit: UnstableWebkit
+}
+
+declare let windowsInteropPostMessage: any
+declare let windowsInteropAddEventListener: any
+declare let windowsInteropRemoveEventListener: any