bare-ipc 1.1.1 → 1.1.3

package/README.md

@@ -1,57 +1,33 @@
 # 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
 ```
 
-## API
-
-### `IPC`
-
-#### `const [portA, portB] = IPC.open(opts)`
-
-Returns a pair of `IPCPort`s for use constructing the IPC duplex stream based on
-`bare-pipe`.
-
-#### `const ipc = new IPC(port)`
-
-Returns a duplex stream using the provided port. See `streamx`'s [`Duplex`](https://github.com/mafintosh/streamx?tab=readme-ov-file#duplex-stream) for Duplex API.
-
-#### `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:
+## Usage
 
 ```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()`](#ipcref) for common pattern to keep the event loop alive.
+const IPC = require('bare-ipc')
 
-### `IPCPort`
+const [portA, portB] = IPC.open()
 
-#### `const port = new IPCPort(incoming, outgoing)`
+const a = portA.connect()
+const b = portB.connect()
 
-The arguments are:
+a.on('data', (data) => {
+  // Handle data received from b
+}).end('hello b')
 
-- `incoming` is the read file handle
-- `outgoing` is the write file handle
-
-#### `port.connect()`
-
-Returns an `IPC` connected to the `port`.
+b.on('data', (data) => {
+  // Handle data received from a
+}).end('hello a')
+```
 
-#### `port.detached`
+## API
 
-A boolean for whether the `port` is detached.
+See the [`bare-ipc` reference](https://docs.pears.com/reference/bare/modules/bare-ipc).
 
 ## License
 

package/index.d.ts

@@ -1,24 +1,51 @@
 import { Duplex } from 'bare-stream'
+import Pipe from 'bare-pipe'
 import { Transferable, symbols } from 'bare-structured-clone'
 
 interface IPC extends Duplex {
+  /** The underlying `bare-pipe` `Pipe` used for reading. Read-only. */
+  readonly incoming: Pipe
+  /** The underlying `bare-pipe` `Pipe` used for writing. Read-only. */
+  readonly outgoing: Pipe
+
+  /** Increase the reference count for the IPC to keep the event loop alive. */
   ref(): this
+  /** Decrease the reference count for the IPC to allow the event loop to exit. */
   unref(): this
 }
 
 declare class IPC {
+  /**
+   * Returns a duplex stream using the provided `port`. See `bare-stream`'s `Duplex`
+   * (<https://github.com/holepunchto/bare-stream>) for the duplex stream API.
+   * @param port - The port to open the stream over, as returned by `IPC.open()`.
+   */
   constructor(port: IPCPort)
 }
 
 interface IPCPort extends Transferable<[incoming: number, outgoing: number]> {
+  /** The file handle used for reading. Read-only. */
   readonly incoming: number
+  /** The file handle used for writing. Read-only. */
   readonly outgoing: number
+  /**
+   * 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.
+   */
   readonly detached: boolean
 
+  /**
+   * @returns An `IPC` duplex stream connected to the port.
+   */
   connect(): IPC
 }
 
 declare class IPCPort {
+  /**
+   * Constructs a port from a pair of file handles, `incoming` and `outgoing`.
+   * @param incoming - The file handle used for reading.
+   * @param outgoing - The file handle used for writing.
+   */
   constructor(incoming: number, outgoing: number)
 
   static [symbols.attach](input: [incoming: number, outgoing: number]): IPCPort
@@ -27,6 +54,12 @@ declare class IPCPort {
 declare namespace IPC {
   export { IPCPort }
 
+  /**
+   * 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.
+   * @returns A pair of connected ports, one for each end of the IPC channel.
+   */
   export function open(): [IPCPort, IPCPort]
 }
 

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() {
@@ -50,6 +61,10 @@ module.exports = exports = class IPC extends Duplex {
     this._outgoing.destroy()
   }
 
+  _onerror(err) {
+    this.destroy(err)
+  }
+
   _ondata(data) {
     if (this.push(data) === false) {
       this._incoming.pause()
@@ -68,7 +83,7 @@ module.exports = exports = class IPC extends Duplex {
   }
 }
 
-const IPC = module.exports
+module.exports = exports = IPC
 
 class IPCPort {
   constructor(incoming, outgoing) {
@@ -85,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

package/lib/errors.d.ts

@@ -1,4 +1,10 @@
 declare class IPCError extends Error {
+  /**
+   * Create the error thrown when transferring a port that has already been connected or
+   * transferred.
+   * @param msg - The error message.
+   * @returns An error with code `ALREADY_CONNECTED`.
+   */
   static ALREADY_CONNECTED(msg: string): IPCError
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-ipc",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "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",
@@ -34,11 +36,12 @@
   "dependencies": {
     "bare-pipe": "^4.0.0",
     "bare-stream": "^2.1.3",
-    "bare-structured-clone": "^1.4.0"
+    "bare-structured-clone": "^2.0.0"
   },
   "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"
   }
 }