Documentation errors fixed

Author: gkoos

README.md

@@ -156,12 +156,12 @@ Native `fetch`'s controversial behavior of not throwing errors for HTTP error st
 
 ## Environment Requirements
 
-`ffetch` requires modern AbortSignal APIs:
+`ffetch` works best with native `AbortSignal.any` support:
 
-- **Node.js 20.6+** (for AbortSignal.any)
-- **Modern browsers** (Chrome 117+, Firefox 117+, Safari 17+, Edge 117+)
+- **Node.js 20.6+** (native `AbortSignal.any`)
+- **Modern browsers with `AbortSignal.any`** (for example: Chrome 117+, Firefox 117+, Safari 17+, Edge 117+)
 
-If your environment does not support `AbortSignal.any` (Node.js < 20.6, older browsers), you **must install a polyfill** before using ffetch. See the [compatibility guide](./docs/compatibility.md) for instructions.
+If your environment does not support `AbortSignal.any` (Node.js < 20.6, older browsers), you can still use ffetch by installing an `AbortSignal.any` polyfill. `AbortSignal.timeout` is optional because ffetch includes an internal timeout fallback. See the [compatibility guide](./docs/compatibility.md) for instructions.
 
 **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.

docs/advanced.md

@@ -126,7 +126,7 @@ You can provide a function for `retryDelay` that receives a context object:
 ```typescript
 const client = createClient({
   retryDelay: ({ attempt, request, response, error }) => {
-    // attempt: number (starts at 2 for first retry)
+    // attempt: number (starts at 1 for first retry decision)
     // request: Request
     // response: Response | undefined
     // error: unknown
@@ -198,13 +198,14 @@ This is useful for:
 - Implementing custom fallback or degraded mode logic
 - Integrating with dashboards or metrics
 
-> **Note:** If the client is not configured with a circuit breaker (`circuit` option omitted), `client.circuitOpen` will always be `false` and the property is inert.
+> **Note:** `client.circuitOpen` is provided by `circuitPlugin`. If that plugin is not installed, this extension is not available on the client.
 
 ### How it Works
 
 - When the number of consecutive failures reaches the `threshold`, the circuit "opens" and all further requests fail fast with a `CircuitOpenError`
 - After the `reset` period (in milliseconds), the circuit "closes" and requests are allowed again
 - If a request succeeds, the failure count resets
+- If `onCircuitOpen` is configured, it runs both when the circuit opens and when requests are blocked while it is already open
 
 ### Configuration
 

docs/api.md

@@ -116,7 +116,7 @@ See [plugins.md](./plugins.md) for full lifecycle, ordering, extensions, and adv
 
 ### Removed Legacy Options (Breaking)
 
-The following top-level options were removed and now throw a migration error if passed:
+The following top-level options were removed:
 
 - `dedupe`
 - `dedupeHashFn`
@@ -164,5 +164,5 @@ type FFetch = {
 ### Notes
 
 - Signal combination (user, timeout, transformRequest) requires `AbortSignal.any`.
-- The first retry attempt uses `attempt = 2`.
+- The first retry decision uses `attempt = 1`.
 - Plugin order is deterministic: first by `order`, then by registration order.

docs/compatibility.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-`ffetch` requires modern AbortSignal APIs, specifically `AbortSignal.timeout` and **AbortSignal.any**. Signal combination requires `AbortSignal.any` (native or polyfill).
+`ffetch` can work without native `AbortSignal.timeout` because it has an internal timeout fallback. Signal combination requires **`AbortSignal.any`** (native or polyfill).
 
 ## Node.js Support
 
@@ -13,7 +13,8 @@
 
 ### Polyfills for Older Versions
 
-For older Node.js versions, you must install a polyfill for both `AbortSignal.timeout` and `AbortSignal.any`:
+For older Node.js versions, you must install a polyfill for `AbortSignal.any`.
+`AbortSignal.timeout` polyfill is optional because `ffetch` has an internal timeout fallback:
 
 ```bash
 npm install abortcontroller-polyfill abort-controller-x
@@ -22,10 +23,10 @@ npm install abortcontroller-polyfill abort-controller-x
 Then ensure the APIs are available globally before importing `ffetch`:
 
 ```javascript
-// Option 1: abortcontroller-polyfill (for AbortSignal.timeout)
+// Optional: abortcontroller-polyfill (for native-style AbortSignal.timeout)
 require('abortcontroller-polyfill/dist/polyfill-patch-fetch')
 
-// Option 2: abort-controller-x (for AbortSignal.any)
+// Required when AbortSignal.any is missing
 import 'abort-controller-x/polyfill'
 
 // Now you can use ffetch
@@ -43,50 +44,60 @@ await client('https://api.example.com') // Works
 await client('http://localhost:3000') // Works
 ```
 
