Skip to content

A better JSON-RPC 2.0 client for TypeScript projects.

License

Notifications You must be signed in to change notification settings

silesky/jsonrpc-ts-client

Repository files navigation

Build Status

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 SDK generator.

Warning: this project is in alpha, and the API is subject to change.

Check out the Open RPC Ecosystem for more tools.

Basic Example

Features

Feature Supported
Isomorphism
Batch Support
Contract Support
Websockets / Alt. Transport Future

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 JsonRpcYeah<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
}

API Contract Declaration Support

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 JSONRPC<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)
}

Batch Support [Experimental API]

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

Note: This API is still in flex and may change slightly in the future versions.

Basic Example

import JSONRPC from 'jsonrpc-ts-client'


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

const client = new JSONRPC<MyApiContract>({
  idGeneratorFn: uuid.v4,
  url: JSONRPC_URL,
});

const [user, config] = await client.execBatch([
      { method: "getUser", params: { userId: 123 } },
      { method: "getConfig" },
    ] as const
);

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

if (config.isSuccesss()) {
  console.log(config.foo)
}

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'

// automatically generate IDs on each request
const client = new JSONRPC({
  ...
  idGeneratorFn: uuid.v4,
})



// override your generated IDs at any time...
const response = await client.exec( 'my_method', { userId: 123 }, 'MY_OVERRIDING_ID');
// => {jsonrpc: '2.0', id: 'MY_OVERRIDING_ID',  params: { userId: 123 } }