Skip to main content

@rtorcato/cf-common

Interfaces​

AcceptWebSocketOptions​

Defined in: index.ts:13

Options for acceptWebSocket.

Type Parameters​

A​

A

Properties​

tags?​

optional tags?: string[]

Defined in: index.ts:15

Tags for ctx.getWebSockets(tag) (at most 10, each at most 256 characters).

attachment?​

optional attachment?: A

Defined in: index.ts:17

Per-socket state that survives hibernation. Read it back with getAttachment.


BroadcastOptions​

Defined in: index.ts:101

Options for broadcast.

Properties​

tag?​

optional tag?: string

Defined in: index.ts:103

Only send to sockets accepted with this tag.

except?​

optional except?: WebSocket

Defined in: index.ts:105

Skip this socket, typically the sender.

Functions​

acceptWebSocket()​

acceptWebSocket<A>(request, ctx, options?): Response

Defined in: index.ts:31

Accept a WebSocket upgrade on a Durable Object with the hibernation API and return the 101 response for its fetch handler. A request without an Upgrade: websocket header throws an exposed 426 with code WS_UPGRADE_REQUIRED.

Example​

async fetch(request: Request) {
return acceptWebSocket(request, this.ctx, { tags: ['lobby'], attachment: { name: 'ada' } })
}

Type Parameters​

A​

A = unknown

Parameters​

request​

Request

ctx​

DurableObjectState

options?​

AcceptWebSocketOptions<A> = {}

Returns​

Response


getAttachment()​

getAttachment<A>(ws): A | null

Defined in: index.ts:52

Read a socket's attachment, typed as A, or null if none was set. The type is asserted, not validated.

Type Parameters​

A​

A

Parameters​

ws​

WebSocket

Returns​

A | null


setAttachment()​

setAttachment<A>(ws, attachment): void

Defined in: index.ts:60

Replace a socket's attachment. It is stored with structured clone, and the runtime caps its serialized size (it throws past that), so keep it small.

Type Parameters​

A​

A

Parameters​

ws​

WebSocket

attachment​

A

Returns​

void


parseMessage()​

parseMessage<T>(message, schema): T

Defined in: index.ts:76

Parse a webSocketMessage payload as JSON and validate it with schema (any object with parse(input): T, such as a Zod schema). Binary messages are decoded as UTF-8 first. Malformed JSON or a failed parse throws an exposed 400 with code WS_INVALID_MESSAGE; the handler isn't wrapped by defineFetch, so catch it and reply or close the socket yourself.

Example​

async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
const msg = parseMessage(message, ChatMessage)
}

Type Parameters​

T​

T

Parameters​

message​

string | ArrayBuffer

schema​

SchemaLike<T>

Returns​

T


sendMessage()​

sendMessage<T>(ws, data): void

Defined in: index.ts:96

Send data to one socket as a JSON text message.

Type Parameters​

T​

T

Parameters​

ws​

WebSocket

data​

T

Returns​

void


broadcast()​

broadcast<T>(ctx, data, options?): number

Defined in: index.ts:116

Send data as JSON to every socket the Durable Object has accepted (or only those with tag). The payload is serialized once. A socket that throws on send (already closing) is skipped. Returns how many sockets it was sent to.

Example​

broadcast(this.ctx, { type: 'joined', name }, { tag: 'lobby', except: ws })

Type Parameters​

T​

T

Parameters​

ctx​

DurableObjectState

data​

T

options?​

BroadcastOptions = {}

Returns​

number