# json-rpc-protocol

> JSON-RPC 2 protocol messages parsing and formatting

Latest version **0.13.2** (published 2022-02-09) · ISC license · 0 weekly downloads

## Install

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

## Health

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

Positive: has types; no vulnerabilities; high quality score.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.13.2 |
| Published | 2022-02-09 |
| First published | 2015-06-04 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=4 |
| Dependencies | 1 |
| Unpacked size | 50.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 16 |
| Author | Julien Fontanet |
| Maintainers | julien-f, marsaud, pdonias |
| Keywords | json, json-rpc, jsonrpc, jsonrpc2, rpc |

## Links

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

## Dependencies (1)

- [make-error](https://npm.io/package/make-error.md) ^1.3.0

## 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.13.2 (latest) — 2022-02-09
- 0.13.1 — 2018-10-26
- 0.13.0 — 2018-10-24
- 0.12.0 — 2018-06-17
- 0.11.4 — 2018-05-10
- 0.11.3 — 2017-05-24
- 0.11.2 — 2016-11-07
- 0.11.1 — 2016-11-07
- 0.11.0 — 2016-08-25
- 0.10.0 — 2015-06-25
- 0.9.0 — 2015-06-04

## README

# json-rpc-protocol [![Build Status](https://travis-ci.org/JsCommunity/json-rpc-protocol.png?branch=master)](https://travis-ci.org/JsCommunity/json-rpc-protocol) [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-blue.svg)](https://www.typescriptlang.org/)

> JSON-RPC 2 protocol messages parsing and formatting

## Install

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

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

## Usage

### Errors

```javascript
// ES5
var protocol = require('json-rpc-protocol')

var JsonRpcError = protocol.JsonRpcError
var InvalidJson = protocol.InvalidJson
var InvalidRequest = protocol.InvalidRequest
var MethodNotFound = protocol.MethodNotFound
var InvalidParameters = protocol.InvalidParameters

// ES6
import {
  JsonRpcError,
  InvalidJson,
  InvalidRequest,
  MethodNotFound,
  InvalidParameters
} from 'json-rpc-protocol'
```

This is the base error for all JSON-RPC errors:

```javascript
throw new JsonRpcError(message, code)
```

The JSON-RPC 2 specification defined also the following specialized
errors:

```javascript
// Parse error: invalid JSON was received by the peer.
throw new InvalidJson()

// Invalid request: the JSON sent is not a valid JSON-RPC 2 message.
throw new InvalidRequest()

// Method not found: the method does not exist or is not available.
throw new MethodNotFound(methodName)

// Invalid parameters.
throw new InvalidParameters(data)
```

Custom errors can of course be created, they just have to inherit
`JsonRpcError`:

```javascript
// ES5
function MyError () {
  JsonRpcError.call(this, 'my error', 1)
}
MyError.prototype = Object.create(JsonRpcError.prototype, {
  constructor: {
    value: MyError
  }
})

// ES6
class MyError extends JsonRpcError {
  constructor () {
    super('my error', 1)
  }
}
```

### Parsing

```javascript
// ES5
var parse = require('json-rpc-protocol').parse

// ES6
import {parse} from 'json-rpc-protocol'
```

The `parse()` function parses, normalizes and validates JSON-RPC 1 or
JSON-RPC 2 messages.

These message can be either JS objects or JSON strings (they will be
parsed automatically).

This function may throws:

- `InvalidJson`: if the string cannot be parsed as a JSON;
- `InvalidRequest`: if the message is not a valid JSON-RPC message.

```javascript
parse('{"jsonrpc":"2.0", "method": "foo", "params": ["bar"]}')
// → {
//   [type: 'notification']
//   jsonrpc: '2.0',
//   method: 'foo',
//   params: ['bar']
// }

parse('{"jsonrpc":"2.0", "id": 0, "method": "add", "params": [1, 2]}')
// → {
//   [type: 'request']
//   jsonrpc: '2.0',
//   id: 0,
//   method: 'add',
//   params: [1, 2]
// }

parse('{"jsonrpc":"2.0", "id": 0, "result": 3}')
// → {
//   [type: 'response']
//   jsonrpc: '2.0',
//   id: 0,
//   result: 3
// }
```

> A parsed message has a non enumerable property `type` set to easily
> differentiate between types of JSON-RPC messages.


#### Response/Error

The `parse.result` helper parses and returns the result of a response message or throws the error of an error message:

```js
try {
  const result = await parse.result(message)
  // do something with the result
} catch (error) {
  // deal with the failure
}
```

### Formatting

```javascript
// ES5
var format = require('json-rpc-protocol').format

// ES6
import {format} from 'json-rpc-protocol'
```

The `format.*()` functions can be used to create valid JSON-RPC
messages (as JavaScript strings).

#### Notification

```javascript
format.notification('foo', ['bars'])
// → {
//   "jsonrpc": "2.0",
//   "method": "foo",
//   "params": ["bar"]
// }
```

The last argument, the parameters of the notification, is optional and
defaults to `undefined`.

#### Request

The last argument, the parameters of the request, is optional and
defaults to `undefined`.

```javascript
format.request(0, 'add', [1, 2])
// → {
//   "jsonrpc": "2.0",
//   "id": 0,
//   "method": "add",
//   "params": [1, 2]
// }
```

#### Response

A successful response:

```javascript
format.response(0, 3)
// → {
//   "jsonrpc": "2.0",
//   "id": 0,
//   "result": 3
// }
```

A failed response:

```javascript
var MethodNotFound = require('json-rpc-protocol').MethodNotFound

format.error(0, new MethodNotFound('add'))
// → {
//   "jsonrpc": "2.0",
//   "id": 0,
//   "error": {
//     "code": -3601,
//     "message": "method not found: add",
//     "data": "add"
//   }
// }
```

Note: the error to format must implement a `toJsonRpcError` function which returns an object or it
will be automatically replaced by an unknown error for security
reasons.

`toJsonRpcError` example:

```js
toJsonRpcError () {
  return {
    code: 42, // must be an integer
    message: 'Hacking too much time!', // must be a string
    data: [ 'Hackerman' ] // optional
  }
}
```

## Development

```
# Install dependencies
> npm install

# Run the tests
> npm test

# Continuously compile
> npm run dev

# Continuously run the tests
> npm run dev-test

# Build for production (automatically called by npm install)
> npm run build
```

## Related

- [json-rpc-peer](https://github.com/JsCommunity/json-rpc-peer) − High level interface

## Contributions

Contributions are *very* welcomed, either on the documentation or on
the code.

You may:

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

## License

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

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