@wooksjs/event-ws 0.7.0

package/dist/index.d.ts

@@ -0,0 +1,335 @@
+import * as _wooksjs_event_core from '@wooksjs/event-core';
+import { EventContext, EventContextOptions } from '@wooksjs/event-core';
+export { EventContext, useLogger, useRouteParams } from '@wooksjs/event-core';
+import { TConsoleBase } from '@prostojs/logger';
+import http, { IncomingMessage, Server } from 'http';
+import { Duplex } from 'stream';
+import * as wooks from 'wooks';
+import { WooksAdapterBase, WooksUpgradeHandler, Wooks, TWooksHandler } from 'wooks';
+
+/**
+ * Returns the connection `EventContext` from either connection-level or message-level handlers.
+ * Mirrors `current()` from `@wooksjs/event-core`.
+ *
+ * - In `onConnect` / `onDisconnect`: returns `current()` directly.
+ * - In `onMessage`: returns `current().parent` (the connection context).
+ */
+declare function currentConnection(ctx?: EventContext): EventContext;
+/**
+ * Provides access to the current WebSocket connection (id, send, close).
+ * Works in both connection and message contexts via parent chain traversal.
+ */
+declare const useWsConnection: (ctx?: EventContext) => {
+    /** Unique connection ID. */
+    id: string;
+    /** Send a push message to this connection. */
+    send(event: string, path: string, data?: unknown, params?: Record<string, string>): void;
+    /** Close the connection. */
+    close(code?: number, reason?: string): void;
+    /** The connection EventContext (for advanced use). */
+    context: EventContext;
+};
+
+/**
+ * Provides access to the current WebSocket message data.
+ * Only available in message context (inside `onMessage` handlers).
+ */
+declare function useWsMessage<T = unknown>(ctx?: EventContext): WsMessageResult<T>;
+interface WsMessageResult<T> {
+    /** Parsed message data (typed via generic). */
+    data: T;
+    /** Raw message before parsing. */
+    raw: Buffer | string;
+    /** Correlation ID (undefined if fire-and-forget). */
+    id: string | number | undefined;
+    /** Message path. */
+    path: string;
+    /** Message event type. */
+    event: string;
+}
+
+interface WsBroadcastOptions {
+    /** Room to broadcast to. Default: current message path. */
+    room?: string;
+    /** Exclude the sender from the broadcast. Default: true. */
+    excludeSelf?: boolean;
+}
+/**
+ * Provides room management for the current connection.
+ * All methods default to the current message path as the room.
+ * Only available in message context (inside `onMessage` handlers).
+ */
+declare const useWsRooms: (ctx?: EventContext) => {
+    /** Join a room. Default: current message path. */
+    join(room?: string): void;
+    /** Leave a room. Default: current message path. */
+    leave(room?: string): void;
+    /** Broadcast to a room. Default room: current message path. */
+    broadcast(event: string, data?: unknown, options?: WsBroadcastOptions): void;
+    /** List rooms this connection has joined. */
+    rooms(): string[];
+};
+
+/** Client-to-server message. */
+interface WsClientMessage {
+    /** Event type — used as the router method (e.g. "message", "subscribe", "unsubscribe", "rpc"). */
+    event: string;
+    /** Route path (e.g. "/chat/rooms/lobby"). Always a concrete path, never a pattern. */
+    path: string;
+    /** Payload. */
+    data?: unknown;
+    /** Optional correlation ID. When present, the server sends a reply with the same ID. */
+    id?: string | number;
+}
+/** Server-to-client reply (sent only when client message included an `id`). */
+interface WsReplyMessage {
+    /** Correlation ID matching the client's request. */
+    id: string | number;
+    /** Response payload (handler return value). */
+    data?: unknown;
+    /** Error (mutually exclusive with data). */
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+/** Server-to-client push (broadcast, direct send, subscription notification). */
+interface WsPushMessage {
+    /** Event type. */
+    event: string;
+    /** The concrete path this message relates to. */
+    path: string;
+    /** Route params extracted from the path by the server router. */
+    params?: Record<string, string>;
+    /** Payload. */
+    data?: unknown;
+}
+/** Minimal WebSocket instance interface (compatible with ws, uWebSockets.js, Bun). */
+interface WsSocket {
+    send(data: string | Buffer): void;
+    close(code?: number, reason?: string): void;
+    on(event: 'message', handler: (data: Buffer | string) => void): void;
+    on(event: 'close', handler: (code: number, reason: Buffer) => void): void;
+    on(event: 'error', handler: (err: Error) => void): void;
+    on(event: 'pong', handler: () => void): void;
+    ping(): void;
+    readonly readyState: number;
+}
+/** WebSocket server instance (handles upgrades, tracks no connections itself). */
+interface WsServerInstance {
+    handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer, cb: (ws: WsSocket) => void): void;
+    close(): void;
+}
+/** Factory that creates a WebSocket server in noServer mode. */
+interface WsServerAdapter {
+    create(): WsServerInstance;
+}
+/** Pluggable transport for cross-instance broadcasting (e.g. Redis pub/sub). */
+interface WsBroadcastTransport {
+    /** Publish a message to a channel (other instances will receive it). */
+    publish(channel: string, payload: string): void | Promise<void>;
+    /** Subscribe to messages on a channel. */
+    subscribe(channel: string, handler: (payload: string) => void): void | Promise<void>;
+    /** Unsubscribe from a channel. */
+    unsubscribe(channel: string): void | Promise<void>;
+}
+interface TWooksWsOptions {
+    /** Heartbeat ping interval in ms (default: 30000). Set 0 to disable. */
+    heartbeatInterval?: number;
+    /** Heartbeat pong timeout in ms (default: 5000). Connection closed if pong not received. */
+    heartbeatTimeout?: number;
+    /** Custom message parser. Default: JSON.parse expecting WsClientMessage shape. */
+    messageParser?: (raw: Buffer | string) => WsClientMessage;
+    /** Custom message serializer. Default: JSON.stringify. */
+    messageSerializer?: (msg: WsReplyMessage | WsPushMessage) => string | Buffer;
+    /** Logger instance. */
+    logger?: TConsoleBase;
+    /** Max message size in bytes (default: 1MB). Messages exceeding this are silently dropped. */
+    maxMessageSize?: number;
+    /** Custom WsServerAdapter. Default: wraps the `ws` package. */
+    wsServerAdapter?: WsServerAdapter;
+    /** Broadcast transport for multi-instance deployments. Default: local only. */
+    broadcastTransport?: WsBroadcastTransport;
+}
+
+/** Internal class representing a connected WebSocket client. */
+declare class WsConnection {
+    readonly id: string;
+    readonly ws: WsSocket;
+    readonly ctx: EventContext;
+    private readonly serializer;
+    readonly rooms: Set<string>;
+    alive: boolean;
+    constructor(id: string, ws: WsSocket, ctx: EventContext, serializer: (msg: WsReplyMessage | WsPushMessage) => string | Buffer);
+    /** Send a push message to this connection. */
+    send(event: string, path: string, data?: unknown, params?: Record<string, string>): void;
+    /** Send a reply to a client request. */
+    reply(id: string | number, data?: unknown): void;
+    /** Send an error reply to a client request. */
+    replyError(id: string | number, code: number, message: string): void;
+    /** Close the connection. */
+    close(code?: number, reason?: string): void;
+}
+
+/**
+ * Provides server-wide operations. Available in any context.
+ * Not a `defineWook` — reads directly from the adapter state.
+ */
+declare function useWsServer(): {
+    /** All active connections. */
+    connections(): Map<string, WsConnection>;
+    /** Broadcast to ALL connections (not room-scoped). */
+    broadcast(event: string, path: string, data?: unknown, params?: Record<string, string>): void;
+    /** Get a specific connection by ID. */
+    getConnection(id: string): WsConnection | undefined;
+    /** Get all connections in a room. */
+    roomConnections(room: string): Set<WsConnection>;
+};
+
+/** WebSocket adapter for Wooks. Implements WooksUpgradeHandler for HTTP integration. */
+declare class WooksWs extends WooksAdapterBase implements WooksUpgradeHandler {
+    protected logger: TConsoleBase;
+    protected eventContextOptions: EventContextOptions;
+    private readonly connections;
+    private readonly roomManager;
+    private readonly wsServer;
+    private readonly opts;
+    private readonly serializer;
+    private readonly parser;
+    private onConnectHandler?;
+    private onDisconnectHandler?;
+    private heartbeatTimer?;
+    private server?;
+    readonly reqKey: _wooksjs_event_core.Key<http.IncomingMessage>;
+    readonly socketKey: _wooksjs_event_core.Key<Duplex>;
+    readonly headKey: _wooksjs_event_core.Key<Buffer<ArrayBufferLike>>;
+    constructor(wooksOrOpts?: Wooks | WooksAdapterBase | TWooksWsOptions, opts?: TWooksWsOptions);
+    /** Register a handler that runs when a new WebSocket connection is established. */
+    onConnect(handler: TWooksHandler): void;
+    /** Register a handler that runs when a WebSocket connection closes. */
+    onDisconnect(handler: TWooksHandler): void;
+    /** Register a routed message handler. Uses the standard Wooks router internally. */
+    onMessage<ResType = unknown, ParamsType = Record<string, string | string[]>>(event: string, path: string, handler: TWooksHandler<ResType>): wooks.TProstoRouterPathHandle<ParamsType>;
+    /**
+     * Complete the WebSocket handshake from inside an UPGRADE route handler.
+     * Reads req/socket/head from the current HTTP context (set by the HTTP adapter).
+     * The HTTP context becomes the parent of the WS connection context.
+     */
+    upgrade(): void;
+    /**
+     * Fallback: called by the HTTP adapter when no UPGRADE route matches.
+     * Also used internally for standalone mode.
+     */
+    handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void;
+    /** Start a standalone server (without event-http). */
+    listen(port: number, hostname?: string): Promise<void>;
+    /** Stop the server and clean up. */
+    close(): void;
+    /** Returns the underlying HTTP server (if any). */
+    getServer(): Server | undefined;
+    private doUpgrade;
+    private acceptConnection;
+    private rejectConnection;
+    private handleMessage;
+    private processHandlers;
+    private processAsyncResult;
+    private sendReply;
+    private handleHandlerError;
+    private handleClose;
+    private startHeartbeat;
+    private stopHeartbeat;
+}
+/**
+ * Creates a new WooksWs WebSocket adapter.
+ *
+ * @example Integrated with HTTP (recommended):
+ * ```ts
+ * const http = createHttpApp()
+ * const ws = createWsApp(http) // auto-registers upgrade contract
+ * http.upgrade('/ws', () => ws.upgrade())
+ * http.listen(3000)
+ * ```
+ *
+ * @example Standalone:
+ * ```ts
+ * const ws = createWsApp({ heartbeatInterval: 30_000 })
+ * ws.listen(3000)
+ * ```
+ */
+declare function createWsApp(wooksOrOpts?: Wooks | WooksAdapterBase | TWooksWsOptions, opts?: TWooksWsOptions): WooksWs;
+
+/** Event kind for WebSocket connections (long-lived, one per client). */
+declare const wsConnectionKind: _wooksjs_event_core.EventKind<{
+    id: _wooksjs_event_core.SlotMarker<string>;
+    ws: _wooksjs_event_core.SlotMarker<WsSocket>;
+}>;
+/** Event kind for WebSocket messages (short-lived, one per incoming message). */
+declare const wsMessageKind: _wooksjs_event_core.EventKind<{
+    data: _wooksjs_event_core.SlotMarker<unknown>;
+    rawMessage: _wooksjs_event_core.SlotMarker<string | Buffer<ArrayBufferLike>>;
+    messageId: _wooksjs_event_core.SlotMarker<string | number | undefined>;
+    messagePath: _wooksjs_event_core.SlotMarker<string>;
+    messageEvent: _wooksjs_event_core.SlotMarker<string>;
+}>;
+
+/** WebSocket error with a numeric code following HTTP conventions (401, 403, 404, 500, etc.). */
+declare class WsError extends Error {
+    readonly code: number;
+    constructor(code: number, message?: string);
+}
+
+/** Manages room → connections mapping with optional distributed broadcast transport. */
+declare class WsRoomManager {
+    private readonly transport?;
+    private readonly rooms;
+    constructor(transport?: WsBroadcastTransport | undefined);
+    /** Add a connection to a room. */
+    join(connection: WsConnection, room: string): void;
+    /** Remove a connection from a room. */
+    leave(connection: WsConnection, room: string): void;
+    /** Remove a connection from ALL rooms (called on disconnect). */
+    leaveAll(connection: WsConnection): void;
+    /** Get all connections in a room. */
+    connections(room: string): Set<WsConnection>;
+    /** Broadcast to all connections in a room. */
+    broadcast(room: string, event: string, path: string, data?: unknown, params?: Record<string, string>, exclude?: WsConnection): void;
+    /** Handle inbound message from broadcast transport (other instances). */
+    private onTransportMessage;
+}
+
+/** Options for creating a test WS connection context. */
+interface TTestWsConnectionContext {
+    /** Connection ID. Default: 'test-conn-id'. */
+    id?: string;
+    /** Pre-set route parameters. */
+    params?: Record<string, string | string[]>;
+    /** Optional parent context (e.g., an HTTP context for testing composable reuse). */
+    parentCtx?: EventContext;
+}
+/** Options for creating a test WS message context (includes connection context). */
+interface TTestWsMessageContext extends TTestWsConnectionContext {
+    /** Message event type. */
+    event: string;
+    /** Message path. */
+    path: string;
+    /** Message data. */
+    data?: unknown;
+    /** Message correlation ID. */
+    messageId?: string | number;
+    /** Raw message. */
+    rawMessage?: Buffer | string;
+}
+/**
+ * Creates a fully initialized WS connection context for testing.
+ * Returns a runner function that executes callbacks inside the context scope.
+ */
+declare function prepareTestWsConnectionContext(options?: TTestWsConnectionContext): <T>(cb: (...a: any[]) => T) => T;
+/**
+ * Creates a fully initialized WS message context for testing.
+ * Sets up both connection context (parent) and message context (child).
+ * Returns a runner function that executes callbacks inside the message context scope.
+ */
+declare function prepareTestWsMessageContext(options: TTestWsMessageContext): <T>(cb: (...a: any[]) => T) => T;
+
+export { WooksWs, WsConnection, WsError, WsRoomManager, createWsApp, currentConnection, prepareTestWsConnectionContext, prepareTestWsMessageContext, useWsConnection, useWsMessage, useWsRooms, useWsServer, wsConnectionKind, wsMessageKind };
+export type { TTestWsConnectionContext, TTestWsMessageContext, TWooksWsOptions, WsBroadcastOptions, WsBroadcastTransport, WsClientMessage, WsPushMessage, WsReplyMessage, WsServerAdapter, WsServerInstance, WsSocket };