Documentation tweaked

Author: gkoos

README.md

@@ -289,17 +289,18 @@ Native `fetch`'s controversial behavior of not throwing errors for HTTP error st
 
 ## Documentation
 
-| Topic                                         | Description                                                               |
-| --------------------------------------------- | ------------------------------------------------------------------------- |
-| **[Complete Documentation](./docs/index.md)** | **Start here** - Documentation index and overview                         |
-| **[API Reference](./docs/api.md)**            | Complete API documentation and configuration options                      |
-| **[Plugin Architecture](./docs/plugins.md)**  | Plugin lifecycle, custom plugin authoring, and integration patterns       |
-| **[Deduplication](./docs/deduplication.md)**  | How deduplication works, hash config, optional TTL cleanup, limitations   |
-| **[Error Handling](./docs/errorhandling.md)** | Strategies for managing errors, including `throwOnHttpError`              |
-| **[Advanced Features](./docs/advanced.md)**   | Per-request overrides, pending requests, circuit breakers, custom errors  |
-| **[Hooks & Transformation](./docs/hooks.md)** | Lifecycle hooks, authentication, logging, request/response transformation |
-| **[Usage Examples](./docs/examples.md)**      | Real-world patterns: REST clients, GraphQL, file uploads, microservices   |
-| **[Compatibility](./docs/compatibility.md)**  | Browser/Node.js support, polyfills, framework integration                 |
+| Topic                                                        | Description                                                               |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------- |
+| **[Complete Documentation](./docs/index.md)**                | **Start here** - Documentation index and overview                         |
+| **[API Reference](./docs/api.md)**                           | Complete API documentation and configuration options                      |
+| **[Plugin Architecture](./docs/plugins.md)**                 | Plugin lifecycle, custom plugin authoring, and integration patterns       |
+| **[Deduplication](./docs/deduplication.md)**                 | How deduplication works, hash config, optional TTL cleanup, limitations   |
+| **[Error Handling](./docs/errorhandling.md)**                | Strategies for managing errors, including `throwOnHttpError`              |
+| **[Advanced Features](./docs/advanced.md)**                  | Per-request overrides, pending requests, circuit breakers, custom errors  |
+| **[Production Operations](./docs/production-operations.md)** | Pre-deploy checklist, alerting baseline, and incident playbook            |
+| **[Hooks & Transformation](./docs/hooks.md)**                | Lifecycle hooks, authentication, logging, request/response transformation |
+| **[Usage Examples](./docs/examples.md)**                     | Real-world patterns: REST clients, GraphQL, file uploads, microservices   |
+| **[Compatibility](./docs/compatibility.md)**                 | Browser/Node.js support, polyfills, framework integration                 |
 
 ## Environment Requirements
 

docs/advanced.md

@@ -1,5 +1,7 @@
 # Advanced Features
 
+For deployment readiness, alerting, and incident response, use the canonical runbook in [production-operations.md](./production-operations.md).
+
 ## Per-request Overrides
 
 You can override any client option on a per-request basis by passing it in the `init` parameter:

docs/index.md

@@ -49,6 +49,12 @@
   - Abort behavior for queued requests
   - Integration with dedupe, retries, and circuit breaker
 
+- **[production-operations.md](./production-operations.md)** - Canonical production runbook and checklist
+  - Pre-deployment configuration checklist
+  - Metrics and alerting baseline
+  - Incident playbook for circuit, latency, and rate-limit failures
+  - Recommended baseline configurations
+
 ### **Hooks & Transformation**
 
 - **[hooks.md](./hooks.md)** - Lifecycle hooks and request/response transformation
@@ -83,6 +89,7 @@
 6. **Read [api.md](./api.md)** for full option and plugin reference details
 7. **Read [plugins.md](./plugins.md)** to understand lifecycle, ordering, and custom plugins
 8. **Dive into [advanced.md](./advanced.md)** for retry strategy, circuit behavior, and production patterns
+9. **Use [production-operations.md](./production-operations.md)** when preparing rollout, alerts, and incident response
 
 ### **Alternative Learning Paths**
 