-#### Custom Agents
+#### Custom Node Connection Agent
 
 ```javascript
 import https from 'https'
+import fetch from 'node-fetch'
 
-const client = createClient()
-
-// Use custom HTTPS agent
-await client('https://api.example.com', {
-  agent: new https.Agent({
-    keepAlive: true,
-    timeout: 5000,
-  }),
+const agent = new https.Agent({
+  keepAlive: true,
+  timeout: 5000,
 })
+
+// Wrap your fetch implementation and inject transport-specific options there.
+const fetchWithAgent = (input, init) => fetch(input, { ...init, agent })
+
+const client = createClient({ fetchHandler: fetchWithAgent })
+
+await client('https://api.example.com')
 ```
 
+`agent` is fetch-implementation-specific and not part of standard `RequestInit`. Prefer configuring it inside `fetchHandler`.
+
 #### Self-signed Certificates (Development)
 
 ```javascript
 // For development only - never use in production
 process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'
 
-// Better approach: use custom agent
+// Better approach: configure a custom agent in fetchHandler
 import https from 'https'
+import fetch from 'node-fetch'
 
 const agent = new https.Agent({
   rejectUnauthorized: false,
 })
 
-await client('https://localhost:8443', { agent })
+const client = createClient({
+  fetchHandler: (input, init) => fetch(input, { ...init, agent }),
+})
+
+await client('https://localhost:8443')
 ```
 
 ## Browser Support
 
 ### Modern Browsers (Recommended)
 
-- **Chrome 88+**: Full support
-- **Firefox 89+**: Full support
-- **Safari 15.4+**: Full support
-- **Edge 88+**: Full support
+- **Chrome 117+**: Native support for required AbortSignal APIs
+- **Firefox 117+**: Native support for required AbortSignal APIs
+- **Safari 17+**: Native support for required AbortSignal APIs
+- **Edge 117+**: Native support for required AbortSignal APIs
 
 ### Legacy Browser Support
 
-For older browsers, you need polyfills for `AbortSignal.timeout` and `AbortSignal.any`:
+Older browsers can still work when `AbortSignal.any` is polyfilled. `AbortSignal.timeout` polyfill is optional:
 
 ```html
 <!-- Include polyfills before your app -->
@@ -95,7 +106,7 @@ For older browsers, you need polyfills for `AbortSignal.timeout` and `AbortSigna
 
 <!-- Your app -->
 <script type="module">
-  import createClient from 'https://unpkg.com/@fetchkit/ffetch/dist/index.min.js'
+  import { createClient } from 'https://unpkg.com/@fetchkit/ffetch/dist/index.min.js'
   // ... your code
 </script>
 ```
@@ -118,8 +129,8 @@ self.addEventListener('fetch', async (event) => {
 #### Web Workers
 
 ```javascript
-// Works in web workers
-importScripts('https://unpkg.com/@fetchkit/ffetch/dist/index.min.js')
+// Use a module worker and import the ESM build
+import { createClient } from 'https://unpkg.com/@fetchkit/ffetch/dist/index.min.js'
 
 const client = createClient()
 self.postMessage(await client('/api/data').then((r) => r.json()))
@@ -202,10 +213,6 @@ function checkCompatibility() {
     throw new Error('AbortSignal not supported. Please add a polyfill.')
   }
 
