jsonbird

JSONBird

JSONBird is a Duplex stream which makes it easy to create a flexible JSON-RPC 2.0 client or server (or a bidirectional combination) over any reliable transport. You can use out of order messaging or an in-order byte stream.

It can parse/emit JSON strings or parse/emit plain-old-javascript-objects in memory.

JSONBird does not care what transport is used, for example you could use:

• Synchronous HTTP request/responses
• HTTP polling
• WebSocket
• TCP
• SCTP
• postMessage() between a Web Worker or iframe's in a browser (without having to serialize to JSON)
• Direct in-memory communication between two instances (for example, for test stubs)
• Message port's for multiprocess browser extensions

Examples

Registering methods

const Promise = require('bluebird');
const JSONBird = require('jsonbird');
const rpc = new JSONBird({/*options*/});

class MyMethods {
  add(a, b) {
    return a + b;
  }

  subtract(a, b) {
    return this.add(a, -b);
  }

  slowAdd(a, b) {
    return Promise.delay(100).then(() => this.add(a, b));
  }
}

rpc.methods(new MyMethods());
rpc.method('multiply', (a, b) => a * b);

WebSocket Server (node.js)

const JSONBird = require('jsonbird');
const express = require('express');
const {createServer: createWebSocketServer} = require('websocket-stream');

const app = express();
app.get('/', (request, response) => response.end('Hi!'));

const server = app.listen(1234);
const webSocketServer = createWebSocketServer({server}, wsStream => {
  // `rpc` is a node.js duplex stream. The "readable" side refers to the
  // output of JSONBird (you "read" the output from the stream). The
  // "writable" side refers to the input of JSONBird (you "write" the
  // input to the stream):

  const rpc = new JSONBird({
    // The "json-message" readable mode emits JSON documents in object
    // mode, this ensures that our peer never receives a split up json
    // document from us (WebSocket is message based, as opposed to
    // stream based)
    readableMode: 'json-message',

    // The "json-stream" writable mode accepts JSON documents as a
    // string and will reconstruct a split up json document.
    writableMode: 'json-stream',

    // Combining these two modes in this example will maximize
    // compatibility with other JSON-RPC implementations.
  });

  rpc.methods(new MyMethods());

  wsStream.pipe(rpc);
  rpc.pipe(wsStream);
});

WebSocket client (browser)

// this example should be bundled using browserify or webpack
const JSONBird = require('jsonbird');
const {WebSocket} = window;

const rpc = new JSONBird({
  readableMode: 'json-message',
  writableMode: 'json-stream',
});

const connect = () => {
  const ws = new WebSocket('ws://localhost:1234/');
  ws.binaryType = 'arraybuffer';

  const rpcOnData = str => ws.send(str);

  ws.onopen = () => {
    rpc.on('data', rpcOnData);

    rpc.call('add', 10, 3)
      .then(result => rpc.call('subtract', result, 1))
      .then(result => console.log('result:', result)) // 12
      ;
  };
  ws.onclose = () => {
    rpc.removeListener('data', rpcOnData);
  };
  ws.onmessage = e => {
    const data = Buffer.from(e.data);
    rpc.write(data);
  };
};

connect();

WebWorker

// this example should be bundled using browserify or webpack
const JSONBird = require('jsonbird');
const {WebSocket} = window;
const worker = new Worker('myWorker.js');
const rpc = new JSONBird({
    // take advantage of the structured clone algorithm
    readableMode: 'object',
    writableMode: 'object',
    receiveErrorStack: true,
    sendErrorStack: true,
});
worker.onmessage = e => rpc.write(e.data);
rpc.on('data', object => worker.postMessage(object));

myWorker.js:

// this example should be bundled using browserify or webpack
const JSONBird = require('jsonbird');
const rpc = new JSONBird({
  readableMode: 'object',
  writableMode: 'object',
  receiveErrorStack: true,
  sendErrorStack: true,
});
self.onmessage = e => rpc.write(e.data);
rpc.on('data', object => self.postMessage(object));

Shared WebWorker

// this example should be bundled using browserify or webpack
const JSONBird = require('jsonbird');
const {WebSocket} = window;
const worker = new SharedWorker('mySharedWorker.js');
const rpc = new JSONBird({
    // take advantage of the structured clone algorithm
    readableMode: 'object',
    writableMode: 'object',
    receiveErrorStack: true,
    sendErrorStack: true,
});
worker.port.onmessage = e => rpc.write(e.data);
rpc.on('data', object => worker.port.postMessage(object));

mySharedWorker.js:

