@richie-rpc/server 1.2.3 → 1.2.4

package/README.md

@@ -20,19 +20,19 @@ const router = createRouter(contract, {
   getUser: async ({ params }) => {
     // params is fully typed based on the contract
     const user = await db.getUser(params.id);
-    
+
     if (!user) {
       return { status: Status.NotFound, body: { error: 'User not found' } };
     }
-    
+
     return { status: Status.OK, body: user };
   },
-  
+
   createUser: async ({ body }) => {
     // body is fully typed and already validated
     const user = await db.createUser(body);
     return { status: Status.Created, body: user };
-  }
+  },
 });
 ```
 
@@ -41,22 +41,22 @@ const router = createRouter(contract, {
 You can serve your API under a path prefix (e.g., `/api`) using the `basePath` option:
 
 ```typescript
-const router = createRouter(contract, handlers, { 
-  basePath: '/api' 
+const router = createRouter(contract, handlers, {
+  basePath: '/api',
 });
 
 Bun.serve({
   port: 3000,
   fetch(request) {
     const url = new URL(request.url);
-    
+
     // Route all /api/* requests to the router
     if (url.pathname.startsWith('/api/')) {
       return router.fetch(request);
     }
-    
+
     return new Response('Not Found', { status: 404 });
-  }
+  },
 });
 ```
 
@@ -67,7 +67,7 @@ The router will automatically strip the basePath prefix before matching routes.
 ```typescript
 Bun.serve({
   port: 3000,
-  fetch: router.fetch
+  fetch: router.fetch,
 });
 ```
 
@@ -78,13 +78,13 @@ Bun.serve({
   port: 3000,
   fetch(request) {
     const url = new URL(request.url);
-    
+
     if (url.pathname.startsWith('/api')) {
       return router.handle(request);
     }
-    
+
     return new Response('Not Found', { status: 404 });
-  }
+  },
 });
 ```
 
@@ -94,6 +94,9 @@ Bun.serve({
 - ✅ Automatic response validation
 - ✅ Type-safe handler inputs
 - ✅ Type-safe status codes with `Status` const object
+- ✅ HTTP Streaming with `StreamEmitter`
+- ✅ Server-Sent Events with `SSEEmitter`
+- ✅ WebSocket router with pub/sub support
 - ✅ Path parameter matching
 - ✅ Query parameter parsing
 - ✅ JSON body parsing
@@ -137,14 +140,15 @@ Use the `Status` const object for type-safe status codes:
 ```typescript
 import { Status } from '@richie-rpc/server';
 
-return { status: Status.OK, body: user };           // 200
-return { status: Status.Created, body: newUser };   // 201
-return { status: Status.NoContent, body: {} };      // 204
-return { status: Status.BadRequest, body: error };  // 400
-return { status: Status.NotFound, body: error };    // 404
+return { status: Status.OK, body: user }; // 200
+return { status: Status.Created, body: newUser }; // 201
+return { status: Status.NoContent, body: {} }; // 204
+return { status: Status.BadRequest, body: error }; // 400
+return { status: Status.NotFound, body: error }; // 404
 ```
 
 Available status codes in `Status` object:
+
 - **Success**: `OK` (200), `Created` (201), `Accepted` (202), `NoContent` (204)
 - **Redirection**: `MovedPermanently` (301), `Found` (302), `NotModified` (304)
 - **Client Errors**: `BadRequest` (400), `Unauthorized` (401), `Forbidden` (403), `NotFound` (404), `MethodNotAllowed` (405), `Conflict` (409), `UnprocessableEntity` (422), `TooManyRequests` (429)
@@ -172,18 +176,18 @@ const contract = defineContract({
     method: 'GET',
     path: '/teapot',
     responses: {
-      418: z.object({ message: z.string(), isTeapot: z.boolean() })
-    }
-  }
+      418: z.object({ message: z.string(), isTeapot: z.boolean() }),
+    },
+  },
 });
 
 const router = createRouter(contract, {
   teapot: async () => {
     return {
       status: 418 as const,
-      body: { message: "I'm a teapot", isTeapot: true }
+      body: { message: "I'm a teapot", isTeapot: true },
     };
-  }
+  },
 });
 ```
 
@@ -198,11 +202,13 @@ const contract = defineContract({
     path: '/upload',
     contentType: 'multipart/form-data',
     body: z.object({
-      documents: z.array(z.object({
-        file: z.instanceof(File),
-        name: z.string(),
-        tags: z.array(z.string()).optional(),
-      })),
+      documents: z.array(
+        z.object({
+          file: z.instanceof(File),
+          name: z.string(),
+          tags: z.array(z.string()).optional(),
+        }),
+      ),
       category: z.string(),
     }),
     responses: {
@@ -240,10 +246,229 @@ const router = createRouter(contract, {
 ```
 
 The server automatically:
+
 - Parses `multipart/form-data` requests
 - Reconstructs nested structures with File objects
 - Validates the body against your Zod schema
 
