npm - vigor-fetch - Versions diffs - 3.1.8 → 4.0.0 - Mend

vigor-fetch 3.1.8 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -1,1143 +1,471 @@
-# vigor-fetch
-## Vigor is a composable, lightweighted (minified + gzipped ~5.8kb) network workflow toolkit built on top of native Fetch.
-> Vigor provides a fluent, chainable API for building robust network logic with built-in retry, backoff, interceptors, parsing, and concurrency control.
----
-## Features
-- 🧩 **Fluent & Immutable API** — Fully composable, side-effect-free chaining
-- 🔁 **Advanced Retry System** — Constant, linear, backoff, custom delay with jitter support.
-- 🌐 **Smart Fetch Layer** — Automatic 429 handling & configurable retry rules
-- ⚡ **Parallel Requests** — Concurrency-limited task runner
-- 🔌 **Smart Response Parsing** — Auto parsing based on Content-Type, Sniffing
-- ⚡ **Zero Dependencies** — Built on native Fetch + AbortController
-- 🪝 **Powerful Interceptors** — Lifecycle hooks for full control flow
-- 🧠 **TypeScript First** — Fully typed inference across all modules
----
-## Installation
-```bash
-npm  install  vigor-fetch
-```
-## Why Vigor?
-| Feature | Vigor | Axios | Ky | Got |
-|---|:---:|:---:|:---:|:---:|
-| Runtime | Browser + Node | Browser + Node | Browser + Node | Primarily Node.js |
-| Built on Fetch | ✅ Native Fetch-based | ❌ Custom adapter-based | ✅ | ❌ |
-| Immutable Fluent Builder | ✅ | ❌ | ⚠️ Partial | ⚠️ Partial |
-| Built-in Retry Engine | ✅ Advanced | ⚠️ Limited | ✅ | ✅ |
-| Custom Retry Algorithms | ✅ | ❌ | ⚠️ Limited | ⚠️ Limited |
-| Retry Interceptors | ✅ | ❌ | ❌ | ❌ |
-| Automatic RateLimit Handling (`429`) | ✅ | ❌ | ⚠️ Partial | ✅ |
-| Automatic Content-Type Parsing | ✅ | ⚠️ Mostly JSON | ✅ | ✅ |
-| Standalone Parse Engine | ✅ | ❌ | ❌ | ❌ |
-| Custom Parsing Strategies | ✅ | ❌ | ❌ | ⚠️ Hook-level |
-| Lifecycle Interceptors | ✅ Full lifecycle | ✅ | ⚠️ Hook-based | ✅ Hook-based |
-| Concurrency Queue Engine | ✅ | ❌ | ❌ | ❌ |
-| Default Fallback Values | ✅ | ❌ | ❌ | ❌ |
-## Quick Start
-### Fetch
-```ts
-import vigor from "vigor-fetch";
-const data = await vigor
-	.fetch("https://api.example.com", "api")
-	.path("v1", "main")
-	.request();
-// -> https://api.example.com/api/v1/main
-```
-#### Advanced
-```ts
-const data = await vigor
-  .fetch("https://api.example.com")
-  .path("users")
-  .retryConfig(r => r
-	  .settings(s => s.attempt(5))
-  )
-  .parseConfig(p => p
-  .strategies(s => s.sniff())
-  )
-  .interceptors(i => i
-	  .onError((ctx, api) => {
-	      api.restart();
-	   })
-  )
-  .request();
-```
-### Retry
-```ts
-import vigor from "vigor-fetch";
-const data = await vigor
-	.retry(async(ctx, {signal, abort}) => {
-		return await db.select(~)
-	})
-	.request()
-```
-### Parse
-```ts
-import vigor from "vigor-fetch";
-const response = await fetch("https://api.example.com");
-const data = await vigor
-	.parse(response)
-	.request();
-```
-### Concurrency
-```ts
-import vigor from "vigor-fetch";
-const data = await vigor
-	.all(
-		async () => fetch("/api/1"),
-		async () => fetch("/api/2")
-	)
-	.request();
-```
-## vigor.retry
-### Methods
-| Method | Description |
-|---|---|
-| target(fn) | Sets retry target function |
-| settings(fn \| config) | Configures retry settings |
-| interceptors(fn \| config) | Configures retry interceptors |
-| algorithms(fn) | Configures retry delay algorithm |
-| abortSignals(...signals) | Attaches external AbortSignals |
-| request(config?) | Executes retry pipeline |
----
-### target
-Sets the retry target.
-```ts
-vigor.retry(async () => {
-	return await fetch("/api");
-})
-```
----
-### settings
-Configures retry behavior.
-```ts
-.settings(s => s
-	.attempt(10)
-	.timeout(5000)
-	.jitter(1000)
-)
-```
-#### Settings API
-| Method | Description | Default |
-|---|---|---|
-| attempt(number) | Maximum retry attempts | `5` |
-| timeout(ms) | Timeout per attempt | `20000` |
-| jitter(ms) | Random retry jitter | `1000` |
-| default(value) | Fallback return value | `throws` |
----
-### algorithms
-Configures retry delay algorithm.
-```ts
-.algorithms(a => a
-	.backoff()
-	.initial(1000)
-	.multiplier(2)
-)
-```
----
-## Retry Algorithms
-### constant
-Fixed retry delay.
-```ts
-.algorithms(a => a
-	.constant()
-	.interval(2000)
-)
-```
-#### API
-| Method | Description |
-|---|---|
-| interval(ms) | Fixed retry interval |
----
-### linear
-Linearly increasing delay.
-```ts
-.algorithms(a => a
-	.linear()
-	.initial(1000)
-	.increment(1000)
-)
-```
-#### API
-| Method | Description |
-|---|---|
-| initial(ms) | Initial delay |
-| increment(ms) | Delay increment |
-| minDelay(ms) | Minimum delay |
-| maxDelay(ms) | Maximum delay |
----
-### backoff
-Exponential backoff delay.
-```ts
-.algorithms(a => a
-	.backoff()
-	.initial(1000)
-	.multiplier(1.7)
-)
-```
-#### API
-| Method | Description |
-|---|---|
-| initial(ms) | Initial delay |
-| multiplier(number) | Exponential multiplier |
-| unit(ms) | Delay unit |
-| minDelay(ms) | Minimum delay |
-| maxDelay(ms) | Maximum delay |
----
-### custom
-Fully custom retry algorithm.
-```ts
-.algorithms(a => a
-	.custom()
-	.func(attempt => {
-		return attempt * 3000;
-	})
-)
-```
-#### API
-| Method | Description |
-|---|---|
-| func(fn) | Custom delay calculator |
----
-### abortSignals
-Attaches external AbortSignals.
-```ts
-const controller = new AbortController();
-await vigor
-	.retry(task)
-	.abortSignals(controller.signal)
-	.request();
-```
----
-### request
-Executes retry workflow.
-```ts
-const result = await vigor
-	.retry(task)
-	.request();
-```
----
-## Interceptors
-| Name | API |
-|---|:---:|
-| before | throwError / breakRetry / abort |
-| after | setResult / throwError / breakRetry |
-| result | setResult / throwError |
-| retryIf | proceedRetry / cancelRetry |
-| onRetry | throwError / setDelay / setAttempt |
-| onError | setResult / throwError / restart |
----
-### before
-Runs before each retry attempt.
-```ts
-.before(async (ctx, api) => {
-	console.log(ctx.attempt);
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| throwError(error) | Immediately throws an error |
-| breakRetry(error) | Stops retry loop immediately |
-| abort(error) | Aborts current request |
----
-### after
-Runs after successful task execution.
-```ts
-.after(async (ctx, api) => {
-	api.setResult({
-		wrapped: ctx.result
-	});
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| setResult(value) | Replaces current result |
-| throwError(error) | Throws an error |
-| breakRetry(error) | Stops retry loop |
----
-### result
-Runs before returning final result.
-```ts
-.result(async (ctx, api) => {
-	api.setResult(transform(ctx.result));
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| setResult(value) | Replaces current result |
-| throwError(error) | Throws an error |
----
-### retryIf
-Controls retry continuation.
-```ts
-.retryIf(async (ctx, api) => {
-	if (ctx.error instanceof TypeError) {
-		api.proceedRetry();
-	}
-	else {
-		api.cancelRetry();
-	}
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| proceedRetry() | Continues retry |
-| cancelRetry() | Cancels retry |
----
-### onRetry
-Runs before retry delay.
-```ts
-.onRetry(async (ctx, api) => {
-	api.setDelay(5000);
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| throwError(error) | Throws an error |
-| setDelay(ms) | Overrides retry delay |
-| setAttempt(num) | Overrides attempt count |
----
-### onError
-Runs after retry exhaustion.
-```ts
-.onError(async (ctx, api) => {
-	console.error(ctx.error);
-	api.restart();
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| setResult(value) | Returns fallback value |
-| throwError(error) | Throws an error |
-| restart() | Restarts retry pipeline |
----
-## vigor.parse
-### Methods
-| Method | Description |
-|---|---|
-| target(response) | Sets target Response object |
-| settings(fn \| config) | Configures parser settings |
-| strategies(fn) | Configures parser strategies |
-| parsers(fn \| config) | Registers custom parsers |
-| interceptors(fn \| config) | Configures parser interceptors |
-| request(config?) | Executes parse pipeline |
----
-### target
-Sets the target `Response`.
-```ts
-const response = await fetch("/api");
-await vigor
-  .parse(response)
-  .request();
-```
----
-### settings
-Configures parser behavior.
-```ts
-.settings(s =>
-  s
-    .original(false)
-    .fallback(null)
-)
-```
-#### Settings API
-| Method | Description | Default |
-|---|---|---|
-| original(boolean) | Returns original Response object | `false` |
-| fallback(value) | Fallback return value on parse failure | `throws` |
----
-### strategies
-Configures parser strategy.
-```ts
-.strategies(s =>
-  s.contentType()
-)
-```
----
-## Parse Strategies
-### contentType
-Parses response using `content-type` header.
-```ts
-.strategies(s =>
-  s.contentType()
-)
-```
-Supported:
-- JSON
-- Text
-- Blob
-- FormData
-- ArrayBuffer
-- Audio
-- Video
-- Image
----
-### sniff
-Attempts all parsers until one succeeds.
-```ts
-.strategies(s =>
-  s.sniff()
-)
-```
-Useful when:
-- content-type is invalid
-- server responses are inconsistent
-- APIs return malformed headers
----
-### custom
-Uses custom parser strategy.
-```ts
-.strategies(s =>
-  s.custom()
-    .func(async ({ response, parsers }) => {
-      return await parsers.json();
-    })
-)
-```
-#### API
-| Method | Description |
-|---|---|
-| func(fn) | Custom parse resolver |
----
-### parsers
-Registers custom parsers.
-```ts
-.parsers(p =>
-  p.add("csv", async response => {
-    return parseCSV(await response.text());
-  })
-)
-```
-#### Parser API
-| Method | Description |
-|---|---|
-| add(name, parser) | Adds custom parser |
-| remove(name) | Removes parser |
-| clear() | Removes all parsers |
----
-### request
-Executes parse workflow.
-```ts
-const result = await vigor
-  .parse(response)
-  .request();
-```
----
-## Interceptors
-| Name | API |
-|---|:---:|
-| before | throwError |
-| after | setResult / throwError |
-| result | setResult / throwError |
-| onError | setResult / throwError |
----
-### before
-Runs before parsing starts.
-```ts
-.before(async (ctx, api) => {
-  console.log(ctx.response.headers);
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| throwError(error) | Immediately throws error |
----
-### after
-Runs after parser succeeds.
-```ts
-.after(async (ctx, api) => {
-  api.setResult({
-    wrapped: ctx.result
-  });
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| setResult(value) | Replaces parsed result |
-| throwError(error) | Throws error |
----
-### result
-Runs before returning final result.
-```ts
-.result(async (ctx, api) => {
-  api.setResult(transform(ctx.result));
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| setResult(value) | Replaces final result |
-| throwError(error) | Throws error |
----
-### onError
-Runs when parsing fails.
-```ts
-.onError(async (ctx, api) => {
-  api.setResult(null);
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| setResult(value) | Returns fallback value |
-| throwError(error) | Throws error |
----
-## Example
-```ts
-const response = await fetch("/api");
-const data = await vigor
-  .parse(response)
-  .strategies(s =>
-    s.sniff()
-  )
-  .interceptors(i =>
-    i.onError((ctx, api) => {
-      console.log(ctx.error);
-      api.setResult(null);
-    })
-  )
-  .request();
-```
-## vigor.fetch
-### Methods
-| Method | Description |
-|---|---|
-| method(http method) | Forces the http method |
-| origin(...paths) | Sets base URL and origin paths |
-| path(...paths) | Appends request paths |
-| query(params) | Sets query parameters |
-| headers(headers) | Sets request headers |
-| options(options) | Sets fetch options |
-| retryConfig(fn \| config) | Configures retry engine |
-| parseConfig(fn \| config) | Configures parse engine |
-| interceptors(fn \| config) | Configures fetch interceptors |
-| abortSignals(...signals) | Attaches external AbortSignals |
-| request(config?) | Executes fetch pipeline |
----
-### origin
-Sets base URL and origin paths.
-```ts
-.fetch("https://api.example.com/", "/api")
-```
-Produces:
-```txt
-https://api.example.com/api
-```
----
-### path
-Appends request paths.
-```ts
-.path("v1", "users")
-```
-Produces:
-```txt
-https://api.example.com/api/v1/users
-```
----
-### query
-Adds query parameters.
-```ts
-.query({
-  page: 1,
-  limit: 10
-})
-```
-Produces:
-```txt
-?page=1&limit=10
-```
----
-### headers
-Sets request headers.
-```ts
-.headers({
-  Authorization: "Bearer token"
-})
-```
----
-### options
-Sets native fetch options.
-```ts
-.options({
-  method: "POST",
-  body: JSON.stringify({
-    username: "john"
-  })
-})
-```
----
-### retryConfig
-Configures internal retry engine.
-```ts
-.retryConfig(r => r
-	.settings(s => s
-		.attempt(5)
-  )
-)
-```
----
-### parseConfig
-Configures internal parse engine.
-```ts
-.parseConfig(p => p
-	.strategies(s => s
-		.sniff()
-  )
-)
-```
----
-### abortSignals
-Attaches external AbortSignals.
-```ts
-const controller = new AbortController();
-await vigor
-  .fetch("/api")
-  .abortSignals(controller.signal)
-  .request();
-```
----
-### request
-Executes fetch workflow.
-```ts
-const data = await vigor
-  .fetch("https://api.example.com")
-  .request();
-```
----
-## Interceptors
-| Name | API |
-|---|:---:|
-| before | throwError / abort |
-| after | setResponse / throwError |
-| result | setResult / throwError |
-| onError | setResult / throwError / retry |
----
-### before
-Runs before fetch execution.
-```ts
-.before(async (ctx, api) => {
-  console.log(ctx.url);
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| throwError(error) | Immediately throws error |
-| abort(error) | Aborts request |
----
-### after
-Runs after receiving Response.
-```ts
-.after(async (ctx, api) => {
-  console.log(ctx.response.status);
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| setResponse(response) | Replaces Response object |
-| throwError(error) | Throws error |
----
-### result
-Runs before returning parsed result.
-```ts
-.result(async (ctx, api) => {
-  api.setResult({
-    data: ctx.result
-  });
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| setResult(value) | Replaces final result |
-| throwError(error) | Throws error |
----
-### onError
-Runs when fetch fails.
-```ts
-.onError(async (ctx, api) => {
-  api.retry();
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| setResult(value) | Returns fallback value |
-| throwError(error) | Throws error |
-| restart() | Re-executes fetch pipeline |
----
-## Example
-```ts
-const data = await vigor
-  .fetch("https://api.example.com", "api")
-  .path("v1", "users")
-  .query({
-    page: 1
-  })
-  .headers({
-    Authorization: "Bearer token"
-  })
-  .retryConfig(r =>
-    r.settings(s =>
-      s.attempt(5)
-    )
-  )
-  .request();
-```
-## vigor.all
-### Methods
-| Method | Description |
-|---|---|
-| target(...tasks) | Sets async task list |
-| settings(fn \| config) | Configures concurrency settings |
-| interceptors(fn \| config) | Configures concurrency interceptors |
-| abortSignals(...signals) | Attaches external AbortSignals |
-| request(config?) | Executes concurrency pipeline |
----
-### target
-Sets async task list.
-```ts
-.all(
-  async () => fetch("/api/1"),
-  async () => fetch("/api/2")
-)
-```
----
-### settings
-Configures concurrency behavior.
-```ts
-.settings(s => s
-    .concurrency(2)
-    .onlySuccess(true)
-)
-```
-#### Settings API
-| Method | Description | Default |
-|---|---|---|
-| concurrency(number) | Maximum concurrent tasks | `Infinity` |
-| onlySuccess(boolean) | Returns only successful results | `false` |
-| fallback(value) | Fallback return value | `throws` |
----
-### abortSignals
-Attaches external AbortSignals.
-```ts
-const controller = new AbortController();
-await vigor
-  .all(task1, task2)
-  .abortSignals(controller.signal)
-  .request();
-```
----
-### request
-Executes concurrency workflow.
-```ts
-const results = await vigor
-  .all(task1, task2)
-  .request();
-```
----
-## Interceptors
-| Name | API |
-|---|:---:|
-| before | throwError / abort |
-| afterEach | setResult / throwError |
-| after | setResults / throwError |
-| result | setResults / throwError |
-| onError | setResults / throwError |
----
-### before
-Runs before task execution starts.
-```ts
-.before(async (ctx, api) => {
-  console.log(ctx.tasks.length);
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| throwError(error) | Immediately throws error |
-| abort(error) | Aborts execution |
----
-### after
-Runs after all tasks complete.
-```ts
-.after(async (ctx, api) => {
-  console.log(ctx.results);
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| setResults(value) | Replaces result array |
-| throwError(error) | Throws error |
----
-### result
-Runs before returning final results.
-```ts
-.result(async (ctx, api) => {
-  api.setResults(
-    ctx.results.filter(Boolean)
-  );
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| setResults(value) | Replaces final results |
-| throwError(error) | Throws error |
----
-### onError
-Runs when concurrency execution fails.
-```ts
-.onError(async (ctx, api) => {
-  api.setResults([]);
-})
-```
-#### Available APIs
-| API | Description |
-|---|---|
-| setResults(value) | Returns fallback results |
-| throwError(error) | Throws error |
----
-## Example
-```ts
-const results = await vigor
-  .all(
-    async () => fetch("/api/1"),
-    async () => fetch("/api/2"),
-    async () => fetch("/api/3")
-  )
-  .settings(s =>
-    s
-      .concurrency(2)
-      .onlySuccess(true)
-  )
-  .request();
-```
+# vigor-fetch
+**A composable, lightweight network workflow toolkit built on native Fetch.**
+Vigor gives you an immutable, chainable API for building robust network logic: retry with configurable backoff, content-aware response parsing, and concurrency-limited task running — all composed together, or used standalone.
+---
+## Features
+- 🧩 **Immutable, fluent builders** — every call returns a new instance; nothing is mutated in place
+- 🔁 **Two-level retry** — per-attempt retry/backoff *and* whole-pipeline restart, each independently configurable
+- 🌐 **Smart fetch layer** — automatic `429 Retry-After` handling, configurable "never retry" status codes
+- 🔌 **Content-aware parsing** — auto-detects `Content-Type`, with a sniffing fallback and custom strategies
+- ⚡ **Bounded concurrency runner** — run many tasks with a concurrency cap and per-task hooks
+- 🪝 **Two middleware modes** — `"fluent"` (return a value) or `"intercept"` (get an explicit control API)
+- 🧠 **TypeScript-first** — config shape is inferred and carried through the whole chain
+---
+## Installation
+```bash
+npm install vigor-fetch
+```
+## Import
+```ts
+import vigor from "vigor-fetch";
+// or
+import { vigor } from "vigor-fetch";
+```
+Both work — `vigor` is exported as both the default and a named export. Every internal class (`VigorFetch`, `VigorRetry`, `VigorParse`, `VigorAll`, their settings/middleware/strategy/algorithm builders, and error classes) is also exported by name if you want to construct them directly instead of going through `vigor.*`.
+---
+## Quick start
+### Fetch
+```ts
+import vigor from "vigor-fetch";
+const data = await vigor
+  .fetch("https://api.example.com")
+  .path("v1", "users")
+  .query({ page: 1, limit: 10 })
+  .request();
+// -> GET https://api.example.com/v1/users?page=1&limit=10
+```
+### Retry (standalone)
+```ts
+const data = await vigor
+  .retry(async (signal) => {
+    return await db.select("...");
+  })
+  .request();
+```
+### Parse (standalone)
+```ts
+const response = await fetch("https://api.example.com");
+const data = await vigor
+  .parse(response)
+  .request();
+```
+### Concurrency
+```ts
+const results = await vigor
+  .all(
+    () => fetch("/api/1"),
+    () => fetch("/api/2")
+  )
+  .request();
+```
+---
+## The `vigor` object
+```ts
+vigor.fetch(origin?)   // -> VigorFetch, origin pre-set if given
+vigor.retry(task?)     // -> VigorRetry, target pre-set if given
+vigor.parse(response?) // -> VigorParse, target pre-set if given
+vigor.all(...tasks)    // -> VigorAll, target pre-set if any tasks given
+vigor.use(plugin, options?)
+```
+Every module follows the same shape: an **immutable builder** with `.settings()`, `.middlewares()`, and a terminal `.request()` / `.requestVerbose()` pair.
+- `.request()` returns the result directly and **throws** on final failure.
+- `.requestVerbose()` never throws — it returns `{ success: true, data, error: null }` or `{ success: false, data: null, error }`.
+---
+## `vigor.fetch`
+### Methods
+| Method | Description |
+|---|---|
+| `method(str)` | Forces the HTTP method. Default: `POST` if a body is set, otherwise `GET` |
+| `origin(str)` | Sets the base URL (absolute) or a path relative to the current page |
+| `path(...strs)` | Appends path segments |
+| `query(...objs)` | Adds query-parameter objects (each call appends another object to the list) |
+| `hash(str)` | Sets the URL fragment, replacing any previous value |
+| `headers(mode, obj)` | Sets headers. `mode`: `"overwrite"` (discard previous) or `"merge"` (`Object.assign`-style) |
+| `body(mode, obj)` | Sets the body. `"overwrite"` replaces it entirely; `"merge"` shallow-merges when both old and new body are plain objects, otherwise replaces |
+| `options(mode, obj)` | Sets extra native `RequestInit` fields other than `method`/`headers`/`body`/`signal` (e.g. `credentials`, `mode`, `cache`) |
+| `settings(fn \| config)` | Configures fetch-level settings (below) |
+| `middlewares(fn \| config)` | Configures the fetch middleware pipeline (below) |
+| `retry(fn \| config \| VigorRetry)` | Configures the **internal retry engine** used to send the request |
+| `parse(fn \| config \| VigorParse)` | Configures the **internal parse engine** used to interpret the response |
+| `request()` | Executes and returns the parsed result, throwing on failure |
+| `requestVerbose()` | Executes and returns `{ success, data, error }` |
+> `path()`, `query()`, `headers()` in merge mode, etc. are all additive per call — chain them incrementally rather than passing everything in one call.
+### origin / path / query / hash
+```ts
+vigor.fetch("https://api.example.com/", "/api")
+  .path("v1", "users")
+  .query({ page: 1 })
+  .hash("section-2")
+// -> https://api.example.com/api/v1/users?page=1#section-2
+```
+`origin()` only accepts one argument — pass origin + first path segments as separate calls, or fold extra segments into `path()`.
+### headers / body / options
+```ts
+vigor.fetch("/api")
+  .headers("merge", { Authorization: "Bearer token" })
+  .body("overwrite", { username: "john" })
+  .options("merge", { credentials: "include" })
+```
+Body is auto-normalized based on type (string, `Blob`, `ArrayBuffer`, `URLSearchParams`, `FormData`, or plain object → JSON), and a matching `Content-Type` header is set automatically unless you've already set one via `.headers()`.
+### settings
+```ts
+.settings(s => s
+  .unretryStatus(400, 401, 403, 404, 405, 413, 422)
+  .retryHeaders("retry-after", "x-ratelimit-reset")
+  .maxRestarts(3)
+  .default(ctx => ({ fallback: true }))
+)
+```
+| Method | Description | Default |
+|---|---|---|
+| `retryHeaders(...strs)` | Response headers checked for a `429` retry delay | `["retry-after", "ratelimit-reset", "x-ratelimit-reset", "x-retry-after", "x-amz-retry-after", "chrome-proxy-next-link"]` |
+| `unretryStatus(...nums)` | HTTP status codes that are never retried, regardless of the retry engine's attempt budget | `[400, 401, 403, 404, 405, 413, 422]` |
+| `maxRestarts(num)` | Max number of full pipeline restarts (see `onError` below) | `3` |
+| `default(fn)` | Fallback value/factory used only if the request ultimately fails and no restart/override happened | throws |
+On any non-`unretryStatus` failure response, the internal retry engine retries per its own `settings`/`algorithms` (defaults: 5 attempts, 20s timeout, exponential-ish backoff jitter — see `vigor.retry` below). On a `429`, Vigor reads `retryHeaders` off the response and uses that value (seconds or an HTTP date) as the next delay automatically.
+### interceptors (`middlewares`)
+Every stage takes a mode as the first argument: `"fluent"` (return a plain value) or `"intercept"` (receive an explicit API object and return the context).
+```ts
+.middlewares(m => m
+  .before("intercept", async (ctx, api) => {
+    api.setHeaders({ ...ctx.options.headers, "X-Trace": crypto.randomUUID() });
+    return ctx;
+  })
+  .onError("intercept", async (ctx, api) => {
+    if (ctx.error instanceof SomeRecoverableError) api.proceedRestart();
+    return ctx;
+  })
+)
+```
+| Stage | Runs | Intercept API |
+|---|---|---|
+| `before` | Before the request is sent | `throwError`, `setOptions`, `setHeaders`, `setBody` |
+| `after` | After the response is parsed | `setResult`, `throwError` |
+| `onResult` | Right before returning the final result | `setResult`, `throwError` |
+| `onError` | After the request has finally failed | `setResult`, `throwError`, `proceedRestart`, `cancelRestart` |
+Fluent-mode signatures: `before`/`after` take `(ctx) => void`, `onResult` takes `(res) => newRes`, `onError` takes `(err) => void`.
+`onError` → `proceedRestart()` re-runs the **entire** fetch pipeline from scratch (up to `settings.maxRestarts` times) — this is separate from, and on top of, the internal retry engine's per-attempt retries.
+### retry / parse (nested engines)
+```ts
+const data = await vigor
+  .fetch("/api/users")
+  .retry(r => r.settings(s => s.maxAttempts(8)).algorithms(a => a.backoff({ multiplier: 2 })))
+  .parse(p => p.strategies(s => s.sniff()))
+  .request();
+```
+Both accept a config object, a builder callback, or an already-built `VigorRetry`/`VigorParse` instance. The target function you'd normally set with `.target()` is ignored here — fetch always supplies its own target (the actual `fetch()` call) and its own `.target()` (`response.clone()` fed through your parse config).
+---
+## `vigor.retry`
+### Methods
+| Method | Description |
+|---|---|
+| `target(fn)` | Sets the function to run: `(signal: AbortSignal) => any \| Promise<any>` |
+| `abortSignals(...sigs)` | Attaches external `AbortSignal`s that cancel the current attempt when aborted |
+| `settings(fn \| config)` | General retry settings (below) |
+| `middlewares(fn \| config)` | Middleware pipeline (below) |
+| `algorithms(fn)` | Selects and configures the delay algorithm (below) |
+| `request()` / `requestVerbose()` | Executes |
+```ts
+const controller = new AbortController();
+await vigor
+  .retry(async (signal) => fetch("/api", { signal }))
+  .abortSignals(controller.signal)
+  .settings(s => s.maxAttempts(5).timeout(5000))
+  .request();
+```
+### settings
+| Method | Description | Default |
+|---|---|---|
+| `default(fn)` | Fallback value/factory when the target ultimately fails | throws |
+| `maxAttempts(num)` | Max attempts before giving up on this run | `5` |
+| `maxRestarts(num)` | Max full pipeline restarts (see `onError`) | `3` |
+| `timeout(ms)` | Timeout per individual attempt | `20000` |
+### algorithms
+Delay algorithm is a **replace**, not merge — switching algorithms discards the previous one's config.
+```ts
+.algorithms(a => a.backoff({ initial: 1000, multiplier: 1.7 }))
+```
+| Algorithm | Fields (with defaults) |
+|---|---|
+| `constant(cfg?)` | `interval` (`2000`), `jitter` (`1000`) |
+| `linear(cfg?)` | `initial` (`500`), `increment` (`1000`), `minDelay` (`0`), `maxDelay` (`10000`), `jitter` (`1000`) |
+| `backoff(cfg?)` | `initial` (`0`), `multiplier` (`1.7`), `unit` (`1000`), `minDelay` (`500`), `maxDelay` (`10000`), `jitter` (`800`) |
+| `custom(cfg?)` | `target: (attempt) => number` (required), `minDelay` (`500`), `maxDelay` (`10000`), `jitter` (`800`) |
+Each computed delay is clamped to `[minDelay, maxDelay]` (except `constant`, which has no bounds) and then perturbed by `±jitter` ms.
+```ts
+.algorithms(a => a.custom({
+  target: (attempt) => attempt * 3000
+}))
+```
+### interceptors (`middlewares`)
+```ts
+.middlewares(m => m
+  .retryIf("intercept", async (ctx, api) => {
+    if (ctx.error instanceof TypeError) api.proceedRetry();
+    else api.cancelRetry();
+    return ctx;
+  })
+  .onRetry("intercept", async (ctx, api) => {
+    api.setDelay(5000);
+    return ctx;
+  })
+)
+```
+| Stage | Runs | Intercept API |
+|---|---|---|
+| `before` | Before each attempt | `throwError`, `abort`, `breakRetry` |
+| `after` | After the target settles successfully | `setResult`, `throwError` |
+| `onResult` | Right before returning the attempt's result | `setResult`, `throwError` |
+| `retryIf` | After a failed attempt, decides whether to retry | `proceedRetry`, `cancelRetry` |
+| `onRetry` | Right before the retry delay is awaited | `throwError`, `setDelay` |
+| `onError` | After attempts are exhausted (or `breakRetry` was called) | `setResult`, `throwError`, `proceedRestart`, `cancelRestart` |
+Fluent-mode signatures: `before`/`after` take `(ctx) => void`, `onResult` takes `(res) => newRes`, `retryIf` takes `(err) => boolean`, `onRetry`/`onError` take `(err) => void`.
+There are two independent resilience layers here:
+- **`retryIf`/`onRetry`** loop through attempts (bounded by `settings.maxAttempts`) without ever fully failing.
+- **`onError`** fires once attempts are exhausted; calling `api.proceedRestart()` there resets the attempt counter and starts over (bounded by `settings.maxRestarts`).
+---
+## `vigor.parse`
+### Methods
+| Method | Description |
+|---|---|
+| `target(response)` | Sets the `Response` to parse |
+| `settings(fn \| config)` | General settings (below) |
+| `middlewares(fn \| config)` | Middleware pipeline (below) |
+| `strategies(fn \| config)` | Configures the ordered fallback chain of parsing strategies |
+| `request()` / `requestVerbose()` | Executes |
+### settings
+| Method | Description | Default |
+|---|---|---|
+| `raw(bool)` | When `true`, skips parsing entirely and returns the raw `Response` object | `false` |
+| `default(fn)` | Fallback value/factory when parsing ultimately fails | throws |
+| `maxRestarts(num)` | Max full pipeline restarts | `3` |
+### strategies
+Strategies form an ordered list that's tried in sequence until one succeeds (each attempt but the last clones the response first, so a failed strategy doesn't consume the body). If you never configure any, Vigor defaults to content-type detection.
+```ts
+.strategies(s => s.sniff())
+```
+| Method | Behavior |
+|---|---|
+| `contentType(replace?)` | Parses based on the response's `Content-Type` header (JSON / XML / form-urlencoded / octet-stream / image / audio / video / multipart / text) |
+| `sniff(replace?)` | Tries `json → formData → text → blob` in order until one parses |
+| `json(replace?)` | Always parses as JSON |
+| `text(replace?)` | Always parses as text |
+| `arrayBuffer(replace?)` | Always parses as `ArrayBuffer` |
+| `blob(replace?)` | Always parses as `Blob` |
+| `bytes(replace?)` | Always parses as `Uint8Array` |
+| `formData(replace?)` | Always parses as `FormData` |
+| `custom(func, replace?)` | Uses a custom `(response: Response) => Promise<any>` |
+By default each call **appends** to the chain (they concatenate, so you can layer fallbacks: e.g. `contentType()` then `sniff()` as a last resort). Pass `replace: true` as the trailing argument to replace the whole chain instead.
+### interceptors (`middlewares`)
+| Stage | Runs | Intercept API |
+|---|---|---|
+| `before` | Before parsing starts | `throwError` |
+| `after` | After a strategy succeeds | `setResult`, `throwError` |
+| `onResult` | Right before returning the final result | `setResult`, `throwError` |
+| `onError` | When every strategy in the chain failed | `setResult`, `throwError`, `proceedRestart`, `cancelRestart` |
+```ts
+const data = await vigor
+  .parse(response)
+  .strategies(s => s.sniff())
+  .middlewares(m => m.onError("intercept", async (ctx, api) => {
+    api.setResult(null);
+    return ctx;
+  }))
+  .request();
+```
+---
+## `vigor.all`
+Runs a fixed list of zero-argument tasks with bounded concurrency.
+### Methods
+| Method | Description |
+|---|---|
+| `target(...funcs)` | Sets the task list — each is `() => unknown \| Promise<unknown>` |
+| `settings(fn \| config)` | Concurrency settings (below) |
+| `middlewares(fn \| config)` | Per-task hooks (below) |
+| `request()` / `requestVerbose()` | Executes |
+```ts
+const results = await vigor
+  .all(
+    () => fetch("/api/1"),
+    () => fetch("/api/2"),
+    () => fetch("/api/3")
+  )
+  .settings(s => s.concurrency(2).onlySuccess(true))
+  .request();
+```
+### settings
+| Method | Description | Default |
+|---|---|---|
+| `concurrency(num)` | Max number of tasks running at once | `5` |
+| `onlySuccess(bool)` | When `true`, filters the final array down to only tasks whose middleware chain resolved successfully | `false` |
+> Unlike `vigor.retry`/`vigor.fetch`/`vigor.parse`, `vigor.all` has no `default`/fallback setting, and per-task failures don't throw the whole call by themselves — a task that fails (and whose `onError` middleware doesn't call `setResult`) simply contributes its error value into the results array (or is dropped, if `onlySuccess` is on). The only thing that makes `.request()` throw is an **empty** task list.
+### hooks (`middlewares`)
+Unlike the other modules, `all`'s per-task hooks are plain functions — there's no `"fluent"`/`"intercept"` mode split.
+| Stage | Signature | Runs |
+|---|---|---|
+| `before(fn)` | `(ctx) => void \| Promise<void>` | Before each task is invoked |
+| `after(fn)` | `(ctx) => void \| Promise<void>` | After a task settles successfully |
+| `onError(fn)` | `(ctx, { setResult }) => void \| Promise<void>` | When an individual task throws |
+```ts
+.middlewares(m => m
+  .onError(async (ctx, api) => {
+    console.error(ctx.error);
+    api.setResult(null); // recover instead of letting this task register as failed
+  })
+)
+```
+---
+## Plugins
+```ts
+export type VigorPlugin<O> = {
+  options: O // type-only anchor for inferring O — not used at runtime
+  func: (v: typeof vigor, options: O) => void
+}
+vigor.use(plugin, options?)
+```
+`vigor.use(plugin, options)` simply invokes `plugin.func(vigor, options)` — a lightweight hook for setup-time side effects (e.g. registering shared config, wiring up logging) rather than a full plugin/extension system.
+---
+## Error handling
+Every module throws its own error subclass (`VigorFetchError`, `VigorRetryError`, `VigorParseError`, `VigorAllError`) — all extending a common `VigorError` with `.code`, `.data`, `.method`, `.context`, and `.timestamp`.
+```ts
+try {
+  await vigor.fetch("/api/users").request();
+} catch (err) {
+  if (err instanceof VigorFetchError && err.code === "FETCH_FAILED") {
+    console.log(err.data.status, err.data.parsed); // failed response's status + best-effort parsed body
+  }
+}
+```
+Or avoid try/catch entirely with `requestVerbose()`:
+```ts
+const res = await vigor.fetch("/api/users").requestVerbose();
+if (!res.success) {
+  // res.error is typed, res.data is null
+}
+```
+| Module | Error codes |
+|---|---|
+| `VigorFetchError` | `VALUE_REQUIRED`, `INVALID_BODY`, `INVALID_PROTOCOL`, `FETCH_FAILED`, `RESTART_EXHAUSTED` |
+| `VigorRetryError` | `VALUE_REQUIRED`, `RETRY_EXHAUSTED`, `RESTART_EXHAUSTED`, `TIMED_OUT` |
+| `VigorParseError` | `VALUE_REQUIRED`, `INVALID_CONTENT_TYPE`, `PARSER_NOT_FOUND`, `PARSER_ALL_FAILED`, `RESTART_EXHAUSTED` |
+| `VigorAllError` | `EMPTY_TARGET` |
+`FETCH_FAILED`'s `data` includes `parsed`: Vigor best-effort parses the failed response's body (using your configured parse strategies) before throwing, so you can inspect an API's error payload without re-fetching. If parsing that body also fails, `parsed` is simply `undefined`.
+---
+## TypeScript notes
+- Every builder is **immutable** — `.settings(...)`, `.path(...)`, etc. all return a *new* instance with the change merged in; the original is untouched.
+- Array-valued config (`path`, `query`, parse `strategies`, etc.) **concatenates** across calls by default; object-valued config deep-merges. A handful of methods (`hash`, `headers("overwrite", ...)`, `body("overwrite", ...)`, `options("overwrite", ...)`, `retry(...)`, `parse(...)`, `algorithms(...)`) force a full **replace** instead, since merging wouldn't make sense there.
+- Config shape is tracked through the whole chain via TypeScript generics, so `.settings()`/`.middlewares()` callbacks and `.request()`'s inferred return type stay accurate as you chain.