From 504cebf32253b92c8d2f009a355db2df45817e21 Mon Sep 17 00:00:00 2001
From: Clemens Stolle <klaemo@fastmail.fm>
Date: Mon, 26 Oct 2026 13:34:34 +0000
Subject: [PATCH 1/2] fix TypeScript definitions for parseUrl, agentOptions and
 RequestError.request. Fixes #362, fixes #380

- restore `parseUrl?: boolean` in `Configuration` and put the
  `headers` doc comment back above `headers`
- type `agentOptions` as an undici `Dispatcher` instance, which is what
  nano passes to `fetch` as `dispatcher`; the previous union of
  constructor types rejected `new Agent()` / `new MockAgent()` and
  accepted values that fail with "agent.dispatch is not a function"
- describe `RequestError.request` as the scrubbed fetch options nano
  attaches (`url`, lower-case `method`, `headers`, `body`, ...)
  instead of the request-era `uri`/`qs` shape

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 lib/nano.d.ts | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/lib/nano.d.ts b/lib/nano.d.ts
index 523cf997..1220ec91 100644
--- a/lib/nano.d.ts
+++ b/lib/nano.d.ts
@@ -20,7 +20,7 @@
 
 import { EventEmitter } from "events";
 import { ConnectionOptions } from "tls";
-import undici from "undici";
+import type { Dispatcher } from "undici";
 
 /** nano entry function */
 declare function nano(
@@ -94,10 +94,11 @@ declare namespace nano {
     url: string;
     /** For cookie authentication */
     cookie?: string;
-    /** HTTP Agent options
+    /** An undici Dispatcher instance (e.g. `new undici.Agent({ connections: 10 })`
+     * or a `MockAgent`), passed to `fetch` as its `dispatcher`
      * @see README: {@link https://www.npmjs.com/package/nano#pool-size-and-open-sockets}
      */
-    agentOptions?: AgentOptions | typeof undici.Agent | typeof undici.MockAgent | typeof undici.Dispatcher;
+    agentOptions?: Dispatcher;
     /** Logging function 
      * @see README: {@link https://www.npmjs.com/package/nano#logging}
      */
@@ -105,10 +106,11 @@ declare namespace nano {
     /** Set to false to prevent parsing of url 
      * @see README: {@link https://www.npmjs.com/package/nano#configuration}
      */
-    headers?: object;
+    parseUrl?: boolean;
     /** Custom request headers
      * @see README: {@link https://www.npmjs.com/package/nano#configuration}
      */
+    headers?: object;
   }
 
   /** An error triggered by nano */
@@ -121,12 +123,20 @@ declare namespace nano {
     scope?: 'couch'  | 'socket';
     /** Status code returned by the server */
     statusCode?: number; // 404;
-    /** Request sent to Couch */
+    /** Request sent to Couch (the options passed to `fetch`, with credentials scrubbed) */
     request?: {
-      method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+      /** Request URL including the query string */
+      url?: string; // 'http://couchhost:5984/db/tsp2?revs_info=true',
+      /** Lower-case HTTP method */
+      method?: string; // 'get', 'put'
       headers?: { [key: string]: string | number };
-      uri?: string; // 'http://couchhost:5984/db/tsp2',
-      qs?: any; // { revs_info: true }
+      body?: any;
+      credentials?: string; // 'include'
+      redirect?: string; // 'error'
+      signal?: AbortSignal;
+      bodyTimeout?: number;
+      /** The `agentOptions` Dispatcher, if one was configured */
+      dispatcher?: Dispatcher;
     };
     /** Response headers */
     headers?: { [key: string]: string | number };

From 6d5fc2b54612029b2df68d0a08b76c0f8876e480 Mon Sep 17 00:00:00 2001
From: Clemens Stolle <klaemo@fastmail.fm>
Date: Wed, 28 Oct 2026 12:52:54 +0000
Subject: [PATCH 2/2] remove the undici import from the TypeScript definitions.
 Fixes #381

undici is only a devDependency, so consumers without it got TS2307 from
`import ... from "undici"` (or an `any`-typed `agentOptions` with
skipLibCheck). Declare a structural `Dispatcher` interface instead; undici
Agent, Pool, MockAgent, ProxyAgent and RetryAgent instances all satisfy it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 lib/nano.d.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/lib/nano.d.ts b/lib/nano.d.ts
index 1220ec91..8f5b5efe 100644
--- a/lib/nano.d.ts
+++ b/lib/nano.d.ts
@@ -20,7 +20,6 @@
 
 import { EventEmitter } from "events";
 import { ConnectionOptions } from "tls";
-import type { Dispatcher } from "undici";
 
 /** nano entry function */
 declare function nano(
@@ -28,6 +27,12 @@ declare function nano(
 ): nano.ServerScope;
 
 declare namespace nano {
+  /** Anything that can be passed to `fetch` as its `dispatcher`, e.g. an
+   * undici `Agent`, `Pool` or `MockAgent` instance. Declared structurally
+   * so that consumers don't need undici's type declarations. */
+  interface Dispatcher {
+    dispatch(options: object, handler: object): boolean;
+  }
   /** AgentOptionsConnect options */
   interface AgentOptionsConnect extends ConnectionOptions {
     /** An IPC endpoint, either Unix domain socket or Windows named pipe.