@firtoz/hono-fetcher 2.0.0 → 2.1.0

package/README.md

@@ -12,6 +12,7 @@ Type-safe Hono API client with full TypeScript inference for routes, params, and
 - 🎯 **Path Parameters** - Automatic extraction and validation of path parameters (`:id`, `:slug`, etc.)
 - 📝 **Request Bodies** - Type-safe JSON and form data support with automatic serialization
 - 🌐 **Cloudflare Workers** - First-class support for Durable Objects with `honoDoFetcher`
+- 🔌 **WebSocket Support** - Type-safe WebSocket connections with automatic acceptance and configuration
 - 🚀 **Zero Runtime Overhead** - All type inference happens at compile time
 - 🔄 **Full HTTP Methods** - Support for GET, POST, PUT, DELETE, and PATCH
 
@@ -298,17 +299,132 @@ await api.get({
 });
 ```
 
+## WebSocket Support
+
+`hono-fetcher` provides first-class support for WebSocket connections with full type safety.
+
+### Basic WebSocket Connection
+
+```typescript
+import { honoFetcher } from '@firtoz/hono-fetcher';
+
+const api = honoFetcher<typeof app>(fetcher);
+
+// Connect to a WebSocket endpoint
+const wsResponse = await api.websocket({
+  url: '/chat',
+});
+
+// Access the WebSocket
+const ws = wsResponse.webSocket;
+if (ws) {
+  ws.send(JSON.stringify({ type: 'hello' }));
+  
+  ws.addEventListener('message', (event) => {
+    console.log('Received:', event.data);
+  });
+}
+```
+
+### WebSocket with Auto-Accept
+
+By default, WebSockets are **automatically accepted** for convenience:
+
+```typescript
+// Default behavior - WebSocket is auto-accepted
+const wsResp = await api.websocket({
+  url: '/websocket',
+  // config.autoAccept defaults to true
+});
+
+// WebSocket is ready to use immediately!
+wsResp.webSocket?.send('Hello!');
+```
+
+### Manual WebSocket Acceptance
+
+For advanced scenarios where you need control over when the WebSocket is accepted:
+
+```typescript
+const wsResp = await api.websocket({
+  url: '/websocket',
+  config: { autoAccept: false }, // Disable auto-accept
+});
+
+const ws = wsResp.webSocket;
+if (ws) {
+  // Set up your listeners first
+  ws.addEventListener('message', (event) => {
+    console.log('Message:', event.data);
+  });
+  
+  // Then manually accept when ready
+  ws.accept();
+}
+```
+
+### WebSocket with Path Parameters
+
+```typescript
+const api = honoFetcher<typeof app>(fetcher);
+
+// WebSocket endpoint with path parameters
+const wsResp = await api.websocket({
+  url: '/rooms/:roomId/websocket',
+  params: { roomId: 'room-123' }, // Type-safe params!
+});
+```
+
+### Integration with ZodWebSocketClient
+
+For even better type safety, combine with `@firtoz/websocket-do`'s `ZodWebSocketClient`:
+
+```typescript
+import { ZodWebSocketClient } from '@firtoz/websocket-do';
+import { honoDoFetcherWithName } from '@firtoz/hono-fetcher';
+
+// 1. Connect to DO WebSocket
+const api = honoDoFetcherWithName(env.CHAT_ROOM, 'room-1');
+const wsResp = await api.websocket({
+  url: '/websocket',
+  config: { autoAccept: false }, // Let ZodWebSocketClient handle acceptance
+});
+
+// 2. Wrap with type-safe client
+const client = new ZodWebSocketClient({
+  webSocket: wsResp.webSocket,
+  clientSchema: ClientMessageSchema,
+  serverSchema: ServerMessageSchema,
+  onMessage: (message) => {
+    // Fully typed message!
+    console.log('Received:', message);
+  },
+});
+
+// 3. Now accept
+wsResp.webSocket?.accept();
+
+// 4. Send type-safe messages
+client.send({ type: 'chat', text: 'Hello!' }); // Validated with Zod!
+```
+
+See the [ZodWebSocketClient documentation](#) for more details on type-safe WebSocket communication.
+
 ## Durable Objects API
 
 ### `honoDoFetcher<T>(stub)`
 
-Creates a typed fetcher for a Durable Object stub.
+Creates a typed fetcher for a Durable Object stub with support for both HTTP and WebSocket connections.
 
 ```typescript
 const stub = env.MY_DO.getByName('example');
 const api = honoDoFetcher(stub);
 
+// HTTP requests
 await api.get({ url: '/status' });
+
+// WebSocket connections
+const wsResp = await api.websocket({ url: '/ws' });
 ```
 
 ### `honoDoFetcherWithName<T>(namespace, name)`
@@ -317,7 +433,12 @@ Convenience method to create a fetcher from a namespace and name.
 
 ```typescript
 const api = honoDoFetcherWithName(env.MY_DO, 'example');
+
+// HTTP
 await api.get({ url: '/status' });
