@richie-rpc/server 1.2.3 → 1.2.4

package/dist/types/websocket.d.ts

@@ -0,0 +1,125 @@
+import type { ExtractClientMessage, ExtractWSHeaders, ExtractWSParams, ExtractWSQuery, WebSocketContract, WebSocketContractDefinition } from '@richie-rpc/core';
+import type { z } from 'zod';
+/**
+ * Validation error for WebSocket messages
+ */
+export declare class WebSocketValidationError extends Error {
+    messageType: string;
+    issues: z.ZodIssue[];
+    constructor(messageType: string, issues: z.ZodIssue[]);
+}
+/**
+ * Data attached to WebSocket connections for routing
+ */
+export interface WebSocketData<T extends WebSocketContractDefinition = WebSocketContractDefinition, S = unknown> {
+    endpointName: string;
+    endpoint: T;
+    params: ExtractWSParams<T>;
+    query: ExtractWSQuery<T>;
+    headers: ExtractWSHeaders<T>;
+    context: unknown;
+    state: S;
+}
+/**
+ * Typed WebSocket wrapper for sending messages
+ */
+export interface TypedServerWebSocket<T extends WebSocketContractDefinition, S = unknown> {
+    /** The underlying Bun WebSocket */
+    readonly raw: WebSocket;
+    /** Send a typed message to the client */
+    send<K extends keyof T['serverMessages']>(type: K, payload: z.infer<T['serverMessages'][K]['payload']>): void;
+    /** Subscribe to a topic for pub/sub */
+    subscribe(topic: string): void;
+    /** Unsubscribe from a topic */
+    unsubscribe(topic: string): void;
+    /** Publish a message to a topic */
+    publish<K extends keyof T['serverMessages']>(topic: string, type: K, payload: z.infer<T['serverMessages'][K]['payload']>): void;
+    /** Close the connection */
+    close(code?: number, reason?: string): void;
+    /** Connection data */
+    readonly data: WebSocketData<T, S>;
+}
+/**
+ * Handler functions for a WebSocket endpoint
+ */
+export interface WebSocketEndpointHandlers<T extends WebSocketContractDefinition, C = unknown, S = unknown> {
+    /** Called when connection opens */
+    open?(ws: TypedServerWebSocket<T, S>, ctx: C): void | Promise<void>;
+    /** Called for each validated message */
+    message(ws: TypedServerWebSocket<T, S>, message: ExtractClientMessage<T>, ctx: C): void | Promise<void>;
+    /** Called when connection closes */
+    close?(ws: TypedServerWebSocket<T, S>, ctx: C): void;
+    /** Called when message validation fails */
+    validationError?(ws: TypedServerWebSocket<T, S>, error: WebSocketValidationError, ctx: C): void;
+}
+/**
+ * Contract handlers mapping for WebSocket endpoints
+ */
+export type WebSocketContractHandlers<T extends WebSocketContract, C = unknown, S = unknown> = {
+    [K in keyof T]: WebSocketEndpointHandlers<T[K], C, S>;
+};
+/**
+ * Upgrade data returned by matchAndPrepareUpgrade
+ */
+export interface UpgradeData<S = unknown> {
+    endpointName: string;
+    endpoint: WebSocketContractDefinition;
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+    headers: Record<string, string>;
+    context: unknown;
+    state: S;
+}
+/**
+ * Options for WebSocket router
+ */
+export interface WebSocketRouterOptions<C = unknown, S = unknown> {
+    basePath?: string;
+    context?: (request: Request, endpointName: string, endpoint: WebSocketContractDefinition) => C | Promise<C>;
+    /** Type hint for per-connection state. Use `{} as YourStateType` */
+    state?: S;
+}
+/**
+ * Bun WebSocket handler type (subset of Bun's types)
+ */
+export interface BunWebSocketHandler<T = unknown> {
+    open(ws: Bun.ServerWebSocket<T>): void | Promise<void>;
+    message(ws: Bun.ServerWebSocket<T>, message: string | Buffer<ArrayBuffer>): void | Promise<void>;
+    close(ws: Bun.ServerWebSocket<T>, code: number, reason: string): void;
+    drain(ws: Bun.ServerWebSocket<T>): void;
+}
+/**
+ * WebSocket router for managing WebSocket contract endpoints
+ */
+export declare class WebSocketRouter<T extends WebSocketContract, C = unknown, S = unknown> {
+    private contract;
+    private handlers;
+    private basePath;
+    private contextFactory?;
+    constructor(contract: T, handlers: WebSocketContractHandlers<T, C, S>, options?: WebSocketRouterOptions<C, S>);
+    /**
+     * Find matching endpoint for a path
+     */
+    private findEndpoint;
+    /**
+     * Parse and validate upgrade request parameters
+     */
+    private parseUpgradeParams;
+    /**
+     * Match a request and prepare upgrade data
+     * Returns null if no match, or UpgradeData for server.upgrade()
+     */
+    matchAndPrepareUpgrade(request: Request): Promise<UpgradeData<S> | null>;
+    /**
+     * Validate an incoming client message
+     */
+    private validateMessage;
+    /**
+     * Get Bun-compatible WebSocket handler
+     */
+    get websocketHandler(): BunWebSocketHandler<UpgradeData<S>>;
+}
+/**
+ * Create a WebSocket router from a contract and handlers
+ */
+export declare function createWebSocketRouter<T extends WebSocketContract, C = unknown, S = unknown>(contract: T, handlers: WebSocketContractHandlers<T, C, S>, options?: WebSocketRouterOptions<C, S>): WebSocketRouter<T, C, S>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@richie-rpc/server",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "main": "./dist/cjs/index.cjs",
   "exports": {
     ".": {
@@ -10,7 +10,7 @@
     }
   },
   "peerDependencies": {
-    "@richie-rpc/core": "^1.2.2",
+    "@richie-rpc/core": "^1.2.3",
     "typescript": "^5",
     "zod": "^4.1.12"
   },