defineWebSocket (@defjs/core)

@defjs/core · Function

Signature

function defineWebSocket<
  const P extends string,
  TInput extends AnyStruct | undefined = undefined,
  TIncoming extends AnyStruct = AnyStruct,
  TOutgoing extends AnyStruct | undefined = undefined,
>(
  definition: Omit<WebSocketDefinitionBase<TIncoming, TOutgoing>, "path"> & {
    input?: TInput;
    path: P;
  } & BuilderField<NoInfer<TInput>, WebSocketRequestShape<NoInfer<P>>>,
): WebSocketEndpoint<
  EndpointArgs<TInput>,
  WebSocketIncomingData<TIncoming>,
  WebSocketOutgoingData<TOutgoing>
>;

Pass path, incoming (and optional outgoing) message structs, and queue limits. Call the returned operation with a client and, when declared, the input.

definition — path, one incoming struct, and the required maxIncomingQueueSize (a positive safe integer). Optional outgoing and input structs, static protocols, maxOutgoingQueueSize (a non-negative safe integer), and operation. A declared input always requires an explicit builder. input only defines the parameters; the builder alone decides where each value goes. Only definitions without input may omit builder.

A WebSocket builder may return path and query only; headers and body are rejected. WebSocketDefinitionBase and BuilderField are internal helper types.

Parameters

Prop

Type

definition

Omit<WebSocketDefinitionBase<TIncoming, TOutgoing>, "path"> & { input?: TInput; path: P; } & { builder?: (() => WebSocketRequestShape<P>) | undefined; }

WebSocket contract (path, structs, queue limits, optional input).

Returns

An operation (client, ...input) => Promise<error-first tuple>.

Examples

import { defineWebSocket, struct } from "@defjs/core";

const chat = defineWebSocket({
  maxIncomingQueueSize: 100,
  path: "/chat",
  protocols: ["chat.v1"],
  incoming: struct.object({
    text: struct.string(),
    type: struct.literal("message"),
  }),
  outgoing: struct.object({
    text: struct.string(),
    type: struct.literal("message"),
  }),
});