promise-worker-bi 4.0.3 → 4.1.0

package/README.md

@@ -16,22 +16,20 @@ Inside your main bundle:
 // main.js
 import { PWBHost } from "promise-worker-bi";
 
-var worker = new Worker("worker.js");
-var promiseWorker = new PWBHost(worker);
+const worker = new Worker("worker.js");
+const promiseWorker = new PWBHost(worker);
 
 // Only needed if you send messages from the worker to the host
-promiseWorker.register(function(message) {
+promiseWorker.register((message) => {
   return "pong2";
 });
 
-promiseWorker
-  .postMessage("ping")
-  .then(function(response) {
-    // handle response 'pong'
-  })
-  .catch(function(error) {
-    // handle error
-  });
+try {
+  const response = await promiseWorker.postMessage("ping");
+  // handle response 'pong'
+} catch (error) {
+  // handle error
+}
 ```
 
 Inside your `worker.js` bundle:
@@ -40,48 +38,37 @@ Inside your `worker.js` bundle:
 // worker.js
 import { PWBWorker } from "promise-worker-bi";
 
-var promiseWorker = new PWBWorker();
+const promiseWorker = new PWBWorker();
 
 // Only needed if you send messages from the host to the worker
-promiseWorker.register(function(message) {
+promiseWorker.register((message) => {
   return "pong";
 });
 
-promiseWorker
-  .postMessage("ping2")
-  .then(function(response) {
-    // handle response 'pong2'
-  })
-  .catch(function(error) {
-    // handle error
-  });
+try {
+  const response = await promiseWorker.postMessage("ping2");
+  // handle response 'pong2'
+} catch (error) {
+  // handle error
+}
 ```
 
 **Notice that except for initialization of the `promiseWorker` object, the API is identical in the browser and in the worker. Either one can initiate a message.** In all of the subsequent examples, `promiseWorker` initialization is omitted, so you can put the two blocks of code respectively in the worker and browser, or in the browser and worker.
 
-And it's even better with async/await:
-
-```js
-const response = await promiseWorker.postMessage("ping2");
-// response contains 'pong2'
-```
-
 ### Message format
 
-The message you send can be any object, array, string, number, etc. - anything that is serializable by the structured clone algorithm:
+The message you send can be any object, array, string, number, etc. - anything that is serializable by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm):
 
 ```js
-promiseWorker
-  .postMessage({
-    hello: "world",
-    answer: 42,
-    "this is fun": true
-  })
-  .then(/* ... */);
+await promiseWorker.postMessage({
+  hello: "world",
+  answer: 42,
+  "this is fun": true,
+});
 ```
 
 ```js
-promiseWorker.register(function(message) {
+promiseWorker.register((message) => {
   console.log(message); // { hello: 'world', answer: 42, 'this is fun': true }
 });
 ```
@@ -91,17 +78,14 @@ promiseWorker.register(function(message) {
 The registered handler can return either a Promise or a normal value:
 
 ```js
-promiseWorker.register(function() {
-  return Promise.resolve().then(function() {
-    return "much async, very promise";
-  });
+promiseWorker.register(async () => {
+  "much async, very promise";
 });
 ```
 
 ```js
-promiseWorker.postMessage(null).then(function (message) {
-  console.log(message): // 'much async, very promise'
-});
+const message = await promiseWorker.postMessage(null);
+console.log(message): // 'much async, very promise'
 ```
 
 ### Error handling
@@ -109,23 +93,27 @@ promiseWorker.postMessage(null).then(function (message) {
 Any thrown errors or asynchronous rejections during a response will be propagated as a rejected promise. For instance:
 
 ```js
-promiseWorker.register(function(message) {
+promiseWorker.register((message) => {
   throw new Error("naughty!");
 });
 ```
 
 ```js
-promiseWorker.postMessage("whoops").catch(function(err) {
-  console.log(err.message); // 'naughty!'
-});
+try {
+  await promiseWorker.postMessage("whoops");
+} catch (error) {
+  console.log(error.message); // 'naughty!'
+}
 ```
 
 But what about errors in the worker that are _not_ during a response? (Errors in the host, you can handle as you would normally do.)
 
-For a Web Worker, we could just use [the normal `error` event](https://developer.mozilla.org/en-US/docs/Web/API/AbstractWorker/onerror) and be fine. But for a Shared Worker, that is not the case, because browsers seem to handle errors inside Shared Workers differently (currently Firefox seems to send the normal `error` event to all hosts, but [Chrome does not](https://bugs.chromium.org/p/chromium/issues/detail?id=105001)). Therefore, promise-worker-bi includes a unified API that works in Web Workers and Shared Workers.
+For a Web Worker, we could just use [the normal `error` event](https://developer.mozilla.org/en-US/docs/Web/API/AbstractWorker/onerror) and be fine. But for a Shared Worker, that is not the case, because browsers seem to handle errors inside Shared Workers differently (currently Firefox seems to send the normal `error` event to all hosts, but [Chrome does not](https://bugs.chromium.org/p/chromium/issues/detail?id=105001)).
+
+Therefore, promise-worker-bi includes a unified API that works in Web Workers and Shared Workers. Include some code like this in your host:
 
 ```js
-promiseWorker.registerError(function(err) {
+promiseWorker.registerError((error) => {
   console.log("Error inside worker!", err);
 });
 ```
@@ -141,21 +129,17 @@ If you use a source map for your worker script, this will not be reflected in th
 If you need to send messages of multiple types to the worker, just add some type information to the message you send:
 
 ```js
-promiseWorker
-  .postMessage({
-    type: "en"
-  })
-  .then(/* ... */);
-
-promiseWorker
-  .postMessage({
-    type: "fr"
-  })
-  .then(/* ... */);
+const response1 = await promiseWorker.postMessage({
+  type: "en",
+});
+
+const response2 = await promiseWorker.postMessage({
+  type: "en",
+});
 ```
 
 ```js
-promiseWorker.register(function(message) {
+promiseWorker.register((message) => {
   if (message.type === "en") {
     return "Hello!";
   } else if (message.type === "fr") {
@@ -174,19 +158,18 @@ Here's an example:
 // main.js
 import { PWBHost } from "promise-worker-bi";
 
-var worker = new SharedWorker("worker.js");
-var promiseWorker = new PWBHost(worker);
+const worker = new SharedWorker("worker.js");
+const promiseWorker = new PWBHost(worker);
 
-promiseWorker.register(function(message) {
+promiseWorker.register((message) => {
   console.log(message);
 });
 
 // setTimeout is just to give you enough time to open main.js and main2.js in
 // two separate tabs.
-setTimeout(function() {
-  promiseWorker.postMessage("broadcast").then(function(response) {
-    console.log("Echoed response:", response);
-  });
+setTimeout(async () => {
+  const response = await promiseWorker.postMessage("broadcast");
+  console.log("Echoed response:", response);
 }, 1000);
 ```
 
@@ -194,19 +177,18 @@ setTimeout(function() {
 // main2.js
 import { PWBHost } from "promise-worker-bi";
 
-var worker = new SharedWorker("worker.js");
-var promiseWorker = new PWBHost(worker);
+const worker = new SharedWorker("worker.js");
+const promiseWorker = new PWBHost(worker);
 
-promiseWorker.register(function(message) {
+promiseWorker.register((message) => {
   console.log(message);
 });
 
 // setTimeout is just to give you enough time to open main.js and main2.js in
 // two separate tabs.
-setTimeout(function() {
-  promiseWorker.postMessage("just this tab").then(function(response) {
-    console.log("Echoed response:", response);
-  });
+setTimeout(() => {
+  const reponse = await promiseWorker.postMessage("just this tab");
+  console.log("Echoed response:", response);
 }, 2000);
 ```
 
@@ -214,13 +196,13 @@ setTimeout(function() {
 // worker.js
 import { PWBWorker } from "promise-worker-bi";
 
-var promiseWorker = new PWBWorker();
+const promiseWorker = new PWBWorker();
 
-promiseWorker.register(function(message, hostID) {
+promiseWorker.register((message, hostID) => {
   if (message === "broadcast") {
     promiseWorker.postMessage("to all tabs");
   } else {
-    promiseWorker.postMessage("hello host " + hostID, hostID);
+    promiseWorker.postMessage(`hello host ${hostID}`, hostID);
   }
 
   return message;
@@ -240,8 +222,43 @@ And this in the second tab:
 
 (If you open main2.js first, "hello host 1" will instead be "hello host 0".)
 
+### Transferable objects
+
+It is possible to [transfer certain types of objects](https://developer.mozilla.org/en-US/docs/Glossary/Transferable_objects) from host to worker or from worker to host. The syntax is similar to how it works with [a normal `postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Worker/postMessage), where an array of the objects to be transferred is added as an additional parameter.
+
+One tricky thing - because `promiseWorker.postMessage` already has a second argument for specifying an optional `hostID` value fo sending a message from a shared worker to a specific host, the transferables argument is the third argument:
+
+```js
+const buffer = new ArrayBuffer(1);
+promiseWorker.postMessage(buffer, hostID, [buffer]);
+```
+
+From host to worker, the `hostID` argument doesn't do anything, so in most situations (host -> worker, web worker -> host, shared worker -> all hosts) you can pass `undefined` as the second argument:
+
+```js
+const buffer = new ArrayBuffer(1);
+promiseWorker.postMessage(buffer, undefined, [buffer]);
+```
+
+If you want to respond to a message by sending a transferable object back, such as if you want to send an object a worker for processing and then return it to the host, you can do it like this, in either the worker or host:
+
+```js
+promiseWorker.register(async (message) => {
+  const processedMessage = await processMessage(message);
+
+  return {
+    message: processedMessage,
+    _PWB_TRANSFER: [processedMessage.someTransferableProprty],
+  };
+});
+```
+
+That `_PWB_TRANSFER` property is used internally by promise-worker-bi under the assumption that no normal object in your application would have a property with that name.
+
 ## Browser support
 
+In theory it should work in:
+
 - Chrome
 - Firefox
 - Safari 8+
@@ -250,8 +267,6 @@ And this in the second tab:
 - iOS 8+
 - Android 4.4+
 
-Old browsers will need Map and Promise polyfills.
-
 There used to be automated tests in various browsers via [zuul](https://github.com/defunctzombie/zuul) and Sauce Labs, but it suffered bit rot and I could no longer get it to work consistently (PRs welcome!). Currently, `yarn test` uses [Karma](https://karma-runner.github.io/) to run tests in whatever versions of Chrome and Firefox you have installed.
 
 ## API
@@ -286,8 +301,12 @@ Register a message handler wherever you will be receiving messages: in the worke
 
 The `hostID` parameter is only defined inside a shared worker, in which case it is a unique number identifying the host that the message came from.
 
-#### `promiseWorker.postMessage(message: any, hostID?: number): Promise<any>`
+The return value of the callback function (shown above as `any`) must resolve to something [structured cloneable](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm).
+
+If you want to [transfer an object](https://developer.mozilla.org/en-US/docs/Glossary/Transferable_objects) in the return value of the callback, then the return type should be `{ message: any, transfer: Transferable[] }` rather than just `any`.
+
+#### `promiseWorker.postMessage(message: any, hostID?: number, transfer?: Transferable[]): Promise<any>`
 
-Send a message to the browser or worker and return a Promise.
+Send a message to the browser or worker and return a Promise. `message` must resolve to something [structured cloneable](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm).
 
 The `hostID` parameter is only meaningful when sending a message from a shared worker. If you leave it out, it will send the message to all hosts. If you include it, it will send the message only to that specific host. You can get the `hostID` from the `promiseWorker.register` function described above.

package/dist/commonjs.js

@@ -21,23 +21,23 @@ const toFakeError = error => {
   if (typeof error.stack === "string") {
     fakeError.stack = error.stack;
   } // These are non-standard properties, I think only in some versions of Firefox
-  // @ts-ignore
+  // @ts-expect-error
 
 
   if (typeof error.fileName === "string") {
-    // @ts-ignore
+    // @ts-expect-error
     fakeError.fileName = error.fileName;
-  } // @ts-ignore
+  } // @ts-expect-error
 
 
   if (typeof error.columnNumber === "number") {
-    // @ts-ignore
+    // @ts-expect-error
     fakeError.columnNumber = error.columnNumber;
-  } // @ts-ignore
+  } // @ts-expect-error
 
 
   if (typeof error.lineNumber === "number") {
-    // @ts-ignore
+    // @ts-expect-error
     fakeError.lineNumber = error.lineNumber;
   }
 
@@ -63,9 +63,9 @@ const logError = err => {
 class PWBBase {
   constructor() {
     // console.log('constructor', worker);
-    this._callbacks = new Map();
+    this._callbacks = new Map(); // eslint-disable-next-line @typescript-eslint/no-empty-function
 
-    this._queryCallback = () => {}; // @ts-ignore
+    this._queryCallback = () => {}; // @ts-expect-error
 
 
     this._onMessage = this._onMessage.bind(this);
@@ -74,13 +74,9 @@ class PWBBase {
   register(cb) {
     // console.log('register', cb);
     this._queryCallback = cb;
-  } // eslint-disable-next-line
+  } // From worker, 2nd param could be hostID if sending to specific host. From UI, 2nd param could be an array of transferable objects
 
 
-  _postMessage(obj, targetHostID) {
-    throw new Error("Not implemented");
-  }
-
   _postResponse(messageID, error, result, hostID) {
     // console.log('_postResponse', messageID, error, result);
     if (error) {
@@ -88,7 +84,12 @@ class PWBBase {
 
       this._postMessage([MSGTYPE_RESPONSE, messageID, toFakeError(error)], hostID);
     } else {
-      this._postMessage([MSGTYPE_RESPONSE, messageID, null, result], hostID);
+      // Hackily identify when message contains transferable objects
+      if (typeof result === "object" && result !== null && result.hasOwnProperty("message") && result.hasOwnProperty("_PWB_TRANSFER")) {
+        this._postMessage([MSGTYPE_RESPONSE, messageID, null, result.message], hostID, result._PWB_TRANSFER);
+      } else {
+        this._postMessage([MSGTYPE_RESPONSE, messageID, null, result], hostID);
+      }
     }
   }
 
@@ -189,16 +190,16 @@ class PWBHost extends PWBBase {
     //     console.log(worker instanceof Worker);
     //
     // So instead, let's do this test for worker.port which only exists on shared workers.
-    // @ts-ignore
+    // @ts-expect-error
 
     if (worker.port === undefined) {
-      this._workerType = "Worker"; // @ts-ignore
+      this._workerType = "Worker"; // @ts-expect-error
 
       worker.addEventListener("message", this._onMessage);
     } else {
-      this._workerType = "SharedWorker"; // @ts-ignore - it doesn't know if _worker is Worker or SharedWorker, but I do
+      this._workerType = "SharedWorker"; // @ts-expect-error - it doesn't know if _worker is Worker or SharedWorker, but I do
 
-      worker.port.addEventListener("message", this._onMessage); // @ts-ignore - it doesn't know if _worker is Worker or SharedWorker, but I do
+      worker.port.addEventListener("message", this._onMessage); // @ts-expect-error - it doesn't know if _worker is Worker or SharedWorker, but I do
 
       worker.port.start(); // Handle tab close. This isn't perfect, but there is no perfect method
       // http://stackoverflow.com/q/13662089/786644 and this should work like
@@ -228,21 +229,21 @@ class PWBHost extends PWBBase {
     });
   }
 
-  _postMessage(obj) {
-    // console.log('_postMessage', obj);
+  _postMessage(obj, _hostID, transfer) {
+    // console.log('_postMessage', obj, _hostID, transfer);
     if (this._workerType === "Worker") {
-      // @ts-ignore - it doesn't know if _worker is Worker or SharedWorker, but I do
-      this._worker.postMessage(obj);
+      // @ts-expect-error - it doesn't know if _worker is Worker or SharedWorker, but I do
+      this._worker.postMessage(obj, transfer);
     } else if (this._workerType === "SharedWorker") {
-      // @ts-ignore - it doesn't know if _worker is Worker or SharedWorker, but I do
-      this._worker.port.postMessage(obj);
+      // @ts-expect-error - it doesn't know if _worker is Worker or SharedWorker, but I do
+      this._worker.port.postMessage(obj, transfer);
     } else {
       throw new Error("WTF");
     }
   }
 
-  postMessage(userMessage) {
-    // console.log('postMessage', userMessage, targetHostID);
+  postMessage(userMessage, _hostID, transfer) {
+    // console.log('postMessage', userMessage, _hostID, transfer);
     const actuallyPostMessage = (resolve, reject) => {
       const messageID = messageIDs;
       messageIDs += 1;
@@ -256,7 +257,7 @@ class PWBHost extends PWBBase {
         }
       });
 
-      this._postMessage(messageToSend);
+      this._postMessage(messageToSend, undefined, transfer);
     };
 
     return new Promise((resolve, reject) => {
@@ -320,12 +321,12 @@ class PWBWorker extends PWBBase {
     this._hosts = new Map();
     this._maxHostID = -1;
 
-    if ( // @ts-ignore
-    typeof SharedWorkerGlobalScope !== "undefined" && // @ts-ignore
+    if ( // @ts-expect-error
+    typeof SharedWorkerGlobalScope !== "undefined" && // @ts-expect-error
     self instanceof SharedWorkerGlobalScope) {
       this._workerType = "SharedWorker";
       self.addEventListener("connect", e => {
-        // @ts-ignore
+        // @ts-expect-error
         const port = e.ports[0];
         port.addEventListener("message", e2 => this._onMessage(e2)); // eslint-disable-line no-undef
 
@@ -365,7 +366,7 @@ class PWBWorker extends PWBBase {
     }
   }
 
-  _postMessage(obj, targetHostID) {
+  _postMessage(obj, targetHostID, transfer) {
     // console.log('_postMessage', obj, targetHostID);
     if (this._workerType === "SharedWorker") {
       // If targetHostID has been deleted, this will do nothing, which is fine I think
@@ -373,18 +374,19 @@ class PWBWorker extends PWBBase {
         port
       }, hostID) => {
         if (targetHostID === undefined || targetHostID === hostID) {
-          port.postMessage(obj);
+          // @ts-expect-error TypeScript thinks transfer can't be undefined
+          port.postMessage(obj, transfer);
         }
       });
     } else if (this._workerType === "Worker") {
-      // @ts-ignore
-      self.postMessage(obj);
+      // @ts-expect-error TypeScript thinks self is window, which has a different postMessage call signature. In a worker, this is correct.
+      self.postMessage(obj, transfer);
     } else {
       throw new Error("WTF");
     }
   }
 
-  postMessage(userMessage, targetHostID) {
+  postMessage(userMessage, targetHostID, transfer) {
     // console.log('postMessage', userMessage, targetHostID);
     const actuallyPostMessage = (resolve, reject) => {
       const messageID = messageIDs;
@@ -399,7 +401,7 @@ class PWBWorker extends PWBBase {
         }
       });
 
-      this._postMessage(messageToSend, targetHostID);
+      this._postMessage(messageToSend, targetHostID, transfer);
     };
 
     return new Promise((resolve, reject) => {