@zudojs/middleware 0.0.1 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @zudojs/middleware
 
-Composable middleware pipeline with composition, timing, error handling, and context propagation.
+Composable middleware pipeline with composition, priority ordering, execution tracking, error handling, and built-in middleware.
 
 ## Installation
 
@@ -12,28 +12,175 @@ npm install @zudojs/middleware
 
 ```typescript
 import {
-  createMiddlewarePipeline,
-  createTimeoutMiddleware,
+  createPipeline,
+  timeoutMiddleware,
+  loggingMiddleware,
+  rateLimitMiddleware,
 } from "@zudojs/middleware";
 
-const pipeline = createMiddlewarePipeline([
-  createTimeoutMiddleware(5000),
-  createLoggingMiddleware(),
-  createAuthMiddleware(),
-]);
+interface RequestContext {
+  readonly method?: string;
+  readonly path?: string;
+  readonly key?: string;
+}
 
-await pipeline(context, async () => {
-  return handler(context);
+// The handler runs after every middleware has called next().
+const pipeline = createPipeline<RequestContext, string>(
+  [
+    timeoutMiddleware(5_000),
+    loggingMiddleware(),
+    rateLimitMiddleware(100, 60_000),
+  ],
+  async (context) => `handled ${context.method} ${context.path}`,
+);
+
+const outcome = await pipeline({
+  method: "GET",
+  path: "/users",
+  key: "client-1",
 });
+
+if (outcome.success) {
+  console.log(outcome.result); // "handled GET /users"
+} else {
+  console.error(outcome.error);
+}
+```
+
+`PipelineResult` is a discriminated union: narrowing on `success` gives you a
+non-optional `result`, so no `!` is needed on the happy path.
+
+## Composition without the result wrapper
+
+`compose` chains middleware around a handler and returns the handler's value
+directly. Use it when you want the raw function rather than a
+`PipelineResult`.
+
+```typescript
+import { compose } from "@zudojs/middleware";
+import type { Middleware } from "@zudojs/middleware";
+
+const auth: Middleware<RequestContext, string> = async (context, next) => {
+  if (context.key === undefined) throw new Error("unauthenticated");
+  return next();
+};
+
+const handle = compose([auth], async (context) => `hello ${context.key}`);
+await handle({ key: "client-1" });
 ```
 
