@firtoz/hono-fetcher 2.4.0 → 2.5.0

package/README.md

@@ -131,17 +131,12 @@ export class ChatRoomDO extends DurableObject {
   }
 }
 
-// In your worker
+// In your worker — use `using` so the RPC stub is disposed when the block exits
 export default {
   async fetch(request: Request, env: Env): Promise<Response> {
-    // Option 1: From a stub (using new getByName API)
-    const stub = env.CHAT_ROOM.getByName('room-1');
-    const api = honoDoFetcher(stub);
-    
-    // Option 2: Directly with name (recommended)
-    const api2 = honoDoFetcherWithName(env.CHAT_ROOM, 'room-1');
-    
-    // Use it!
+    // From namespace + name (recommended)
+    using api = honoDoFetcherWithName(env.CHAT_ROOM, 'room-1');
+    // Or from an existing stub: using api = honoDoFetcher(env.CHAT_ROOM.getByName('room-1'));
     const response = await api.get({ url: '/messages' });
     return response;
   }
@@ -414,13 +409,16 @@ See the [ZodWebSocketClient documentation](#) for more details on type-safe WebS
 
 ## Durable Objects API
 
+Each of `honoDoFetcher`, `honoDoFetcherWithName`, and `honoDoFetcherWithId` returns a fetcher that is also a **`Disposable`**: calling `api[Symbol.dispose]()` releases the underlying Durable Object stub. In production Workers, prefer the **`using`** declaration so disposal runs when the block exits (success or throw). See [Durable Object stubs and disposal](#durable-object-stubs-and-disposal) below.
+
 ### `honoDoFetcher<T>(stub)`
 
 Creates a typed fetcher for a Durable Object stub with support for both HTTP and WebSocket connections.
 
+**Returns:** `TypedDoFetcher<T> & Disposable`
+
 ```typescript
-const stub = env.MY_DO.getByName('example');
-const api = honoDoFetcher(stub);
+using api = honoDoFetcher(env.MY_DO.getByName('example'));
 
 // HTTP requests
 await api.get({ url: '/status' });
@@ -431,10 +429,12 @@ const wsResp = await api.websocket({ url: '/ws' });
 
 ### `honoDoFetcherWithName<T>(namespace, name)`
 
-Convenience method to create a fetcher from a namespace and name.
+Convenience method to create a fetcher from a namespace and name. Uses a single stub internally and wires disposal to that stub.
+
+**Returns:** `TypedDoFetcher<DurableObjectStub<T>> & Disposable`
 
 ```typescript
-const api = honoDoFetcherWithName(env.MY_DO, 'example');
+using api = honoDoFetcherWithName(env.MY_DO, 'example');
 
 // HTTP
 await api.get({ url: '/status' });
@@ -447,11 +447,20 @@ await api.websocket({ url: '/chat' });
 
 Convenience method to create a fetcher from a namespace and hex ID string.
 
+**Returns:** `TypedDoFetcher<DurableObjectStub<T>> & Disposable`
+
 ```typescript
-const api = honoDoFetcherWithId(env.MY_DO, 'abc123...');
+using api = honoDoFetcherWithId(env.MY_DO, 'abc123...');
 await api.get({ url: '/status' });
 ```
 
+### Durable Object stubs and disposal
+
+- **Production Workers:** Durable Object stubs participate in RPC and should be released when you are done. The easiest pattern is **`using api = honoDoFetcherWithName(...)`** (or `honoDoFetcher` / `honoDoFetcherWithId`). You can also call **`api[Symbol.dispose]()`** manually (for example in a `finally` block) if you cannot use `using`.
+- **Vite SSR, some Miniflare setups, or test mocks** may expose stubs that only implement **`fetch`** and not **`Symbol.dispose`**. The library checks for a callable `Symbol.dispose` before invoking it; if it is missing, disposal is a no-op (no `TypeError`).
+- **Errors from `Symbol.dispose`:** If the runtime’s dispose implementation throws (for example during unwind after your code threw), the library catches the error and logs it with **`console.error`**. It does **not** rethrow, so your original error is not masked by a `SuppressedError`.
+- **TypeScript `using`:** Add **`"ESNext.Disposable"`** to the `compilerOptions.lib` array in your **`tsconfig.json`** (alongside your existing libs) so `using` and `Disposable` type-check. TypeScript 5.2+ is required for `using`.
+
 ## Type Exports
 
 ### `TypedHonoFetcher<T>`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/hono-fetcher",
-	"version": "2.4.0",
+	"version": "2.5.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/honoDoFetcher.ts

@@ -29,13 +29,56 @@ export type TypedDoFetcher<T extends DurableObjectStub> = TypedHonoFetcher<
 	Hono<any, DOStubSchema<T>>
 >;
 
-export const honoDoFetcher = <const T extends DurableObjectStub<DOWithHonoApp>>(
+/** Shape honoDoFetcher uses at runtime; full stubs or minimal mocks (e.g. tests) with only `fetch`. */
+export type HonoDoFetcherStubInput =
+	| DurableObjectStub<DOWithHonoApp>
+	| Pick<DurableObjectStub<DOWithHonoApp>, "fetch">;
+
+function withStubDispose<
+	TStub extends Pick<DurableObjectStub<DOWithHonoApp>, "fetch">,
+	TS extends Schema,
+>(
+	stub: TStub,
+	// biome-ignore lint/suspicious/noExplicitAny: Matches honoFetcher generic pattern for schema-driven apps
+	api: TypedHonoFetcher<Hono<any, TS>>,
+	// biome-ignore lint/suspicious/noExplicitAny: Matches honoFetcher generic pattern for schema-driven apps
+): TypedHonoFetcher<Hono<any, TS>> & Disposable {
+	return Object.assign(api, {
+		[Symbol.dispose]() {
+			// Stubs may omit Symbol.dispose (e.g. Vite mocks); DurableObjectStub types may not list it.
+			const disposeFn = Reflect.get(stub, Symbol.dispose);
+			if (typeof disposeFn !== "function") {
+				return;
+			}
+			try {
+				disposeFn.call(stub);
+			} catch (e) {
+				console.error(
+					"[@firtoz/hono-fetcher] Durable Object stub dispose failed",
+					e,
+				);
+			}
+		},
+	});
+}
+
+export const honoDoFetcher = <const T extends HonoDoFetcherStubInput>(
 	durableObject: T,
-): TypedDoFetcher<T> => {
+): T extends DurableObjectStub<DOWithHonoApp>
+	? TypedDoFetcher<T> & Disposable
+	: TypedHonoFetcher<Hono> & Disposable => {
+	type OutSchema =
+		T extends DurableObjectStub<DOWithHonoApp> ? DOStubSchema<T> : Schema;
 	// biome-ignore lint/suspicious/noExplicitAny: Generic parameter needs flexibility
-	return honoFetcher<Hono<any, DOStubSchema<T>>>((url, init) => {
+	const api = honoFetcher<Hono<any, OutSchema>>((url, init) => {
 		return durableObject.fetch(`${DUMMY_URL}${url}`, init);
 	});
+	return withStubDispose(
+		durableObject,
+		api,
+	) as T extends DurableObjectStub<DOWithHonoApp>
+		? TypedDoFetcher<T> & Disposable
+		: TypedHonoFetcher<Hono> & Disposable;
 };
 
 export const honoDoFetcherWithName = <
@@ -43,8 +86,11 @@ export const honoDoFetcherWithName = <
 >(
 	namespace: DurableObjectNamespace<T>,
 	name: string,
-): TypedDoFetcher<DurableObjectStub<T>> => {
-	return honoDoFetcher(namespace.getByName(name));
+): TypedDoFetcher<DurableObjectStub<T>> & Disposable => {
+	return honoDoFetcher(namespace.getByName(name)) as TypedDoFetcher<
+		DurableObjectStub<T>
+	> &
+		Disposable;
 };
 
 export const honoDoFetcherWithId = <
@@ -52,6 +98,8 @@ export const honoDoFetcherWithId = <
 >(
 	namespace: DurableObjectNamespace<T>,
 	id: string,
-): TypedDoFetcher<DurableObjectStub<T>> => {
-	return honoDoFetcher(namespace.get(namespace.idFromString(id)));
+): TypedDoFetcher<DurableObjectStub<T>> & Disposable => {
+	return honoDoFetcher(
+		namespace.get(namespace.idFromString(id)),
+	) as TypedDoFetcher<DurableObjectStub<T>> & Disposable;
 };

package/src/honoFetcher.ts

@@ -66,6 +66,16 @@ function appendQueryString(
 	return `${url}${separator}${serialized}`;
 }
 
+/**
+ * `RequestInit` fields that honoFetcher sets must not be overwritten by spreading `...init` last.
+ */
+function restOfRequestInit(
+	init: RequestInit,
+): Omit<RequestInit, "headers" | "body" | "method"> {
+	const { headers: _h, body: _b, method: _m, ...rest } = init;
+	return rest;
+}
+
 type FetcherParams<SchemaPath extends string> =
 	HasPathParams<SchemaPath> extends true
 		? {
@@ -209,10 +219,10 @@ const createMethodFetcher = <T extends Hono, M extends HttpMethod>(
 
 		try {
 			return await fetcher(finalUrl, {
+				...restOfRequestInit(init),
 				method: method.toUpperCase(),
 				headers: newHeaders,
 				...(body ? { body } : {}),
-				...init,
 			});
 		} catch (error) {
 			console.error(`Error ${method}ing`, error);
@@ -248,9 +258,9 @@ const createWebSocketFetcher = <T extends Hono>(
 
 		try {
 			const response = await fetcher(finalUrl, {
+				...restOfRequestInit(init),
 				method: "GET",
 				headers: newHeaders,
-				...init,
 			});
 
 			// Auto-accept the WebSocket if configured (default: true)