-  if (typeof AbortSignal.timeout !== 'function') {
-    throw new Error('AbortSignal.timeout not supported. Please add a polyfill.')
-  }
-
   if (typeof AbortSignal.any !== 'function') {
     throw new Error(
       'AbortSignal.any is required for combining multiple signals. Please install a polyfill.'
@@ -234,22 +241,16 @@ const client = createClient({
 
 ```html
 <script type="module">
-  import createClient from 'https://unpkg.com/@fetchkit/ffetch/dist/index.min.js'
+  import { createClient } from 'https://unpkg.com/@fetchkit/ffetch/dist/index.min.js'
 
   const client = createClient()
   const data = await client('/api/data').then((r) => r.json())
 </script>
 ```
 
-### UMD (Legacy)
+### UMD
 
-```html
-<script src="https://unpkg.com/@fetchkit/ffetch/dist/index.umd.js"></script>
-<script>
-  const client = FFetch.createClient()
-  // ... use client
-</script>
-```
+`ffetch` does not currently publish a UMD build. Use the ESM build shown above (or import from the package in a bundler/runtime environment).
 
 ## Framework Integration
 
@@ -355,7 +356,7 @@ onUnmounted(() => {
 
 ### 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).
+For SvelteKit, Next.js, and Nuxt, it is recommended to pass the fetch instance provided by the framework in your handler or context for SSR-safe behavior. The parameter name may vary (often `fetch`, but check your framework docs).
 
 **SvelteKit example:**
 
@@ -392,7 +393,7 @@ export default async function handler(request) {
 }
 ```
 
-> 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.
+> Recommended: use the fetch instance provided by the framework in handler/context code. ffetch also supports any fetch-compatible implementation and falls back to global fetch when no `fetchHandler` is provided.
 
 ## Troubleshooting
 
@@ -401,7 +402,9 @@ export default async function handler(request) {
 #### "AbortSignal.timeout is not a function"
 
 ```
-Solution: Add a polyfill for AbortSignal.timeout
+ffetch has an internal fallback, so this is usually non-fatal.
+
+Optional: add a polyfill for AbortSignal.timeout
 npm install abortcontroller-polyfill
 ```
 

docs/examples.md

@@ -24,7 +24,7 @@ if (client.circuitOpen) {
 }
 ```
 
-// If the client is not configured with a circuit breaker, client.circuitOpen will always be false.
+// `client.circuitOpen` is available when `circuitPlugin(...)` is installed on the client.
 
 ### Simple HTTP Client
 

docs/hooks.md

@@ -4,15 +4,29 @@ Hooks allow you to observe, log, or modify the request/response lifecycle. All h
 
 ## Lifecycle Hooks
 
+In this document, **core hooks** means the callbacks under `createClient({ hooks: ... })`:
+
+- `before`
+- `after`
+- `onError`
+- `onRetry`
+- `onTimeout`
+- `onAbort`
+- `onComplete`
+- `transformRequest`
+- `transformResponse`
+
+These are separate from plugin lifecycle callbacks (`setup`, `preRequest`, `wrapDispatch`, `onSuccess`, `onError`, `onFinally`).
+
 ### Available Hooks
 
 - `before(req)`: Called before each request is sent
 - `after(req, res)`: Called after a successful response
-- `onError(req, err)`: Called when a request fails with any error
+- `onError(req, err)`: Called when core request execution fails (before plugin post-processing)
 - `onRetry(req, attempt, err, res)`: Called before each retry attempt
 - `onTimeout(req)`: Called when a request times out
 - `onAbort(req)`: Called when a request is aborted by the user
-- `onComplete(req, res, err)`: Called after every request, whether it succeeded or failed
+- `onComplete(req, res, err)`: Called when core request execution completes (last among core hooks)
 
 ### Basic Hooks Example
 
@@ -256,10 +270,11 @@ const client = createClient({
   retries: 3,
   hooks: {
     onRetry: async (req, attempt, err, res) => {
-      console.log(`Retry ${attempt - 1}/3 for ${req.url}`)
+      // `attempt` is zero-based in onRetry (0 = first retry)
+      console.log(`Retry ${attempt + 1}/3 for ${req.url}`)
 
       // Add exponential backoff delay
-      const delay = Math.min(1000 * Math.pow(2, attempt - 2), 10000)
+      const delay = Math.min(1000 * Math.pow(2, attempt), 10000)
       console.log(`Waiting ${delay}ms before retry...`)
       await new Promise((resolve) => setTimeout(resolve, delay))
 
@@ -276,7 +291,7 @@ const client = createClient({
 
 ### onCircuitOpen
 
-Called when the circuit transitions to open after consecutive failures. Receives the request that triggered the open event.
+Called when the circuit opens after consecutive failures, and also when a request is blocked while the circuit is already open. Receives the request associated with that event.
 
 Signature: `(req: Request) => void | Promise<void>`
 
@@ -313,17 +328,20 @@ When a request is made, hooks execute in this order:
 3. **Request is sent**
 4. `transformResponse` - Modify the incoming response (if successful)
 5. `after` - Called after successful response
-6. `onComplete` - Always called last
+6. `onComplete` - Last among core hooks
 
 If an error occurs or retry is needed:
 
-1. `onError` - Called on any error
+1. `onError` - Called on core execution errors
 2. `onRetry` - Called before retry attempts
 3. `onTimeout` - Called on timeout errors
 4. `onAbort` - Called on abort errors
-5. Plugin `onCircuitOpen` callback - Called when circuit breaker transitions to open
+5. Plugin `onCircuitOpen` callback - Called when circuit opens, and on blocked requests while already open
 6. Plugin `onCircuitClose` callback - Called when circuit breaker transitions to closed
-7. `onComplete` - Always called last
+7. `onComplete` - Last among core hooks
+
+After core hooks run, plugin lifecycle callbacks may still run (for example plugin `onSuccess`, `onError`, and `onFinally`).
+If a plugin throws after core completion, core `onError` is not re-fired and core `onComplete` may already have run with success arguments.
 
 ## Per-Request Hooks
 

docs/migration.md

@@ -127,11 +127,7 @@ const plugins = [circuitPlugin({ threshold: 5, reset: 30_000 })] as const
 const client = createClient({ plugins })
 ```
 
-## 6) Runtime Guard for Legacy Options
-
-v5 throws a clear runtime error if removed options are still present in client options or per-request init.
-
-## 7) Quick Upgrade Checklist
+## 6) Quick Upgrade Checklist
 
 1. Replace default root import with named root import.
 2. Add plugin imports from: