Changelog - 2026-02-11
WebSocket Generic Type Parameters
In one line. Type your WebSocket auth payload and client metadata once, and drop the as string casts in your callbacks.
What changed
- Typed server.
WebSocketServerHelper<AuthDataType, MetadataType>andIWebSocketServerOptions<AuthDataType, MetadataType>carry the generics into every callback. - Typed callbacks.
TWebSocketAuthenticateFn,TWebSocketHandshakeFn,TWebSocketClientConnectedFnandTWebSocketOutboundTransformeraccept the generic parameters. serverPublicKeyis its own field. The server's ECDH public key is nowIWebSocketClient.serverPublicKey, no longer stored insidemetadata.- Constrained metadata.
IWebSocketClient<MetadataType>andIWebSocketData<MetadataType>now requireMetadataType extends Record<string, unknown>, so something likeIWebSocketClient<string>no longer compiles.
Who is affected
- Existing code. No action needed; every generic defaults to
Record<string, unknown>. - Code that read
serverPublicKeyfromclient.metadata. Readclient.serverPublicKeyinstead.
Details
typescript
interface AuthPayload { token: string; publicKey?: string }
interface UserMetadata { role: string; permissions: string[] }
const helper = new WebSocketServerHelper<AuthPayload, UserMetadata>({
identifier: 'typed-ws',
server: bunServer,
redisConnection: redis,
authenticateFn: async (data) => {
// data is typed as AuthPayload
const user = await verifyJWT(data.token);
if (!user) return null;
return { userId: user.id, metadata: { role: user.role, permissions: user.permissions } };
},
clientConnectedFn: ({ metadata }) => {
// metadata is typed as UserMetadata | undefined
if (metadata?.role === 'admin') console.log(metadata.permissions);
},
});