pluv.io
DocsQuickstart
GitHubNpm

API Reference

createClient

Returns a PluvClient instance.

Create a frontend PluvClient that will create rooms to connect to your server's PluvIO instance.

createClient basic example

If you've created a basic PluvIO backend without any auth, you can create a PluvClient with your websocket connection endpoint.

1// frontend/io.ts
2

3import { createClient } from "@pluv/client";
4

5const client = createClient({
6    // Defaults to (room) => `/api/pluv/room/${room}`
7    // This is the default from `createPluvHandler`.
8    wsEndpoint: (room: string) => `/api/room?room=${room}`,
9});

createClient with fetch options

If you need to use a POST request or specify additional headers, you can return an object containing options for fetch.

1// frontend/io.ts
2

3import { createClient } from "@pluv/client";
4

5const client = createClient({
6    wsEndpoint: (room: string) => ({
7        url: "/api/room",
8        // specify fetch options here
9        options: {
10            method: "post",
11            body: JSON.stringify({ room }),
12        },
13    }),
14});

createClient with auth endpoint

If your PluvIO implements auth, you will need to specify an authEndpoint on your frontend client.

1import { createClient } from "@pluv/client";
2

3const client = createClient({
4    wsEndpoint: (room: string) => `/api/room?room=${room}`,
5    authEndpoint: (room: string) => `/api/room/auth?room=${room}`,
6});

PluvClient

This is the client returned by createClient.

PluvClient.createRoom

Returns a PluvRoom instance.

Create a PluvRoom that websockets can join and leave. The second argument is an optional configuration for presence and storage. See the example below for the available properties of the configuration.

1// frontend/room.ts
2import { y } from "@pluv/client";
3import { z } from "zod";
4import { client } from "./io.ts";
5

6const room = client.createRoom("my-example-room", {
7    // Define your presence schema
8    presence: z.object({
9        selectionId: z.nullable(z.string()),
10    }),
11    // Define the user's initial presence
12    initialPresence: {
13        selectionId: null,
14    },
15    // Define the initial storage for the room
16    initialStorage: () => ({
17        messages: y.array(["hello world!"]),
18    }),
19});

PluvClient.enter

Returns Promise<PluvRoom>.

Establishes a websocket connection with a room. If the PluvClient specifies an authEndpoint, the endpoint will be called when this function is called. Returns the PluvRoom that was entered.

Note: This method will fail if the room does not already exist beforehand.

1// frontend/room.ts
2import { client } from "./io.ts";
3

4const room = client.createRoom("my-example-room", {
5    // ...
6})
7

8// Enter room by room name
9client.enter("my-example-room").then(() => {
10    console.log("Connected to: my-example-room");
11});
12

13// Alternatively, you can pass the PluvRoom instance
14client.enter(room).then(() => {
15    console.log("Connected to: my-example-room");
16});

PluvClient.getRoom

Returns a PluvRoom instance or null if none is found.

1// frontend/room.ts
2

3import { client } from "./io.ts";
4

5const room = client.getRoom("my-example-room");

PluvClient.getRooms

Returns a PluvRoom array.

Retrieves all active rooms under the current PluvClient instance.

1// frontend/room.ts
2

3import { client } from "./io.ts";
4

5const rooms = client.getRooms();

PluvClient.leave

Returns void.

Disconnects from a PluvRoom and deletes the room on the PluvClient. If the room does not exist, nothing happens and the function returns immediately.

1// frontend/room.ts
2

3import { client } from "./io.ts";
4

5const room = client.createRoom("my-example-room", {
6    // ...
7})
8

9// Leave room by room name
10client.leave("my-example-room");
11

12// Alternatively, you can pass the PluvRoom instance
13client.leave(room);

PluvRoom

This is the room returned by PluvClient.createRoom.

PluvRoom.webSocket

Type of WebSocket | null.

This is the WebSocket that is created and attached to the room when connected to.

PluvRoom.broadcast

Returns void.

Broadcasts an event to all websockets connected to the room.

1// frontend/room.ts
2

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

PluvRoom.connect

Returns Promise<void>.

Connects to the room if not connected to already. If an authEndpoint is configured, this function will call your authEndpoint.

1// frontend/room.ts
2

3room.connect().then(() => {
4    console.log(`Connected to room: ${room.id}`);
5});

PluvRoom.disconnect

Returns void.

Disconnects from the room if already connected.

PluvRoom.event

Returns () => void.

