@zudojs/middleware 0.1.0 → 1.0.0

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

package/dist/middlewareTypes/middlewareContext.type.d.ts

@@ -4,27 +4,96 @@
  * @module middlewareTypes/middlewareContext
  */
 /**
- * Result of executing a middleware pipeline.
+ * How a pipeline reacts to a middleware or handler that throws.
+ *
+ * - `"capture"` — stop the chain and report the failure as a
+ *   {@link PipelineFailure}. The default.
+ * - `"throw"` — stop the chain and let the error propagate to the caller.
+ * - `"continue"` — record the failure, skip the rest of the failing
+ *   middleware, and continue with the next one. The handler still runs.
+ *   A handler that throws is always captured or thrown; there is nothing
+ *   left to continue to.
  */
-export interface PipelineResult<TResult> {
-    /** Whether the pipeline completed successfully */
-    readonly success: boolean;
-    /** The result value (if successful) */
-    readonly result?: TResult;
-    /** Error that occurred (if failed) */
-    readonly error?: unknown;
-    /** Execution time in milliseconds */
+export type PipelineErrorMode = "capture" | "throw" | "continue";
+/**
+ * A failure recorded while the pipeline was running.
+ */
+export interface PipelineMiddlewareFailure {
+    /** Name of the middleware that threw, or `"handler"` for the final handler. */
+    readonly name: string;
+    /** The thrown value. */
+    readonly error: unknown;
+}
+/**
+ * A pipeline run that reached the handler and completed.
+ */
+export interface PipelineSuccess<TResult> {
+    readonly success: true;
+    /** The value returned by the handler. */
+    readonly result: TResult;
+    /** Always absent on a successful run. Present in the type so that
+     *  `result.error` is legal to read before narrowing. */
+    readonly error?: undefined;
+    /** Execution time in milliseconds. */
     readonly durationMs: number;
-    /** Names of middleware that executed */
+    /** Names of middleware that started executing, in execution order. */
     readonly executedMiddleware: readonly string[];
+    /** Failures swallowed under `errorMode: "continue"`. Empty otherwise. */
+    readonly errors: readonly PipelineMiddlewareFailure[];
 }
+/**
+ * A pipeline run that ended in a captured failure.
+ */
+export interface PipelineFailure {
+    readonly success: false;
+    /** Always absent on a failed run. */
+    readonly result?: undefined;
+    /** The error that ended the run. */
+    readonly error: unknown;
+    /** Execution time in milliseconds. */
+    readonly durationMs: number;
+    /** Names of middleware that started executing, in execution order. */
+    readonly executedMiddleware: readonly string[];
+    /** Every failure recorded during the run, including {@link PipelineFailure.error}. */
+    readonly errors: readonly PipelineMiddlewareFailure[];
+}
+/**
+ * Result of executing a middleware pipeline.
+ *
+ * Discriminated on `success`, so narrowing gives a non-optional `result`:
+ *
+ * ```ts
+ * const outcome = await pipeline(context);
+ * if (outcome.success) {
+ *   use(outcome.result); // TResult, not TResult | undefined
+ * }
+ * ```
+ */
+export type PipelineResult<TResult> = PipelineSuccess<TResult> | PipelineFailure;
 /**
  * Options for creating a middleware pipeline.
  */
 export interface PipelineOptions {
-    /** Maximum number of middleware allowed */
+    /** Maximum number of enabled middleware allowed. Default: 50. */
     readonly maxMiddleware?: number;
-    /** Whether to stop on first error (default: true) */
+    /**
+     * How the pipeline reacts to an error. Default: `"capture"`.
+     *
+     * @see PipelineErrorMode
+     */
+    readonly errorMode?: PipelineErrorMode;
+    /**
+     * Legacy alias for {@link PipelineOptions.errorMode}: `true` maps to
+     * `"capture"` and `false` to `"throw"`. Ignored when `errorMode` is set.
+     *
+     * @deprecated Use `errorMode` — the name describes the wrong axis, since
+     * both settings stop the chain.
+     */
     readonly stopOnError?: boolean;
+    /**
+     * Aborts the run. Checked before each middleware and before the handler;
+     * an aborted pipeline fails with a `MiddlewareAbortedError`.
+     */
+    readonly signal?: AbortSignal;
 }
 //# sourceMappingURL=middlewareContext.type.d.ts.map

package/dist/middlewareUtils/index.d.ts

@@ -3,5 +3,5 @@
  *
  * @module middlewareUtils
  */
-export { loggingMiddleware, errorMiddleware, timeoutMiddleware, rateLimitMiddleware, } from "./middlewareUtils.builtins.js";
+export { loggingMiddleware, errorMiddleware, timeoutMiddleware, rateLimitMiddleware, sanitizeLogValue, type LoggingContext, type LoggingOptions, type TimeoutOptions, type RateLimitOptions, type RateLimitState, type RateLimitMiddleware, } from "./middlewareUtils.builtins.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/middlewareUtils/index.js

@@ -3,5 +3,5 @@
  *
  * @module middlewareUtils
  */
-export { loggingMiddleware, errorMiddleware, timeoutMiddleware, rateLimitMiddleware, } from "./middlewareUtils.builtins.js";
+export { loggingMiddleware, errorMiddleware, timeoutMiddleware, rateLimitMiddleware, sanitizeLogValue, } from "./middlewareUtils.builtins.js";
 //# sourceMappingURL=index.js.map

package/dist/middlewareUtils/middlewareUtils.builtins.d.ts

@@ -9,30 +9,109 @@ export interface LoggingContext {
     readonly path?: string;
     readonly method?: string;
 }
+/**
+ * Make a caller-supplied value safe to write into a single-line log.
+ *
+ * CR and LF above all are what let a request path forge extra log lines, so
+ * control characters are escaped rather than dropped — the original stays
+ * visible without being able to break out of its line.
+ */
+export declare function sanitizeLogValue(value: unknown, maxLength?: number): string;
+/** Options for {@link loggingMiddleware}. */
+export interface LoggingOptions {
+    /**
+     * Include the failing error's message in the completion line.
+     * Defaults to `false`: error messages routinely carry connection strings,
+     * tokens and user data, and the pipeline already surfaces the error object
+     * to the caller.
+     */
+    readonly includeErrorMessage?: boolean;
+    /** Longest field value written before truncation. Default: 256. */
+    readonly maxFieldLength?: number;
+}
 /**
  * Create a logging middleware.
  *
- * Logs request start, completion, and errors.
+ * Logs request start, completion, and errors. Every interpolated field is
+ * escaped, so a path containing newlines cannot forge log lines.
  */
-export declare function loggingMiddleware(logger?: (msg: string) => void): NamedMiddleware<LoggingContext>;
+export declare function loggingMiddleware<TResult = void>(logger?: (msg: string) => void, options?: LoggingOptions): NamedMiddleware<LoggingContext, TResult>;
 /**
  * Create an error-handling middleware.
  *
- * Catches errors and wraps them with context.
+ * Reports errors through `onError` and rethrows them. A reporter that throws
+ * cannot replace the error it was reporting — its own failure goes to
+ * `onReporterError` instead.
  */
-export declare function errorMiddleware(onError?: (error: unknown, ctx: unknown) => void): NamedMiddleware<unknown>;
+export declare function errorMiddleware<TResult = void>(onError?: (error: unknown, ctx: unknown) => void, onReporterError?: (error: unknown) => void): NamedMiddleware<unknown, TResult>;
+/** Options for {@link timeoutMiddleware}. */
+export interface TimeoutOptions {
+    /** Name reported in the timeout error. Default: `"timeout"`. */
+    readonly name?: string;
+}
 /**
  * Create a timeout middleware.
  *
- * Rejects if the pipeline takes too long.
+ * Rejects with a {@link MiddlewareTimeoutError} if the rest of the pipeline
+ * takes too long. The timer is always cleared, so a fast request leaves
+ * nothing pending on the event loop, and the losing promise stays handled so
+ * a late rejection cannot surface as an unhandled rejection.
+ *
+ * The downstream work is not cancelled — nothing in the middleware contract
+ * can cancel it. Use the pipeline's `signal` option, or carry an
+ * `AbortSignal` on your own context, when the work itself needs to stop.
  */
-export declare function timeoutMiddleware<TContext>(timeoutMs: number): NamedMiddleware<TContext>;
+export declare function timeoutMiddleware<TContext, TResult = void>(timeoutMs: number, options?: TimeoutOptions): NamedMiddleware<TContext, TResult>;
+/** Options for {@link rateLimitMiddleware}. */
+export interface RateLimitOptions {
+    /**
+     * Maximum number of distinct keys tracked at once. When the limit is
+     * reached, expired keys are swept and — if that is not enough — the
+     * least-recently-seen keys are evicted. Default: 10,000.
+     *
+     * Keys are usually caller-controlled (an IP, an API key, a tenant), so an
+     * unbounded map is a memory sink an attacker can drive.
+     */
+    readonly maxKeys?: number;
+    /** How often expired keys are swept, in milliseconds. Default: 60,000. */
+    readonly sweepIntervalMs?: number;
+    /**
+     * Reject requests that arrive with no key instead of pooling them into a
+     * single shared bucket. Default: `false`, preserving the shared bucket.
+     */
+    readonly rejectUnkeyed?: boolean;
+}
+/** A rate limiter's live view of one key. */
+export interface RateLimitState {
+    /** Requests counted in the current window. */
+    readonly count: number;
+    /** Milliseconds until the oldest request leaves the window. */
+    readonly retryAfterMs: number;
+}
+/** The middleware returned by {@link rateLimitMiddleware}. */
+export interface RateLimitMiddleware<TContext, TResult = void> extends NamedMiddleware<TContext, TResult> {
+    /** Inspect a key's current window. Exposed for metrics and tests. */
+    readonly inspect: (key: string) => RateLimitState | undefined;
+    /** Number of keys currently tracked. */
+    readonly size: () => number;
+    /** Drop all tracked keys. */
+    readonly reset: () => void;
+}
 /**
  * Create a rate-limiting middleware.
  *
- * Uses a sliding window counter per key.
+ * Implements a true sliding window: each key keeps the timestamps of its
+ * requests within `windowMs`, so a client cannot burst `2 × maxRequests`
+ * across a window boundary the way a fixed-window counter allows.
+ *
+ * Rejections throw {@link MiddlewareRateLimitError}, which carries
+ * `retryAfterMs` for an HTTP adapter to turn into a 429 with `Retry-After`.
+ *
+ * State is per-instance and in-process. Behind more than one instance of a
+ * service, each process enforces its own limit; use a shared store for a
+ * cluster-wide one.
  */
 export declare function rateLimitMiddleware<TContext extends {
     readonly key?: string;
-}>(maxRequests: number, windowMs: number): NamedMiddleware<TContext>;
+}, TResult = void>(maxRequests: number, windowMs: number, options?: RateLimitOptions): RateLimitMiddleware<TContext, TResult>;
 //# sourceMappingURL=middlewareUtils.builtins.d.ts.map