Enable pluggable fetch implementations

gkoos · gkoos · commit abcc2f3af578 · 2025-09-15T01:55:24.000+01:00
diff --git a/README.md b/README.md
@@ -11,7 +11,9 @@
 
 # @gkoos/ffetch
 
-**A production-ready TypeScript-first drop-in replacement for native fetch.**
+**A production-ready TypeScript-first drop-in replacement for native fetch, or any fetch-compatible implementation.**
+
+ffetch can wrap any fetch-compatible implementation (native fetch, node-fetch, undici, or framework-provided fetch), making it flexible for SSR, edge, and custom environments.
 
 **Key Features:**
 
@@ -49,6 +51,26 @@ const response = await api('https://api.example.com/users')
 const data = await response.json()
 ```
 
+### Using a Custom fetchHandler (SSR, metaframeworks, or polyfills)
+
+```typescript
+// Example: SvelteKit, Next.js, Nuxt, or node-fetch
+import createClient from '@gkoos/ffetch'
+
+// Pass your framework's fetch implementation
+const api = createClient({
+  fetchHandler: fetch, // SvelteKit/Next.js/Nuxt provide their own fetch
+  timeout: 5000,
+})
+
+// Or use node-fetch/undici in Node.js
+import nodeFetch from 'node-fetch'
+const apiNode = createClient({ fetchHandler: nodeFetch })
+
+// All ffetch features work identically
+const response = await api('/api/data')
+```
+
 ### Advanced Example
 
 ```typescript
