rest-pipeline-js 1.3.14 → 1.4.0

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep -n \"stepIndex,$\\\\|stepIndex: i,\\\\|emitStepStart\\(\\\\|emitStepFinish\\(\\\\|emitStepError\\(\\\\|emitStepSkipped\\(\\\\|stageResults: { \\\\.\\\\.\\\\.this\\\\.stageResults }\" src/pipeline-orchestrator.ts)",
+      "Bash(cat > *)"
+    ],
+    "additionalDirectories": [
+      "\\tmp"
+    ]
+  }
+}

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## [Unreleased]
+
+### Fixed
+
+- **Flaky test in `tests/rest-client.test.ts`** ("при повторном 401 после onUnauthorized — не попадает в бесконечный цикл") — the mock error set `err.isAxiosError = true` *after* `Object.setPrototypeOf(err, axios.AxiosError.prototype)`. `AxiosError.prototype.isAxiosError` is defined as non-writable (`Object.defineProperty(..., { value: true })`), so that assignment threw a `TypeError` in strict mode, which masked the actual 401-retry logic being exercised. Fixed by assigning `isAxiosError` before swapping the prototype, matching the (correct) pattern already used by the other axios-error mocks in the same file. No production code changed.
+
+### Added
+
+#### Pipeline Orchestrator
+
+- **`signal` in stage hooks** — `request`, `condition`, `before`, `after`, `errorHandler`, and `StreamStageConfig.stream` now receive the pipeline's `AbortSignal` in their params object. Pass it down to `fetch`/`axios`/etc. so `abort()` actually cancels custom async work inside stage functions, not just the orchestrator's own bookkeeping.
+- **`recoverStep(data)`** (from `types.ts`, re-exported from the root entry point) — `errorHandler` can return `recoverStep(data)` to recover a failed stage back into a successful one (`status: "success"`, `data`), running the same commit path as a normal success (metrics, `persistAdapter.save()`, `middleware.afterEach`, `step:success` event) instead of stopping/continuing-as-error. Returning anything else keeps the previous behavior (error, transformed via `toApiError`).
+
+#### RestClient
+
+- **No `axios.create()` when `adapter` is set** — `createRestClient()` no longer constructs the built-in axios instance if a custom `HttpAdapter` is provided, avoiding unnecessary work in edge/serverless environments that only use the adapter.
+
+### Changed
+
+- Internal: `PipelineOrchestrator.executeStage()` success/error commit logic was extracted into `_commitStepSuccess()` / `_commitStepError()` so the new `errorHandler` recovery path and the normal success path share identical metrics/persist/middleware/event behavior.
+
+#### Pipeline Orchestrator
+
+- **`ParallelStageGroup.concurrency`** — caps how many stages of a parallel group run at once instead of always starting all of them via `Promise.all`. Useful for fan-out over many items (e.g. paginated fetches) without opening hundreds of requests at the same time. Results are still returned/stored in the same shape and order as an unlimited group. Supported by the `pipe()` builder via `.parallel(stages, { concurrency })`.
+
+#### RestClient
+
+- **`AuthProvider.tokenTtlMs`** — caches `getToken()`'s result for the given duration instead of calling it before every request. The cache is invalidated automatically on a `401` (before `onUnauthorized` runs), so the retried request always fetches a fresh token. Without `tokenTtlMs`, behavior is unchanged (`getToken()` called every request).
+- **`invalidateCache(matcher)`** — new method on the client returned by `createRestClient()`. Removes only the response-cache entries whose URL matches `matcher` (substring, `RegExp`, or `(info: { method, url }) => boolean`) instead of clearing the whole cache like `clearCache()`. Returns the number of entries removed.
+- `TtlCache` gained `keys()` and `deleteWhere(predicate)` to support the above.
+
+### Added (continued)
+
+#### RestClient — Circuit breaker
+
+- **`HttpConfig.circuitBreaker`** (new `CircuitBreakerConfig`: `{ failureThreshold, openMs, successThreshold?, isFailure? }`) — after `failureThreshold` consecutive failures the client rejects requests immediately with `CircuitOpenError` (`code: "CIRCUIT_OPEN"`) for `openMs`, without making a network call. After `openMs` it probes with real requests in a `half-open` state: success (×`successThreshold`, default 1) closes the circuit, failure re-opens it. `isFailure(error)` can exclude certain errors (e.g. 4xx) from counting as failures. Cancelled/aborted requests never count as failures. New module `src/circuit-breaker.ts` exports `CircuitBreaker`, `CircuitOpenError`, and the `CircuitBreakerState` type.
+- **`client.getCircuitBreakerState()`** — returns `"closed" | "open" | "half-open"`, or `null` if `circuitBreaker` isn't configured.
+- Not set by default — without `circuitBreaker`, behavior is unchanged.
+
+#### Pipeline Orchestrator — run correlation
+
+- **`runId`** — every `run()` call generates a fresh ID (via `crypto.randomUUID()`, falling back to a timestamp-based string), shared by `PipelineMetrics.onPipelineStart/onPipelineEnd/onStepDuration`, every `PipelineStepEvent` (`.runId`), and every entry returned by `getLogs()`/`exportState()`. All attempts within one `run()` (including `pipelineRetry` retries) share the same `runId`. `rerunStep()` generates its own separate `runId`. New `orchestrator.getRunId()` reads the current/last one. `PipelineMetrics`' three callback `info` objects and `PipelineStepEvent` gained a `runId` field (required on the former, optional on the latter for backward compatibility).
+
+#### DX utilities — typed `pipe()` builder
+
+- **`PipelineBuilder<TPrev>`** — the fluent builder is now generic: `.step()` infers and threads the previous step's output type into the next step's `prev`, so TypeScript catches type mismatches across a chain and provides autocomplete. The first step's `prev` is typed `undefined`, matching actual runtime behavior. `.parallel()` / `.subPipeline()` / `.stream()` intentionally don't change the threaded type, since the orchestrator's `prev` for the next step always comes from the last regular `.step()`, never from a parallel group/sub-pipeline/stream. Purely a type-level addition — `PipelineBuilder` still mutates the same instance internally, so existing non-chained usage (calling `.step()` without reassigning the result) keeps working unchanged.
+- `ParallelStageGroup.concurrency` is also exposed through `pipe().parallel(stages, { concurrency })`.
+
+---
+
 ## [1.3.7] - 2026-04-04
 
 ### Added

