@zudojs/middleware 1.0.1 → 1.0.3

package/README.md

@@ -2,6 +2,12 @@
 
 Composable middleware pipeline with composition, priority ordering, execution tracking, error handling, and built-in middleware.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-middleware](https://zudojs.oyinlola.site/docs/packages-middleware) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-middleware.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -28,7 +34,7 @@ interface RequestContext {
 const pipeline = createPipeline<RequestContext, string>(
   [
     timeoutMiddleware(5_000),
-    loggingMiddleware(),
+    loggingMiddleware((line) => console.info(line)),
     rateLimitMiddleware(100, 60_000),
   ],
   async (context) => `handled ${context.method} ${context.path}`,
@@ -133,8 +139,10 @@ 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
+- **`loggingMiddleware(logger?, options?)`** — logs start and completion
+  to `logger`, a `(line: string) => void` sink such as
+  `(line) => log.info(line)` from `@zudojs/logger`. Without a sink it writes
+  nothing (it never falls back to the console). 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
@@ -147,7 +155,9 @@ const pipeline = createPipeline(list, handler, { signal: controller.signal });
 - **`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.
+  for a `Retry-After` header. A rejected request also counts as recent
+  activity, so a throttled key is never the first one evicted when the key
+  cap is reached.
 
 ```typescript
 import { MiddlewareRateLimitError } from "@zudojs/middleware";
@@ -162,7 +172,8 @@ each process enforces its own limit.
 
 ## Timing
 
-`withTiming` wraps any middleware and reports slow executions. It is
+`withTiming` wraps any middleware and reports slow executions to
+`options.logger`. Without a logger nothing is reported. It is
 transparent — the return value and any error pass through unchanged.
 
 ```typescript
@@ -174,9 +185,11 @@ const timed = withTiming("db-lookup", lookup, {
 
 ## Errors
 
-All errors extend `MiddlewareError` (itself a `BaseError` from
-`@zudojs/errors`), so a single `instanceof` catches everything from this
-package:
+All errors extend `MiddlewareError`, which is the class owned by
+`@zudojs/errors` (re-exported here). `MiddlewareTimeoutError` and
+`MiddlewareNextCalledMultipleTimesError` are the `@zudojs/errors` classes
+too, so an `instanceof` check against either import path matches, and a
+single `instanceof MiddlewareError` catches everything from this package:
 
 `MiddlewareTimeoutError` · `MiddlewareNextCalledMultipleTimesError` ·
 `MiddlewareLimitExceededError` · `MiddlewareDepthExceededError` ·

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

@@ -50,7 +50,7 @@ export declare function resolveMiddleware<TContext, TResult>(middlewareList: rea
 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`. */
+    /** Where to report slow middleware. Default: nothing is reported. */
     readonly logger?: (message: string) => void;
 }
 /**

package/dist/middlewareCore/middlewareCore.compose.js

@@ -84,10 +84,7 @@ export function resolveMiddleware(middlewareList) {
  */
 export function withTiming(name, middleware, options) {
     const thresholdMs = options?.thresholdMs ?? 100;
-    const log = options?.logger ??
-        ((message) => {
-            console.warn(message);
-        });
+    const log = options?.logger ?? (() => undefined);
     return {
         name,
         handler: async (ctx, next) => {

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

@@ -1,58 +1,11 @@
 /**
  * Middleware-specific error classes.
  *
- * @module middlewareErrors
- */
-import { BaseError } from "@zudojs/errors";
-/**
- * Error thrown when a middleware pipeline fails.
- */
-export declare class MiddlewareError extends BaseError {
-    constructor(message: string, options?: {
-        readonly middlewareName?: string;
-        readonly cause?: unknown;
-    });
-}
-/**
- * Error thrown when a middleware exceeds its timeout.
- */
-export declare class MiddlewareTimeoutError extends MiddlewareError {
-    constructor(middlewareName: string, timeoutMs: number);
-}
-/**
- * Error thrown when a middleware calls next() multiple times.
- */
-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.
+ * Every class is owned by `@zudojs/errors` and re-exported here, so
+ * `instanceof` checks against either import path match the same errors.
+ * Codes, messages and fields are unchanged.
  *
- * `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`.
+ * @module middlewareErrors
  */
-export declare class MiddlewareAbortedError extends MiddlewareError {
-    constructor(reason?: unknown);
-}
+export { MiddlewareError, MiddlewareTimeoutError, MiddlewareNextCalledMultipleTimesError, MiddlewareLimitExceededError, MiddlewareDepthExceededError, MiddlewareRateLimitError, MiddlewareAbortedError, } from "@zudojs/errors";
 //# sourceMappingURL=middlewareError.base.d.ts.map

package/dist/middlewareErrors/middlewareError.base.js

@@ -1,86 +1,11 @@
 /**
  * Middleware-specific error classes.
  *
- * @module middlewareErrors
- */
-import { BaseError, ErrorCode, ErrorCategory, ErrorSeverity, } from "@zudojs/errors";
-/**
- * Error thrown when a middleware pipeline fails.
- */
-export class MiddlewareError extends BaseError {
-    constructor(message, options) {
-        super(message, {
-            code: ErrorCode.OPERATION_FAILED,
-            category: ErrorCategory.INTERNAL,
-            severity: ErrorSeverity.ERROR,
-            metadata: {
-                middlewareName: options?.middlewareName,
-            },
-            cause: options?.cause,
-        });
-    }
-}
-/**
- * Error thrown when a middleware exceeds its timeout.
- */
-export class MiddlewareTimeoutError extends MiddlewareError {
-    constructor(middlewareName, timeoutMs) {
-        super(`Middleware "${middlewareName}" timed out after ${timeoutMs}ms`, {
-            middlewareName,
-        });
-    }
-}
-/**
- * Error thrown when a middleware calls next() multiple times.
- */
-export class MiddlewareNextCalledMultipleTimesError extends MiddlewareError {
-    constructor(middlewareName) {
-        super(`Middleware "${middlewareName}" called next() multiple times`, {
-            middlewareName,
-        });
-    }
-}
-/**
- * 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.
+ * Every class is owned by `@zudojs/errors` and re-exported here, so
+ * `instanceof` checks against either import path match the same errors.
+ * Codes, messages and fields are unchanged.
  *
- * `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`.
+ * @module middlewareErrors
  */
-export class MiddlewareAbortedError extends MiddlewareError {
-    constructor(reason) {
-        super("Middleware pipeline aborted", { cause: reason });
-    }
-}
+export { MiddlewareError, MiddlewareTimeoutError, MiddlewareNextCalledMultipleTimesError, MiddlewareLimitExceededError, MiddlewareDepthExceededError, MiddlewareRateLimitError, MiddlewareAbortedError, } from "@zudojs/errors";
 //# sourceMappingURL=middlewareError.base.js.map

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

@@ -34,6 +34,10 @@ export interface LoggingOptions {
  *
  * Logs request start, completion, and errors. Every interpolated field is
  * escaped, so a path containing newlines cannot forge log lines.
+ *
+ * Lines go to `logger`, typically a `@zudojs/logger` method such as
+ * `(line) => log.info(line)`. Without one the middleware writes nothing;
+ * it never falls back to the console.
  */
 export declare function loggingMiddleware<TResult = void>(logger?: (msg: string) => void, options?: LoggingOptions): NamedMiddleware<LoggingContext, TResult>;
 /**

package/dist/middlewareUtils/middlewareUtils.builtins.js

@@ -38,14 +38,21 @@ export function sanitizeLogValue(value, maxLength = MAX_LOG_FIELD_LENGTH) {
         ? `${escaped.slice(0, maxLength)}…`
         : escaped;
 }
+function noopLog() {
+    return;
+}
 /**
  * Create a logging middleware.
  *
  * Logs request start, completion, and errors. Every interpolated field is
  * escaped, so a path containing newlines cannot forge log lines.
+ *
+ * Lines go to `logger`, typically a `@zudojs/logger` method such as
+ * `(line) => log.info(line)`. Without one the middleware writes nothing;
+ * it never falls back to the console.
  */
 export function loggingMiddleware(logger, options) {
-    const log = logger ?? ((msg) => console.log(msg));
+    const log = logger ?? noopLog;
     const maxFieldLength = options?.maxFieldLength ?? MAX_LOG_FIELD_LENGTH;
     const includeErrorMessage = options?.includeErrorMessage ?? false;
     return {
@@ -234,6 +241,7 @@ export function rateLimitMiddleware(maxRequests, windowMs, options) {
                 sweep(now);
             const live = prune(hits.get(key) ?? [], now);
             if (live.length >= maxRequests) {
+                hits.delete(key);
                 hits.set(key, live);
                 const retryAfterMs = Math.max(1, live[0] + windowMs - now);
                 throw new MiddlewareRateLimitError(maxRequests, windowMs, retryAfterMs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/middleware",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Composable middleware pipeline with composition, timing, error handling, and context propagation.",
   "license": "MIT",
   "author": {
@@ -25,7 +25,7 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.1"
+    "@zudojs/errors": "1.2.0"
   },
   "engines": {
     "node": ">=24.0.0"