Wondering what’s next for npm?Check out our public roadmap! »

    jsonbird

    3.1.0 • Public • Published

    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

    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

    Install

    npm i jsonbird

    DownloadsWeekly Downloads

    1,335

    Version

    3.1.0

    License

    MIT

    Last publish

    Collaborators

    • avatar