@@ -116,6 +123,7 @@
 | Use `client(url).json()` style shortcuts         | [api.md](./api.md#response-shortcuts-plugin)                 |
 | Reduce tail latency with parallel attempts       | [hedging.md](./hedging.md)                                   |
 | Cap concurrency with queue backpressure          | [bulkhead.md](./bulkhead.md)                                 |
+| Operate ffetch safely in production              | [production-operations.md](./production-operations.md)       |
 
 ## **Key Concepts**
 

docs/plugins.md

@@ -298,6 +298,7 @@ const jsonShortcutPlugin: ClientPlugin<
 ## App-Level Concerns
 
 Plugins provide request-time mechanics, but some resilience concerns are best handled at application boundaries:
+For a deployment checklist, metrics baseline, and incident playbook, see [production-operations.md](./production-operations.md).
 
 - **Graceful circuit recovery**: When a circuit closes, avoid sending all queued or waiting traffic at once. Recover gradually (for example, ramp request rate or release waiting callers in batches) to prevent thundering herd spikes.
 - **Bulkhead boundaries**: Decide bulkhead scope per dependency (service, host, or endpoint class). A single global bulkhead can cause unrelated traffic to compete for the same slots.

docs/production-operations.md

@@ -0,0 +1,102 @@
+# Production Operations Guide
+
+This guide is the canonical runbook for operating `@fetchkit/ffetch` in production.
+
+## 1. Pre-Deployment Checklist
+
+### Core configuration
+
+- [ ] Set `timeout` per dependency SLA (avoid using one global value for everything).
+- [ ] Set `retries` conservatively (`1-3` in most systems).
+- [ ] Decide `throwOnHttpError` policy (`true` for strict exception flow, `false` for response-driven handling).
+- [ ] Use a runtime-appropriate `fetchHandler` for SSR/edge/custom environments.
+
+### Resilience plugins
+
+- [ ] Enable `circuitPlugin` for external dependencies.
+- [ ] Enable `bulkheadPlugin` for dependencies that can saturate under load.
+- [ ] Enable `dedupePlugin` on bursty read-heavy endpoints.
+- [ ] Enable `hedgePlugin` only for safe methods and latency-sensitive paths.
+- [ ] Validate plugin order assumptions when composing multiple plugins.
+
+### Observability and hooks
+
+- [ ] Instrument `before`/`after`/`onError` hooks for logs and metrics.
+- [ ] Track request latency (`p50/p95/p99`) and error-rate by endpoint.
+- [ ] Track resilience signals: circuit opens, bulkhead queue depth, retry counts.
+- [ ] Add request correlation IDs in `transformRequest`.
+
+## 2. Operational Metrics
+
+Minimum metrics to collect:
+
+- Request count by endpoint/method/status
+- Latency histogram (`p50`, `p95`, `p99`)
+- Error count by error class (`TimeoutError`, `CircuitOpenError`, `NetworkError`, `RetryLimitError`, etc.)
+- Circuit breaker open events and duration
+- Bulkhead `activeCount`, `queueDepth`, rejection count
+- Retry attempts and eventual success-after-retry rate
+
+## 3. Alerting Baseline
+
+- Alert on sustained high error rate for a dependency.
+- Alert when circuit remains open beyond expected recovery windows.
+- Alert when bulkhead queue remains near capacity.
+- Alert when `p99` latency regresses significantly from baseline.
+
+## 4. Incident Playbook
+
+### Circuit open incidents
+
+1. Check downstream dependency health first.
+2. Confirm `threshold`/`reset` values are aligned with failure patterns.
+3. Use fallback/degraded responses at app level while circuit is open.
+4. Avoid releasing queued traffic all at once during recovery.
+
+### High latency incidents
+
+1. Check bulkhead saturation (`activeCount`, `queueDepth`).
+2. Check retry inflation (too many retries amplifying load).
+3. If using hedging, verify `delay` and `maxHedges` are tuned for current latency distribution.
+
+### Rate-limit incidents (429)
+
+1. Ensure retry strategy honors `Retry-After` behavior.
+2. Reduce concurrency (`bulkhead`) and hedge aggressiveness.
+3. Add app-level backpressure or queueing upstream.
+
+## 5. Recommended Baseline Configs
+
+### Internal service-to-service client
+
+```typescript
+createClient({
+  timeout: 10_000,
+  retries: 2,
+  plugins: [
+    circuitPlugin({ threshold: 5, reset: 30_000 }),
+    bulkheadPlugin({ maxConcurrent: 20, maxQueue: 100 }),
+    dedupePlugin({ ttl: 30_000 }),
+  ],
+})
+```
+
+### Latency-sensitive read path
+
+```typescript
+createClient({
+  timeout: 5_000,
+  retries: 1,
+  plugins: [
+    dedupePlugin({ ttl: 10_000 }),
+    hedgePlugin({ delay: 75, maxHedges: 1 }),
+  ],
+})
+```
+
+## 6. Related References
+
+- [api.md](./api.md) for full option and plugin reference
+- [plugins.md](./plugins.md) for plugin lifecycle and ordering semantics
+- [advanced.md](./advanced.md) for retry, circuit, and operational patterns
+- [errorhandling.md](./errorhandling.md) for exact error behavior

package.json

@@ -16,7 +16,7 @@
   },
   "homepage": "https://github.com/fetch-kit/ffetch#readme",
   "bugs": "https://github.com/fetch-kit/ffetch/issues",
-  "author": "Your Name <you@example.com>",
+  "author": "Gabor Koos <gabor@gaborkoos.com>",
   "license": "MIT",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",