ipc-proxy0-pmb

ipc-proxy0-pmb
==============

Convenience wrapper for child_process.fork

API
---

This module exports an object with these methods:

$3

Spawns an IPC proxy instance for the module name(s) from libs,
which should be a string or an array of strings.
Returns the subprocess object, or false if it couldn't fork().

If present, spawnOpts are passed as options to fork().

In case a callback function then is provided, it is called with
arguments (error, child) on the child's close event. (Actually,
the close:nodeback event from package child-exit-nodeback.)

$3

These functions translate between Error objects and plain, JSON-able
(dictionary) objects.
Currently they're based heavily on the error-to-json package,
but implementation may change without notice.

IPC message protocol
--------------------

* NB: Node v6 IPC channels are JSON-based, so un-JSON-able data may be
transformed or discarded. The jsonize-loudfail package can check
your data and warn you in advance.

:TODO:

Usage
-----

from test.usage.js:

``javascript
var logArgs = test.log.args, ipcProxy = require('ipc-proxy0-pmb'),
child = ipcProxy.spawn('querystring', logArgs('child quit'));
equal(typeof child.pid, 'number');
child.on('msg:result', logArgs('got result:'));

test.add(function () {
child.send({ mtd: 'stringify', ret: 'result',
arg: [ { Hello: 'World!', foo: 23, bar: 42 }, '/', ':' ] });
test.log.expect([
[ 'got result:', 'Hello:World!/foo:23/bar:42' ],
]);
});

test.add(function () {
child.send({ mtd: 'parse', ret: 'result', fin: true,
arg: [ 'Hello=World&foo=23&bar=42' ] });
test.log.expect([
[ 'got result:', { Hello: 'World', foo: '23', bar: '42' } ],
[ 'child quit', false, '{ChildProcess}' ],
]);
});

test.add(function () {
var whale = ipcProxy.spawn('/dev/null/404.js', logArgs('whale quit'));
equal(typeof whale.pid, 'number');
whale.on('error', logArgs('whale fail'));
test.log.expect([
[ 'whale fail', '{Error "IPC proxy child:'
+ ' Cannot find module \'/dev/null/404.js\'"}' ],
[ 'whale quit', '{Error "IPC proxy child:'
+ ' Cannot find module \'/dev/null/404.js\'"}',
'{ChildProcess}' ],
]);
});

test.add(function () {
var whale = ipcProxy.spawn('querystring', logArgs('whale quit'));
whale.send({ mtd: "method doesn't exist", ret: true, arg: [] });
whale.on('error', logArgs('whale fail'));
test.log.expect([
[ 'whale fail', '{Error "IPC proxy child:'
+ ' Cannot read property \'apply\' of undefined"}' ],
[ 'whale quit', '{Error "IPC proxy child:'
+ ' Cannot read property \'apply\' of undefined"}',
'{ChildProcess}' ],
]);
});

test.add(function () {
var oneshot = ipcProxy.spawn('querystring', logArgs('oneshot quit'));
oneshot.send({ mtd: 'parse', ret: true, fin: true,
arg: [ 'Hello=World&foo=23&bar=42' ] });
test.log.expect([
[ 'oneshot quit', false, { Hello: 'World', foo: '23', bar: '42' } ],
]);
});
``

Known issues
------------

* needs more/better tests and docs

License
-------

ISC