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)

const JSONBird = require('jsonbird'); // e.g. browserify
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();

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
    • .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
    • .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
  • 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

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.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.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 property will be an object 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