API Reference – pluv.io

Returns a PluvIO instance.

Creates a server-side PluvIO client that will create rooms to register your websockets to. Below will show a available configurations for createIO. To learn more about createIO, read Authorization, Cloudflare Workers, Node.js and PubSub.

1import { createIO } from "@pluv/io";
2import { platformNode } from "@pluv/platform-node";
3import { z } from "zod";
4import { db } from "./db";
5
6const io = createIO({
7    // Optional: if provided, defines authorization for rooms created by io
8    authorize: {
9        // If required is false, users can authenticate for a room to
10        // attach an identity to their presence. Otherwise they will be
11        // anonymous.
12        required: true,
13        // The secret for generating your JWT
14        secret: process.env.PLUV_AUTH_SECRET!,
15        // The shape of your user object. `id` must always be required.
16        user: z.object({
17            id: z.string(),
18            // Here is an additional field we wish to add.
19            name: z.string(),
20        }),
21    },
22    // Optional. Only needed to load persisted storage for rooms.
23    // Load storage for a newly created room.
24    initialStorage: async (room: string) => {
25        const existingRoom = await db.room.findUnique({ where: { room } });
26
27        return existingRoom?.encodedState ?? null;
28    },
29    // Enable @pluv/io for Node.js
30    platform: platformNode(),
31    // Optional. Only needed for persisting storage for rooms.
32    // Before the room is destroyed, persist the state to a database
33    // to load when the room is re-created.
34    onRoomDeleted: async (room: string, encodedState: string) => {
35        await db.room.upsert({
36            where: { room },
37            create: { encodedState, room },
38            update: { encodedState },
39        });
40    },
41    // It is unnecessary to save the storage state in this listener.
42    // If a room already exists, users will load the currently active
43    // storage before the storage from initialStorage.
44    onStorageUpdated: (room: string, encodedState: string) => {
45        console.log(room, encodedState);
46    },
47});

This is the client returned by createIO.

Returns Promise<string>.

Creates a JWT for a user trying to connect to a room. This should be called within a custom authentication endpoint you define. See Authorization for more information.

1const token = await io.createToken({
2    room: "my-example-room",
3    user: {
4        id: "abc123",
5        name: "leedavidcs",
6    },
7});

Returns PluvIO.

Adds a new type-safe event to be broadcasted from PluvClient. See Define Events for more information.

1import { createIO } from "@pluv/io";
2import { platformNode } from "@pluv/platform-node";
3import { z } from "zod";
4
5const io = createIO({ platform: platformNode() })
6    // When event "SEND_MESSAGE" is sent by the frontend and received
7    // on the server
8    .event("SEND_MESSAGE", {
9        // Define a zod validation schema for the input
10        input: z.object({
11            message: z.string(),
12        }),
13        // Emit a "MESSAGE_RECEIVED" from the server to the client
14        resolver: ({ message }) => ({ MESSAGE_RECEIVED: { message } }),
15    })
16    .event("EMIT_EMOJI", {
17        input: z.object({
18            emojiCode: z.number(),
19        }),
20        resolver: ({ emojiCode }) => ({ EMOJI_RECEIVED: { emojiCode } }),
21    });

Returns IORoom.

Retrieves a room by room name if it already exists. If the room doesn't already exist, the room is created and returned.

1const room = io.getRoom("my-example-room");

This is the room returned by PluvIO.getRoom. This is what websockets are registered to.

Returns void.

Broadcasts an event to all connected websockets to the room.

1room.broadcast("EMIT_EMOJI", {
2    emojiCode: 123,
3});

Type of string.

This is the id of the room, when the room was created.

1const roomId = room.id;

Returns Promise<void>.

Registers a websocket to the room. Accepts a secondary options parameter to pass-in a token for authorizing the room. Read Cloudflare Workers, Node.js and Authorization to learn more.

1// const token: string = ...
2
3room.register(webSocket, { token })