README.md

remote-event-emitter

Deliver Node's EventEmitter events over Unix sockets or TCP connections 🚀

About

This module allows forwarding events (including JSON-serialisable arguments to the events) to another process, with the receiving end behaving as if the events were emitted locally. You can use this for IPC communications where one-directional messaging is needed (ie. one process sends events and another process receives them).

The events are delivered as follows:

1. The consumer (process which wants to receive events) creates a Unix socket or TCP connection and start listening for connections
2. The provider (process which wants to send events) connects to this socket and starts emitting events locally just like any other EventEmitter instance - via emitter.emit('event', ...args)
3. The consumer emits a connection event every time someone connects to the socket. This event will receive a single argument, a source, which basically mirrors the event emitter from the provider side (it will emit the events the provider emits in the other process)

Installation

Install this package on both ends and use either the Consumer or Producer class.

npm install --save remote-event-emitter

Usage

Consumer

import { Consumer } from 'remote-event-emitter'

const consumer = new Consumer()
// Bind to a socket
await consumer.listen({ address: '/tmp/my-fancy.sock' })
// Or, bind to a TCP port 12345
await consumer.listen({ address: 12345 })

// Handle for incoming connections
consumer.on('connection', source => {
  // The events emitted on source will match the events emitted
  // in the provider process
  source.on('hello', string, flag => {
    console.log(string)   // -> "world"
    console.log(flag)   // true
  })

  source.once('close', () => {
    console.log('Client disconnected!')
  })
})

// When you no longer want to accept new connections from providers
// This will close the socket.
await consumer.close()

Provider

import { Provider } from 'remote-event-emitter'

// The socket must exist, otherwise an error will be thrown
const provider = new Provider({ address: '/tmp/my-fancy.sock' })

provider.emit('hello', 'world', true)

// Always close the connection when you are done sending events
provider.end()

Reference implementations

See mocha-reporter-remote for a reference implementation on the provider and atom-ide-mocha for the consumer side.

License

See the LICENSE file for information.