nextjs-middleware-stack 1.1.1 → 2.0.0

package/README.md

@@ -1,155 +1,186 @@
-# 🚣️ `middlewareStack` – A Lightweight Middleware Router for Next.js
+# 🚣 `middlewareStack` – A Composable Middleware Router for Next.js
 
-A composable middleware stack for Next.js, supporting `string`-based route patterns (with dynamic parameters and wildcards), raw `RegExp` objects, and custom sync/async predicate functions.
+A lightweight, composable middleware stack for Next.js that supports:
 
-Perfect for building layered request logic like authentication, logging, redirects, or feature flags in Next.js Edge or Node middlewares.
+- `string` route patterns (with dynamic parameters & wildcards)
+- Raw `RegExp`
+- Sync/async predicate functions
+- Strict `pipe()` composition API
+
+Perfect for authentication gates, logging, redirects, feature flags, i18n integration, and layered request logic in Next.js Edge or Node runtimes.
 
 ---
 
 ## ✨ Features
 
-- ✅ Simple pattern matching with support for:
+- ✅ Clean `pipe()` API (no tuple arrays)
+- ✅ String pattern matching via `compare-path`
+
   - `:param` dynamic segments
-  - `**` wildcards (greedy)
-- ✅ `RegExp` support
-- ✅ Custom `PatternFn` support: `(req) => boolean | Promise<boolean>`
-- ✅ Middleware short-circuiting (first matching response stops the stack)
-- ✅ Fully compatible with `next/server` and middleware in `apps/<name>/src/middleware.ts`
+  - `**` greedy wildcards
+
+- ✅ Native `RegExp` support
+- ✅ Sync or async predicate matching
+- ✅ Middleware short-circuiting
+- ✅ Edge & Node compatible
+- ✅ Type-safe enforcement of `pipe()` usage
 
 ---
 
 ## 📦 Installation
 
 ```bash
-npm install compare-path
+npm install nextjs-middleware-stack
 ```
 
 ---
 
 ## 🧠 API
 
-### `middlewareStack(routes: [Pattern, MiddlewareHandler][])`
+### `pipe(pattern, handler)`
 
-Creates a Next.js-compatible middleware handler from an ordered list of route matchers and handler functions.
+Creates a middleware pipe.
 
 ```ts
 export type PatternFn = (req: Request) => boolean | Promise<boolean>
 export type Pattern = PatternFn | string | RegExp
 ```
 
-#### Parameters:
+#### Parameters
+
+- `pattern`
 
-- `routes`: An array of tuples where:
-  - The first item is a `Pattern`:
-    - a string pattern (e.g., `/users/:id`)
-    - a `RegExp`
-    - a function/async function `(req) => boolean | Promise<boolean>`
-  - The second item is a handler function `(req: NextRequest) => Response | void | Promise<Response | void>`.
+  - string route shape (`/users/:id`)
+  - `RegExp`
+  - predicate function `(req) => boolean | Promise<boolean>`
 
-#### Returns:
+- `handler`
 
-- A function `(req: NextRequest) => Promise<Response | void>` – ready to be exported as default from `middleware.ts`.
+  - `(req: Request) => Response | void | Promise<Response | void>`
+
+> `pipe()` must be used. Raw `[pattern, handler]` tuples are not supported.
 
 ---
 
-## 📊 Supported Path Shapes
+### `middlewareStack(pipes)`
 
-You can use `string`-based shape patterns (powered by `compare-path`), `RegExp`, or predicate functions.
+```ts
+middlewareStack(pipes: Pipe[])
+```
 
-| Shape           | Matches Path Example        |
-| --------------- | --------------------------- |
-| `/user/:id`     | `/user/42`                  |
-| `/users/[id]`   | `/users/42` (same as above) |
-| `/docs/**/edit` | `/docs/api/v1/intro/edit`   |
-| `/a/:x/**/b/:y` | `/a/1/foo/bar/b/2`          |
+Creates a Next.js-compatible middleware handler from an ordered list of `pipe()` calls.
 
-> Use RegExp when you need full regex control.
+Returns:
 
-Use a predicate function when matching depends on request headers, cookies, or any custom runtime logic.
+```ts
+;(req: Request) => Promise<Response | void>
+```
+
+Ready to export as default from `middleware.ts`.
 
 ---
 
