WebSocket Link
On this page
wsLink is a terminating link that's used when using tRPC's WebSockets Client and Subscriptions, which you can learn more about here.
Usage
To use wsLink, you need to pass it a TRPCWebSocketClient, which you can create with createWSClient:
client/index.ts
import { function createTRPCClient<TRouter extends AnyRouter>(opts: CreateTRPCClientOptions<TRouter>): TRPCClient<TRouter>createTRPCClient, function createWSClient(opts: WebSocketClientOptions): WsClientcreateWSClient, function wsLink<TRouter extends AnyRouter>(opts: WebSocketLinkOptions<TRouter>): TRPCLink<TRouter>wsLink } from '@trpc/client';
import type { type AppRouter = Router<{
ctx: object;
meta: object;
errorShape: DefaultErrorShape;
transformer: false;
}, DecorateCreateRouterOptions<{}>> & DecorateCreateRouterOptions<{}>
AppRouter } from './server';
const const wsClient: WsClientwsClient = function createWSClient(opts: WebSocketClientOptions): WsClientcreateWSClient({
UrlOptionsWithConnectionParams.url: CallbackOrValue<string>url: 'ws://localhost:3000',
});
const const trpcClient: TRPCClient<BuiltRouter<{
ctx: object;
meta: object;
errorShape: DefaultErrorShape;
transformer: false;
}, DecorateCreateRouterOptions<{}>>>
trpcClient = createTRPCClient<BuiltRouter<{
ctx: object;
meta: object;
errorShape: DefaultErrorShape;
transformer: false;
}, DecorateCreateRouterOptions<{}>>>(opts: CreateTRPCClientOptions<BuiltRouter<{
ctx: object;
meta: object;
errorShape: DefaultErrorShape;
transformer: false;
}, DecorateCreateRouterOptions<{}>>>): TRPCClient<BuiltRouter<{
ctx: object;
meta: object;
errorShape: DefaultErrorShape;
transformer: false;
}, DecorateCreateRouterOptions<...>>>
createTRPCClient<type AppRouter = Router<{
ctx: object;
meta: object;
errorShape: DefaultErrorShape;
transformer: false;
}, DecorateCreateRouterOptions<{}>> & DecorateCreateRouterOptions<{}>
AppRouter>({
links: TRPCLink<BuiltRouter<{
ctx: object;
meta: object;
errorShape: DefaultErrorShape;
transformer: false;
}, DecorateCreateRouterOptions<{}>>>[]
links: [wsLink<BuiltRouter<{
ctx: object;
meta: object;
errorShape: DefaultErrorShape;
transformer: false;
}, DecorateCreateRouterOptions<{}>>>(opts: WebSocketLinkOptions<BuiltRouter<{
ctx: object;
meta: object;
errorShape: DefaultErrorShape;
transformer: false;
}, DecorateCreateRouterOptions<{}>>>): TRPCLink<BuiltRouter<{
ctx: object;
meta: object;
errorShape: DefaultErrorShape;
transformer: false;
}, DecorateCreateRouterOptions<{}>>>
wsLink<type AppRouter = Router<{
ctx: object;
meta: object;
errorShape: DefaultErrorShape;
transformer: false;
}, DecorateCreateRouterOptions<{}>> & DecorateCreateRouterOptions<{}>
AppRouter>({ client: WsClientclient: const wsClient: WsClientwsClient })],
});Authentication / Connection params
wsLink / createWSClient Options
The wsLink function requires a TRPCWebSocketClient to be passed, which can be configured with the fields defined in WebSocketClientOptions:
export interface WebSocketLinkOptions {
WebSocketLinkOptions.client: anyclient: type TRPCWebSocketClient = anyTRPCWebSocketClient;
/**
* Data transformer
* @see https://trpc.io/docs/v11/data-transformers
**/
WebSocketLinkOptions.transformer?: anytransformer?: type DataTransformerOptions = anyDataTransformerOptions;
}
declare function function createWSClient(opts: WebSocketClientOptions): TRPCWebSocketClientcreateWSClient(opts: WebSocketClientOptionsopts: WebSocketClientOptions): type TRPCWebSocketClient = anyTRPCWebSocketClient;
export interface WebSocketClientOptions {
/**
* The URL to connect to (can be a function that returns a URL)
*/
WebSocketClientOptions.url: string | (() => MaybePromise<string>)url: string | (() => type MaybePromise<T> = T | Promise<T>MaybePromise<string>);
/**
* Connection params that are available in `createContext()`
* These are sent as the first message
*/
WebSocketClientOptions.connectionParams?: Record<string, string> | (() => MaybePromise<Record<string, string> | null>) | null | undefinedconnectionParams?: type Record<K extends keyof any, T> = { [P in K]: T; }Record<string, string> | null | (() => type MaybePromise<T> = T | Promise<T>MaybePromise<type Record<K extends keyof any, T> = { [P in K]: T; }Record<string, string> | null>);
/**
* Ponyfill which WebSocket implementation to use
*/
WebSocketClientOptions.WebSocket?: {
new (url: string | URL, protocols?: string | string[]): WebSocket;
prototype: WebSocket;
readonly CONNECTING: 0;
readonly OPEN: 1;
readonly CLOSING: 2;
readonly CLOSED: 3;
} | undefined
WebSocket?: typeof var WebSocket: {
new (url: string | URL, protocols?: string | string[]): WebSocket;
prototype: WebSocket;
readonly CONNECTING: 0;
readonly OPEN: 1;
readonly CLOSING: 2;
readonly CLOSED: 3;
}
WebSocket;
/**
* The number of milliseconds before a reconnect is attempted.
* @default {@link exponentialBackoff}
*/
WebSocketClientOptions.retryDelayMs?: ((attemptIndex: number) => number) | undefinedretryDelayMs?: typeof function exponentialBackoff(attemptIndex: number): numberexponentialBackoff;
/**
* Triggered when a WebSocket connection is established
*/
WebSocketClientOptions.onOpen?: (() => void) | undefinedonOpen?: () => void;
/**
* Triggered when a WebSocket connection encounters an error
*/
WebSocketClientOptions.onError?: ((evt?: Event) => void) | undefinedonError?: (evt: Event | undefinedevt?: Event) => void;
/**
* Triggered when a WebSocket connection is closed
*/
WebSocketClientOptions.onClose?: ((cause?: {
code?: number;
}) => void) | undefined
onClose?: (cause: {
code?: number;
} | undefined
cause?: { code?: number | undefinedcode?: number }) => void;
/**
* Lazy mode will close the WebSocket automatically after a period of inactivity (no messages sent or received and no pending requests)
*/
WebSocketClientOptions.lazy?: {
enabled: boolean;
closeMs: number;
} | undefined
lazy?: {
/**
* Enable lazy mode
* @default false
*/
enabled: booleanenabled: boolean;
/**
* Close the WebSocket after this many milliseconds
* @default 0
*/
closeMs: numbercloseMs: number;
};
/**
* Send ping messages to the server and kill the connection if no pong message is returned
*/
WebSocketClientOptions.keepAlive?: {
enabled: boolean;
intervalMs?: number;
pongTimeoutMs?: number;
} | undefined
keepAlive?: {
/**
* @default false
*/
enabled: booleanenabled: boolean;
/**
* Send a ping message every this many milliseconds
* @default 5_000
*/
intervalMs?: number | undefinedintervalMs?: number;
/**
* Close the WebSocket after this many milliseconds if the server does not respond
* @default 1_000
*/
pongTimeoutMs?: number | undefinedpongTimeoutMs?: number;
};
/**
* Custom encoder for wire encoding (e.g. custom binary formats)
* @default jsonEncoder
*/
WebSocketClientOptions.experimental_encoder?: anyexperimental_encoder?: type Encoder = anyEncoder;
}Reference
You can check out the source code for this link on GitHub.