gentleRpc

JSON-RPC 2.0 TypeScript library for deno and the browser.

This library is accessible through the https://deno.land/x/ service.

Features

• Complies with the JSON-RPC 2.0 specification
• Transfers data over the fetch API
• Uses TypeScript native proxies for a simple API on the client side

Example

Server/deno side

import { serve, ServerRequest } from "https://deno.land/std/http/server.ts"
import { respondRpc } from "https://deno.land/x/gentleRpc/rpcServer.ts"

const s = serve("0.0.0.0:8000")
const rpcMethods = {
  sayHello: (w: string) => `Hello ${w}`,
  animalsMakeNoise: (noise: string) => noise.toUpperCase(),
}

for await (const req of s) {
  await respondRpc(req, rpcMethods)
}

Client/remote side

import { createRemote } from "https://deno.land/x/gentleRpc/rpcClient.ts"

const remote = createRemote("http://0.0.0.0:8000")
const greeting = await remote.sayHello("World") // Hello World

API

Server

respondRpc(request, methods, { includeServerErrorStack, callMethodsWithRequestObj })

• request: ServerRequest
• methods: { [method: string]: (...args: any[]) => any }
• includeServerErrorStack: boolean detemines if the client’s error objects may contain the server’s error stack. Default is false.
• callMethodsWithRequestObj: boolean if true the request object will be added as the first argument to the method call. Default is false.

Client

createRemote(url, options, handleUnsuccessfulResponse)

• url: string fetch data from
• options: object this object will be merged into default options for fetch with exception of the two additional and optional properties notification: boolean and id: string | number.
  • notification causes the server to make an empty response
  • id sets an custom id
• handleUnsuccessfulResponse: (response: object => any) this optional callback is called, with the returned response object as argument, if fetch was not successful (status code outside the range 200-299).

remote.method(values)

Each method call of the remote object will look for the identically named method on the server side, where the methods are defined. This API is based on the native JS/TS Proxy object.

The methods return the result or error property of the RPC response object as promise.

Any number of arguments to the method calls is possible.

await remote.sayHello("World") // Hello World

Batch Requests

Additionally, to send several request objects at the same time, the client may send an array filled with request objects. You can do this on two different ways:

1. remote.batch([[“method1”, [“arg1”, “arg2”]], [“method2”, [“arg1”, “arg2”]]])

const noise1 = await remote.batch([
  ["animalsMakeNoise", ["miaaow"]],
  ["animalsMakeNoise", ["wuuuufu"]],
  ["animalsMakeNoise", ["iaaaiaia"]],
  ["animalsMakeNoise", ["fiiiiire"]],
])
// [ "MIAAOW", "WUUUUFU", "IAAAIAIA", "FIIIIIRE" ]

1. remote.batch({key1: [“method1”, [“arg1”, “arg2”]], key2: [“method1”, [“arg1”, “arg2”]]})

The way of making batch requests uses the object keys (cat, dog, donkey, dragon) as RPC request object ids under the hood. The returned result values will be assigned to these key. Let’s take a look at the following example:

const noise2 = await remote.batch({
  cat: ["animalsMakeNoise", ["miaaow"]],
  dog: ["animalsMakeNoise", ["wuuuufu"]],
  donkey: ["animalsMakeNoise", ["iaaaiaia"]],
  dragon: ["animalsMakeNoise", ["fiiiiire"]],
})
// { cat: "MIAAOW", dog: "WUUUUFU", donkey: "IAAAIAIA", dragon: "FIIIIIRE" }

Examples and Tests

Checkout the examples and tests folders for more detailed examples.