// this example should be bundled using browserify or webpack
const JSONBird = require('jsonbird');
const rpc = new JSONBird({
  readableMode: 'object',
  writableMode: 'object',
  receiveErrorStack: true,
  sendErrorStack: true,
});
self.onconnect = e => {
    const port = e.ports[0];
    port.onmessage = e => rpc.write(e.data);
    rpc.on('data', object => port.postMessage(object));
};

API Documentation

JSONBird

JSONBird is a Duplex stream which makes it easy to create a flexible JSON-RPC 2.0 client or server (or a bidirectional combination) over any reliable transport. You can use out of order messaging or an in-order byte stream.

Kind: global class

• JSONBird
  • new JSONBird([optionsArg])
  • instance
    • .setTimeout ⇒ function
    • .clearTimeout ⇒ function
    • .ended ⇒ boolean
    • .finished ⇒ boolean
    • .sessionId ⇒ string
    • .writableMode ⇒ string
    • .readableMode ⇒ string
    • .endOfJSONWhitespace ⇒ string
    • .endOnFinish ⇒ boolean
    • .endOnFinish
    • .finishOnEnd ⇒ boolean
    • .finishOnEnd
    • .serverPending ⇒ number
    • .clientPending ⇒ number
    • .receiveErrorStack ⇒ boolean
    • .receiveErrorStack
    • .sendErrorStack ⇒ boolean
    • .sendErrorStack
    • .defaultTimeout ⇒ number
    • .defaultTimeout
    • .pingReceive ⇒ boolean
    • .isSendingPings ⇒ boolean
    • .pingMethod ⇒ string
    • .pingInterval ⇒ number
    • .pingInterval
    • .pingTimeout ⇒ number
    • .pingTimeout
    • .generateId() ⇒ string | number
    • .waitForPendingResponses() ⇒ Promise
    • .waitForPendingRequests() ⇒ Promise
    • .method(name, func)
    • .methods(objectOrMap)
    • .notification(name, func)
    • .notifications(objectOrMap)
    • .call(nameOrOptions, ...args) ⇒ Promise
    • .bindCall(nameOrOptions) ⇒ function
    • .notify(nameOrOptions, ...args) ⇒ Promise
    • .bindNotify(nameOrOptions) ⇒ function
    • .startPinging()
    • .stopPinging()
    • .resetPingStatistics()
    • "error" (error)
    • "protocolError" (error)
    • "pingSuccess" (delay)
    • "pingFail" (consecutiveFails, error)
  • static
    • .errorToResponseObject(error, [includeErrorStack]) ⇒ Object
    • .isValidVersion(jsonrpc) ⇒ boolean
    • .isValidID(id) ⇒ boolean
    • .isValidMethodName(method) ⇒ boolean
    • .isValidParams(params) ⇒ boolean
    • .isObjectBuiltinFunction(object, name) ⇒ boolean

new JSONBird([optionsArg])

Param	Type	Default	Description
[optionsArg]	Object		The effect of these options are documented at the getter/setter with the same name
[optionsArg.receiveErrorStack]	boolean	false
[optionsArg.sendErrorStack]	boolean	false
[optionsArg.writableMode]	string	"json-stream"
[optionsArg.readableMode]	string	"json-stream"
[optionsArg.firstRequestId]	number	0	The first request id to use
[optionsArg.sessionId]	string	"randomString()"
[optionsArg.endOfJSONWhitespace=]	string
[optionsArg.endOnFinish]	boolean	true
[optionsArg.finishOnEnd]	boolean	true
[optionsArg.pingReceive]	boolean	true
[optionsArg.pingMethod]	string	"'jsonbird.ping'"
[optionsArg.pingInterval]	number	2000
[optionsArg.pingTimeout]	number	1000
[optionsArg.pingNow]	number	Date.now	Timer function used to figure out ping delays
[optionsArg.setTimeout]	function	global.setTimeout
[optionsArg.clearTimeout]	function	global.clearTimeout

jsonBird.setTimeout ⇒ function

The HTML setTimeout function

This function may be overridden for unit tests

Kind: instance property of JSONBird
Returns: function - https://html.spec.whatwg.org/#dom-settimeout

jsonBird.clearTimeout ⇒ function

The HTML clearTimeout function

This function may be overridden for unit tests

Kind: instance property of JSONBird
Returns: function - https://html.spec.whatwg.org/#dom-cleartimeout

jsonBird.ended ⇒ boolean

Has the readable side of this duplex stream been ended?

(has the 'end' event been emitted)

Kind: instance property of JSONBird

jsonBird.finished ⇒ boolean

Has the writable side of this duplex stream been finished?

(has the 'finish' event been emitted)

Kind: instance property of JSONBird

jsonBird.sessionId ⇒ string