-## 🧪 Example Usage (Auth Middleware)
+## 🚀 Example (Authentication Middleware)
 
 ```ts
-// File: apps/example-app/src/middleware.ts
+// apps/example-app/src/middleware.ts
 import { NextResponse } from 'next/server'
-import { middlewareStack } from './utils/middleware-stack'
+import { middlewareStack, pipe } from 'nextjs-middleware-stack'
 import { validateAuthToken } from './utils/validate-jwt'
 
 export default middlewareStack([
-  [
-    /^\/dashboard\/.*/,
-    async (req) => {
-      const token = req.cookies.get('AUTH_TOKEN')?.value
-      const isValid = token && (await validateAuthToken(token))
-      if (!isValid) return NextResponse.redirect(new URL('/login', req.url))
-    },
-  ],
-  [
-    '/public/:page',
-    async (req) => {
-      console.log('Logging public page hit')
-    },
-  ],
+  pipe(/^\/dashboard\/.*/, async (req) => {
+    const token = req.cookies.get('AUTH_TOKEN')?.value
+    const isValid = token && (await validateAuthToken(token))
+
+    if (!isValid) {
+      return NextResponse.redirect(new URL('/login', req.url))
+    }
+  }),
+
+  pipe('/public/:page', async () => {
+    console.log('Public page hit')
+  }),
+
+  // Always run last
+  pipe(
+    () => true,
+    async () => {
+      console.log('Final middleware')
+    }
+  ),
 ])
 ```
 
 ---
 
-## 🧪 Example with String Matching
+## 📊 Supported Path Shapes
+
+String patterns are powered by `compare-path`.
+
+| Pattern         | Matches                   |
+| --------------- | ------------------------- |
+| `/user/:id`     | `/user/42`                |
+| `/users/[id]`   | `/users/42`               |
+| `/docs/**/edit` | `/docs/api/v1/intro/edit` |
+| `/a/:x/**/b/:y` | `/a/1/foo/bar/b/2`        |
+
+Use `RegExp` for advanced matching.
+
+Use a predicate function when matching depends on:
+
+- Cookies
+- Headers
+- Geo
+- Runtime conditions
+- Feature flags
+
+---
+
+## 🧪 Example: String Matching
 
 ```ts
-// File: apps/example-app/src/middleware.ts
-import { middlewareStack } from './utils/middleware-stack'
+import { middlewareStack, pipe } from 'nextjs-middleware-stack'
 
 export default middlewareStack([
-  [
-    '/users/:id',
-    async (req) => {
-      // Handle specific user route
-    },
-  ],
-  [
-    'cars/:id',
-    async (req) => {
-      // Same as above with different route
-    },
-  ],
-  [
-    'hello/**',
-    async (req) => {
-      // Match anything starting with /hello/
-    },
-  ],
+  pipe('/users/:id', async (req) => {
+    // Handle specific user route
+  }),
+
+  pipe('cars/:id', async () => {
+    // Match /cars/123
+  }),
+
+  pipe('hello/**', async () => {
+    // Match anything under /hello/
+  }),
 ])
 ```
 
 ---
 
-## 🧪 Example with `PatternFn`
+## 🧪 Example: Predicate Function
 
 ```ts
-import { middlewareStack } from './utils/middleware-stack'
+import { middlewareStack, pipe } from 'nextjs-middleware-stack'
 
 export default middlewareStack([
-  [
+  pipe(
     async (req) => {
-      // Match only API requests that include an auth header
       return req.url.includes('/api/') && !!req.headers.get('authorization')
     },
-    async (req) => {
-      // Custom logic for authenticated API requests
-    },
-  ],
+    async () => {
+      console.log('Authenticated API request')
+    }
+  ),
 ])
 ```
 
 ---
 
-## 🧹 Integration in Next.js
+## 🧹 Next.js Integration
 
-You must also export the `config` to ensure the middleware applies to your desired routes:
+You must also export `config` to control where middleware runs:
 
 ```ts
 export const config = {
@@ -157,7 +188,6 @@ export const config = {
     '/((?!_next|.*\\..*).*)', // Skip static assets
     '/(api|trpc)(.*)', // Always include API routes
   ],
-  runtime: 'nodejs',
 }
 ```
 
