Simple but versatile IPC interface
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.editorconfig
.gitattributes
.gitignore
CHANGELOG.md
LICENSE
README.md
example-child.js
example-master.js
index.js
package-lock.json
package.json
types.d.ts

README.md

wormhole

Standard - JavaScript Style Guide

This module can be used to provide handy functionality on top of remote connections such as Inter-Process Communication (IPC). It's designed to be small and easy to use.

It has the following features:

  • Send and receive events with arbitrary arguments
  • RPC-style remote command calling
  • Can be used on both sides of a communication channel

wormhole is developed with process and child_process (over IPC) in mind.

TypeScript definitions included!

Installing

npm i @art-of-coding/wormhole

Example

This is an attempt to write a complete example. In this example we fork a process and then we want to communicate with it. By using wormhole on both ends, we can send and receive events and commands in both directions.

The master process:

const childProcess = require('child_process')
const Wormhole = require('@art-of-coding/wormhole')

const child = childProcess.fork('./my-child.js')
const wormhole = new Wormhole(child)

// Register a `startup` event handler
wormhole.events.on('startup', () => {
  console.log('received startup event!')
})

// Register an `add` command
wormhole.define('add', function (a, b) {
  return a + b
})

// Send the `quit` event to the child
setTimeout(() => wormhole.event('quit'), 5000)

The child process:

const Wormhole = require('@art-of-coding/wormhole')

// Without the `channel` argument, `process` is selected by default
const wormhole = new Wormhole()

// Register a `quit` event handler
wormhole.events.once('quit', () => {
  process.exit(-1)
})

// Send an event
wormhole.event('startup')

// Call a remote command
wormhole.command('add', 5, 6).then(result => {
  console.log(`5 + 6 = ${result}`)
})

API

This API is applicable to version 1.x.x! For the 0.x.x documentation, see here.

new Wormhole (channel = process)

Instantiates a new wormhole instance.

  • channel: The channel to use (must either be process or an instance of child_process.ChildProcess)

Events

A Wormhole instance is an EventEmitter with the following events:

  • error: There was an error
  • message: A received message that isn't handled by Wormhole
  • disconnect: The channel is disconnected

wormhole.connected

Returns true if the channel is connected.

wormhole.pendingCallbacks

Returns the amount of pending command callbacks.

wormhole.events

Getter to get the events EventEmitter.

wormhole.events.on('some-event', () => {
  console.log('some-event emitted')
})

wormhole.define (name, fn, context)

Define a command.

If the command is not a promise, the result will be cast into one. Throwing an Error (or subclassed) results in the rejection of the promise.

  • name: The name for this command
  • fn: The function for this command
  • context: The command context (optional)
wormhole.define('add', function (a, b) {
  if (isNaN(a) || isNaN(b)) {
    throw new TypeError('arguments must be numbers')
  }

  return a + b
})

wormhole.event (event, ...args)

Emit an event named event.

  • event: The name of the event
  • ...args: The event arguments

wormhole.command (name, ...args)

Call a remote command named name.

  • name: The name of the command to call
  • ...args: The command arguments
wormhole.command('add', 5, 6).then(result => {
  console.log(`5 + 6 = ${result}`)
})

wormhole.write (message, handle)

Writes a message over the channel.

  • message: The message primitive or object
  • handle: An instance of net.Socket to transfer (optional)

wormhole.disconnect ()

Disconnects the channel and releases all resources. After calling this, the instance is no longer usable.

Standard - JavaScript Style Guide

License

Copyright 2017 Art of Coding.

This software is licensed under the MIT License.