This is a string that will be appended to the id of all request objects that we send out.

This is useful in case the same transport is reused, to make sure that we do not parse any stale response objects. By default, this is set to a short unique id (using the "shortid" module)

Kind: instance property of JSONBird

jsonBird.writableMode ⇒ string

Determines how to JSONBird interprets messages that are written to the writable side of this Duplex stream.

If the value is "object", the writable stream is put in object mode and a plain old javascript object is expected.

For example:

rpc.write({jsonrpc: '2.0', method: 'subtract', params: [42, 23], id: 0})

If the value is "json-message", the writable stream is put in object mode and a json string or a Buffer (utf8) is expected,

For example:

rpc.write('{"jsonrpc":"2.0","method":"subtract","params":[42,23],"id":0}')
rpc.write('{"jsonrpc"') // invalid json string, a `protocolError` event will emitted

If the value is "json-stream", a streaming sequence of json strings or Buffers (utf8) are expected.

For example:

// will wait until more data arrives to complete the json string:
rpc.write('{"jsonrpc":"2.0","method":"subt')
rpc.write('ract","params":[42,23],"id":0}{"jsonrpc"')
rpc.write(':"2.0","method":"subtract","params":[100,1],"id":1}')

Kind: instance property of JSONBird
Returns: string - "object", "json-stream" or "json-message"

jsonBird.readableMode ⇒ string

Determines how JSONBird sends messages to the readable side of this Duplex stream.

If the value is "object", the readable stream is put in object mode and a plain old javascript object is sent.

For example:

rpc.on('data', object => assert.deepEqual(object, {jsonrpc: '2.0', result: 19, id: 0}));

If the value is "json-message", the readable stream is put in object mode and a json string is sent.

For example:

rpc.on('data', string => console.log('json string:', string));
// json string: {"jsonrpc":"2.0","result":19,"id":0}
// json string: {"jsonrpc":"2.0","result":99,"id":1}

If the value is "json-stream", a streaming sequence of json strings are sent.

For example:

rpc.on('data', string => console.log('chunk:', string));
// chunk: {"jsonrpc":"2.0","res
// chunk: ult":19,"id":0}{"jsonrpc":"2.0",
// chunk: "result":99,"id":1}

Kind: instance property of JSONBird
Returns: string - "object" or "json-stream"

jsonBird.endOfJSONWhitespace ⇒ string

This value is appended to the end of every json string sent to the readable stream.

Only whitespace characters are allowed. This option only has an affect if readableMode == 'json-stream'

Kind: instance property of JSONBird

jsonBird.endOnFinish ⇒ boolean

If true and the writable side of this Duplex stream has finished, automatically end the readable side (after all pending responses have been sent).

Kind: instance property of JSONBird

jsonBird.endOnFinish

If true and the writable side of this Duplex stream has finished, automatically end the readable side (after all pending responses have been sent).

Kind: instance property of JSONBird

Param	Type
value	boolean

jsonBird.finishOnEnd ⇒ boolean

If true and the readable side of this Duplex stream has ended, automatically finish the writable side (after all pending requests have received a response).

Kind: instance property of JSONBird

jsonBird.finishOnEnd

If true and the readable side of this Duplex stream has ended, automatically finish the writable side (after all pending requests have received a response).

Kind: instance property of JSONBird

Param	Type
value	boolean

jsonBird.serverPending ⇒ number

The number of incoming RPC requests for which we have not sent a reply yet

Kind: instance property of JSONBird

jsonBird.clientPending ⇒ number

The number of outstanding RPC requests for which we have not yet received a response.

Kind: instance property of JSONBird

jsonBird.receiveErrorStack ⇒ boolean

If true and a remote method throws, attempt to read stack trace information from the JSON-RPC error.data property. This stack trace information is then used to set the fileName, lineNumber, columnNumber and stack properties of our local Error object (the Error object that the .call() function will reject with).

Kind: instance property of JSONBird

jsonBird.receiveErrorStack

If true and a remote method throws, attempt to read stack trace information from the JSON-RPC error.data property. This stack trace information is then used to set the fileName, lineNumber, columnNumber and stack properties of our local Error object (the Error object that the .call() function will reject with).

Kind: instance property of JSONBird

Param	Type
value	boolean

jsonBird.sendErrorStack ⇒ boolean

If true, the fileName, lineNumber, columnNumber and stack of an Error thrown during a method is sent to the client using the JSON-RPC error.data property.

Kind: instance property of JSONBird

jsonBird.sendErrorStack

If true, the fileName, lineNumber, columnNumber and stack of an Error thrown during a method is sent to the client using the JSON-RPC error.data property.