+## Streaming Responses
+
+For AI-style streaming responses, handlers receive a `stream` object:
+
+```typescript
+const contract = defineContract({
+  generateText: {
+    type: 'streaming',
+    method: 'POST',
+    path: '/generate',
+    body: z.object({ prompt: z.string() }),
+    chunk: z.object({ text: z.string() }),
+    finalResponse: z.object({ totalTokens: z.number() }),
+  },
+});
+
+const router = createRouter(contract, {
+  generateText: async ({ body, stream }) => {
+    const words = body.prompt.split(' ');
+
+    for (const word of words) {
+      if (!stream.isOpen) return; // Client disconnected
+      stream.send({ text: word + ' ' });
+      await new Promise((r) => setTimeout(r, 100));
+    }
+
+    stream.close({ totalTokens: words.length });
+  },
+});
+```
+
+### StreamEmitter Interface
+
+- `send(chunk)` - Send a chunk to the client (NDJSON format)
+- `close(finalResponse?)` - Close the stream with optional final response
+- `isOpen` - Check if the stream is still open
+
+## Server-Sent Events (SSE)
+
+For server-to-client event streaming, handlers receive an `emitter` object:
+
+```typescript
+const contract = defineContract({
+  notifications: {
+    type: 'sse',
+    method: 'GET',
+    path: '/notifications',
+    events: {
+      message: z.object({ text: z.string() }),
+      heartbeat: z.object({ timestamp: z.string() }),
+    },
+  },
+});
+
+const router = createRouter(contract, {
+  notifications: ({ emitter, signal }) => {
+    // Send heartbeats every 30 seconds
+    const heartbeatInterval = setInterval(() => {
+      if (!emitter.isOpen) return;
+      emitter.send('heartbeat', { timestamp: new Date().toISOString() });
+    }, 30000);
+
+    // Cleanup when client disconnects
+    signal.addEventListener('abort', () => {
+      clearInterval(heartbeatInterval);
+    });
+
+    // Optional: return cleanup function
+    return () => clearInterval(heartbeatInterval);
+  },
+});
+```
+
+### SSEEmitter Interface
+
+- `send(event, data, options?)` - Send an event with data and optional ID
+- `close()` - Close the connection
+- `isOpen` - Check if the connection is still open
+
+## WebSocket Router
+
+For bidirectional real-time communication, use `createWebSocketRouter`:
+
+```typescript
+import { createWebSocketRouter } from '@richie-rpc/server';
+import { defineWebSocketContract } from '@richie-rpc/core';
+
+const wsContract = defineWebSocketContract({
+  chat: {
+    path: '/ws/chat/:roomId',
+    params: z.object({ roomId: z.string() }),
+    clientMessages: {
+      sendMessage: { payload: z.object({ text: z.string() }) },
+    },
+    serverMessages: {
+      message: { payload: z.object({ userId: z.string(), text: z.string() }) },
+      error: { payload: z.object({ code: z.string(), message: z.string() }) },
+    },
+  },
+});
+
+const wsRouter = createWebSocketRouter(wsContract, {
+  chat: {
+    open(ws) {
+      // Called when connection opens
+      ws.subscribe(`room:${ws.data.params.roomId}`);
+      console.log('User joined room:', ws.data.params.roomId);
+    },
+
+    message(ws, msg) {
+      // Called for each validated client message
+      if (msg.type === 'sendMessage') {
+        ws.publish(`room:${ws.data.params.roomId}`, 'message', {
+          userId: 'user1',
+          text: msg.payload.text,
+        });
+      }
+    },
+
+    close(ws) {
+      // Called when connection closes
+      console.log('User left room:', ws.data.params.roomId);
+    },
+
+    validationError(ws, error) {
+      // Called when client message validation fails
+      ws.send('error', { code: 'VALIDATION_ERROR', message: error.message });
+    },
+  },
+});
+```
+
+### Typed Per-Connection State
+
+You can store typed per-connection state by defining a state interface and passing it as an option. This follows the same pattern as Bun's WebSocket data:
+
+```typescript
+// Define your per-connection state type
+interface ChatConnectionState {
+  connectionId: string;
+  userId?: string;
+  username?: string;
+}
+
+const wsRouter = createWebSocketRouter(
+  wsContract,
+  {
+    chat: {
+      open(ws) {
+        // Initialize typed state - fully typed, no casts needed
+        ws.data.state.connectionId = generateId();
+        ws.subscribe(`room:${ws.data.params.roomId}`);
+      },
+
+      message(ws, msg) {
+        // Access typed state
+        const { connectionId, username } = ws.data.state;
+
+        if (msg.type === 'join') {
+          // Update state
+          ws.data.state.username = msg.payload.username;
+          ws.data.state.userId = connectionId;
+        }
+
+        if (msg.type === 'sendMessage' && username) {
+          ws.publish(`room:${ws.data.params.roomId}`, 'message', {
+            userId: connectionId,
+            text: msg.payload.text,
+          });
+        }
+      },
+
+      close(ws) {
+        // State is available throughout connection lifecycle
+        console.log(`User ${ws.data.state.username} disconnected`);
+      },
+    },
+  },
+  // Pass state type hint as third argument
+  { state: {} as ChatConnectionState },
+);
+```
+
+The state object is initialized as an empty object for each connection and is available via `ws.data.state` in all handlers (`open`, `message`, `close`, `validationError`).
+
+### TypedServerWebSocket Interface
+
+- `send(type, payload)` - Send a typed message to the client
+- `subscribe(topic)` - Subscribe to a pub/sub topic
+- `unsubscribe(topic)` - Unsubscribe from a topic
+- `publish(topic, type, payload)` - Broadcast to all subscribers
+- `close(code?, reason?)` - Close the connection
+- `data.params` - Access path parameters from the connection
+- `data.query` - Access query parameters from the connection
+- `data.headers` - Access headers from the connection
+- `data.state` - Access typed per-connection state (see above)
+
+### Integrating with Bun.serve
+
+```typescript
+Bun.serve({
+  port: 3000,
+
+  websocket: wsRouter.websocketHandler,
+
+  async fetch(request, server) {
+    // Try WebSocket upgrade
+    const wsMatch = await wsRouter.matchAndPrepareUpgrade(request);
+    if (wsMatch && request.headers.get('upgrade') === 'websocket') {
+      if (server.upgrade(request, { data: wsMatch })) return;
+    }
+
+    // Handle regular HTTP requests
+    return router.fetch(request);
+  },
+});
+```
+
 ## Error Handling
 
 The router throws specific error classes that you can catch and handle. These errors are thrown before handlers are called, so you should wrap your router calls in try-catch blocks.
