@firtoz/hono-fetcher 2.4.1 → 2.6.0

package/README.md

@@ -131,19 +131,13 @@ export class ChatRoomDO extends DurableObject {
   }
 }
 
-// In your worker
+// `using api` disposes the stub. Returning the DO `Response` directly is a common pass-through pattern;
+// if you consume the body in this worker instead, also dispose the RPC result (e.g. `using res`).
+// See https://developers.cloudflare.com/workers/runtime-apis/rpc/lifecycle/
 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!
-    const response = await api.get({ url: '/messages' });
-    return response;
+    using api = honoDoFetcherWithName(env.CHAT_ROOM, 'room-1');
+    return api.get({ url: '/messages' });
   }
 };
 ```
@@ -414,44 +408,67 @@ See the [ZodWebSocketClient documentation](#) for more details on type-safe WebS
 
 ## Durable Objects API
 
+All of these return a fetcher that is also a **`Disposable`** for the **stub**: **`api[Symbol.dispose]()`** releases the Durable Object stub only.
+
+**RPC `Response` typing:** **`honoDoFetcherWithName`** / **`honoDoFetcherWithId`** (and **`honoDoFetcher`** when you pass a **full `DurableObjectStub`**) use **`TypedDoFetcher`**: HTTP results are **`RpcDisposableJsonResponse`** and **`websocket`** is **`Response & Disposable`**, so **`using res = await …`** type-checks when Workers RPC attaches disposers. If you pass only **`Pick<DurableObjectStub, "fetch">`** (minimal mock), the return type is **`TypedHonoFetcher<Hono>`** with **plain `JsonResponse` / `Response`**—**not** typed as **`Disposable`**, so we do not pretend mocks have RPC disposers. See [Durable Object stubs and disposal](#durable-object-stubs-and-disposal) and the [RPC lifecycle](https://developers.cloudflare.com/workers/runtime-apis/rpc/lifecycle/) doc.
+
 ### `honoDoFetcher<T>(stub)`
 
 Creates a typed fetcher for a Durable Object stub with support for both HTTP and WebSocket connections.
 
+**Returns:** **`TypedDoFetcher<T> & Disposable`** when **`T`** is a **full `DurableObjectStub<DOWithHonoApp>`**; **`TypedHonoFetcher<Hono> & Disposable`** when **`T`** is only **`Pick<DurableObjectStub<DOWithHonoApp>, "fetch">`** (e.g. unit tests).
+
 ```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' });
+// HTTP — dispose each RPC Response (stub disposal alone is not enough)
+using res = await api.get({ url: '/status' });
+const data = await res.json();
 
-// WebSocket connections
-const wsResp = await api.websocket({ url: '/ws' });
+// WebSocket
+using wsRes = await api.websocket({ url: '/ws' });
+wsRes.webSocket?.accept();
 ```
 
 ### `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' });
+using res = await api.get({ url: '/status' });
+await res.json();
 
-// WebSocket
-await api.websocket({ url: '/chat' });
+using wsRes = await api.websocket({ url: '/chat' });
+wsRes.webSocket?.accept();
 ```
 
 ### `honoDoFetcherWithId<T>(namespace, id)`
 
 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...');
-await api.get({ url: '/status' });
+using api = honoDoFetcherWithId(env.MY_DO, 'abc123...');
+using res = await api.get({ url: '/status' });
+await res.json();
 ```
 
