Added messaging library as an example to document

Author: Shane Osbourne

package.json

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

packages/messaging/index.js

@@ -0,0 +1,179 @@
+/**
+ * @module Messaging
+ *
+ * @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 "Webkit Messaging".WebkitMessagingConfig}
+ *     - Or, to learn about how messages are sent and received in Webkit, see {@link "Webkit Messaging".WebkitMessagingTransport}
+ *
+ * @example Webkit Messaging
+ *
+ * ```js
+ * import { Messaging, WebkitMessagingConfig } from "@duckduckgo/content-scope-scripts/lib/messaging.js"
+ *
+ * // This config would be injected into the UserScript
+ * const injectedConfig = {
+ *   hasModernWebkitAPI: true,
+ *   webkitMessageHandlerNames: ["foo", "bar", "baz"],
+ *   secret: "dax",
+ * };
+ *
+ * // Then use that config to construct platform-specific configuration
+ * const config = new WebkitMessagingConfig(injectedConfig);
+ *
+ * // finally, get an instance of Messaging and start sending messages in a unified way 🚀
+ * const messaging = new Messaging(config);
+ * messaging.notify("hello world!", {foo: "bar"})
+ *
+ * ```
+ *
+ * @example Windows Messaging
+ *
+ * ```js
+ * import { Messaging, WindowsMessagingConfig } from "@duckduckgo/content-scope-scripts/lib/messaging.js"
+ *
+ * // Messaging on Windows is namespaced, so you can create multiple messaging instances
+ * const autofillConfig  = new WindowsMessagingConfig({ featureName: "Autofill" });
+ * const debugConfig     = new WindowsMessagingConfig({ featureName: "Debugging" });
+ *
+ * const autofillMessaging = new Messaging(autofillConfig);
+ * const debugMessaging    = new Messaging(debugConfig);
+ *
+ * // Now send messages to both features as needed 🚀
+ * autofillMessaging.notify("storeFormData", { "username": "dax" })
+ * debugMessaging.notify("pageLoad", { time: window.performance.now() })
+ * ```
+ */
+import { WindowsMessagingConfig, WindowsMessagingTransport } 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, WindowsMessagingConfig }

packages/messaging/lib/examples/windows.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/messaging.types.d.ts

@@ -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