utrpc

Fullstack uwebsockets typesafety inspired by trpc. Made for Bun. Written in TS.

This is a work-in-progress - contributors welcome! Current code is not transpiled to js and usage via npm may require configuration.

Features:

• Full typescript safety for websocket events via trpc-esque interface
• Custom transformers to serialize your JSON data into binary transports
• Input and Output validation can be disabled for performance
• Make requests through an existing websocket connection
• Two-way communication allows server to call client for data
• Define data types via zod or pass a ts generic

Examples

server.ts

1import { z } from 'zod';
2import {
3  Io,
4  router,
5  method,
6} from '../server';
7
8class Message {
9  message: string;
10
11  constructor(message: string) {
12    this.message = message;
13  }
14};
15
16const appRouter = router({
17  ping: method()
18    .input(z.object({ id: z.number(), message: z.string() }))
19    .output(z.string())
20    .transfer(({ input }) => {
21      return `pong: ${input.id}: ${input.message}`;
22    }),
23  callClient: method()
24    .input(z.object({ id: z.number() }))
25    .output<{ id: number; message: string; }>()
26    .receiver(),
27  subscriptions: method()
28    .input<Message>()
29    .output<Message>()
30    .subscribe(({ input }) => {
31      console.log('lobby received message', input);
32    }),
33});
34
35export type AppRouter = typeof appRouter;
36
37const uws = Io({
38  router: appRouter,
39});
40
41const server = Bun.serve({
42  fetch: uws.fetch,
43  websocket: {
44    open: uws.open,
45    close: uws.close,
46    message: uws.message,
47  },
48});
49
50uws.start(server);
51
52// send a message to all subscribed to 'subscriptions'
53uws.router.subscriptions.send({ message: 'Goodbye World' });
54// send a message to all subscribed to room '123'
55uws.router.subscriptions.sendTo('123', { message: 'Goodbye World' });
56
57// call client id '123' passing the { id: 1 } object to get a result
58const result = await uws.router.callClient.pull('123', { id: 1 });
59console.log('callClient.pull', result); // { id: 1, message: 'Hello World' }

client.ts

1import { client } from 'utrpc/client';
2import type { AppRouter } from './server';
3
4const utrpc = client<AppRouter>({
5  ws: {
6    url: 'ws://localhost:1337',
7  },
8});
9
10// send the server a ping, expecting back a message 
11const result = await utrpc.ping.request({ id: 1, message: 'Hello World' });
12console.log(result); // `pong: 1: Hello World`
13
14// subscribe to callClient so we can send back message when the server calls
15utrpc.callClient.onRequest(async function({ id }) {
16  console.log('client', 'received request for client name', { id });
17  return { id, message: 'Hello World' };
18});
19
20// subscribe to all 'subscriptions' notifications
21utrpc.subscriptions.subscribe({
22  onData: data => console.log('subscriptions', data),
23  onError: err => console.error('subscriptions', err),
24});
25
26// subscribe to 'subscriptions' notifications for room '123'
27utrpc.subscriptions.subscribe({
28  to: '123',
29  onData: data => console.log('subscriptions:123', data),
30  onError: err => console.error('subscriptions:123', err),
31});
32
33// send a message to subscriptions
34trpc.subscriptions.send({ message: 'Hello World' });
35
36// send a message to subscriptions in room '123'
37trpc.subscriptions.sendTo('123', { message: 'Hello World' });
38
39// call utrpc() to get the top-level object to latch into lifecycle events
40const uws = utrpc();
41uws.lifecycle.on('message', (...args) => {
42  // log out every utrpc message that comes through the websocket 
43  console.log('message', ...args);
44});
45
46uws.lifecycle.on('open', () => {
47  // interact with the ws directly
48  // (utrpc will ignore these messages)
49  uws.ws.send('hello world');
50});