package/README.md

@@ -23,12 +23,15 @@ Flexible, modular pipeline orchestrator for REST APIs — sequential and paralle
 - [Auth Provider](#auth-provider)
 - [Log Sanitization](#log-sanitization)
 - [RequestExecutor](#requestexecutor)
+- [Circuit breaker](#circuit-breaker)
 - [PipelineOrchestrator](#pipelineorchestrator)
+- [Error recovery (errorHandler + recoverStep)](#error-recovery-errorhandler--recoverstep)
 - [Parallel stages](#parallel-stages)
 - [Global middleware](#global-middleware)
 - [Pause / Resume](#pause--resume)
 - [Export / Import state](#export--import-state)
 - [Pipeline metrics](#pipeline-metrics)
+- [Correlating a run (runId)](#correlating-a-run-runid)
 - [createPipeline() + pipe() builder](#createpipeline--pipe-builder)
 - [validatePipelineConfig()](#validatepipelineconfig)
 - [Plugin system](#plugin-system)
@@ -45,15 +48,16 @@ Flexible, modular pipeline orchestrator for REST APIs — sequential and paralle
 
 ## Features
 
-- **`createRestClient()`** — full-featured HTTP client built on top of axios: retry with exponential backoff and `Retry-After` support, response caching for GET requests, rate limiting (concurrency + req/interval), auth provider with automatic 401 refresh, request cancellation by key, custom HTTP adapters
-- **`PipelineOrchestrator`** — sequential and parallel stage execution; each stage has `condition`, `before`, `request`, `after`, `errorHandler` hooks; `sharedData` pool shared across all stages
+- **`createRestClient()`** — full-featured HTTP client built on top of axios: retry with exponential backoff and `Retry-After` support, response caching (incl. targeted `invalidateCache()`), rate limiting (concurrency + req/interval), circuit breaker, auth provider with automatic 401 refresh and optional token caching, request cancellation by key, custom HTTP adapters
+- **`PipelineOrchestrator`** — sequential and parallel stage execution; each stage has `condition`, `before`, `request`, `after`, `errorHandler` hooks (all receive the pipeline's `AbortSignal`); `sharedData` pool shared across all stages
+- **Error recovery** — `errorHandler` can return `recoverStep(data)` to turn a failed stage back into a successful one and keep the pipeline going, instead of only transforming the error
 - **Global middleware** — `beforeEach` / `afterEach` / `onError` hooks that apply to every stage without modifying individual configs
-- **Parallel groups** — multiple stages run concurrently via `Promise.all`; single failure stops the group
-- **Pause / Resume / Abort** — `pause()` waits after the current stage; `resume()` continues; `abort()` cancels the current HTTP request via `AbortController`
+- **Parallel groups** — multiple stages run concurrently via `Promise.all`, or through a bounded pool via `concurrency`; single failure stops the group
+- **Pause / Resume / Abort** — `pause()` waits after the current stage; `resume()` continues; `abort()` cancels the current HTTP request and propagates its `AbortSignal` into every stage hook so custom `request`/`before`/`after` functions can cancel their own work too
 - **Export / Import state** — serialize `stageResults` + logs to a plain object; restore on the next page load
 - **Stream stages** — `stream: async function*` for SSE / any `AsyncIterable`; `onChunk` callback in real time; abort-aware
-- **Pipeline metrics** — `onPipelineStart`, `onPipelineEnd`, `onStepDuration` callbacks without touching stage logic
-- **`createPipeline()` / `pipe()` builder** — short factory and fluent builder API for common patterns
+- **Pipeline metrics & run correlation** — `onPipelineStart`, `onPipelineEnd`, `onStepDuration` callbacks, plus a `runId` (also on `getRunId()`, log entries, and step events) shared by every callback/event from the same run
+- **`createPipeline()` / `pipe()` builder** — short factory and fluent builder API for common patterns; in TypeScript, `pipe().step()` chains infer `prev`'s type from the previous step automatically
 - **`validatePipelineConfig()`** — catch duplicate keys, empty keys, type errors before runtime
 - **Plugin system** — install reusable behavior (logging, analytics, etc.); cleanup via `destroy()`
 - **Persist adapter** — pluggable save/load interface; auto-save after each stage
@@ -168,7 +172,9 @@ Creates a REST client with advanced HTTP features.
 | `request(url, config?)`                 | Generic request                    |
 | `cancellableRequest(key, url, config?)` | Request cancellable by key         |
 | `cancelRequest(key)`                    | Cancel request by key              |
-| `clearCache()`                          | Clear this client's response cache |
+| `clearCache()`                          | Clear this client's entire response cache |
+| `invalidateCache(matcher)`               | Clear only cache entries whose URL matches `matcher` (substring, `RegExp`, or `(info) => boolean`); returns the number of entries removed |
+| `getCircuitBreakerState()`              | `"closed" \| "open" \| "half-open"`, or `null` if `circuitBreaker` isn't configured |
 
 ### HttpConfig options
 
@@ -190,11 +196,13 @@ Creates a REST client with advanced HTTP features.
 | `rateLimit.intervalMs`             | Time window size in ms                                                           |
 | `metrics.onRequestStart`           | Callback on request start                                                        |
 | `metrics.onRequestEnd`             | Callback on request end (includes duration and bytes)                            |
-| `auth.getToken`                    | Async function returning a Bearer token (called before every request)            |
+| `auth.getToken`                    | Async function returning a Bearer token (called before every request, unless `auth.tokenTtlMs` is set) |
 | `auth.onUnauthorized`              | Optional async callback on 401 — refresh the token here; request is retried once |
+| `auth.tokenTtlMs`                  | Cache `getToken()`'s result for this many ms instead of calling it before every request; invalidated automatically on 401 |
 | `sanitizeHeaders`                  | Mask sensitive headers in metrics callbacks (default: `false`)                   |
 | `sensitiveHeaders`                 | Additional headers to mask (extends `DEFAULT_SENSITIVE_HEADERS`)                 |
 | `adapter`                          | Custom HTTP adapter (e.g. native `fetch`) — replaces built-in axios              |
+| `circuitBreaker`                   | See [Circuit breaker](#circuit-breaker) — `{ failureThreshold, openMs, successThreshold?, isFailure? }` |
 
 ### Per-request cache override
 
@@ -206,6 +214,18 @@ const res = await client.get("/data", {
 });
 ```
 
+### Targeted cache invalidation
+
+`clearCache()` wipes the entire response cache. To invalidate only the entries affected by a mutation (e.g. after a `POST`/`PUT`/`DELETE`), use `invalidateCache()` instead — it accepts a substring, a `RegExp`, or a predicate over `{ method, url }`, and returns how many entries were removed:
+
+```js
+await client.post("/users/1/orders", newOrder);
+
+client.invalidateCache("/users/1"); // substring match on the cached URL
+client.invalidateCache(/^https:\/\/api\.example\.com\/users\/\d+$/);
+client.invalidateCache(({ method, url }) => method === "GET" && url.includes("/orders"));
+```
+
 ### Full example
 
 ```js
@@ -269,6 +289,21 @@ const client = createRestClient({
 const res = await client.get("/profile");
 ```
 
+### Caching the token
+
+If `getToken()` is expensive (e.g. it talks to a secure storage or refresh endpoint), set `tokenTtlMs` to reuse the result across requests instead of calling `getToken()` before every single one. The cache is invalidated automatically on a `401`, so the next request always re-fetches a fresh token before retrying:
+
+```js
+const client = createRestClient({
+  baseURL: "https://api.example.com",
+  auth: {
+    getToken: async () => requestTokenFromSecureEnclave(), // expensive
+    onUnauthorized: async () => refreshAccessToken(),
+    tokenTtlMs: 5 * 60_000, // reuse for up to 5 minutes
+  },
+});
+```
+
 ---
 
 ## Log Sanitization
@@ -334,6 +369,41 @@ When the server returns a `Retry-After` header (numeric seconds or HTTP-date), t
 
 ---
 
+## Circuit breaker
+
+Protect a failing backend (and your own app) from piling up retries/timeouts: after `failureThreshold` consecutive failures, the client stops calling the network entirely for `openMs` and rejects requests immediately with a `CircuitOpenError` (`code: "CIRCUIT_OPEN"`). After `openMs`, it lets a probe request through (`half-open`); success closes the circuit again, failure re-opens it.
+
+```js
+import { createRestClient, CircuitOpenError } from "rest-pipeline-js";
+
+const client = createRestClient({
+  baseURL: "https://api.example.com",
+  circuitBreaker: {
+    failureThreshold: 5, // open after 5 consecutive failures
+    openMs: 30_000, // stay open for 30s before probing again
+    successThreshold: 2, // need 2 successful probes to fully close
+    isFailure: (error) => error.status === undefined || error.status >= 500, // ignore 4xx
+  },
+});
+
+try {
+  await client.get("/flaky-endpoint");
+} catch (err) {
+  if (err instanceof CircuitOpenError) {
+    // rejected locally — no network call was made
+  }
+}
+
+client.getCircuitBreakerState(); // "closed" | "open" | "half-open"
+```
+
+- Works on top of retry, cache, rate limiting, auth, and custom `adapter`s — it sits around the actual network call, same as those features.
+- Each retry attempt (from `RequestExecutor`/`request.retry`) counts as its own pass through the breaker, so a flaky endpoint with retries enabled opens the circuit faster, not slower.
+- Cancelled/aborted requests are never counted as failures.
+- Not set by default — without `circuitBreaker`, behavior is unchanged.
+
+---
+
 ## PipelineOrchestrator
 
 Main class for building and managing a pipeline of sequential (and parallel) stages.
@@ -363,6 +433,7 @@ new PipelineOrchestrator({
 | `exportState()`                            | Serialize stageResults and logs to a plain object                                     |
 | `importState(state)`                       | Restore stageResults and logs from a snapshot                                         |
 | `getStageResults()`                        | Synchronous snapshot of all stage results                                             |
+| `getRunId()`                               | ID of the current/last `run()` or `rerunStep()` — see [Correlating a run](#correlating-a-run-runid) |
 | `destroy()`                                | Run cleanup callbacks from all installed plugins                                      |
 | `subscribeProgress(listener)`              | Subscribe to progress updates                                                         |
 | `subscribeStageResults(listener)`          | Subscribe to stageResults changes                                                     |
@@ -375,18 +446,37 @@ new PipelineOrchestrator({
 
 ### Stage parameters (PipelineStageConfig)
 
-| Parameter                                     | Description                                                              |
-| --------------------------------------------- | ------------------------------------------------------------------------ |
-| `key`                                         | Unique stage identifier                                                  |
-| `request({ prev, allResults, sharedData })`   | Main stage function — return value becomes the stage result              |
-| `condition({ prev, allResults, sharedData })` | If returns `false`, stage is skipped with status `"skipped"`             |
-| `before({ prev, allResults, sharedData })`    | Pre-processing hook — returned value replaces `prev` passed to `request` |
-| `after({ result, allResults, sharedData })`   | Post-processing hook — returned value replaces the stage result          |
-| `errorHandler({ error, key, sharedData })`    | Per-stage error handler                                                  |
-| `retryCount`                                  | Override retry count for this stage                                      |
-| `timeoutMs`                                   | Override timeout for this stage                                          |
-| `pauseBefore`                                 | Delay in ms before executing `request`                                   |
-| `pauseAfter`                                  | Delay in ms after executing `request`                                    |
+Every hook below also receives `signal: AbortSignal` in its params object — the same signal used by `orchestrator.abort()`. Pass it down to `fetch`/`axios`/etc. inside `request`/`before`/`after` so cancellation actually stops in-flight work, not just the pipeline's bookkeeping.
+
+| Parameter                                             | Description                                                              |
+| ------------------------------------------------------ | ------------------------------------------------------------------------ |
+| `key`                                                  | Unique stage identifier                                                  |
+| `request({ prev, allResults, sharedData, signal })`   | Main stage function — return value becomes the stage result              |
+| `condition({ prev, allResults, sharedData, signal })` | If returns `false`, stage is skipped with status `"skipped"`             |
+| `before({ prev, allResults, sharedData, signal })`    | Pre-processing hook — returned value replaces `prev` passed to `request` |
+| `after({ result, allResults, sharedData, signal })`   | Post-processing hook — returned value replaces the stage result          |
+| `errorHandler({ error, key, sharedData, signal })`    | Per-stage error handler — see [Error recovery](#error-recovery-errorhandler--recoverstep) below |
+| `retryCount`                                           | Override retry count for this stage                                      |
+| `timeoutMs`                                            | Override timeout for this stage                                          |
+| `pauseBefore`                                          | Delay in ms before executing `request`                                   |
+| `pauseAfter`                                           | Delay in ms after executing `request`                                    |
+
+### Error recovery (`errorHandler` + `recoverStep`)
+
+By default, whatever `errorHandler` returns is wrapped into an `ApiError` and the stage stays `"error"` — it can transform/enrich the error but not turn the failure into a success. Return `recoverStep(data)` to recover the stage instead: it's committed exactly like a successful stage (status `"success"`, `afterEach` middleware, metrics, persistence) and the pipeline continues normally.
+
+```js
+import { recoverStep } from "rest-pipeline-js";
+
+{
+  key: "fetchPrice",
+  request: async () => fetchPriceFromApi(),
+  errorHandler: ({ error }) => {
+    if (isNetworkError(error)) return recoverStep(0); // fall back to a default and continue
+    return error; // anything else: keep failing as before
+  },
+}
+```
 
 ### Stage execution flow
 
@@ -410,7 +500,9 @@ middleware.afterEach
 [status: success] → next stage
 
 On error at any point:
-  └─► stage.errorHandler (if set) → middleware.onError → [status: error] → stop
+  └─► stage.errorHandler (if set)
+        ├─► returns recoverStep(data) → [status: success] → next stage
+        └─► otherwise → middleware.onError → [status: error] → stop
 ```
 
 ### Full example
@@ -501,11 +593,28 @@ const orchestrator = new PipelineOrchestrator({
 });
 ```
 
-- All stages in a `parallel` group run simultaneously via `Promise.all`.
+- All stages in a `parallel` group run simultaneously via `Promise.all` — unless `concurrency` is set (see below).
 - If **any** stage in the group fails, the pipeline stops and marks `success: false`.
 - Each parallel stage has its own key and result in `stageResults`.
 - `rerunStep(key)` works for stages inside parallel groups too.
 
+### Limiting concurrency
+
+For fan-out over many items (e.g. paginated fetches), set `concurrency` on the group to cap how many stages run at once instead of starting all of them immediately:
+
+```js
+{
+  key: "fetch-all-pages",
+  parallel: pageNumbers.map((n) => ({
+    key: `page-${n}`,
+    request: async () => fetchPage(n),
+  })),
+  concurrency: 5, // at most 5 requests in flight at a time
+}
+```
+
+Results land in `stageResults` under their own key regardless of `concurrency`, in the same shape as an unlimited group. With the `pipe()` builder: `.parallel(stages, { concurrency: 5 })`.
+
 ---
 
 ## Global middleware
@@ -600,25 +709,33 @@ const orchestrator = new PipelineOrchestrator({
       /* ... */
     ],
     metrics: {
-      onPipelineStart: ({ timestamp }) => {
-        console.log("Pipeline started at", new Date(timestamp).toISOString());
+      onPipelineStart: ({ timestamp, runId }) => {
+        console.log(`[${runId}] Pipeline started at`, new Date(timestamp).toISOString());
       },
-      onPipelineEnd: ({ durationMs, success, stageResults }) => {
-        analytics.track("pipeline_complete", { durationMs, success });
+      onPipelineEnd: ({ durationMs, success, stageResults, runId }) => {
+        analytics.track("pipeline_complete", { durationMs, success, runId });
       },
-      onStepDuration: ({ stepKey, durationMs, status }) => {
-        console.log(`[${stepKey}] ${status} in ${durationMs}ms`);
+      onStepDuration: ({ stepKey, durationMs, status, runId }) => {
+        console.log(`[${runId}] [${stepKey}] ${status} in ${durationMs}ms`);
       },
     },
   },
 });
 ```
 
-| Callback          | Receives                                | Description                       |
-| ----------------- | --------------------------------------- | --------------------------------- |
-| `onPipelineStart` | `{ timestamp }`                         | Fires at the beginning of `run()` |
-| `onPipelineEnd`   | `{ durationMs, success, stageResults }` | Fires when `run()` completes      |
-| `onStepDuration`  | `{ stepKey, durationMs, status }`       | Fires after every executed step   |
+| Callback          | Receives                                         | Description                       |
+| ----------------- | ------------------------------------------------- | --------------------------------- |
+| `onPipelineStart` | `{ timestamp, runId }`                            | Fires at the beginning of `run()` |
+| `onPipelineEnd`   | `{ durationMs, success, stageResults, runId }`     | Fires when `run()` completes      |
+| `onStepDuration`  | `{ stepKey, durationMs, status, runId }`           | Fires after every executed step   |
+
+### Correlating a run (`runId`)
+
+Every `run()` call generates a fresh `runId` (a UUID, or a timestamp-based fallback in environments without `crypto.randomUUID`), shared by all metrics callbacks, log entries (`getLogs()`), and step events (`PipelineStepEvent.runId`) produced during that run — including all attempts of `pipelineRetry`. `rerunStep()` generates its own separate `runId`. Use `orchestrator.getRunId()` to read the current/last one, or read `runId` off any event/log/metrics callback to correlate everything that happened during one execution in your logging/tracing backend:
+
+```js
+orchestrator.on("log", (entry) => sendToLogBackend({ ...entry, runId: orchestrator.getRunId() }));
+```
 
 ---
 
@@ -671,12 +788,26 @@ const orchestrator = pipe()
 | Builder method                | Description                                              |
 | ----------------------------- | -------------------------------------------------------- |
 | `.step(stage)`                | Add a sequential stage                                   |
-| `.parallel(stages, options?)` | Add a parallel group (`key` auto-generated if omitted)   |
+| `.parallel(stages, options?)` | Add a parallel group (`key`/`concurrency` optional, see [Limiting concurrency](#limiting-concurrency)) |
 | `.subPipeline(item)`          | Embed a sub-pipeline as a stage                          |
 | `.stream(stage)`              | Add a stream stage (AsyncIterable)                       |
 | `.build(options?)`            | Create and return a `PipelineOrchestrator`               |
 | `.toConfig(options?)`         | Return `PipelineConfig` without creating an orchestrator |
 
+#### Typed chaining (TypeScript)
+
+In TypeScript, `pipe().step(...)` tracks the type of `prev` across the chain: each `.step()`'s `prev` is typed as the previous step's return value (`undefined` for the very first step, matching the orchestrator's actual runtime behavior). `.parallel()` / `.subPipeline()` / `.stream()` don't change it — exactly like at runtime, where `prev` for the next step still comes from the last regular `.step()`, not from a parallel group's results:
+
+```ts
+const orchestrator = pipe()
+  .step({ key: "auth", request: async (): Promise<string> => getToken() })
+  .step({ key: "fetchUser", request: async ({ prev }) => fetchUser(prev) }) // prev: string — inferred, autocompletes
+  .step({ key: "oops", request: async ({ prev }) => prev.totallyNotAMethod() }) // ✗ compile error: wrong type for prev
+  .build();
+```
+
+This works whether or not you keep reassigning the chain (`builder.step(...)` without capturing the return value still mutates the same instance, just like before) — the typing is purely additive and doesn't change runtime behavior.
+
 ---
 
 ## validatePipelineConfig()
@@ -848,6 +979,8 @@ type HttpAdapter = {
 };
 ```
 
+When `adapter` is set, `createRestClient()` never calls `axios.create()` — the built-in axios instance simply isn't constructed, so adapter-only usage (e.g. in Cloudflare Workers / Deno) doesn't pay for it.
+
 ---
 
 ## Vue integration
@@ -989,7 +1122,8 @@ rest-pipeline-js
 │     ├── RequestExecutor      — retry + backoff + Retry-After + AbortController timeout
 │     ├── CacheManager         — in-memory TTL cache for GET responses
 │     ├── RateLimiter          — concurrency + req/interval sliding window
-│     ├── AuthProvider         — Bearer injection; 401 refresh + one retry
+│     ├── CircuitBreaker       — closed → open → half-open; rejects locally when open
+│     ├── AuthProvider         — Bearer injection; 401 refresh + one retry; optional tokenTtlMs cache
 │     ├── MetricsCollector     — onRequestStart / onRequestEnd callbacks
 │     ├── HeaderSanitizer      — masks sensitive headers before metrics callbacks
 │     └── HttpAdapter          — pluggable transport (default: axios; swap for fetch / edge)

package/dist/cjs/cache.js

@@ -64,6 +64,21 @@ class TtlCache {
     delete(key) {
         this.store.delete(key);
     }
+    /** Итератор по всем ключам кэша (включая потенциально устаревшие — не фильтрует по TTL). */
+    keys() {
+        return this.store.keys();
+    }
+    /** Удаляет все записи, для которых predicate(key) вернул true. Возвращает количество удалённых записей. */
+    deleteWhere(predicate) {
+        let count = 0;
+        for (const key of [...this.store.keys()]) {
+            if (predicate(key)) {
+                this.store.delete(key);
+                count++;
+            }
+        }
+        return count;
+    }
     clear() {
         this.store.clear();
     }

package/dist/cjs/circuit-breaker.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreaker = exports.CircuitOpenError = void 0;
+/** Ошибка, бросаемая вместо реального запроса, когда circuit breaker открыт. */
+class CircuitOpenError extends Error {
+    constructor() {
+        super("Circuit breaker is open — request rejected without calling the network");
+        this.code = "CIRCUIT_OPEN";
+        this.name = "CircuitOpenError";
+    }
+}
+exports.CircuitOpenError = CircuitOpenError;
+/**
+ * Простой circuit breaker (closed → open → half-open → closed) для HTTP-клиента.
+ * - closed: запросы выполняются как обычно, считаются последовательные ошибки.
+ * - open: запросы немедленно отклоняются (CircuitOpenError), без обращения к сети.
+ * - half-open: после openMs пропускает запросы "на пробу"; успех закрывает circuit,
+ *   неудача снова открывает его.
+ */
+class CircuitBreaker {
+    constructor(config) {
+        this.config = config;
+        this.state = "closed";
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.openedAt = 0;
+    }
+    /** Текущее состояние (учитывает автоматический переход open → half-open по таймауту). */
+    getState() {
+        this._maybeTransitionToHalfOpen();
+        return this.state;
+    }
+    /** Можно ли выполнить запрос сейчас (false, если circuit открыт). */
+    canExecute() {
+        this._maybeTransitionToHalfOpen();
+        return this.state !== "open";
+    }
+    /** Зарегистрировать успешный запрос. */
+    onSuccess() {
+        var _a;
+        if (this.state === "half-open") {
+            this.successCount++;
+            const needed = (_a = this.config.successThreshold) !== null && _a !== void 0 ? _a : 1;
+            if (this.successCount >= needed) {
+                this._close();
+            }
+        }
+        else {
+            this.failureCount = 0;
+        }
+    }
+    /** Зарегистрировать неудачный запрос (error уже приведена к ApiError). */
+    onFailure(error) {
+        if (this.config.isFailure && !this.config.isFailure(error))
+            return;
+        if (this.state === "half-open") {
+            this._open();
+            return;
+        }
+        this.failureCount++;
+        if (this.failureCount >= this.config.failureThreshold) {
+            this._open();
+        }
+    }
+    _maybeTransitionToHalfOpen() {
+        if (this.state === "open" &&
+            Date.now() - this.openedAt >= this.config.openMs) {
+            this.state = "half-open";
+            this.successCount = 0;
+        }
+    }
+    _open() {
+        this.state = "open";
+        this.openedAt = Date.now();
+        this.failureCount = 0;
+        this.successCount = 0;
+    }
+    _close() {
+        this.state = "closed";
+        this.failureCount = 0;
+        this.successCount = 0;
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;

package/dist/cjs/index.js

@@ -23,3 +23,4 @@ __exportStar(require("./progress-tracker"), exports);
 __exportStar(require("./pipeline-orchestrator"), exports);
 __exportStar(require("./pipeline-builder"), exports);
 __exportStar(require("./pipeline-validator"), exports);
+__exportStar(require("./circuit-breaker"), exports);

package/dist/cjs/pipeline-builder.js

@@ -36,10 +36,19 @@ function createPipeline(stages, options = {}) {
  * Fluent builder для создания pipeline.
  * Позволяет строить конвейер цепочкой вызовов вместо ручного конструирования массива stages.
  *
+ * `TPrev` — тип `prev`, который получит *следующий* `.step()` (тип данных, возвращённых
+ * текущим шагом). Это чисто типовой (phantom) параметр — во время выполнения класс всегда
+ * работает с одним и тем же массивом stages, поведение не меняется по сравнению с
+ * нетипизированным использованием (без чейнинга — через отдельные вызовы без переприсвоения).
+ *
+ * `.parallel()` / `.subPipeline()` / `.stream()` не меняют `TPrev` — это соответствует
+ * реальному поведению orchestrator: `prev` следующего шага берётся из последнего обычного
+ * (`step`) шага, а не из параллельной группы/sub-pipeline/стрима.
+ *
  * @example
  * const orchestrator = pipe()
- *   .step({ key: "auth", request: async () => getToken() })
- *   .step({ key: "fetchUser", condition: ({ prev }) => !!prev, request: async ({ prev }) => fetchUser(prev) })
+ *   .step({ key: "auth", request: async () => getToken() })            // TPrev для следующего шага: string
+ *   .step({ key: "fetchUser", request: async ({ prev }) => fetchUser(prev) }) // prev: string — автокомплит и проверка типов
  *   .parallel([
  *     { key: "loadA", request: async () => loadA() },
  *     { key: "loadB", request: async () => loadB() },
@@ -52,14 +61,19 @@ class PipelineBuilder {
     }
     /**
      * Добавить обычный (последовательный) шаг.
+     * `prev` в этом шаге типизируется как результат предыдущего `.step()` (или `undefined` для первого).
+     * Тип `TOutput` обычно выводится автоматически из возвращаемого значения `request`/`after`.
      */
     step(stage) {
         this.stages.push(stage);
+        // Безопасный cast: TPrev/TOutput — чисто типовые параметры, не хранятся в экземпляре,
+        // поэтому смена фантомного типа не требует создания нового объекта.
         return this;
     }
     /**
      * Добавить группу параллельных шагов.
-     * Все шаги в группе выполняются одновременно через Promise.all.
+     * Все шаги в группе выполняются одновременно через Promise.all (либо через пул,
+     * если задан `concurrency`).
      */
     parallel(stages, options) {
         var _a;
@@ -69,6 +83,9 @@ class PipelineBuilder {
             ...((options === null || options === void 0 ? void 0 : options.continueOnError) !== undefined
                 ? { continueOnError: options.continueOnError }
                 : {}),
+            ...((options === null || options === void 0 ? void 0 : options.concurrency) !== undefined
+                ? { concurrency: options.concurrency }
+                : {}),
         };
         this.stages.push(group);
         return this;
@@ -110,6 +127,8 @@ exports.PipelineBuilder = PipelineBuilder;
 /**
  * Создаёт новый PipelineBuilder.
  * Точка входа для fluent API.
+ * `prev` первого `.step()` типизируется как `undefined` — ровно так, как ведёт себя
+ * orchestrator в реальности (у первого шага pipeline нет предыдущего результата).
  *
  * @example
  * const orchestrator = pipe()