# json-rpc-peer

> JSON-RPC 2 transport-agnostic library

Latest version **0.17.0** (published 2020-11-06) · ISC license · 0 weekly downloads

## Install

```sh
npm install json-rpc-peer
pnpm add json-rpc-peer
yarn add json-rpc-peer
bun add json-rpc-peer
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.17.0 |
| Published | 2020-11-06 |
| First published | 2015-06-05 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=4 |
| Dependencies | 3 |
| Unpacked size | 25.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 13 |
| Author | Julien Fontanet |
| Maintainers | julien-f, marsaud |
| Keywords | json, json-rpc, jsonrpc, jsonrpc2, rpc |

## Links

- npm: https://www.npmjs.com/package/json-rpc-peer
- Repository: https://github.com/JsCommunity/json-rpc-peer
- Issues: https://github.com/JsCommunity/json-rpc-peer/issues
- npm.io page: https://npm.io/package/json-rpc-peer

## Dependencies (3)

- [lodash](https://npm.io/package/lodash.md) ^4.17.4
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.3.4
- [json-rpc-protocol](https://npm.io/package/json-rpc-protocol.md) ^0.13.1

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.17.0 (latest) — 2020-11-06
- 0.16.0 — 2020-06-30
- 0.15.5 — 2018-08-10
- 0.15.4 — 2018-08-10
- 0.15.3 — 2018-02-07
- 0.15.2 — 2018-01-09
- 0.15.1 — 2018-01-08
- 0.15.0 — 2017-12-18
- 0.14.0 — 2017-05-24
- 0.13.2 — 2017-05-24
- 0.13.1 — 2016-11-07
- 0.13.0 — 2016-11-07
- 0.12.1 — 2016-11-07
- 0.12.0 — 2016-08-25
- 0.11.0 — 2015-10-20
- … 3 more at https://npm.io/package/json-rpc-peer/versions

## README

# json-rpc-peer [![Build Status](https://travis-ci.org/JsCommunity/json-rpc-peer.png?branch=master)](https://travis-ci.org/JsCommunity/json-rpc-peer)

> JSON-RPC 2 transport-agnostic library

## Install

Installation of the [npm package](https://npmjs.org/package/json-rpc-peer):

```
> npm install --save json-rpc-peer
```

## Usage

This library provides a high-level peer implementation which should
be flexible enough to use in any environments.

```javascript
// ES5
var Peer = require("json-rpc-peer")["default"];

// ES6
import Peer from "json-rpc-peer";
```

### Construction

```javascript
var peer = new Peer(function onMessage(message) {
  // Here is the main handler where every incoming
  // notification/request message goes.
  //
  // For a request, this function just has to throw an exception or
  // return a value to send the related response.
  //
  // If the response is asynchronous, just return a promise.
});
```

> The `onMessage` parameter is optional, it can be omitted if this
> peer does not handle notifications and requests.

> Note: For security concerns, only exceptions which are instance of
> `JsonRpcError` will be transmitted to the remote peer, all others
> will be substituted by an instance of `UnknownError`.

### Connection

> The peer is now almost ready, but before being usable, it has to be
> connected to the transport layer.

The simplest interface, the `exec()` method, has some limitations (no
notifications support) but is often good enough.

It is often used with non-connected protocols such as HTTP:

```javascript
var readAllStream = require("read-all-stream");

// For this example we create an HTTP server:
require("http").createServer(
  {
    port: 8081,
  },
  function onRequest(req, res) {
    // Read the whole request body.
    readAllStream(req, function(err, message) {
      // Error handling would be better.
      if (err) return;

      // Here `peer` is not used as a stream, it can therefore be used
      // to handle all the connections.
      peer.exec(message).then(function(response) {
        res.end(response);
      });
    });
  }
);
```

If you have a connected transport, such as WebSocket, you may want to
use the stream interface: the peer is a duplex stream and can
therefore be connected to other streams via the `pipe()` method:

```javascript
// For this example, we create a WebSocket server:
require("websocket-stream").createServer(
  {
    port: 8080,
  },
  function onConnection(stream) {
    // Because a stream can only be used once, it is necessary to create
    // a dedicated peer per connection.
    stream.pipe(new Peer(onMessage)).pipe(stream);
  }
);
```

### Notification

```javascript
peer.notify("foo", ["bar"]);
```

### Request

The `request()` method returns a promise which will be resolved or
rejected when the response will be received.

```javascript
peer
  .request("add", [1, 2])
  .then(function(result) {
    console.log(result);
  })
  .catch(function(error) {
    console.error(error.message);
  });
```

### Failure

Sometimes it is known that current pending requests will not get
answered (e.g. connection lost), it is therefore necessary to fail
them manually.

```javascript
peer.request("add", [1, 2]).catch(function(reason) {
  console.error(reason);
  // → connection lost
});

peer.failPendingRequests("connection lost");
```

### Low level interface

> `json-rpc-peer` also exports everything from [`json-rpc-protocol`](https://www.npmjs.com/package/json-rpc-protocol).

```js
// ES5
var peer = require("json-rpc-peer");

var format = peer.format;
var parse = peer.parse;
var JsonRpcError = peer.JsonRpcError;
var InvalidJson = peer.InvalidJson;
var InvalidRequest = peer.InvalidRequest;
var MethodNotFound = peer.MethodNotFound;
var InvalidParameters = peer.InvalidParameters;

// ES2015 (formerly known as ES6)
import {
  format,
  parse,
  JsonRpcError,
  InvalidJson,
  InvalidRequest,
  MethodNotFound,
  InvalidParameters,
} from "json-rpc-peer";
```

## Development

```
# Install dependencies
> yarn

# Run the tests
> yarn test

# Continuously compile
> yarn dev

# Continuously run the tests
> yarn dev-test

# Build for production
> yarn build
```

## Contributions

Contributions are _very_ welcomed, either on the documentation or on
the code.

You may:

- report any [issue](https://github.com/JsCommunity/json-rpc-peer/issues)
  you've encountered;
- fork and create a pull request.

## License

ISC © [Julien Fontanet](https://julien.isonoe.net)

---
_Source: https://npm.io/package/json-rpc-peer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._