+### Durable Object stubs and disposal
+
+Cloudflare Workers RPC gives **separate disposers** for the **Durable Object stub** and for **non-primitive RPC results** such as the `Response` from `stub.fetch()`. Disposing only the stub can still produce *“An RPC stub was not disposed properly”* if the `Response` was not released. See the official **[Workers RPC lifecycle](https://developers.cloudflare.com/workers/runtime-apis/rpc/lifecycle/)** documentation.
+
+- **Stub (`using api = honoDoFetcherWithName(...)`):** Releases the **stub** when the block ends. This does **not** release RPC **`Response`** objects from individual requests.
+- **Response (HTTP / WebSocket upgrade):** On a **real stub** (`TypedDoFetcher`), TypeScript types those results as **`Disposable`** so **`using res`** / **`using wsRes`** is valid. At runtime, **`[Symbol.dispose]`** is present when Workers RPC attaches it (often in production); **minimal `fetch`-only mocks** are typed as **non-**`Disposable` **`Response`**s because disposers are usually absent. Prefer **`using res`** when types allow it; otherwise call **`res[Symbol.dispose]()`** or use a **`DisposableStack`** as described in Cloudflare’s **[Workers RPC lifecycle](https://developers.cloudflare.com/workers/runtime-apis/rpc/lifecycle/)** documentation. Reading the body does **not** implicitly dispose the RPC result in this library.
+- **Returning `Response` to the client:** **Do not** use **`using res`** on a response you **`return`** from your Worker—disposal can run on scope exit before the runtime finishes serving it. Return the value directly; see **[Workers RPC lifecycle](https://developers.cloudflare.com/workers/runtime-apis/rpc/lifecycle/)** for pass-through patterns.
+- **Vite SSR, some Miniflare setups, or test mocks** may expose stubs or **`Response`** objects without **`Symbol.dispose`**; there is nothing to call in that case.
+- **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`. That applies to **`TypedDoFetcher`** (full **`DurableObjectStub`** path): **`RpcDisposableJsonResponse`** / **`Response & Disposable`** on **`websocket`**. **`Pick<stub, "fetch">`** clients get ordinary **`TypedHonoFetcher`** return types without **`Disposable`** on responses. Cloudflare’s runtime rules for RPC disposal are documented under **[Workers RPC lifecycle](https://developers.cloudflare.com/workers/runtime-apis/rpc/lifecycle/)**.
+
 ## Type Exports
 
 ### `TypedHonoFetcher<T>`
@@ -477,6 +494,10 @@ const response: JsonResponse<{ id: string }> = await api.get({ url: '/user' });
 const data = await response.json(); // Type: { id: string }
 ```
 
+### `RpcDisposableJsonResponse<T>` / `BaseDisposableTypedHonoFetcher<T>` / `HonoDoFetcherStubInput`
+
+**`RpcDisposableJsonResponse<T>`** is **`JsonResponse<T> & Disposable`**. **`BaseDisposableTypedHonoFetcher<T>`** mirrors **`TypedHonoFetcher<T>`** but uses that for HTTP methods and **`Response & Disposable`** for **`websocket`**. **`TypedDoFetcher`** is **`BaseDisposableTypedHonoFetcher<Hono<…, DO schema>>`** — used only when **`honoDoFetcher`** is given a **full `DurableObjectStub`**, or when using **`honoDoFetcherWithName` / `honoDoFetcherWithId`**. **`HonoDoFetcherStubInput`** documents the **`DurableObjectStub | Pick<stub, "fetch">`** union for **`honoDoFetcher`**. Background: **[Workers RPC lifecycle](https://developers.cloudflare.com/workers/runtime-apis/rpc/lifecycle/)** (official disposal / `using` / `DisposableStack` guidance).
+
 ### `WebSocketConfig`
 
 Configuration options for WebSocket connections.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/hono-fetcher",
-	"version": "2.4.1",
+	"version": "2.6.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

@@ -1,6 +1,10 @@
 import type { Hono, Schema } from "hono";
 import type { ExtractSchema } from "hono/types";
-import { honoFetcher, type TypedHonoFetcher } from "./honoFetcher";
+import {
+	honoFetcher,
+	type BaseDisposableTypedHonoFetcher,
+	type TypedHonoFetcher,
+} from "./honoFetcher";
 
 const DUMMY_URL = "http://dummy-url";
 
@@ -24,18 +28,94 @@ export type DOStubSchema<T extends DurableObjectStub> =
 			: never
 		: never;
 
-export type TypedDoFetcher<T extends DurableObjectStub> = TypedHonoFetcher<
-	// biome-ignore lint/suspicious/noExplicitAny: Generic parameter needs flexibility
-	Hono<any, DOStubSchema<T>>
->;
+/**
+ * Fetcher for a **real** `DurableObjectStub`: HTTP results are {@link RpcDisposableJsonResponse}
+ * and `websocket` returns `Response & Disposable`, matching Workers RPC when the runtime attaches
+ * disposers. Use with {@link honoDoFetcher} / {@link honoDoFetcherWithName} / {@link honoDoFetcherWithId}
+ * when `T` is a full stub—not with a minimal `Pick<stub, "fetch">` mock (that path uses plain
+ * {@link TypedHonoFetcher} responses instead).
+ *
+ * @see https://developers.cloudflare.com/workers/runtime-apis/rpc/lifecycle/
+ */
+export type TypedDoFetcher<T extends DurableObjectStub> =
+	BaseDisposableTypedHonoFetcher<
+		// biome-ignore lint/suspicious/noExplicitAny: Generic parameter needs flexibility
+		Hono<any, DOStubSchema<T>>
+	>;
+
+/**
+ * Argument to {@link honoDoFetcher}: a **full** {@link DurableObjectStub} (production) or a minimal
+ * **`{ fetch }`** mock. Only the full stub is typed as {@link TypedDoFetcher} with disposable RPC
+ * responses; **`Pick<stub, "fetch">`** is typed as {@link TypedHonoFetcher} for `Hono` with ordinary
+ * `JsonResponse` / `Response` (no `Disposable` on results—matches mocks without `Symbol.dispose`).
+ *
+ * @see https://developers.cloudflare.com/workers/runtime-apis/rpc/lifecycle/
+ */
+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 DurableObjectStub<DOWithHonoApp>>(
+/**
+ * Typed fetcher for a Durable Object stub.
+ *
+ * - **Full `DurableObjectStub`:** return type is {@link TypedDoFetcher} **`& Disposable`** — each
+ *   HTTP/WebSocket result is typed as disposable (`RpcDisposableJsonResponse` / `Response & Disposable`)
+ *   so **`using res = await …`** type-checks when `"ESNext.Disposable"` is in `lib`, matching Workers RPC
+ *   when the runtime attaches `[Symbol.dispose]` (see `@see` below).
+ * - **`Pick<stub, "fetch">` only (e.g. tests):** return type is **`TypedHonoFetcher<Hono> & Disposable`**
+ *   — same **`JsonResponse` / `Response`** shapes as {@link honoFetcher}; results are **not** typed as
+ *   `Disposable` so typings are not faked for mocks that lack RPC disposers.
+ *
+ * Disposing only the fetcher (`using api = …`) releases the **stub**; RPC **`Response`** disposal
+ * (when applicable) is separate — prefer **`using res`**, **`res[Symbol.dispose]()`**, or **`DisposableStack`**.
+ *
+ * @see https://developers.cloudflare.com/workers/runtime-apis/rpc/lifecycle/
+ */
+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 +123,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 +135,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

@@ -29,6 +29,17 @@ export type JsonResponse<T> = Omit<Response, "json"> & {
 	json: () => Promise<T>;
 };
 
+/**
+ * {@link JsonResponse} intersected with `Disposable` for Workers RPC: `Response`
+ * values from `DurableObjectStub#fetch()` may implement `[Symbol.dispose]` even
+ * though `Fetcher.fetch` is still typed as `Promise<Response>`. Use with
+ * {@link BaseDisposableTypedHonoFetcher} (and `TypedDoFetcher` from `./honoDoFetcher`) so
+ * `using resp = await api.get(...)` type-checks when `"ESNext.Disposable"` is in `lib`.
+ *
+ * @see https://developers.cloudflare.com/workers/runtime-apis/rpc/lifecycle/
+ */
+export type RpcDisposableJsonResponse<T> = JsonResponse<T> & Disposable;
+
 type HasPathParams<T extends string> = T extends `${string}:${string}`
 	? true
 	: false;
@@ -111,6 +122,16 @@ type SchemaOutput<
 	? JsonResponse<HonoSchema<T>[M][SchemaPath][DollarM]["output"]>
 	: never;
 
+type DoSchemaOutput<
+	T extends Hono,
+	M extends HttpMethod,
+	SchemaPath extends string & keyof HonoSchema<T>[M],
+	DollarM extends `$${M}` & keyof HonoSchema<T>[M][SchemaPath] = `$${M}` &
+		keyof HonoSchema<T>[M][SchemaPath],
+> = "output" extends keyof HonoSchema<T>[M][SchemaPath][DollarM]
+	? RpcDisposableJsonResponse<HonoSchema<T>[M][SchemaPath][DollarM]["output"]>
+	: never;
+
 type BodyParams<
 	TApp extends Hono,
 	TMethod extends HttpMethod,
@@ -171,6 +192,38 @@ export type BaseTypedHonoFetcher<T extends Hono> = {
 		{}
 	: { websocket: TypedWebSocketFetcher<T> });
 
+type TypedDisposableMethodFetcher<T extends Hono, M extends HttpMethod> = <
+	SchemaPath extends string & keyof HonoSchema<T>[M],
+>(
+	request: {
+		url: SchemaPath;
+	} & FetcherParams<SchemaPath> &
+		(M extends "get" | "delete" ? EmptyObject : BodyParams<T, M, SchemaPath>),
+) => Promise<DoSchemaOutput<T, M, SchemaPath>>;
+
+export type TypedDisposableWebSocketFetcher<T extends Hono> = <
+	SchemaPath extends string & keyof HonoSchema<T>["get"],
+>(
+	request: {
+		url: SchemaPath;
+		config?: WebSocketConfig;
+	} & FetcherParams<SchemaPath>,
+) => Promise<Response & Disposable>;
+
+/**
+ * Same shape as {@link BaseTypedHonoFetcher} but HTTP methods return
+ * {@link RpcDisposableJsonResponse} and `websocket` returns `Response & Disposable`
+ * so `using` on RPC results type-checks for Durable Object clients.
+ *
+ * @see https://developers.cloudflare.com/workers/runtime-apis/rpc/lifecycle/
+ */
+export type BaseDisposableTypedHonoFetcher<T extends Hono> = {
+	[M in AvailableMethods<T>]: TypedDisposableMethodFetcher<T, M>;
+} & (keyof HonoSchema<T>["get"] extends never
+	? // biome-ignore lint/complexity/noBannedTypes: We really do want an empty object if the get method is not available
+		{}
+	: { websocket: TypedDisposableWebSocketFetcher<T> });
+
 const createMethodFetcher = <T extends Hono, M extends HttpMethod>(
 	fetcher: (
 		request: string,

package/src/index.ts

@@ -6,6 +6,7 @@ export {
 	type DOSchemaMap,
 	type DOStubSchema,
 	type DOWithHonoApp,
+	type HonoDoFetcherStubInput,
 	honoDoFetcher,
 	honoDoFetcherWithId,
 	honoDoFetcherWithName,
@@ -13,6 +14,7 @@ export {
 } from "./honoDoFetcher";
 // Core fetcher functionality
 export {
+	type BaseDisposableTypedHonoFetcher,
 	type BaseTypedHonoFetcher,
 	type HonoFetcherQueryParamValue,
 	type HonoFetcherQueryParams,
@@ -21,6 +23,8 @@ export {
 	honoFetcher,
 	type JsonResponse,
 	type ParsePathParams,
+	type RpcDisposableJsonResponse,
+	type TypedDisposableWebSocketFetcher,
 	type TypedHonoFetcher,
 	type TypedWebSocketFetcher,
 	type WebSocketConfig,