@@ -57,6 +79,7 @@ const client = createClient({
   timeout: 10000,
   retries: 2,
   circuit: { threshold: 5, reset: 30000 },
+  fetchHandler: fetch, // Use custom fetch if needed
   hooks: {
     before: async (req) => console.log('→', req.url),
     after: async (req, res) => console.log('←', res.status),
@@ -104,6 +127,9 @@ try {
 
 For older environments, see the [compatibility guide](./docs/compatibility.md).
 
+**Custom fetch support:**
+You can pass any fetch-compatible implementation (native fetch, node-fetch, undici, SvelteKit, Next.js, Nuxt, or a polyfill) via the `fetchHandler` option. This makes ffetch fully compatible with SSR, edge, metaframework environments, custom backends, and test runners.
+
 ## CDN Usage
 
 ```html
@@ -117,17 +143,18 @@ For older environments, see the [compatibility guide](./docs/compatibility.md).
 
 ## Fetch vs. Axios vs. `ffetch`
 
-| Feature            | Native Fetch              | Axios                | ffetch                           |
-| ------------------ | ------------------------- | -------------------- | -------------------------------- |
-| Timeouts           | ❌ Manual AbortController | ✅ Built-in          | ✅ Built-in with fallbacks       |
-| Retries            | ❌ Manual implementation  | ❌ Manual or plugins | ✅ Smart exponential backoff     |
-| Circuit Breaker    | ❌ Not available          | ❌ Manual or plugins | ✅ Automatic failure protection  |
-| Request Monitoring | ❌ Manual tracking        | ❌ Manual tracking   | ✅ Built-in pending requests     |
-| Error Types        | ❌ Generic errors         | ⚠️ HTTP errors only  | ✅ Specific error classes        |
-| TypeScript         | ⚠️ Basic types            | ⚠️ Basic types       | ✅ Full type safety              |
-| Hooks/Middleware   | ❌ Not available          | ✅ Interceptors      | ✅ Comprehensive lifecycle hooks |
-| Bundle Size        | ✅ Native (0kb)           | ❌ ~13kb minified    | ✅ ~3kb minified                 |
-| Modern APIs        | ✅ Web standards          | ❌ XMLHttpRequest    | ✅ Fetch + modern features       |
+| Feature              | Native Fetch              | Axios                | ffetch                                                                                 |
+| -------------------- | ------------------------- | -------------------- | -------------------------------------------------------------------------------------- |
+| Timeouts             | ❌ Manual AbortController | ✅ Built-in          | ✅ Built-in with fallbacks                                                             |
+| Retries              | ❌ Manual implementation  | ❌ Manual or plugins | ✅ Smart exponential backoff                                                           |
+| Circuit Breaker      | ❌ Not available          | ❌ Manual or plugins | ✅ Automatic failure protection                                                        |
+| Request Monitoring   | ❌ Manual tracking        | ❌ Manual tracking   | ✅ Built-in pending requests                                                           |
+| Error Types          | ❌ Generic errors         | ⚠️ HTTP errors only  | ✅ Specific error classes                                                              |
+| TypeScript           | ⚠️ Basic types            | ⚠️ Basic types       | ✅ Full type safety                                                                    |
+| Hooks/Middleware     | ❌ Not available          | ✅ Interceptors      | ✅ Comprehensive lifecycle hooks                                                       |
+| Bundle Size          | ✅ Native (0kb)           | ❌ ~13kb minified    | ✅ ~3kb minified                                                                       |
+| Modern APIs          | ✅ Web standards          | ❌ XMLHttpRequest    | ✅ Fetch + modern features                                                             |
+| Custom Fetch Support | ❌ No (global only)       | ❌ No                | ✅ Yes (wrap any fetch-compatible implementation, including framework or custom fetch) |
 
 ## Contributing
 
diff --git a/docs/advanced.md b/docs/advanced.md
@@ -34,14 +34,19 @@ await client('https://api.example.com/v1/metrics', {
 })
 ```
 
+## Custom Fetch Compatibility
+
+ffetch can wrap any fetch-compatible implementation using the `fetchHandler` option. This includes native fetch, node-fetch, undici, or framework-provided fetch (SvelteKit, Next.js, Nuxt, etc.), as well as polyfills and test runners. All advanced features (timeouts, retries, circuit breaker, hooks, pending requests) work identically regardless of the underlying fetch implementation, making ffetch highly flexible for SSR, edge, and custom environments.
+
 ## Pending Requests Monitoring
 
-> **Technical Note:**
-> Every `PendingRequest` always has a `controller` property, even if you did not supply an AbortController. This allows you to abort any pending request programmatically, regardless of how it was created.
+Pending requests and abort logic work identically whether you use the default global fetch or a custom fetch implementation via `fetchHandler`. All requests are tracked, and you can abort them programmatically using the controller in each `PendingRequest`.
+
+Every `PendingRequest` always has a `controller` property, even if you did not supply an AbortController. This allows you to abort any pending request programmatically, regardless of how it was created.
 
-> When multiple signals (user, timeout, transformRequest) are combined and `AbortSignal.any` is not available, ffetch creates a new internal `AbortController` to manage aborts. This controller is always available in `PendingRequest.controller`.
+When multiple signals (user, timeout, transformRequest) are combined and `AbortSignal.any` is not available, ffetch creates a new internal `AbortController` to manage aborts. This controller is always available in `PendingRequest.controller`.
 
-> You can always abort a pending request using `pendingRequest.controller.abort()`, even if you did not provide a controller or signal. This works for all requests tracked in `pendingRequests`.
+You can always abort a pending request using `pendingRequest.controller.abort()`, even if you did not provide a controller or signal. This works for all requests tracked in `pendingRequests`.
 
 You can access and monitor all active requests through the `pendingRequests` property on the client instance:
 
diff --git a/docs/api.md b/docs/api.md
@@ -2,7 +2,7 @@
 
 ## createClient(options?)
 
-Creates a new HTTP client instance with the specified configuration.
+Creates a new HTTP client instance with the specified configuration. You can use ffetch as a drop-in replacement for native fetch, or wrap any fetch-compatible implementation (e.g., node-fetch, undici, SvelteKit/Next.js/Nuxt-provided fetch) for SSR, edge, and custom environments.
 
 ```typescript
 import createClient from '@gkoos/ffetch'
@@ -16,14 +16,15 @@ const client = createClient({
 
 ### Configuration Options
 
-| Option        | Type                                                                                                                      | Default                             | Description                                                       |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------- |
-| `timeout`     | `number` (ms)                                                                                                             | `5000`                              | Whole-request timeout in milliseconds. Use `0` to disable timeout |
-| `retries`     | `number`                                                                                                                  | `0`                                 | Maximum retry attempts                                            |
-| `retryDelay`  | `number \| (ctx: { attempt, request, response, error }) => number`                                                        | Exponential backoff + jitter        | Delay between retries                                             |
-| `shouldRetry` | `(ctx: { attempt, request, response, error }) => boolean`                                                                 | Retries on network errors, 5xx, 429 | Custom retry logic                                                |
-| `circuit`     | `{ threshold: number, reset: number }`                                                                                    | `undefined`                         | Circuit-breaker configuration                                     |
-| `hooks`       | `{ before, after, onError, onRetry, onTimeout, onAbort, onCircuitOpen, onComplete, transformRequest, transformResponse }` | `{}`                                | Lifecycle hooks and transformers                                  |
+| Option         | Type                                                                                                                      | Default                                        | Description                                                       |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `timeout`      | `number` (ms)                                                                                                             | `5000`                                         | Whole-request timeout in milliseconds. Use `0` to disable timeout |
+| `retries`      | `number`                                                                                                                  | `0`                                            | Maximum retry attempts                                            |
+| `retryDelay`   | `number \| (ctx: { attempt, request, response, error }) => number`                                                        | Exponential backoff + jitter                   | Delay between retries                                             |
+| `shouldRetry`  | `(ctx: { attempt, request, response, error }) => boolean`                                                                 | Retries on network errors, 5xx, 429            | Custom retry logic                                                |
+| `circuit`      | `{ threshold: number, reset: number }`                                                                                    | `undefined`                                    | Circuit-breaker configuration                                     |
+| `hooks`        | `{ before, after, onError, onRetry, onTimeout, onAbort, onCircuitOpen, onComplete, transformRequest, transformResponse }` | `{}`                                           | Lifecycle hooks and transformers                                  |
+| `fetchHandler` | `(input: RequestInfo                                                                                                      | URL, init?: RequestInit) => Promise<Response>` | `global fetch`                                                    | Custom fetch-compatible implementation to wrap (e.g., SvelteKit, Next.js, Nuxt, node-fetch, undici, or any polyfill). Defaults to global fetch. |
 
 ### Return Type
 
@@ -38,6 +39,10 @@ type FFetch = (
     shouldRetry?: (ctx: RetryContext) => boolean
     circuit?: { threshold: number; reset: number }
     hooks?: HooksConfig
+    fetchHandler?: (
+      input: RequestInfo | URL,
+      init?: RequestInit
+    ) => Promise<Response>
   }
 ) => Promise<Response>
 ```
@@ -116,3 +121,26 @@ interface HooksConfig {
   ) => Promise<Response> | Response
 }
 ```
+
+### Usage Examples
+
+```typescript
+import createClient from '@gkoos/ffetch'
+
+// Basic usage
+const client = createClient({
+  timeout: 5000,
+  retries: 3,
+})
+
+// Pass a custom fetch-compatible implementation (SSR, metaframeworks, polyfills, node-fetch, undici, etc.)
+const client = createClient({
+  timeout: 5000,
+  retries: 3,
+  fetchHandler: fetch, // SvelteKit/Next.js/Nuxt provide their own fetch
+})
+
+// Or use node-fetch/undici in Node.js
+import nodeFetch from 'node-fetch'
+const clientNode = createClient({ fetchHandler: nodeFetch })
+```
diff --git a/docs/compatibility.md b/docs/compatibility.md
@@ -141,13 +141,18 @@ await client('https://api.external.com/data', {
 
 ## Environment Detection
 
-`ffetch` automatically adapts to the environment:
+`ffetch` automatically adapts to the environment and can wrap any fetch-compatible implementation:
 
 ```javascript
 // Automatically detects environment and uses appropriate fetch implementation
-const client = createClient()
+// Or pass your own fetch-compatible implementation for SSR, edge, or custom environments
+const client = createClient() // Uses global fetch by default
+
+// Example: Use node-fetch, undici, or framework-provided fetch
+import fetch from 'node-fetch'
+const clientNode = createClient({ fetchHandler: fetch })
 
-// Works in Node.js, browsers, workers, etc.
+// Works in Node.js, browsers, workers, SSR, edge, etc.
 const response = await client('https://api.example.com')
 ```
 
@@ -348,6 +353,47 @@ onUnmounted(() => {
 <div>{data ? JSON.stringify(data) : 'Loading...'}</div>
 ```
 
+### SSR Frameworks: SvelteKit, Next.js, Nuxt
+
+For SvelteKit, Next.js, and Nuxt, you must pass the exact fetch instance provided by the framework in your handler or context. This is not the global fetch, and the parameter name may vary (often `fetch`, but check your framework docs).
+
+**SvelteKit example:**
+
+```typescript
+// In load functions, actions, or endpoints, use the provided fetch
+export async function load({ fetch }) {
+  const client = createClient({ fetchHandler: fetch })
+  // Use client for SSR-safe requests
+}
+
+// In endpoints
+export async function GET({ fetch }) {
+  const client = createClient({ fetchHandler: fetch })
+  // ...
+}
+```
+
+**Nuxt example:**
+
+```typescript
+// In server routes, use event.fetch
+export default defineEventHandler((event) => {
+  const client = createClient({ fetchHandler: event.fetch })
+  // ...
+})
+```
+
+**Next.js edge API route (if fetch is provided):**
+
+```typescript
+export default async function handler(request) {
+  const client = createClient({ fetchHandler: request.fetch })
+  // ...
+}
+```
+
+> Always use the fetch instance provided by the framework in your handler/context, not the global fetch. The parameter name may vary, but it is always context-specific.
+
 ## Troubleshooting
 
 ### Common Issues
diff --git a/docs/examples.md b/docs/examples.md
@@ -91,6 +91,36 @@ const users = await api.get<User[]>('/users')
 const newUser = await api.post<User>('/users', { name: 'John' })
 ```
 
+## Custom Fetch Usage
+
+### Using ffetch with a Custom Fetch (e.g., node-fetch)
+
+```typescript
+import createClient from '@gkoos/ffetch'
+import fetch from 'node-fetch'
+
+const client = createClient({ fetchHandler: fetch })
+const response = await client('https://api.example.com/data')
+const data = await response.json()
+```
+
+### Injecting a Mock Fetch for Unit Tests
+
+```typescript
+import createClient from '@gkoos/ffetch'
+
+function mockFetch(url, options) {
+  return Promise.resolve(
+    new Response(JSON.stringify({ ok: true, url }), { status: 200 })
+  )
+}
+
+const client = createClient({ fetchHandler: mockFetch })
+const response = await client('https://api.example.com/test')
+const data = await response.json()
+// data: { ok: true, url: 'https://api.example.com/test' }
+```
+
 ## Advanced Patterns
 
 ### Microservices Client
diff --git a/docs/index.md b/docs/index.md
@@ -90,6 +90,7 @@
 - **Circuit Breaker**: Automatic failure protection and recovery
 - **Hooks**: Lifecycle events for logging, auth, and transformation
 - **Pending Requests**: Real-time monitoring of active requests
+- **Custom fetch wrapping**: Pluggable fetch implementation for SSR, node-fetch, undici, and framework-provided fetch
 
 ### **Error Handling**
 
diff --git a/docs/migration.md b/docs/migration.md
@@ -43,7 +43,18 @@ const response = await client('https://api.example.com/data', {
 
 ## Key Compatibility Points
 
-### ✅ **Fully Compatible**
+### ✅ **Fully Compatible & Pluggable**
+
+ffetch can now be used as a drop-in wrapper for custom fetch implementations. This makes migration easier for SSR/metaframeworks (SvelteKit, Next.js, Nuxt, etc.) and for environments where you need to provide your own fetch (e.g., node-fetch, undici, framework-provided fetch).
+
+Simply pass your custom fetch implementation using the `fetchHandler` option:
+
+```typescript
+import createClient from '@gkoos/ffetch'
+import fetch from 'node-fetch'
+
+const client = createClient({ fetchHandler: fetch })
+```
 
 These work exactly the same as native fetch:
 
diff --git a/src/client.ts b/src/client.ts
@@ -23,6 +23,7 @@ export function createClient(opts: FFetchOptions = {}): FFetch {
     shouldRetry: clientDefaultShouldRetry = defaultShouldRetry,
     hooks: clientDefaultHooks = {},
     circuit: clientDefaultCircuit,
+    fetchHandler,
   } = opts
 
   const breaker = clientDefaultCircuit
@@ -220,7 +221,8 @@ export function createClient(opts: FFetchOptions = {}): FFetch {
               signal: combinedSignal,
             })
             try {
-              return await fetch(reqWithSignal)
+              const handler = fetchHandler ?? fetch
+              return await handler(reqWithSignal)
             } catch (err) {
               throw mapToCustomError(err)
             }
diff --git a/src/types.ts b/src/types.ts
@@ -14,6 +14,10 @@ export interface FFetchOptions {
   shouldRetry?: (ctx: RetryContext) => boolean
   circuit?: { threshold: number; reset: number }
   hooks?: Hooks
+  fetchHandler?: (
+    input: RequestInfo | URL,
+    init?: RequestInit
+  ) => Promise<Response>
 }
 
 export type FFetch = {
diff --git a/test/client.fetchHandler.test.ts b/test/client.fetchHandler.test.ts