-## Features
+## Priority and toggling
+
+`NamedMiddleware` carries a name, a numeric `priority` (lower runs earlier,
+default 100) and an `enabled` flag. `createPipeline` filters and orders them
+for you, and reports which ones ran.
+
+```typescript
+const pipeline = createPipeline(
+  [
+    { name: "auth", handler: auth, priority: 10 },
+    { name: "audit", handler: audit, priority: 90, enabled: false },
+  ],
+  handler,
+);
+
+const outcome = await pipeline(context);
+outcome.executedMiddleware; // ["auth"] — "audit" is disabled
+```
+
+Ordering is stable, so middleware sharing a priority keeps its declared order.
+
+## Error handling
+
+`errorMode` decides what a failure does:
+
+| Mode                  | Behaviour                                                                                             |
+| --------------------- | ----------------------------------------------------------------------------------------------------- |
+| `"capture"` (default) | Stop and return `{ success: false, error }`.                                                          |
+| `"throw"`             | Stop and let the error propagate to the caller.                                                       |
+| `"continue"`          | Record the failure, skip past the failing middleware, keep going. A handler failure is never skipped. |
+
+Every failure is also collected in `outcome.errors`, each tagged with the name
+of the middleware that threw (or `"handler"`).
+
+> **`"continue"` is not for security middleware.** Stepping past a middleware
+> that threw means an authentication or authorization step that failed is
+> stepped past too, and the handler still runs. A run can come back
+> `success: true` with entries in `outcome.errors`, so under this mode check
+> `outcome.errors` as well as `outcome.success`. Use `"capture"` (the default)
+> or `"throw"` for any chain where a failing step must stop the request.
+
+A middleware that catches a downstream failure and throws its own error in its
+place ends the run: there is no downstream result left to keep, so the
+pipeline reports the failure rather than a result that never existed.
+
+```typescript
+const pipeline = createPipeline(list, handler, { errorMode: "continue" });
+const outcome = await pipeline(context);
+outcome.errors; // [{ name: "audit", error: … }]
+```
+
+## Cancellation
+
+Pass an `AbortSignal` to stop a pipeline between steps. The signal is checked
+before each middleware and before the handler; an aborted run fails with a
+`MiddlewareAbortedError`.
+
+```typescript
+const controller = new AbortController();
+const pipeline = createPipeline(list, handler, { signal: controller.signal });
+```
+
+## Built-in middleware
+
+- **`loggingMiddleware(logger?, options?)`** — logs start and completion.
+  Every interpolated field is escaped, so a path containing newlines cannot
+  forge log lines. Error messages are omitted unless you opt in with
+  `includeErrorMessage`.
+- **`errorMiddleware(onError?, onReporterError?)`** — reports errors and
+  rethrows them. A reporter that throws cannot replace the original error.
+- **`timeoutMiddleware(timeoutMs, options?)`** — fails with
+  `MiddlewareTimeoutError`. The timer is always cleared, so a fast request
+  leaves nothing pending on the event loop. `options.name` names the
+  middleware itself, so two timeouts in one pipeline are distinguishable in
+  `executedMiddleware` and in `outcome.errors`.
+- **`rateLimitMiddleware(maxRequests, windowMs, options?)`** — a true sliding
+  window keyed on `context.key`, with key eviction and a configurable cap.
+  Rejections throw `MiddlewareRateLimitError`, which carries `retryAfterMs`
+  for a `Retry-After` header.
+
+```typescript
+import { MiddlewareRateLimitError } from "@zudojs/middleware";
+
+if (outcome.error instanceof MiddlewareRateLimitError) {
+  respond(429, { retryAfterMs: outcome.error.retryAfterMs });
+}
+```
+
+Rate-limit state is per-instance and in-process: behind more than one replica,
+each process enforces its own limit.
+
+## Timing
+
+`withTiming` wraps any middleware and reports slow executions. It is
+transparent — the return value and any error pass through unchanged.
+
+```typescript
+const timed = withTiming("db-lookup", lookup, {
+  thresholdMs: 50,
+  logger: (message) => logger.warn(message),
+});
+```
+
+## Errors
+
+All errors extend `MiddlewareError` (itself a `BaseError` from
+`@zudojs/errors`), so a single `instanceof` catches everything from this
+package:
 
-- Composable middleware pipeline
-- Error handling middleware
-- Timing and metrics middleware
-- Context propagation
-- Early termination support
+`MiddlewareTimeoutError` · `MiddlewareNextCalledMultipleTimesError` ·
+`MiddlewareLimitExceededError` · `MiddlewareDepthExceededError` ·
+`MiddlewareRateLimitError` · `MiddlewareAbortedError`
 
 ## Use Cases
 

package/dist/middlewareCore/index.d.ts

@@ -3,5 +3,5 @@
  *
  * @module middlewareCore
  */
-export { compose, resolveMiddleware, withTiming, } from "./middlewareCore.compose.js";
+export { compose, resolveMiddleware, resolveNamedMiddleware, withTiming, MAX_DEPTH, type ComposeOptions, type TimingOptions, } from "./middlewareCore.compose.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/middlewareCore/index.js

@@ -3,5 +3,5 @@
  *
  * @module middlewareCore
  */
-export { compose, resolveMiddleware, withTiming, } from "./middlewareCore.compose.js";
+export { compose, resolveMiddleware, resolveNamedMiddleware, withTiming, MAX_DEPTH, } from "./middlewareCore.compose.js";
 //# sourceMappingURL=index.js.map

package/dist/middlewareCore/middlewareCore.compose.d.ts

@@ -7,6 +7,13 @@
  * Each middleware calls `next()` to proceed to the next one.
  */
 import type { Middleware, NamedMiddleware } from "../middlewareTypes/middlewareDefinition.type.js";
+/** Default ceiling on how deeply a composed chain may nest. */
+export declare const MAX_DEPTH = 100;
+/** Options for {@link compose}. */
+export interface ComposeOptions {
+    /** Maximum chain depth. Default: {@link MAX_DEPTH}. */
+    readonly maxDepth?: number;
+}
 /**
  * Compose an array of middleware into a single function.
  *
@@ -15,18 +22,43 @@ import type { Middleware, NamedMiddleware } from "../middlewareTypes/middlewareD
  *
  * @param middlewareList - Array of middleware functions
  * @param handler - The final handler to execute after all middleware
+ * @param options - Composition limits
  * @returns Composed function
+ * @throws MiddlewareDepthExceededError if the chain is longer than `maxDepth`
  */
-export declare function compose<TContext, TResult>(middlewareList: readonly Middleware<TContext, TResult>[], handler: (context: TContext) => Promise<TResult>): (context: TContext) => Promise<TResult>;
+export declare function compose<TContext, TResult>(middlewareList: readonly Middleware<TContext, TResult>[], handler: (context: TContext) => Promise<TResult>, options?: ComposeOptions): (context: TContext) => Promise<TResult>;
 /**
- * Sort and filter named middleware by priority.
+ * Filter disabled middleware and sort the rest by priority.
+ *
+ * Ordering is stable, so middleware sharing a priority keeps its input order.
+ *
+ * @param middlewareList - Array of named middleware
+ * @returns Enabled middleware, in execution order, with names intact
+ */
+export declare function resolveNamedMiddleware<TContext, TResult>(middlewareList: readonly NamedMiddleware<TContext, TResult>[]): NamedMiddleware<TContext, TResult>[];
+/**
+ * Sort and filter named middleware by priority, returning bare handlers.
+ *
+ * Prefer {@link resolveNamedMiddleware} when the names are needed — this is a
+ * thin projection of it.
  *
  * @param middlewareList - Array of named middleware
  * @returns Sorted and filtered array of middleware handler functions
  */
 export declare function resolveMiddleware<TContext, TResult>(middlewareList: readonly NamedMiddleware<TContext, TResult>[]): Middleware<TContext, TResult>[];
+/** Options for {@link withTiming}. */
+export interface TimingOptions {
+    /** Log only when the middleware takes at least this long. Default: 100ms. */
+    readonly thresholdMs?: number;
+    /** Where to report slow middleware. Default: `console.warn`. */
+    readonly logger?: (message: string) => void;
+}
 /**
- * Create a middleware that wraps another with timing.
+ * Wrap a middleware so that slow executions are reported.
+ *
+ * The wrapper is transparent: the inner middleware's return value and any
+ * error it throws pass through unchanged, and the timing is reported either
+ * way.
  */
-export declare function withTiming<TContext>(name: string, middleware: Middleware<TContext, void>): NamedMiddleware<TContext, void>;
+export declare function withTiming<TContext, TResult = void>(name: string, middleware: Middleware<TContext, TResult>, options?: TimingOptions): NamedMiddleware<TContext, TResult>;
 //# sourceMappingURL=middlewareCore.compose.d.ts.map

package/dist/middlewareCore/middlewareCore.compose.js

@@ -6,7 +6,9 @@
  * Middleware executes in order (first added = first executed).
  * Each middleware calls `next()` to proceed to the next one.
  */
-const MAX_DEPTH = 100;
+import { MiddlewareDepthExceededError, MiddlewareNextCalledMultipleTimesError, } from "../middlewareErrors/middlewareError.base.js";
+/** Default ceiling on how deeply a composed chain may nest. */
+export const MAX_DEPTH = 100;
 /**
  * Compose an array of middleware into a single function.
  *
@@ -15,9 +17,15 @@ const MAX_DEPTH = 100;
  *
  * @param middlewareList - Array of middleware functions
  * @param handler - The final handler to execute after all middleware
+ * @param options - Composition limits
  * @returns Composed function
+ * @throws MiddlewareDepthExceededError if the chain is longer than `maxDepth`
  */
-export function compose(middlewareList, handler) {
+export function compose(middlewareList, handler, options) {
+    const maxDepth = options?.maxDepth ?? MAX_DEPTH;
+    if (middlewareList.length > maxDepth) {
+        throw new MiddlewareDepthExceededError(maxDepth);
+    }
     if (middlewareList.length === 0) {
         return handler;
     }
@@ -25,7 +33,12 @@ export function compose(middlewareList, handler) {
         let index = -1;
         async function dispatch(i) {
             if (i <= index) {
-                throw new Error("next() called multiple times");
+                // dispatch(i) is invoked by the middleware at i - 1, so that is the
+                // one that called next() again.
+                throw new MiddlewareNextCalledMultipleTimesError(`middleware[${i - 1}]`);
+            }
+            if (i > maxDepth) {
+                throw new MiddlewareDepthExceededError(maxDepth);
             }
             index = i;
             if (i < middlewareList.length) {
@@ -38,29 +51,55 @@ export function compose(middlewareList, handler) {
     };
 }
 /**
- * Sort and filter named middleware by priority.
+ * Filter disabled middleware and sort the rest by priority.
+ *
+ * Ordering is stable, so middleware sharing a priority keeps its input order.
  *
  * @param middlewareList - Array of named middleware
- * @returns Sorted and filtered array of middleware handler functions
+ * @returns Enabled middleware, in execution order, with names intact
  */
-export function resolveMiddleware(middlewareList) {
+export function resolveNamedMiddleware(middlewareList) {
     return middlewareList
         .filter((mw) => mw.enabled !== false)
-        .sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100))
-        .map((mw) => mw.handler);
+        .sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
 }
 /**
- * Create a middleware that wraps another with timing.
+ * Sort and filter named middleware by priority, returning bare handlers.
+ *
+ * Prefer {@link resolveNamedMiddleware} when the names are needed — this is a
+ * thin projection of it.
+ *
+ * @param middlewareList - Array of named middleware
+ * @returns Sorted and filtered array of middleware handler functions
  */
-export function withTiming(name, middleware) {
+export function resolveMiddleware(middlewareList) {
+    return resolveNamedMiddleware(middlewareList).map((mw) => mw.handler);
+}
+/**
+ * Wrap a middleware so that slow executions are reported.
+ *
+ * The wrapper is transparent: the inner middleware's return value and any
+ * error it throws pass through unchanged, and the timing is reported either
+ * way.
+ */
+export function withTiming(name, middleware, options) {
+    const thresholdMs = options?.thresholdMs ?? 100;
+    const log = options?.logger ??
+        ((message) => {
+            console.warn(message);
+        });
     return {
         name,
         handler: async (ctx, next) => {
             const start = performance.now();
-            await middleware(ctx, next);
-            const duration = performance.now() - start;
-            if (duration > 100) {
-                console.warn(`[middleware] ${name} took ${duration.toFixed(1)}ms`);
+            try {
+                return await middleware(ctx, next);
+            }
+            finally {
+                const duration = performance.now() - start;
+                if (duration >= thresholdMs) {
+                    log(`[middleware] ${name} took ${duration.toFixed(1)}ms`);
+                }
             }
         },
     };

package/dist/middlewareErrors/index.d.ts

@@ -3,5 +3,5 @@
  *
  * @module middlewareErrors
  */
-export { MiddlewareError, MiddlewareTimeoutError, MiddlewareNextCalledMultipleTimesError, } from "./middlewareError.base.js";
+export { MiddlewareError, MiddlewareTimeoutError, MiddlewareNextCalledMultipleTimesError, MiddlewareLimitExceededError, MiddlewareDepthExceededError, MiddlewareRateLimitError, MiddlewareAbortedError, } from "./middlewareError.base.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/middlewareErrors/index.js

@@ -3,5 +3,5 @@
  *
  * @module middlewareErrors
  */
-export { MiddlewareError, MiddlewareTimeoutError, MiddlewareNextCalledMultipleTimesError, } from "./middlewareError.base.js";
+export { MiddlewareError, MiddlewareTimeoutError, MiddlewareNextCalledMultipleTimesError, MiddlewareLimitExceededError, MiddlewareDepthExceededError, MiddlewareRateLimitError, MiddlewareAbortedError, } from "./middlewareError.base.js";
 //# sourceMappingURL=index.js.map

package/dist/middlewareErrors/middlewareError.base.d.ts

@@ -25,4 +25,34 @@ export declare class MiddlewareTimeoutError extends MiddlewareError {
 export declare class MiddlewareNextCalledMultipleTimesError extends MiddlewareError {
     constructor(middlewareName: string);
 }
+/**
+ * Error thrown when a pipeline is configured with more middleware than allowed.
+ */
+export declare class MiddlewareLimitExceededError extends MiddlewareError {
+    constructor(count: number, maximum: number);
+}
+/**
+ * Error thrown when the middleware chain nests deeper than the allowed limit.
+ */
+export declare class MiddlewareDepthExceededError extends MiddlewareError {
+    constructor(maxDepth: number);
+}
+/**
+ * Error thrown when a rate limit is exceeded.
+ *
+ * `retryAfterMs` tells the caller how long to wait before retrying, which is
+ * what an HTTP adapter needs to emit a `Retry-After` header alongside a 429.
+ */
+export declare class MiddlewareRateLimitError extends MiddlewareError {
+    readonly retryAfterMs: number;
+    readonly limit: number;
+    readonly windowMs: number;
+    constructor(limit: number, windowMs: number, retryAfterMs: number);
+}
+/**
+ * Error thrown when a pipeline is aborted through its `AbortSignal`.
+ */
+export declare class MiddlewareAbortedError extends MiddlewareError {
+    constructor(reason?: unknown);
+}
 //# sourceMappingURL=middlewareError.base.d.ts.map

package/dist/middlewareErrors/middlewareError.base.js

@@ -40,4 +40,47 @@ export class MiddlewareNextCalledMultipleTimesError extends MiddlewareError {
         });
     }
 }
+/**
+ * Error thrown when a pipeline is configured with more middleware than allowed.
+ */
+export class MiddlewareLimitExceededError extends MiddlewareError {
+    constructor(count, maximum) {
+        super(`Pipeline has ${count} middleware, exceeding the maximum of ${maximum}`);
+    }
+}
+/**
+ * Error thrown when the middleware chain nests deeper than the allowed limit.
+ */
+export class MiddlewareDepthExceededError extends MiddlewareError {
+    constructor(maxDepth) {
+        super(`Middleware chain exceeded the maximum depth of ${maxDepth}`);
+    }
+}
+/**
+ * Error thrown when a rate limit is exceeded.
+ *
+ * `retryAfterMs` tells the caller how long to wait before retrying, which is
+ * what an HTTP adapter needs to emit a `Retry-After` header alongside a 429.
+ */
+export class MiddlewareRateLimitError extends MiddlewareError {
+    retryAfterMs;
+    limit;
+    windowMs;
+    constructor(limit, windowMs, retryAfterMs) {
+        super(`Rate limit exceeded: ${limit} requests per ${windowMs}ms`, {
+            middlewareName: "rate-limit",
+        });
+        this.retryAfterMs = retryAfterMs;
+        this.limit = limit;
+        this.windowMs = windowMs;
+    }
+}
+/**
+ * Error thrown when a pipeline is aborted through its `AbortSignal`.
+ */
+export class MiddlewareAbortedError extends MiddlewareError {
+    constructor(reason) {
+        super("Middleware pipeline aborted", { cause: reason });
+    }
+}
 //# sourceMappingURL=middlewareError.base.js.map

package/dist/middlewarePipeline/middlewarePipeline.core.d.ts

@@ -3,8 +3,8 @@
  *
  * @module middlewarePipeline/middlewarePipeline
  */
-import type { NamedMiddleware } from "../middlewareTypes/middlewareDefinition.type.js";
 import type { PipelineResult, PipelineOptions } from "../middlewareTypes/middlewareContext.type.js";
+import type { NamedMiddleware } from "../middlewareTypes/middlewareDefinition.type.js";
 /**
  * Create a middleware pipeline that tracks execution.
  *
@@ -12,6 +12,8 @@ import type { PipelineResult, PipelineOptions } from "../middlewareTypes/middlew
  * @param handler - Final handler function
  * @param options - Pipeline configuration
  * @returns Pipeline execution function
+ * @throws MiddlewareLimitExceededError if more middleware are enabled than
+ * `maxMiddleware` allows
  */
 export declare function createPipeline<TContext, TResult>(middlewareList: readonly NamedMiddleware<TContext, TResult>[], handler: (context: TContext) => Promise<TResult>, options?: PipelineOptions): (context: TContext) => Promise<PipelineResult<TResult>>;
 //# sourceMappingURL=middlewarePipeline.core.d.ts.map

package/dist/middlewarePipeline/middlewarePipeline.core.js

@@ -3,8 +3,18 @@
  *
  * @module middlewarePipeline/middlewarePipeline
  */
-import { resolveMiddleware } from "../middlewareCore/middlewareCore.compose.js";
+import { resolveNamedMiddleware } from "../middlewareCore/middlewareCore.compose.js";
+import { MiddlewareAbortedError, MiddlewareLimitExceededError, MiddlewareNextCalledMultipleTimesError, } from "../middlewareErrors/middlewareError.base.js";
 const DEFAULT_MAX = 50;
+/** Name recorded for a failure thrown by the final handler. */
+const HANDLER_NAME = "handler";
+function resolveErrorMode(options) {
+    if (options?.errorMode)
+        return options.errorMode;
+    if (options?.stopOnError === false)
+        return "throw";
+    return "capture";
+}
 /**
  * Create a middleware pipeline that tracks execution.
  *
@@ -12,33 +22,93 @@ const DEFAULT_MAX = 50;
  * @param handler - Final handler function
  * @param options - Pipeline configuration
  * @returns Pipeline execution function
+ * @throws MiddlewareLimitExceededError if more middleware are enabled than
+ * `maxMiddleware` allows
  */
 export function createPipeline(middlewareList, handler, options) {
-    const resolved = resolveMiddleware(middlewareList);
+    const resolved = resolveNamedMiddleware(middlewareList);
     const maxMiddleware = options?.maxMiddleware ?? DEFAULT_MAX;
-    const stopOnError = options?.stopOnError ?? true;
+    const errorMode = resolveErrorMode(options);
+    const signal = options?.signal;
     if (resolved.length > maxMiddleware) {
-        throw new Error(`Pipeline has ${resolved.length} middleware, exceeding maximum of ${maxMiddleware}`);
+        throw new MiddlewareLimitExceededError(resolved.length, maxMiddleware);
     }
-    const enabledNames = middlewareList
-        .filter((mw) => mw.enabled !== false)
-        .sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100))
-        .map((mw) => mw.name);
     return async (context) => {
         const startTime = performance.now();
         const executed = [];
+        const errors = [];
         let index = -1;
+        /**
+         * The error the final handler threw, if it did. Middleware still sees the
+         * error itself — wrapping it would break `catch (e) { if (e instanceof
+         * HttpError) … }` in user middleware — so identity is what marks it as
+         * the handler's, and that is what stops `errorMode: "continue"` from
+         * treating it as a middleware failure it can step past.
+         */
+        let handlerError;
+        function throwIfAborted() {
+            if (signal?.aborted) {
+                throw new MiddlewareAbortedError(signal.reason);
+            }
+        }
+        /** Errors that `"continue"` must never swallow. */
+        function isFatal(error) {
+            return ((handlerError !== undefined && error === handlerError.error) ||
+                error instanceof MiddlewareAbortedError ||
+                error instanceof MiddlewareNextCalledMultipleTimesError);
+        }
         async function dispatch(i) {
             if (i <= index) {
-                throw new Error("next() called multiple times");
+                // dispatch(i) is invoked by the middleware at i - 1, so that is the
+                // one that called next() again.
+                const name = resolved[i - 1]?.name ?? `middleware[${i - 1}]`;
+                throw new MiddlewareNextCalledMultipleTimesError(name);
             }
             index = i;
-            if (i < resolved.length) {
-                executed.push(enabledNames[i] ?? `middleware-${i}`);
-                const mw = resolved[i];
-                return mw(context, () => dispatch(i + 1));
+            throwIfAborted();
+            if (i >= resolved.length) {
+                try {
+                    return await handler(context);
+                }
+                catch (error) {
+                    handlerError = { error };
+                    throw error;
+                }
+            }
+            const mw = resolved[i];
+            executed.push(mw.name);
+            if (errorMode !== "continue") {
+                return mw.handler(context, () => dispatch(i + 1));
+            }
+            let advanced = false;
+            // Boxed rather than a bare `TResult | undefined`, so "the downstream
+            // chain produced a value" is distinguishable from "it produced
+            // `undefined`" without an assertion.
+            let downstream;
+            try {
+                return await mw.handler(context, async () => {
+                    advanced = true;
+                    const value = await dispatch(i + 1);
+                    downstream = { value };
+                    return value;
+                });
+            }
+            catch (error) {
+                if (isFatal(error))
+                    throw error;
+                if (advanced && downstream === undefined) {
+                    // next() was entered but never produced a result — the middleware
+                    // caught the downstream failure and threw something of its own.
+                    // There is no downstream result to keep and no step left to
+                    // continue to, so returning `undefined` as if it were a `TResult`
+                    // would report a successful run that never happened.
+                    throw error;
+                }
+                errors.push({ name: mw.name, error });
+                // The chain already ran past this middleware, so its downstream
+                // result stands; otherwise pick up at the next middleware.
+                return downstream ? downstream.value : dispatch(i + 1);
             }
-            return handler(context);
         }
         try {
             const result = await dispatch(0);
@@ -47,18 +117,26 @@ export function createPipeline(middlewareList, handler, options) {
                 result,
                 durationMs: performance.now() - startTime,
                 executedMiddleware: executed,
+                errors,
             };
         }
         catch (error) {
-            if (stopOnError) {
-                return {
-                    success: false,
+            const fromHandler = handlerError !== undefined && error === handlerError.error;
+            if (!errors.some((failure) => failure.error === error)) {
+                errors.push({
+                    name: fromHandler ? HANDLER_NAME : (executed.at(-1) ?? HANDLER_NAME),
                     error,
-                    durationMs: performance.now() - startTime,
-                    executedMiddleware: executed,
-                };
+                });
             }
-            throw error;
+            if (errorMode === "throw")
+                throw error;
+            return {
+                success: false,
+                error,
+                durationMs: performance.now() - startTime,
+                executedMiddleware: executed,
+                errors,
+            };
         }
     };
 }

package/dist/middlewareTypes/index.d.ts

@@ -4,5 +4,5 @@
  * @module middlewareTypes
  */
 export { type Middleware, type NamedMiddleware, type MiddlewareFactory, } from "./middlewareDefinition.type.js";
-export { type PipelineResult, type PipelineOptions, } from "./middlewareContext.type.js";
+export { type PipelineResult, type PipelineSuccess, type PipelineFailure, type PipelineMiddlewareFailure, type PipelineErrorMode, type PipelineOptions, } from "./middlewareContext.type.js";
 //# sourceMappingURL=index.d.ts.map