@@ -255,11 +480,13 @@ The router throws specific error classes that you can catch and handle. These er
 Thrown when request or response validation fails. Contains detailed Zod validation issues.
 
 **Properties:**
+
 - `field: string` - The field that failed validation (`"params"`, `"query"`, `"headers"`, `"body"`, or `"response[status]"`)
 - `issues: z.ZodIssue[]` - Array of Zod validation issues with detailed error information
 - `message: string` - Error message
 
 **When thrown:**
+
 - Invalid path parameters (params)
 - Invalid query parameters (query)
 - Invalid request headers (headers)
@@ -287,10 +514,10 @@ Bun.serve({
             field: error.field,
             issues: error.issues,
           },
-          { status: 400 }
+          { status: 400 },
         );
       }
-      
+
       if (error instanceof RouteNotFoundError) {
         // Handle route not found
         return Response.json(
@@ -298,16 +525,13 @@ Bun.serve({
             error: 'Not Found',
             message: `Route ${error.method} ${error.path} not found`,
           },
-          { status: 404 }
+          { status: 404 },
         );
       }
-      
+
       // Handle unexpected errors
       console.error('Unexpected error:', error);
-      return Response.json(
-        { error: 'Internal Server Error' },
-        { status: 500 }
-      );
+      return Response.json({ error: 'Internal Server Error' }, { status: 500 });
     }
   },
 });
@@ -318,10 +542,12 @@ Bun.serve({
 Thrown when no matching route is found for the request.
 
 **Properties:**
+
 - `path: string` - The requested path
 - `method: string` - The HTTP method (GET, POST, etc.)
 
 **When thrown:**
+
 - No endpoint in the contract matches the request method and path
 
 **Example:**
@@ -336,7 +562,7 @@ try {
         error: 'Not Found',
         message: `Cannot ${error.method} ${error.path}`,
       },
-      { status: 404 }
+      { status: 404 },
     );
   }
   throw error; // Re-throw other errors
@@ -346,12 +572,7 @@ try {
 ### Complete Error Handling Example
 
 ```typescript
-import {
-  createRouter,
-  ValidationError,
-  RouteNotFoundError,
-  Status,
-} from '@richie-rpc/server';
+import { createRouter, ValidationError, RouteNotFoundError, Status } from '@richie-rpc/server';
 
 const router = createRouter(contract, handlers);
 
@@ -359,7 +580,7 @@ Bun.serve({
   port: 3000,
   async fetch(request) {
     const url = new URL(request.url);
-    
+
     // Handle API routes
     if (url.pathname.startsWith('/api/')) {
       try {
@@ -377,29 +598,26 @@ Bun.serve({
                 code: issue.code,
               })),
             },
-            { status: 400 }
+            { status: 400 },
           );
         }
-        
+
         if (error instanceof RouteNotFoundError) {
           return Response.json(
             {
               error: 'Not Found',
               message: `Route ${error.method} ${error.path} not found`,
             },
-            { status: 404 }
+            { status: 404 },
           );
         }
-        
+
         // Log unexpected errors
         console.error('Unexpected error:', error);
-        return Response.json(
-          { error: 'Internal Server Error' },
-          { status: 500 }
-        );
+        return Response.json({ error: 'Internal Server Error' }, { status: 500 });
       }
     }
-    
+
     // Handle other routes
     return new Response('Not Found', { status: 404 });
   },
@@ -447,4 +665,3 @@ Both request and response data are validated against the contract schemas:
 ## License
 
 MIT
-