+
+// WebSocket
+await api.websocket({ url: '/chat' });
 ```
 
 ### `honoDoFetcherWithId<T>(namespace, id)`
@@ -354,6 +475,23 @@ const response: JsonResponse<{ id: string }> = await api.get({ url: '/user' });
 const data = await response.json(); // Type: { id: string }
 ```
 
+### `WebSocketConfig`
+
+Configuration options for WebSocket connections.
+
+```typescript
+import type { WebSocketConfig } from '@firtoz/hono-fetcher';
+
+const config: WebSocketConfig = {
+  autoAccept: false, // Default: true
+};
+
+await api.websocket({ url: '/ws', config });
+```
+
+**Options:**
+- `autoAccept?: boolean` - Whether to automatically call `accept()` on the WebSocket. Defaults to `true` for convenience. Set to `false` if you need manual control over when the WebSocket is accepted (e.g., when using with `ZodWebSocketClient`).
+
 ### `ParsePathParams<T>`
 
 Utility type to extract path parameters from a route string.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/hono-fetcher",
-	"version": "2.0.0",
+	"version": "2.1.0",
 	"description": "Type-safe Hono API client with full TypeScript inference for routes, params, and payloads",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",

package/src/honoFetcher.ts

@@ -97,9 +97,33 @@ type AvailableMethods<T extends Hono> = {
 	[M in HttpMethod]: keyof HonoSchema<T>[M] extends never ? never : M;
 }[HttpMethod];
 
+export interface WebSocketConfig {
+	/**
+	 * Whether to automatically call accept() on the WebSocket before returning.
+	 * Defaults to true for convenience.
+	 *
+	 * In Cloudflare Workers, you must call accept() before using a WebSocket.
+	 * Setting this to false allows you to call accept() manually if needed.
+	 *
+	 * @default true
+	 */
+	autoAccept?: boolean;
+}
+
+export type TypedWebSocketFetcher<T extends Hono> = <
+	SchemaPath extends string & keyof HonoSchema<T>["get"],
+>(
+	request: {
+		url: SchemaPath;
+		config?: WebSocketConfig;
+	} & FetcherParams<SchemaPath>,
+) => Promise<Response>;
+
 export type BaseTypedHonoFetcher<T extends Hono> = {
 	[M in AvailableMethods<T>]: TypedMethodFetcher<T, M>;
-};
+} & (keyof HonoSchema<T>["get"] extends never
+	? {}
+	: { websocket: TypedWebSocketFetcher<T> });
 
 const createMethodFetcher = <T extends Hono, M extends HttpMethod>(
 	fetcher: (
@@ -158,6 +182,48 @@ const createMethodFetcher = <T extends Hono, M extends HttpMethod>(
 	}) as TypedMethodFetcher<T, M>;
 };
 
+const createWebSocketFetcher = <T extends Hono>(
+	fetcher: (
+		request: string,
+		init?: RequestInit,
+	) => ReturnType<T["request"]> | Promise<ReturnType<T["request"]>>,
+): TypedWebSocketFetcher<T> => {
+	return (async (request) => {
+		let finalUrl: string = request.url;
+
+		const { init = {}, params, config } = request;
+		const autoAccept = config?.autoAccept ?? true; // Default to true
+
+		if (params && typeof params === "object") {
+			finalUrl = Object.entries(params).reduce((acc, [key, value]) => {
+				return acc.replace(`:${key}`, value as string);
+			}, finalUrl);
+		}
+
+		// biome-ignore lint/suspicious/noExplicitAny: Different runtimes have incompatible HeadersInit types
+		const newHeaders = new Headers(init.headers as any);
+		newHeaders.set("Upgrade", "websocket");
+
+		try {
+			const response = await fetcher(finalUrl, {
+				method: "GET",
+				headers: newHeaders,
+				...init,
+			});
+
+			// Auto-accept the WebSocket if configured (default: true)
+			if (autoAccept && response.webSocket) {
+				response.webSocket.accept();
+			}
+
+			return response;
+		} catch (error) {
+			console.error("Error upgrading to WebSocket", error);
+			throw new Error(`Failed to upgrade WebSocket at ${finalUrl}: ${error}`);
+		}
+	}) as TypedWebSocketFetcher<T>;
+};
+
 export type TypedHonoFetcher<T extends Hono> = BaseTypedHonoFetcher<T>;
 
 export const honoFetcher = <T extends Hono>(
@@ -183,5 +249,10 @@ export const honoFetcher = <T extends Hono>(
 		{} as TypedHonoFetcher<T>,
 	);
 
+	// Add websocket method
+	(
+		result as TypedHonoFetcher<T> & { websocket?: TypedWebSocketFetcher<T> }
+	).websocket = createWebSocketFetcher(fetcher);
+
 	return result;
 };

package/src/index.ts

@@ -20,4 +20,6 @@ export {
 	type JsonResponse,
 	type ParsePathParams,
 	type TypedHonoFetcher,
+	type TypedWebSocketFetcher,
+	type WebSocketConfig,
 } from "./honoFetcher";