bare-ipc 1.1.0 → 1.1.2

package/README.md

@@ -1,11 +1,93 @@
 # bare-ipc
 
-Lightweight pipe-based IPC for Bare.
+Lightweight pipe-based IPC for Bare. Built on top of `bare-pipe` (<https://github.com/holepunchto/bare-pipe>), it exposes a duplex stream over a pair of file handles whose ports can be transferred between Bare threads and processes.
 
 ```
 npm i bare-ipc
 ```
 
+## Usage
+
+```js
+const IPC = require('bare-ipc')
+
+const [portA, portB] = IPC.open()
+
+const a = portA.connect()
+const b = portB.connect()
+
+a.on('data', (data) => {
+  // Handle data received from b
+}).end('hello b')
+
+b.on('data', (data) => {
+  // Handle data received from a
+}).end('hello a')
+```
+
+## API
+
+### `IPC`
+
+#### `const [portA, portB] = IPC.open()`
+
+Returns a pair of connected `IPCPort`s for constructing the IPC duplex stream based on `bare-pipe`. Each port is transferable and can be sent to another thread or process before being connected.
+
+#### `const ipc = new IPC(port)`
+
+Returns a duplex stream using the provided `port`. See `bare-stream`'s `Duplex` (<https://github.com/holepunchto/bare-stream>) for the duplex stream API.
+
+Errors emitted by the underlying incoming or outgoing pipes are propagated to the stream as `error` events, after which the stream is destroyed.
+
+#### `ipc.incoming`
+
+The underlying `bare-pipe` `Pipe` used for reading. Read-only.
+
+#### `ipc.outgoing`
+
+The underlying `bare-pipe` `Pipe` used for writing. Read-only.
+
+#### `ipc.ref()`
+
+Increase the reference count for the IPC to keep the event loop alive.
+
+A common pattern is to `ipc.ref()` on `Bare.on('resume')` and `ipc.unref()` on suspend like so:
+
+```js
+Bare.on('suspend', () => ipc.unref()).on('resume', () => ipc.ref())
+```
+
+#### `ipc.unref()`
+
+Decrease the reference count for the IPC to allow the event loop to exit.
+
+See `ipc.ref()` for the common pattern to keep the event loop alive.
+
+### `IPCPort`
+
+#### `const port = new IPCPort(incoming, outgoing)`
+
+Constructs a port from a pair of file handles. The arguments are:
+
+- `incoming` is the read file handle.
+- `outgoing` is the write file handle.
+
+#### `port.connect()`
+
+Returns an `IPC` connected to the `port` and marks the `port` as detached.
+
+#### `port.incoming`
+
+The read file handle. Read-only.
+
+#### `port.outgoing`
+
+The write file handle. Read-only.
+
+#### `port.detached`
+
+A boolean for whether the `port` is detached. A port becomes detached once it is connected or transferred, and a detached port cannot be transferred again.
+
 ## License
 
 Apache-2.0

package/index.d.ts

@@ -1,7 +1,11 @@
 import { Duplex } from 'bare-stream'
+import Pipe from 'bare-pipe'
 import { Transferable, symbols } from 'bare-structured-clone'
 
 interface IPC extends Duplex {
+  readonly incoming: Pipe
+  readonly outgoing: Pipe
+
   ref(): this
   unref(): this
 }

package/index.js

@@ -2,7 +2,7 @@ const Pipe = require('bare-pipe')
 const { Duplex } = require('bare-stream')
 const errors = require('./lib/errors')
 
-module.exports = exports = class IPC extends Duplex {
+class IPC extends Duplex {
   constructor(port) {
     const { incoming, outgoing } = port
 
@@ -13,12 +13,23 @@ module.exports = exports = class IPC extends Duplex {
 
     this._pendingWrite = null
 
+    this._onerror = this._onerror.bind(this)
+
     this._incoming
       .on('data', this._ondata.bind(this))
       .on('end', this._onend.bind(this))
+      .on('error', this._onerror)
       .pause()
 
-    this._outgoing.on('drain', this._ondrain.bind(this))
+    this._outgoing.on('drain', this._ondrain.bind(this)).on('error', this._onerror)
+  }
+
+  get incoming() {
+    return this._incoming
+  }
+
+  get outgoing() {
+    return this._outgoing
   }
 
   ref() {
@@ -45,6 +56,15 @@ module.exports = exports = class IPC extends Duplex {
     cb(null)
   }
 
+  _predestroy() {
+    this._incoming.destroy()
+    this._outgoing.destroy()
+  }
+
+  _onerror(err) {
+    this.destroy(err)
+  }
+
   _ondata(data) {
     if (this.push(data) === false) {
       this._incoming.pause()
@@ -63,7 +83,7 @@ module.exports = exports = class IPC extends Duplex {
   }
 }
 
-const IPC = module.exports
+module.exports = exports = IPC
 
 class IPCPort {
   constructor(incoming, outgoing) {
@@ -80,9 +100,7 @@ class IPCPort {
 
   [Symbol.for('bare.detach')]() {
     if (this.detached) {
-      throw errors.ALREADY_CONNECTED(
-        'Port has already started receiving messages'
-      )
+      throw errors.ALREADY_CONNECTED('Port has already started receiving messages')
     }
 
     this.detached = true
@@ -95,9 +113,9 @@ class IPCPort {
   }
 }
 
-exports.open = function open(opts) {
-  const a = Pipe.pipe(opts)
-  const b = Pipe.pipe(opts)
+exports.open = function open() {
+  const a = Pipe.pipe()
+  const b = Pipe.pipe()
 
-  return [new IPCPort(a[0], b[1], opts), new IPCPort(b[0], a[1], opts)]
+  return [new IPCPort(a[0], b[1]), new IPCPort(b[0], a[1])]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-ipc",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Lightweight pipe-based IPC for Bare",
   "exports": {
     ".": {
@@ -19,7 +19,9 @@
     "lib"
   ],
   "scripts": {
-    "test": "prettier . --check && bare test.js"
+    "format": "prettier --write . && lunte --fix",
+    "lint": "prettier --check . && lunte",
+    "test": "brittle-bare --coverage test.js"
   },
   "repository": {
     "type": "git",
@@ -38,7 +40,8 @@
   },
   "devDependencies": {
     "brittle": "^3.2.1",
+    "lunte": "^1.8.0",
     "prettier": "^3.4.1",
-    "prettier-config-standard": "^7.0.0"
+    "prettier-config-holepunch": "^2.0.0"
   }
 }