@zudojs/middleware 0.1.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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