jsonbird
Advanced tools
Readme
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:
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);
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);
});
// 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();
// 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));
// 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));
};
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
functionfunctionbooleanbooleanstringstringstringstringbooleanbooleannumbernumberbooleanbooleannumberbooleanbooleanstringnumbernumberstring | numberPromisePromisePromisefunctionPromisefunctionObjectbooleanbooleanbooleanbooleanboolean| 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 |
functionThe 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
functionThe 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
booleanHas the readable side of this duplex stream been ended?
(has the 'end' event been emitted)
Kind: instance property of JSONBird
booleanHas the writable side of this duplex stream been finished?
(has the 'finish' event been emitted)
Kind: instance property of JSONBird
stringThis 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
stringDetermines 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"
stringDetermines 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"
stringThis 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
booleanIf 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
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 |
booleanIf 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
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 |
numberThe number of incoming RPC requests for which we have not sent a reply yet
Kind: instance property of JSONBird
numberThe number of outstanding RPC requests for which we have not yet received a response.
Kind: instance property of JSONBird
booleanIf 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
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 |
booleanIf 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
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 |
numberThe timeout to use for an outgoing method call unless a different timeout was explicitly specified to call().
Kind: instance property of JSONBird
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 |
booleanIf true a method with the name this.pingMethod is added which simply returns true as fast as possible.
Kind: instance property of JSONBird
booleanAre we currently sending pings to our peer?
In other words, has this.startPinging() been called?
Kind: instance property of JSONBird
stringThe method name used when receiving or sending pings.
Kind: instance property of JSONBird
numberThe 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
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 |
numberThe maximum amount of time (in milliseconds) to wait for a ping method call to resolve.
Kind: instance property of JSONBird
Returns: number - milliseconds
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 |
string | numberGenerate a new id to be used for an outgoing request object
Kind: instance method of JSONBird
PromiseReturns 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
PromiseReturns 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
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 |
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 |
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 |
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 |
PromiseCall 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 | * |
functionReturns 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. |
PromiseExecute 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 | * |
functionReturns 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. |
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
Stop the periodic ping (if previously enabled by startPinging()).
Kind: instance method of JSONBird
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
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 |
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 |
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) |
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 |
ObjectConverts 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. |
booleanIs 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 | * |
booleanIs the given value for the JSON-RPC id property valid?
Kind: static method of JSONBird
| Param | Type |
|---|---|
| id | * |
booleanIs the given value for the JSON-RPC method property valid?
Kind: static method of JSONBird
| Param | Type |
|---|---|
| method | * |
booleanIs the given value for the JSON-RPC params property valid?
Kind: static method of JSONBird
| Param | Type |
|---|---|
| params | * |
booleanTest 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 |
FAQs
JSON-RPC 2.0 client/server/peer for any reliable transport. Inter-process communication. REST. WebSocket. WebWorker. Out of order messaging or in-order byte streams
The npm package jsonbird receives a total of 224 weekly downloads. As such, jsonbird popularity was classified as not popular.
We found that jsonbird demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.
Security News
GitHub is susceptible to a CDN flaw that allows attackers to host malware on any public repository.
Security News
At Node Congress, Socket CEO Feross Aboukhadijeh uncovers the darker aspects of open source, where applications that rely heavily on third-party dependencies can be exploited in supply chain attacks.