@richie-rpc/server 1.2.2 → 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,10 +94,14 @@ 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
-- ✅ Form data support
+- ✅ File uploads with `multipart/form-data`
+- ✅ Nested file structures in request bodies
 - ✅ BasePath support for serving APIs under path prefixes
 - ✅ Detailed validation errors
 - ✅ 404 handling for unknown routes
@@ -136,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)
@@ -171,18 +176,296 @@ 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 },
     };
-  }
+  },
+});
+```
+
+## Handling File Uploads
+
+The server automatically handles `multipart/form-data` requests when the contract specifies `contentType: 'multipart/form-data'`. File objects are fully reconstructed and passed to your handler:
+
+```typescript
+const contract = defineContract({
+  uploadDocuments: {
+    method: 'POST',
+    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(),
+        }),
+      ),
+      category: z.string(),
+    }),
+    responses: {
+      [Status.Created]: z.object({
+        uploadedCount: z.number(),
+        totalSize: z.number(),
+      }),
+    },
+  },
+});
+
+const router = createRouter(contract, {
+  uploadDocuments: async ({ body }) => {
+    // body.documents is fully typed with File objects
+    let totalSize = 0;
+
+    for (const doc of body.documents) {
+      // doc.file is a File object
+      const buffer = await doc.file.arrayBuffer();
+      totalSize += buffer.byteLength;
+
+      console.log(`Processing: ${doc.name} (${doc.file.name})`);
+      console.log(`Tags: ${doc.tags?.join(', ') ?? 'none'}`);
+    }
+
+    return {
+      status: Status.Created,
+      body: {
+        uploadedCount: body.documents.length,
+        totalSize,
+      },
+    };
+  },
+});
+```
+
+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);
+  },
 });
 ```
 
@@ -197,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)
@@ -229,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(
@@ -240,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 });
     }
   },
 });
@@ -260,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:**
@@ -278,7 +562,7 @@ try {
         error: 'Not Found',
         message: `Cannot ${error.method} ${error.path}`,
       },
-      { status: 404 }
+      { status: 404 },
     );
   }
   throw error; // Re-throw other errors
@@ -288,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);
 
@@ -301,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 {
@@ -319,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 });
   },
@@ -389,4 +665,3 @@ Both request and response data are validated against the contract schemas:
 ## License
 
 MIT
-