Subscribes to an event. These events are defined by PluvIO.event and are emitted when other websockets emit events via PluvRoom.broadcast.

1// Subscribe to EMOJI_RECEIVED messages
2const unsubscribe = room.event("EMOJI_RECEIVED", ({ data }) => {
3    console.log(data);
4});
5

6// ...
7

8// Unsubscribe to the listener later on.
9unsubscribe();

PluvRoom.getConnection

Returns WebSocketConnection.

This returns state information for the current connection to this room.

1const connection = room.getConnection();

PluvRoom.getMyPresence

Returns TPresence | null.

Returns the user's current presence data.

1const myPresence = room.getMyPresence();

PluvRoom.getMyself

Returns UserInfo | null.

Returns a user info object containing data used when generating the JWT during authentication (see Authorization), the user's presence, and the user's connection id.

1const myself = room.getMyself();

PluvRoom.getOther

Returns UserInfo | null.

Returns a user info object for the given connectionId.

1// const connectionId = "some connection id of another connection"
2

3const other = room.getOther(connectionId);

PluvRoom.getOthers

Returns UserInfo[].

Returns all user info objects for connections that are not the current user's.

1const others = room.getOthers();

PluvRoom.getStorage

Returns a yjs shared type defined on the client config.

1// frontend/room.ts
2import { y } from "@pluv/client";
3import { z } from "zod";
4import { client } from "./io.ts";
5

6const room = client.createRoom("my-example-room", {
7    // Define your presence schema
8    presence: z.object({
9        selectionId: z.nullable(z.string()),
10    }),
11    // Define the user's initial presence
12    initialPresence: {
13        selectionId: null,
14    },
15    // Define the initial storage for the room
16    initialStorage: () => ({
17        messages: y.array(["hello world!"]),
18    }),
19});
20

21const messages = room.getStorage("messages");

PluvRoom.other

Returns () => void.

Subscribes to a given user info object for a connection that isn't the current user's.

1// const connectionId = "some connection id of another connection"
2

3const unsubscribe = room.other(connectionId, ({
4    connectionId,
5    presence,
6    user
7}) => {
8    console.log(connectionId, presence, user);
9});
10

11// ...
12

13// Unsubscribe to the listener later on.
14unsubscribe();

PluvRoom.storage

Returns () => void.

Subscribes to a given root-level value in the yjs document storage.

1// frontend/room.ts
2import { y } from "@pluv/client";
3import { z } from "zod";
4import { client } from "./io.ts";
5

6const room = client.createRoom("my-example-room", {
7    // Define your presence schema
8    presence: z.object({
9        selectionId: z.nullable(z.string()),
10    }),
11    // Define the user's initial presence
12    initialPresence: {
13        selectionId: null,
14    },
15    // Define the initial storage for the room
16    initialStorage: () => ({
17        messages: y.array(["hello world!"]),
18    }),
19});
20

21const unsubscribe = room.storage("messages", (messages) => {
22    console.log(messages);
23});
24

25// ...
26

27// Unsubscribe to the listener later on.
28unsubscribe();

PluvRoom.subscribe("connection")

Returns () => void.

Subscribes to the user's connection state.

1const unsubscribe = room.subscribe("connection", ({
2    // The user's authorization state: { token, user }
3    authorization,
4    // The user's connection state: { id, state }
5    connection,
6    // The user's websocket
7    webSocket,
8}) => {
9    console.log(authorization, connection, webSocket);
10});
11

12// ...
13

14// Unsubscribe to the listener later on.
15unsubscribe();

PluvRoom.subscribe("my-presence")

Returns () => void.

Subscribes to the user's presence state.

1const unsubscribe = room.subscribe("my-presence", (myPresence) => {
2    console.log(myPresence);
3});
4

5// ...
6

7// Unsubscribe to the listener later on.
8unsubscribe();

PluvRoom.subscribe("myself")

Returns () => void.

Subscribes to the user's info object.

1const unsubscribe = room.subscribe("myself", (myself) => {
2    console.log(myself);
3});
4

5// ...
6

7// Unsubscribe to the listener later on.
8unsubscribe();

PluvRoom.subscribe("others")

Returns () => void.

Subscribes to the list of user info objects of the other connections that aren't the user's.

1const unsubscribe = room.subscribe("others", (others) => {
2    console.log(others);
3});
4

5// ...
6

7// Unsubscribe to the listener later on.
8unsubscribe();