jayson

Jayson

Jayson is a JSON-RPC 2.0 and 1.0 compliant server and client written in JavaScript for node.js that aims to be as simple as possible to use.

Table of contents

• Features
• Example
• Installation
• Changelog
• Requirements
• Class Documentation
• Running tests
• Typescript
• Usage
  • Client
    • Interface description
    • Browser usage
    • Notifications
    • Batches
    • Callback syntactic sugar
    • Events
  • Server
    • Interface description
    • Many interfaces at the same time
    • Using the server as a relay
    • Method routing
    • Method definition
    • Events
    • Errors
    • CORS
    • Context
• Revivers and replacers
• Named parameters
• Promises
  • Batches
  • Browser client
• FAQ
• Recommended usage
• Contributing

Features

• Servers that can listen to several interfaces at the same time
• Supports both HTTP and TCP client and server connections
• Server-side method routing
• Relaying of requests to other servers
• JSON reviving and replacing for transparent serialization of complex objects
• CLI client
• Promises
• Fully tested to comply with the official JSON-RPC 2.0 specification
• Also supports JSON-RPC 1.0

Example

A basic JSON-RPC 2.0 server via HTTP:

Server example in examples/simple_example/server.js:

const jayson = require('jayson');

// create a server
const server = new jayson.Server({
  add: function(args, callback) {
    callback(null, args[0] + args[1]);
  }
});

server.http().listen(3000);

Client example in examples/simple_example/client.js invoking add on the above server:

const jayson = require('jayson');

// create a client
const client = jayson.Client.http({
  port: 3000
});

// invoke "add"
client.request('add', [1, 1], function(err, response) {
  if(err) throw err;
  console.log(response.result); // 2
});

Installation

Install the latest version of jayson from npm by executing npm install jayson in your shell. Do a global install with npm install --global jayson if you want the jayson client CLI in your PATH.

Changelog (only notable milestones/changes)

• 4.1.0
  • New server option maxBatchLength
• 4.0.0
  • Remove lodash dependency which should halve bundle size. There might be minor incompatibilities if you pass funky object or array types to jayson methods.
• 3.6.4
  • Websocket client and server support
• 3.6.1
  • JSON-RPC 2.0 notifications no longer have id property unless overridden
• 3.3.3
  • Promise support for browser client
  • TypeScript declaration for promise browser client
  • TypeScript declaration for browser client
• 3.3.0
  • Remove URL parsing when passing a string option to the TLS and TCP client, string options are instead treated as an IPC path
• 3.0.0
  • Can pass a context object to handlers
  • Breaking: collect option removed from jayson.Server/Method. JSON-RPC params to handlers are now always in the first argument.
• 2.1.0
  • Experimental typescript support
• 2.0.6
  • Clarified how to use in the browser
• 2.0.0
  • Added support for promises
  • Breaking: collect: true is now the default option for a new jayson.Server and jayson.Method
• 1.2.0
  • Greatly improved server method definition
• 1.1.1
  • More http server events
  • Remove fork server and client
  • Add server routing
• 1.0.11 Add support for a HTTPS client
• 1.0.9 Add support for TCP servers and clients

CLI client

There is a basic CLI client in bin/jayson.js and it should be available as jayson in your shell if you installed the package globally. Run jayson --help to see how it works.

Requirements

Jayson does not have any special dependencies that cannot be resolved with a simple npm install or yarn install.

Class documentation

In addition to this document, a comprehensive class documentation made with jsdoc is available at jayson.tedeh.net.

Running tests

• Change directory to the repository root
• Install the development packages by executing npm install --dev
• Run the tests with npm run test
• Run the typescript tests with npm run test-tsc
• Run the coverage tests with npm run coverage

Typescript

Since v2.1.0 there is typescript support available with jayson.

If you encounter any problems with the type definitions, see the Contributing section.

Usage

Client

The client is available as the Client or client property of require('jayson').

Client interface description

Every client supports these options:

Client.http

Uses the same options as http.request in addition to these options:

| Option | Default | Type | Description | |------------ |------------ |---------- |---------------------------------------- | | encoding | utf8 | String | Determines the encoding to use | | headers | undefined | Object | Extend the headers sent by the client |

Client.http Events

The HTTP client will emit the following events:

| Event | When | Arguments | Notes | |----------------- |----------------------------------- |--------------------------------------------------------------------------- |------------------------------------------- | | http request | Created an HTTP request | 1. Instance of http.ClientRequest | | | http response | Received an HTTP response | 1. Instance of http.IncomingMessage 2. Instance of http.ClientRequest | | | http error | Underlying stream emits error | 1. Error | | | http timeout | Underlying stream emits timeout | | Automatically causes the request to abort |

It is possible to pass a string URL as the first argument. The URL will be run through url.parse. Example:

const jayson = require('jayson');
const client = jayson.Client.http('http://localhost:3000');
// client.options is now the result of url.parse

Client.https

Uses the same options as https.request in addition to the same options as Client.http. This means it is also possible to pass a string URL as the first argument and have it interpreted by url.parse.

Will emit the same custom events as Client.http.

Client.tcp

Uses the same options as net.connect.

Client.tcp Events

Since version 3.5.1

The TCP client will emit the following events:

Client.tls

Uses the same options as tls.connect.

Client.tls Events

Since version 3.5.1

The TLS client will emit the following events:

Client.browser

The browser client is a simplified version of the regular client for use browser-side. It does not have any dependencies on node.js core libraries, but does depend on the uuid package for generating request ids. It also does not know how to "send" a request to a server like th