Add SyncMessagePort.receiveMessageIfAvailable()

Author: nex3

CHANGELOG.md

@@ -0,0 +1,7 @@
+## 1.1.0
+
+* Add `SyncMessagePort.receiveMessageIfAvailable()`.
+
+## 1.0.0
+
+* Initial release

lib/index.test.ts

@@ -73,6 +73,60 @@ describe('SyncMessagePort', () => {
     });
   });
 
+  describe('receiveMessageIfAvailable()', () => {
+    it('without a queued message', () => {
+      const channel = SyncMessagePort.createChannel();
+      const port = new SyncMessagePort(channel.port1);
+      expect(port.receiveMessageIfAvailable()).toBe(undefined);
+      port.close();
+    });
+
+    it('with a queued message', () => {
+      const channel = SyncMessagePort.createChannel();
+      const port1 = new SyncMessagePort(channel.port1);
+      const port2 = new SyncMessagePort(channel.port2);
+
+      port1.postMessage('done!');
+      expect(port2.receiveMessageIfAvailable()?.message).toBe('done!');
+      port1.close();
+    });
+
+    it('on a closed channel', () => {
+      const channel = SyncMessagePort.createChannel();
+      const port1 = new SyncMessagePort(channel.port1);
+      const port2 = new SyncMessagePort(channel.port2);
+
+      port1.close();
+      expect(port2.receiveMessageIfAvailable()).toBe(undefined);
+    });
+
+    it('bewteen receiving blocking messages', () => {
+      const channel = SyncMessagePort.createChannel();
+      const port = new SyncMessagePort(channel.port1);
+
+      spawnWorker(
+        `
+        // Wait a little bit just to make entirely sure that the parent thread
+        // is awaiting a message.
+        setTimeout(() => {
+          port.postMessage('first');
+          port.postMessage('second');
+
+          setTimeout(() => {
+            port.postMessage('third');
+            port.close();
+          }, 100);
+        }, 100);
+      `,
+        channel.port2,
+      );
+
+      expect(port.receiveMessage()).toEqual('first');
+      expect(port.receiveMessageIfAvailable()?.message).toEqual('second');
+      expect(port.receiveMessage()).toEqual('third');
+    });
+  });
+
   describe('with an asynchronous listener', () => {
     it('receives a message sent before listening', async () => {
       const channel = SyncMessagePort.createChannel();

lib/index.ts

@@ -110,8 +110,28 @@ export class SyncMessagePort extends EventEmitter {
     }
   }
 
+  /**
+   * Returns the message sent by the other port, if one is available. This *does
+   * not* block, and will return `undefined` immediately if no message is
+   * available. In order to distinguish between a message with value `undefined`
+   * and no message, a message is return in an object with a `message` field.
+   *
+   * This may not be called while this has a listener for the `'message'` event.
+   * It does *not* throw an error if the port is closed when this is called;
+   * instead, it just returns `undefined`.
+   */
+  receiveMessageIfAvailable(): {message: unknown} | undefined {
+    if (this.listenerCount('message')) {
+      throw new Error(
+        'SyncMessageChannel.receiveMessageIfAvailable() may not be called ' +
+          'while there are message listeners.',
+      );
+    }
+
+    return receiveMessageOnPort(this.port);
+  }
+
   // TODO(nex3):
-  // * Add a non-blocking `receiveMessage()`
   // * Add a timeout option to `receiveMessage()`
   // * Add an option to `receiveMessage()` to return a special value if the
   //   channel is closed.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "sync-message-port",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A Node.js communication port that can pass messages synchronously between workers",
   "repository": "sass/sync-message-port",
   "author": "Google Inc.",