jitpc

jitpc is a module for creating cross-platform ipc servers / clients

Installation

npm i --save jitpc

Usage

See /example for detailed example.

API

const client = jitpc.connect(id, [options])

connect returns a JSON rpc instance. id is a unique string representing the ipc server to connect to.

const id = 'id-of-my-ipc-sever'
const client = jitpc.connect(id)

await client.request('hello', 'world')

Options include:

{
  async spinup () {} // a function that gets called if the client cannot connect to the server
                     // useful for spinning up a server if none exists  
}

Note that when the client has nothing to do, ie no pending requests and no responders attached, it will auto unref itself, to avoid the process hanging. If a new request is issued, it will auto ref itself as well.

client.userData = data

Assign an object to client.userData to associate state with a client.

client.id

For server clients. ID of the client. Number. 0 for client-side clients instances.

const reply = await client.request(method, params)

Send a request.

client.notify(method, params)

Send a fire and forget request.

client.respond(method, async function onrequest (params) { ... })

Setup a response handler (a responder) that responds to any request against method.

client.unrespond(method)

Unregisters the responder to stop responding to a given method.

client.end()

Gracefully end the client, ie wait for requests, pending responds to finish.

client.destroy([err])

Forcefully end the client.

const server = await jitpc.listen(id, [options])

listen returns a Promise that resolves to an EventEmitter or null if a server is already listening on id. id is a unique string representing the ipc server.

const id = 'id-of-my-ipc-sever'
const counters = new Map()
const server = await jitpc.listen(id)
server.on('client', (client) => {
  client.respond('init', function ({ key }) {
    const counter = { count: 0 }
    counters.set(key, counter)
    return { action: 'ok', payload: { id, count: counter.count} }
  })
  client.respond('inc', function ({ key }) {
    const counter = counters.get(key)
    counter.count++
    return { action: 'ok', payload: { id, count: counter.count} }
  })
})

Options include:

{
  async spindown () {},  // a function that gets called before the server is spun down
  spindownTimeout: 5000 // the number of milliseconds to wait before closing the server after
                         // the server opens and doesn't receive any connections OR after the
                         // number of connections to the server drops to zero
}

server.clientById

Get a client by given ID. Returns a client or null if no client found. Consider IDs as quick entry IDs. There is a chance of collision occuring since it is possible for a new client to take up an old ID. To gaurantee that the client ID matches the expected client, keep an independent counter and match it against a counter in client.userData.