Skip to main content
Deno 2 is finally here 🎉️
Learn more

gentleRpc

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

Features

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

Example

Server/deno side

import { serve, ServerRequest } from "https://deno.land/std/http/server.ts"
import { respondRpc } from "https://cdn.jsdelivr.net/gh/timonson/gentleRpc@latest/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) {
  const result = await respondRpc(req, rpcMethods)
  console.log(result)
}

Client/remote side

import { createRemote } from "https://cdn.jsdelivr.net/gh/timonson/gentleRpc@latest/rpcClient.ts"
const remote = createRemote("http://0.0.0.0:8000")
const greeting = await remote.sayHello("World") // Hello World

API

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).

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: false
  • callMethodsWithRequestObj: boolean if true the request object will be added the first argument to the method call.

remote.method(arguments)

Each method call of the remote object will look for the identically named method on the server side, where the methods have been defined. It is based on the native JavaScript Proxy object.

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

await remote.sayHello("World")

Any number of arguments to the method calls is possible.

remote.batch(object)

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:

const noise1 = await remote.batch([
  ["animalsMakeNoise", "miaaow"],
  ["animalsMakeNoise", "wuuuufu"],
  ["animalsMakeNoise", "iaaaiaia"],
  ["animalsMakeNoise", "fiiiiire"],
])

The second example uses the object keys, like cat, dog, donkey, dragon, as RPC Request Object IDs under the hood and reassigns the final results to them. The result might look like this:

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

Checkout the examples and tests folders for more detailed examples.