@@ -165,20 +195,50 @@ export const config = {
 
 ## 🧠 How It Works
 
-Internally, `middlewareStack` will iterate through your routes and:
+For each request:
+
+1. Iterate through pipes in order.
+2. Evaluate the `pattern`.
+3. If matched → execute the `handler`.
+4. If the handler returns a `Response`, execution stops.
+5. Otherwise → continue to the next pipe.
 
-1. Compare the current request to each route pattern (`compare-path`, `RegExp`, or `PatternFn`).
-2. If matched, execute the handler.
-3. If a `Response` is returned from the handler, it stops further execution and returns immediately.
+Middleware order matters.
 
 ---
 
 ## 💡 Tips
 
-- Middleware order matters! First match wins.
-- Use RegExp for more complex or legacy patterns.
-- Use string shapes for clean, readable routes with parameters.
-- Use `PatternFn` for request-aware matching (cookies, headers, auth, geo, etc).
+- Place authentication gates before public routes.
+- Put always-run middleware last:
+
+```ts
+pipe(() => true, someMiddleware)
+```
+
+- Prefer string shapes for readability.
+- Use predicate functions for request-aware logic.
+- Use `RegExp` only when necessary.
+
+---
+
+## ⚠️ Breaking Change (v2+)
+
+`middlewareStack` now accepts **only `pipe()` entries**.
+
+Old style:
+
+```ts
+middlewareStack([[/regex/, handler]])
+```
+
+is no longer supported.
+
+Migration:
+
+```ts
+middlewareStack([pipe(/regex/, handler)])
+```
 
 ---
 

package/dist/main.d.ts

@@ -1,5 +1,30 @@
-export type MiddlewareHandler<T = Request, R = Response> = (req: T) => R | void | Promise<R | void>;
+/** A middleware handler that can short-circuit by returning a Response. */
+export type MiddlewareHandler<T = Request> = (req: T) => Response | void | Promise<Response | void>;
+/** A pattern function can be sync or async. */
 export type PatternFn = (req: Request) => boolean | Promise<boolean>;
 export type Pattern = PatternFn | string | RegExp;
-export declare function middlewareStack<T = Request, R = Response>(routes: [Pattern, MiddlewareHandler<T, R>][]): (req: T) => Promise<R | void>;
+/**
+ * Opaque/Branded "Pipe" type. Enforces that consumers MUST use pipe() (raw tuples won't
+ * type-check).
+ */
+declare const PIPE_BRAND: unique symbol;
+export type Pipe<T extends Request = Request> = Readonly<{
+    /** Brand */
+    [PIPE_BRAND]: true;
+    pattern: Pattern;
+    handler: MiddlewareHandler<T>;
+}>;
+/** Create a middleware pipe (pattern + handler). */
+export declare function pipe<T extends Request = Request>(pattern: Pattern, handler: MiddlewareHandler<T>): Pipe<T>;
+/**
+ * Create a middleware stack that executes pipes in order.
+ *
+ * - For each pipe: if pattern matches, run handler.
+ * - If handler returns a Response, short-circuit and return it.
+ * - Otherwise continue to the next pipe.
+ *
+ * NOTE: This version enforces "pipe() only" (no raw [pattern, handler] tuples).
+ */
+export declare function middlewareStack<T extends Request = Request>(pipes: ReadonlyArray<Pipe<T>>): (req: T) => Promise<Response | void>;
+export {};
 //# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,QAAQ,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;AACnG,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;AACpE,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAA;AAEjD,wBAAgB,eAAe,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,QAAQ,EACvD,MAAM,EAAE,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAE9B,KAAK,CAAC,KAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAsBzC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAEA,2EAA2E;AAC3E,MAAM,MAAM,iBAAiB,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAA;AAEnG,+CAA+C;AAC/C,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;AACpE,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAA;AAEjD;;;GAGG;AACH,QAAA,MAAM,UAAU,EAAE,OAAO,MAA6B,CAAA;AAEtD,MAAM,MAAM,IAAI,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,IAAI,QAAQ,CAAC;IACvD,YAAY;IACZ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAA;CAC9B,CAAC,CAAA;AAEF,oDAAoD;AACpD,wBAAgB,IAAI,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,EAC9C,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC5B,IAAI,CAAC,CAAC,CAAC,CAET;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,EAAE,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAC1E,KAAK,CAAC,KAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAuBhD"}

package/dist/main.js

@@ -9,25 +9,44 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.pipe = pipe;
 exports.middlewareStack = middlewareStack;
 const compare_path_1 = require("compare-path");
-function middlewareStack(routes) {
+/**
+ * Opaque/Branded "Pipe" type. Enforces that consumers MUST use pipe() (raw tuples won't
+ * type-check).
+ */
+const PIPE_BRAND = Symbol('PIPE_BRAND');
+/** Create a middleware pipe (pattern + handler). */
+function pipe(pattern, handler) {
+    return { pattern, handler, [PIPE_BRAND]: true };
+}
+/**
+ * Create a middleware stack that executes pipes in order.
+ *
+ * - For each pipe: if pattern matches, run handler.
+ * - If handler returns a Response, short-circuit and return it.
+ * - Otherwise continue to the next pipe.
+ *
+ * NOTE: This version enforces "pipe() only" (no raw [pattern, handler] tuples).
+ */
+function middlewareStack(pipes) {
     return (req) => __awaiter(this, void 0, void 0, function* () {
         var _a, _b;
-        // const url = (req as MaybeNextRequest).nextUrl?.pathname ?? (req as Request).url
-        const currentUrl = (_b = (_a = req.nextUrl) === null || _a === void 0 ? void 0 : _a.pathname) !== null && _b !== void 0 ? _b : new URL(req.url).pathname;
-        for (const [pattern, handler] of routes) {
+        for (const { pattern, handler } of pipes) {
+            // Recompute each iteration: a previous handler may mutate req.nextUrl.pathname
+            const pathname = (_b = (_a = req.nextUrl) === null || _a === void 0 ? void 0 : _a.pathname) !== null && _b !== void 0 ? _b : new URL(req.url).pathname;
             const isMatch = typeof pattern === 'string'
-                ? (0, compare_path_1.comparePath)(pattern, currentUrl)
+                ? (0, compare_path_1.comparePath)(pattern, pathname)[0]
                 : pattern instanceof RegExp
-                    ? pattern.test(currentUrl)
+                    ? pattern.test(pathname)
                     : typeof pattern === 'function'
                         ? yield pattern(req)
                         : false;
             if (isMatch) {
                 const result = yield handler(req);
-                if (result)
-                    return result; // short-circuit if a handler returns a response
+                if (result !== undefined)
+                    return result;
             }
         }
     });

package/dist/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";;;;;;;;;;;AAMA,0CAyBC;AA/BD,+CAA0C;AAM1C,SAAgB,eAAe,CAC7B,MAA4C;IAE5C,OAAO,CAAO,GAAM,EAAqB,EAAE;;QAEzC,kFAAkF;QAClF,MAAM,UAAU,GACd,MAAA,MAAC,GAAwB,CAAC,OAAO,0CAAE,QAAQ,mCAAI,IAAI,GAAG,CAAE,GAAe,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAA;QAEvF,KAAK,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,MAAM,EAAE,CAAC;YACxC,MAAM,OAAO,GACX,OAAO,OAAO,KAAK,QAAQ;gBACzB,CAAC,CAAC,IAAA,0BAAW,EAAC,OAAO,EAAE,UAAU,CAAC;gBAClC,CAAC,CAAC,OAAO,YAAY,MAAM;oBAC3B,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC;oBAC1B,CAAC,CAAC,OAAO,OAAO,KAAK,UAAU;wBAC/B,CAAC,CAAC,MAAM,OAAO,CAAC,GAAc,CAAC;wBAC/B,CAAC,CAAC,KAAK,CAAA;YAEX,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAA;gBACjC,IAAI,MAAM;oBAAE,OAAO,MAAM,CAAA,CAAC,gDAAgD;YAC5E,CAAC;QACH,CAAC;IACH,CAAC,CAAA,CAAA;AACH,CAAC"}
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";;;;;;;;;;;AAuBA,oBAKC;AAWD,0CAwBC;AA/DD,+CAA0C;AAS1C;;;GAGG;AACH,MAAM,UAAU,GAAkB,MAAM,CAAC,YAAY,CAAC,CAAA;AAStD,oDAAoD;AACpD,SAAgB,IAAI,CAClB,OAAgB,EAChB,OAA6B;IAE7B,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,UAAU,CAAC,EAAE,IAAI,EAAa,CAAA;AAC5D,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,eAAe,CAA8B,KAA6B;IACxF,OAAO,CAAO,GAAM,EAA4B,EAAE;;QAGhD,KAAK,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,KAAK,EAAE,CAAC;YACzC,+EAA+E;YAC/E,MAAM,QAAQ,GACZ,MAAA,MAAC,GAAwB,CAAC,OAAO,0CAAE,QAAQ,mCAAI,IAAI,GAAG,CAAE,GAAe,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAA;YAEvF,MAAM,OAAO,GACX,OAAO,OAAO,KAAK,QAAQ;gBACzB,CAAC,CAAC,IAAA,0BAAW,EAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;gBACnC,CAAC,CAAC,OAAO,YAAY,MAAM;oBAC3B,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;oBACxB,CAAC,CAAC,OAAO,OAAO,KAAK,UAAU;wBAC/B,CAAC,CAAC,MAAM,OAAO,CAAC,GAAyB,CAAC;wBAC1C,CAAC,CAAC,KAAK,CAAA;YAEX,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAA;gBACjC,IAAI,MAAM,KAAK,SAAS;oBAAE,OAAO,MAAM,CAAA;YACzC,CAAC;QACH,CAAC;IACH,CAAC,CAAA,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextjs-middleware-stack",
-  "version": "1.1.1",
+  "version": "2.0.0",
   "description": "Composable route-based middleware for Next.js Middleware.",
   "author": "Islam Yamor",
   "license": "Apache-2.0",