Kind: instance property of JSONBird

Param	Type
value	boolean

jsonBird.defaultTimeout ⇒ number

The timeout to use for an outgoing method call unless a different timeout was explicitly specified to call().

Kind: instance property of JSONBird

jsonBird.defaultTimeout

The timeout to use for an outgoing method call unless a different timeout was explicitly specified to call().

Kind: instance property of JSONBird

Param	Type
value	number

jsonBird.pingReceive ⇒ boolean

If true a method with the name this.pingMethod is added which simply returns true as fast as possible.

Kind: instance property of JSONBird

jsonBird.isSendingPings ⇒ boolean

Are we currently sending pings to our peer?

In other words, has this.startPinging() been called?

Kind: instance property of JSONBird

jsonBird.pingMethod ⇒ string

The method name used when receiving or sending pings.

Kind: instance property of JSONBird

jsonBird.pingInterval ⇒ number

The time (in milliseconds) between each ping if isSendingPings is true. This time is in addition to the time spent waiting for the previous ping to settle.

Kind: instance property of JSONBird
Returns: number - milliseconds

jsonBird.pingInterval

The time (in milliseconds) between each ping if isSendingPings is true. This time is in addition to the time spent waiting for the previous ping to settle.

Kind: instance property of JSONBird

Param	Type	Description
value	number	milliseconds

jsonBird.pingTimeout ⇒ number

The maximum amount of time (in milliseconds) to wait for a ping method call to resolve.

Kind: instance property of JSONBird
Returns: number - milliseconds

jsonBird.pingTimeout

The maximum amount of time (in milliseconds) to wait for a ping method call to resolve.

Kind: instance property of JSONBird

Param	Type	Description
value	number	milliseconds

jsonBird.generateId() ⇒ string | number

Generate a new id to be used for an outgoing request object

Kind: instance method of JSONBird

jsonBird.waitForPendingResponses() ⇒ Promise

Returns a promise which resolves as soon as all pending requests (as a server) have had their appropriate responses sent to the underlying readable stream.

Note that if a new requests comes in after using waitForPendingResponses(), they will not further delay this Promise.

Kind: instance method of JSONBird

jsonBird.waitForPendingRequests() ⇒ Promise

Returns a promise which resolves as soon as all pending requests (as a client) have had their appropriate responses received from the underlying writable stream.

Note that if a new call() is made after using waitForPendingResponses(), it will not further delay this Promise.

Kind: instance method of JSONBird

jsonBird.method(name, func)

Registers a new method with the given name.

If the same method name is registered multiple times, earlier definitions will be overridden

Kind: instance method of JSONBird

Param	Type	Description
name	string	The method name
func	function

jsonBird.methods(objectOrMap)

Registers multiple methods using an object or Map.

Each key->value pair is registered as a method. Values that are not a function are ignored. The this object during a method call is set to the objectOrMap (unless a Map was used)

If the same method name is registered multiple times, earlier definitions will be overridden

Kind: instance method of JSONBird

Param	Type
objectOrMap	Object | Map

jsonBird.notification(name, func)

Registers a notification with the given name.

A notification is a method for which the return value or thrown Error is ignored. A response object is never sent.

If the same method name is registered multiple times, all functions handlers will be called (in the same order as they were registered)

Kind: instance method of JSONBird

Param	Type	Description
name	string	The method name
func	function

jsonBird.notifications(objectOrMap)

Registers multiple notifications using an object or Map.

A notification is a method for which the return value or thrown Error is ignored. A response object is never sent.

If the same method name is registered multiple times, all functions handlers will be called (in the same order as they were registered)

Each key->value pair is registered as a notification. Values that are not a "function" are ignored. The this object during a method call is set to the objectOrMap (unless a Map was used)

If the same method name is registered multiple times, earlier definitions will be overridden

Kind: instance method of JSONBird

Param	Type
objectOrMap	Object | Map

jsonBird.call(nameOrOptions, ...args) ⇒ Promise

Call a method on the remote instance, by sending a JSON-RPC request object to our write stream.

If no write stream has been set, the method call will be buffered until a write stream is set (setWriteStream). Note: if a read stream is never set, any call() will also never resolve.

Kind: instance method of JSONBird
Returns: Promise - A Promise which will resole with the return value of the remote method

Param	Type	Description
nameOrOptions	string | Object	The method name or an options object
nameOrOptions.name	string	The method name
nameOrOptions.timeout	number	A maximum time (in milliseconds) to wait for a response. The returned promise will reject after this time.
...args	*

jsonBird.bindCall(nameOrOptions) ⇒ function

Returns a new function which calls the given method name by binding the function to this RPC instance and the given method name (or options object).

