jsonrpc-ts-client

Warning: this is in alpha.

A modern isomorphic typescript client for JSON-RPC 2.0. The goal of this project is to provide maximum ergonomics for typescript projects (autocomplete all the things!). This app could be used standalone, or as a dependency for an OpenRPC TS SDK generator.

Check out the Open RPC Ecosystem for more tools.

Feature Table

Feature	Supported
Isomorphism	✅
Batch Support	✅
Contract Support	Experimental

Installation

npm install jsonrpc-ts-client --save

or

yarn add jsonrpc-ts-client

Basic Usage

import JSONRPC from 'jsonrpc-ts-client'

interface UserDto { // ideally, these are generated from your JSON Schema.
  name: string,
  occupation: string,
}

const client = new JSONRPC({
  url: 'https://foo.com/jsonrpc'
})

const response = await client.exec<UserDto>('my_method', { userId: 123 }); // sends payload {jsonrpc: '2.0',  params: ...}
if (response.isSuccess()) { // returns an Either<JsonRpcError, Result>
  console.log(response.result.name)
  console.log(response.result.occupation)
} else if (response.isError()) {
  // more information on errors: https://www.jsonrpc.org/specification#error_object
  console.log(result.error.message) // e.g. "Invalid Params"
  console.log(result.error.code) // e.g -32603
}

// as an "escape valve", you can unwrap the result response by throwing an error.
const result = response.unsafeCoerce()
console.log(result.name)

ID Generation

Generate IDs automatically, and/or override or set them on a per-request basis.

import JSONRPC from 'jsonrpc-ts-client'
import uuid from 'uuid'

const client = new JSONRPC({
  ...
  idGeneratorFn: uuid.v4,
})

// Override generate IDs
const response = await client.exec<UserDto>('my_method', { userId: 123 }, 'MY_OVERRIDING_ID'); // sends payload {jsonrpc: '2.0', id: 'MY_OVERRIDING_ID',  params: ...}

Batch Support

You can make batch requests per the JSON-RPC specification.

import JSONRPC from 'jsonrpc-ts-client'

const client = new JSONRPC({
  url: 'https://foo.com/jsonrpc'
})

 const responses = await client.execBatch<[UserDto, ConfigDto]>([
    { method: "get_user",  params: { userId: 123 }, id: "foo" },
    { method: "get_config" },
  ]);

API Contract Declaration Support (experimental)

import JSONRPC from 'jsonrpc-ts-client'


type MyApiContract = {
  getUser: (params: UserParamsDto) => UserDto;
  getConfig: () => ConfigDto,
  getProduct: (productId: string) => ProductDto,
};

// pass in your api contract to get type-safety and autocomplete
const client = new JsonRpcClient<MyApiContract>({
  idGeneratorFn: uuid.v4,
  url: JSONRPC_URL,
});

const result = await client.exec("getUser", { userId: 123 }); // autocomplete!

if (result.isSuccess()) {
  console.log(result.user.name)
  console.log(result.user.id)
}