APIMiddlewares

Middleware Merging

This outlines how two router trees with nested middlewares are intelligently merged to preserve execution order and structure.

Before Merging

Root Router Tree (`RootMiddlewares`)

RootMiddlewares
└── "/test"                             # path
    ├── middlewares: [m1]              # existing middleware
    └── children:
        └── "/test/1"
            ├── middlewares: [m2]

/test: Contains middleware [m1].
/test/1: A subroute with its own middleware [m2].

New Router Tree to Merge (`RouterMiddlewares`)

Incoming Subrouter

RouterMiddlewares
└── "/test"
    ├── middlewares: [m3]              # additional middleware to merge
    └── children:
        └── "/test/2"
            ├── middlewares: [m4]

/test: New middleware [m3] for same path.
/test/2: New child route under /test.

After Merging (`RootMiddlewares`)

RootMiddlewares
└── "/test"
    ├── middlewares: [m1, m3]          # merged middlewares
    └── children:
        ├── "/test/1"
        │   ├── middlewares: [m2]
        └── "/test/2"
            ├── middlewares: [m4]      # newly added

Middleware arrays are merged: [m1] + [m3] → [m1, m3].
All existing children remain untouched (/test/1).
New children are appended (/test/2).

Mermaid Diagram: Middleware Merge Flow

Shows how /test merges middlewares (m1 + m3) and retains all children.

`when` API

/**
 * Registers a route or middleware stack for a specific HTTP method.
 *
 * @param method - HTTP method (e.g., "GET", "POST", "ALL" for middleware).
 * @param path - Path to match (e.g., "/api", "/test").
 * @param handlers - Array of middleware or route handler functions.
 */
when(method: HttpMethod | HttpMethod[], path: string, handlers: Handler[]): void;

method = "ALL" → middleware applied to all HTTP methods.
Used internally when adding reusable or nested routers.

Automatic Middleware Registration Logic

When merging routes via a registry:

if (middlewares?.length) {
  this.#addRoute("ALL", path, middlewares);
}

Ensures all middleware layers from incoming routers are preserved.
Middleware at the same path is concatenated, not replaced.

Context Propagation

Context propagation allows type-safe, request-scoped state sharing across middleware and route handlers. Built on TypeScript, it enables -

use()

The use() method in TezX.Router is a powerful, flexible API for registering middlewares and sub-routers — either globally or scoped to a specific path.

On this page

Before MergingRoot Router Tree (RootMiddlewares)New Router Tree to Merge (RouterMiddlewares)Incoming SubrouterAfter Merging (RootMiddlewares)Mermaid Diagram: Middleware Merge Flowwhen APIAutomatic Middleware Registration Logic