For example:

const subtract = rpc.bindCall('subtract');
subtract(10, 3).then(result => console.log(result)) // 7

Kind: instance method of JSONBird

Param	Type	Description
nameOrOptions	string | Object	The method name or an options object
nameOrOptions.name	string	The method name
nameOrOptions.timeout	number	A maximum time (in milliseconds) to wait for a response. The returned promise will reject after this time.

jsonBird.notify(nameOrOptions, ...args) ⇒ Promise

Execute a notification on the remote instance, by sending a JSON-RPC request object to our write stream.

If no write stream has been set, the method call will be buffered until a write stream is set (setWriteStream).

This function resolves as soon as the request object has been buffered, but does not wait for the remote instance to have actually received the request object.

Kind: instance method of JSONBird

Param	Type	Description
nameOrOptions	string | Object	The method name or an options object
nameOrOptions.name	string	The method name
...args	*

jsonBird.bindNotify(nameOrOptions) ⇒ function

Returns a new function which sends a notification with the given method name by binding the function to this RPC instance and the given method name (or options object).

For example:

const userDeleted = rpc.bindNotify('userDeleted');
userDeleted(123)

Kind: instance method of JSONBird

Param	Type	Description
nameOrOptions	string | Object	The method name or an options object
nameOrOptions.name	string	The method name
nameOrOptions.timeout	number	A maximum time (in milliseconds) to wait for a response. The returned promise will reject after this time.

jsonBird.startPinging()

Start pinging our peer periodically.

A ping is a remote method call with the name this.pingMethod. This method is called every this.pingInterval, with a timeout of this.pingTimeout. The events 'pingSuccess' and 'pingFail' are emitted based on the results of the call. The property this.isSendingPings can be read to find out if pings are currently being sent.

When you are done, make sure to either call stopPinging() or end/finish this stream if pinging is enabled, otherwise you will leak resources.

Kind: instance method of JSONBird

jsonBird.stopPinging()

Stop the periodic ping (if previously enabled by startPinging()).

Kind: instance method of JSONBird

jsonBird.resetPingStatistics()

Resets all statistics which are reported by ping events.

Currently this method only sets pingConsecutiveFails to 1 for the next pingFail event

Kind: instance method of JSONBird

"error" (error)

This event is fired if an uncaught error occurred

Most errors end up at the caller of our functions or at the remote peer, instead of this event. Note that if you do not listen for this event on node.js, your process might exit.

Kind: event emitted by JSONBird

Param	Type
error	Error

"protocolError" (error)

This event is fired if our peer sent us something that we were unable to parse.

These kind of errors do not end up at the 'error' event

Kind: event emitted by JSONBird

Param	Type
error	Error

"pingSuccess" (delay)

The most recent ping sent to our peer succeeded

Kind: event emitted by JSONBird

Param	Type	Description
delay	number	How long the ping took to resolve (in milliseconds)

"pingFail" (consecutiveFails, error)

The most recent ping sent to our peer timed out or resulted in an error

Kind: event emitted by JSONBird

Param	Type	Description
consecutiveFails	number	The amount of consecutive pings that failed
error	Error

JSONBird.errorToResponseObject(error, [includeErrorStack]) ⇒ Object

Converts any javascript Error object to a JSON-RPC error object

Kind: static method of JSONBird

Param	Type	Default	Description
error	Error		The message, code and data properties of this error will be copied over to the resulting object.
[includeErrorStack]	boolean	false	If true and error.data is undefined, the resulting data object will contain a "javascriptError" objecting containing the fileName, lineNumber, columnNumber and stack of the error.

JSONBird.isValidVersion(jsonrpc) ⇒ boolean

Is the given value for the JSON-RPC jsonrpc property a value that we recognise?

Currently, only "2.0" is supported

Kind: static method of JSONBird

Param	Type
jsonrpc	*

JSONBird.isValidID(id) ⇒ boolean

Is the given value for the JSON-RPC id property valid?

Kind: static method of JSONBird

Param	Type
id	*

JSONBird.isValidMethodName(method) ⇒ boolean

Is the given value for the JSON-RPC method property valid?

Kind: static method of JSONBird

Param	Type
method	*

JSONBird.isValidParams(params) ⇒ boolean

Is the given value for the JSON-RPC params property valid?

Kind: static method of JSONBird

Param	Type
params	*

JSONBird.isObjectBuiltinFunction(object, name) ⇒ boolean

Test if the given property name of object is one of the builtin Object.prototype functions.

Such as: hasOwnProperty, defineGetter, etc

Kind: static method of JSONBird

Param	Type
object	Object
name	string