gentle_rpc

JSON-RPC 2.0 library with WebSockets and HTTP support for deno and the browser.

This library is accessible through the https://deno.land/x/ service or through https://nest.land/package/gentle_rpc.

Server

respond

Takes a req, methods and options. You can set options for an additional server argument or public error stacks. For WebSockets use the option {proto: "ws"}.

import { serve } from "https://deno.land/std@0.79.0/http/server.ts"
import { respond } from "https://deno.land/x/gentle_rpc/respond.ts"

const s = serve("0.0.0.0:8000")
console.log("listening on 0.0.0.0:8000")

const rpcMethods = {
  sayHello: (w: [string]) => `Hello ${w}`,
  callNamedParameters: ({ a, b, c }: { a: number; b: number; c: string }) =>
    `${c} ${a * b}`,
  animalsMakeNoise: (noise: [string]) =>
    noise.map((el) => el.toUpperCase()).join(" "),
}

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

Client

createRemote

Takes a resource for HTTP or a WebSocket for WebSockets and returns a TypeScript Proxy or Promise<Proxy> which we will call remote from now on.

import { createRemote } from "../../mod.ts"
// HTTP:
const remote = createRemote("http://0.0.0.0:8000")
// WebSocket:
const remote = await createRemote(new WebSocket("ws://0.0.0.0:8000"))

HTTP

remote

All remote methods take an Array<JsonValue> or Record<string, JsonValue> object and return Promise<JsonValue | undefined>.

const greeting = await remote.sayHello(["World"])
// Hello World

const namedParams = await remote.callNamedParameters({
  a: 5,
  b: 10,
  c: "result:",
})
// result: 50

notification

const notification = await remote.sayHello.notify(["World"]) // undefined

batch

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

batch with different methods

Takes either a batchObject or a batchArray as argument and returns a promise.

await remote.batch({
  cat: ["sayHello", ["miaaow"]],
  dog: ["animalsMakeNoise", ["wuuuufu"]],
  donkey: ["sayHello"],
  dragon: ["animalsMakeNoise", ["fiiiiire", "fiiiiire"]],
})
// { cat: "Hello miaaow", dog: "WUUUUFU", donkey: "Hello ", dragon: "FIIIIIRE FIIIIIRE" }

The example above uses the object keys cat, dog, donkey, dragon as RPC request object ids under the hood. The returned RPC result values will be assigned to these keys.

For other use cases you might prefer the following example:

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

WebSockets

createRemote

const remote = await createRemote(new WebSocket("ws://0.0.0.0:8000"))

remote

The remote proxy methods return a { generator: AsyncGenerator<JsonValue>, send: (params?: RpcParams) => void } object.

async function run(iter: AsyncGenerator<unknown>) {
  try {
    for await (let x of iter) {
      console.log(x)
    }
  } catch (err) {
    console.log(err.message, err.code)
  }
}

const greeting = remote.sayHello(["World"])
greeting.send(["second World"])

run(greeting.generator)
// Hello World
// Hello second World

setTimeout(() => remote.socket.close(), 100)

notification

const notification = remote.sayHello.notify(["World"])

messaging between multiple clients

Other clients can listen to the emitted messages by subscribing to the same method.

const greeting = remote.sayHello.subscribe()
greeting.emit(["first"])
greeting.emitBatch([["second"], ["third"]])
run(greeting.generator)
// Hello first
// Hello second
// Hello third

// You can optionally unsubscribe:
greeting.unsubscribe()

Examples and Tests

Checkout the examples and tests folders for more detailed examples.

Contribution

Every kind of contribution to this project is highly appreciated.
Please run deno fmt on the changed files before making a pull request.