WebSockets and HTTP Support for Deno and The Browser

WebSockets and HTTP Support for Deno and The Browser

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

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.

import { serve } from "https://deno.land/[email protected]/http/server.ts"
import { respond } from "https://deno.land/x/gentle_rpc/mod.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) {
  // HTTP:
  await respond(req, rpcMethods)
  // WebSockets:
  await respond(req, rpcMethods, { proto: "ws" })
}

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 "https://deno.land/x/gentle_rpc/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
auth

This method will set the Authorization header to Bearer ${jwt}.

const greeting = await remote.sayHello.auth(jwt)(["World"])
// Hello World
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

The support for WebSockets is still experimental and has not been fully tested yet.

remote

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

const noise = await remote.animalsMakeNoise(["wuufff"])
console.log(noise)

remote.socket.close()
notification
const notification = await remote.animalsMakeNoise.notify(["wuufff"])
messaging between multiple clients

By using the subscribe method you can send messages between multiple clients. It returns an object with a generator property { generator: AsyncGenerator<JsonValue>} and the methods emit, emitBatch and unsubscribe.

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

// First client
export 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.subscribe()
run(greeting.generator)
greeting.emit(["first"])
// Hello first
// Hello second
// Hello third
// Second client
const greeting = remote.sayHello.subscribe()
run(greeting.generator)
greeting.emitBatch([["second"], ["third"]])
// 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.

Download Details:

Author: timonson

Source Code: https://github.com/timonson/gentle_rpc

deno nodejs node javascript

Bootstrap 5 Complete Course with Examples

Bootstrap 5 Tutorial - Bootstrap 5 Crash Course for Beginners

Nest.JS Tutorial for Beginners

Hello Vue 3: A First Look at Vue 3 and the Composition API

Building a simple Applications with Vue 3

Deno Crash Course: Explore Deno and Create a full REST API with Deno

How to Build a Real-time Chat App with Deno and WebSockets

Convert HTML to Markdown Online

HTML entity encoder decoder Online

AEM Querybuilder for JavaScript (Browser, Node, Deno)

Helix Querybuilder .AEM Querybuilder for JavaScript (Browser, Node, Deno)

NKeys for JavaScript - Node.js, Browsers, and Deno

A public-key signature system based on Ed25519 for the NATS ecosystem system for JavaScript. The nkeys.js library works in Deno, Node.js, and the browser!

Javascript module for easily generating mazes,compatible with both Deno and Node

A work-in-progress Javascript maze generator module, compatible with both Deno and Node.

Deno Tutorial for Beginners: Deno vs. Node: Better Than NodeJS?

Deno is released, it’s time to find out if it can prove a worthy competition for Node.js. What is Deno? Why Deno can be considered an alternative to Node? The main differences between Deno and Node. Write a simple Deno app.

What is Deno? The Node.JS Killer? The Deno-minator to Node?

What is Deno? The Node.JS Killer? The Deno-minator to Node? Deno is the new hype and will it be better than node.js? Deno is a secure runtime for JavaScript and TypeScript that is based on the V8 JavaScript engine and the Rust programming language that addresses Node’s shortcomings