@minisylar/express-typed-router 1.1.0 → 1.3.0

package/README.md

@@ -118,16 +118,28 @@ app.listen(3000);
 
 ### Global Middleware
 
+**Important**: Unlike Express, middleware must be applied using method chaining or capturing returned routers. See the [FAQ section](#faq-and-common-patterns) for details.
+
 ```typescript
+// Method chaining pattern (recommended)
 const router = createTypedRouter()
-  .useTypedMiddleware(authMiddleware)
-  .useTypedMiddleware(loggingMiddleware)
-  .useTypedMiddleware(timestampMiddleware);
+  .useMiddleware(authMiddleware)
+  .useMiddleware(loggingMiddleware)
+  .useMiddleware(timestampMiddleware);
 
 // All routes automatically get types from all middleware
 router.get("/protected", (req, res) => {
   // req.userId, req.requestId, req.timestamp all available and typed
 });
+
+// Alternative: capturing returned router
+const baseRouter = createTypedRouter();
+const routerWithMiddleware = baseRouter
+  .useMiddleware(authMiddleware)
+  .useMiddleware(loggingMiddleware);
+
+// Use the router with middleware applied
+routerWithMiddleware.get("/users", handler);
 ```
 
 ### Per-Route Middleware
@@ -136,7 +148,7 @@ router.get("/protected", (req, res) => {
 router.get(
   "/admin/:userId",
   {
-    middleware: [adminMiddleware, auditMiddleware] as const,
+    middleware: [adminMiddleware, auditMiddleware],
   },
   (req, res) => {
     // Types from both global AND per-route middleware are merged
@@ -191,13 +203,13 @@ app.use(express.json());
 
 // Create router and define middleware inline (automatically typed!)
 const router = createTypedRouter()
-  .useTypedMiddleware((req, res, next) => {
+  .useMiddleware((req, res, next) => {
     const token = req.headers.authorization;
     req.userId = "user123";
     req.isAdmin = token?.includes("admin") || false;
     next();
   })
-  .useTypedMiddleware((req, res, next) => {
+  .useMiddleware((req, res, next) => {
     req.requestId = Math.random().toString(36);
     console.log(`[${req.requestId}] ${req.method} ${req.path}`);
     next();
@@ -223,7 +235,7 @@ router.get(
   },
   (req, res) => {
     // All properties are automatically typed:
-    const { userId } = req.params;        // string (auto-inferred from route)
+    const { userId } = req.params; // string (auto-inferred from route)
     const { include, limit } = req.query; // from schema validation
     const { userId: authUserId, isAdmin, requestId } = req; // from middleware
 
@@ -266,19 +278,21 @@ router.post(
 router.delete(
   "/users/:userId",
   {
-    middleware: [(req, res, next) => {
-      if (!req.isAdmin) {
-        return res.status(403).json({ error: "Admin required" });
-      }
-      req.hasAdminAccess = true;
-      next();
-    }] as const,
+    middleware: [
+      (req, res, next) => {
+        if (!req.isAdmin) {
+          return res.status(403).json({ error: "Admin required" });
+        }
+        req.hasAdminAccess = true;
+        next();
+      },
+    ], // No need for 'as const' - middleware arrays are automatically typed
   },
   (req, res) => {
     // Types from BOTH global middleware AND per-route middleware
-    const { userId } = req.params;               // From route
+    const { userId } = req.params; // From route
     const { userId: authUserId, requestId } = req; // From global middleware
-    const { hasAdminAccess } = req;              // From per-route middleware
+    const { hasAdminAccess } = req; // From per-route middleware
 
     res.json({
       deleted: userId,
@@ -326,8 +340,8 @@ const loggingMiddleware: TypedMiddleware<{ requestId: string }> = (
 
 // Use the explicitly typed middleware
 const router = createTypedRouter()
-  .useTypedMiddleware(authMiddleware)
-  .useTypedMiddleware(loggingMiddleware);
+  .useMiddleware(authMiddleware)
+  .useMiddleware(loggingMiddleware);
 
 // Rest of the routes work the same way...
 ```
@@ -354,7 +368,7 @@ const authMiddleware: TypedMiddleware<{ userId: string; isAdmin: boolean }> = (
 };
 
 // Add to router - types are automatically merged
-router.useTypedMiddleware(authMiddleware);
+router.useMiddleware(authMiddleware);
 
 router.get("/protected", (req, res) => {
   // TypeScript knows about req.userId and req.isAdmin
@@ -381,7 +395,7 @@ const adminMiddleware: TypedMiddleware<{ hasAdminAccess: true }> = (
 router.get(
   "/admin/:userId",
   {
-    middleware: [adminMiddleware] as const,
+    middleware: [adminMiddleware], // No need for 'as const' - arrays are automatically typed
   },
   (req, res) => {
     // Types from BOTH global and per-route middleware are available
@@ -589,8 +603,8 @@ Creates a typed router instance with full flexibility for middleware and validat
 const router = createTypedRouter();
 
 // Add global middleware (chainable)
-router.useTypedMiddleware(middleware1)
-      .useTypedMiddleware(middleware2);
+router.useMiddleware(middleware1)
+      .useMiddleware(middleware2);
 
 // All HTTP methods supported
 router.get(path, options?, handler)
@@ -697,6 +711,177 @@ pnpm build:watch
 
 ISC
 
+## FAQ and Common Patterns
+
+### Middleware Behavior Differences from Express
+
+#### IMPORTANT: Router Middleware and Route Registration
+
+When using middleware with `express-typed-router`, there's an important difference from standard Express behavior:
+
+**In Express**, middleware added with `router.use()` applies to all routes registered _after_ it:
+
+```javascript
+// Express middleware behavior
+const router = express.Router();
+router.use(authMiddleware); // Apply middleware
+router.get("/route1", handler1); // Has authMiddleware
+router.use(logMiddleware); // Apply another middleware
+router.get("/route2", handler2); // Has BOTH auth and log middleware
+```
+
+**In express-typed-router**, `useMiddleware()` returns a _new router instance_ for type safety:
+
+```typescript
+// ❌ WON'T WORK - middleware not applied to route
+const router = createTypedRouter();
+router.useMiddleware(authMiddleware); // Returns new router that isn't captured
+router.get("/route", handler); // Original router without middleware!
+
+// ✅ CORRECT - chain methods (recommended)
+const router = createTypedRouter()
+  .useMiddleware(authMiddleware)
+  .get("/route", handler);
+
+// ✅ CORRECT - chain directly from middleware call
+const router = createTypedRouter();
+router.useMiddleware(authMiddleware).get("/route", handler);
+
+// ✅ ALSO CORRECT - use per-route middleware
+const router = createTypedRouter();
+router.get("/route", { middleware: [authMiddleware] }, handler);
+```
+
+This design is necessary for full type safety but requires a different pattern than standard Express.
+
+### Common Express Patterns vs express-typed-router
+
+Here are common Express patterns and how to achieve them with express-typed-router:
+
+#### Pattern 1: Adding middleware to specific routes
+
+**Express:**
+
+```javascript
+const router = express.Router();
+router.get("/public", publicHandler);
+router.use(authMiddleware); // Only affects routes below
+router.get("/private", privateHandler); // Has authMiddleware
+```
+
+**express-typed-router:**
+
+```typescript
+// Option 1: Separate routers
+const publicRouter = createTypedRouter();
+publicRouter.get("/public", publicHandler);
+
+const privateRouter = createTypedRouter().useMiddleware(authMiddleware);
+privateRouter.get("/private", privateHandler);
+
+// Combine in Express
+app.use(publicRouter.getRouter());
+app.use(privateRouter.getRouter());
+
+// Option 2: Per-route middleware
+const router = createTypedRouter();
+router.get("/public", publicHandler);
+router.get("/private", { middleware: [authMiddleware] }, privateHandler);
+```
+
+#### Pattern 2: Adding middleware for a group of routes
+
+**Express:**
+
+```javascript
+const router = express.Router();
+router.get("/public", handler);
+
+// Only admin routes have auth middleware
+const adminRouter = express.Router();
+adminRouter.use(authMiddleware);
+adminRouter.get("/users", adminHandler1);
+adminRouter.get("/settings", adminHandler2);
+
+router.use("/admin", adminRouter);
+```
+
+**express-typed-router:**
+
+```typescript
+const publicRouter = createTypedRouter();
+publicRouter.get("/public", handler);
+
+// Admin router with middleware
+const adminRouter = createTypedRouter().useMiddleware(authMiddleware);
+adminRouter.get("/users", adminHandler1);
+adminRouter.get("/settings", adminHandler2);
+
+// Combine with Express
+app.use(publicRouter.getRouter());
+app.use("/admin", adminRouter.getRouter());
+```
+
+#### Pattern 3: Middleware with dynamically added routes
+
+**Express:**
+
+```javascript
+const router = express.Router();
+router.use(middleware);
+
+// Later, routes are added dynamically
+function addRoute(path, handler) {
+  router.get(path, handler); // Has middleware
+}
+```
+
+**express-typed-router:**
+
+```typescript
+// Option 1: Pass the router to the function
+const router = createTypedRouter().useMiddleware(middleware);
+
+function addRoute(router, path, handler) {
+  router.get(path, handler);
+}
+
+// Option 2: Factory function
+function createRouteAdder(middleware) {
+  const router = createTypedRouter().useMiddleware(middleware);
+
+  return {
+    addRoute: (path, handler) => router.get(path, handler),
+    getRouter: () => router.getRouter(),
+  };
+}
+
+const routeAdder = createRouteAdder(middleware);
+routeAdder.addRoute("/path", handler);
+app.use(routeAdder.getRouter());
+```
+
+### Using express-typed-router in JavaScript
+
+JavaScript users don't need to worry about TypeScript types but should still follow the middleware chaining pattern:
+
+```javascript
+// JavaScript usage
+const { createTypedRouter } = require("@minisylar/express-typed-router");
+
+const router = createTypedRouter().useMiddleware((req, res, next) => {
+  req.user = { id: "user123" };
+  next();
+});
+
+router.get("/users", (req, res) => {
+  // req.user is available but not typed (JavaScript doesn't have types)
+  res.json({ userId: req.user.id });
+});
+
+module.exports = router.getRouter();
+```
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/zod-router.cjs

@@ -1,180 +1,2 @@
-//#region rolldown:runtime
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-		});
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-
-//#endregion
-const express = __toESM(require("express"));
-const zod = __toESM(require("zod"));
-
-//#region src/zod-router.ts
-var TypedRouter = class {
-	router;
-	constructor() {
-		this.router = express.default.Router();
-	}
-	/**
-	* Add typed middleware that extends the request with additional properties
-	* and/or adds properties to response.locals
-	*/
-	useTypedMiddleware(middleware) {
-		this.router.use(middleware);
-		return this;
-	}
-	/**
-	* Get the underlying Express router
-	*/
-	getRouter() {
-		return this.router;
-	}
-	get(path, optionsOrHandler, handler) {
-		return this.registerRoute("get", path, optionsOrHandler, handler);
-	}
-	post(path, optionsOrHandler, handler) {
-		return this.registerRoute("post", path, optionsOrHandler, handler);
-	}
-	put(path, optionsOrHandler, handler) {
-		return this.registerRoute("put", path, optionsOrHandler, handler);
-	}
-	patch(path, optionsOrHandler, handler) {
-		return this.registerRoute("patch", path, optionsOrHandler, handler);
-	}
-	delete(path, optionsOrHandler, handler) {
-		return this.registerRoute("delete", path, optionsOrHandler, handler);
-	}
-	options(path, optionsOrHandler, handler) {
-		return this.registerRoute("options", path, optionsOrHandler, handler);
-	}
-	head(path, optionsOrHandler, handler) {
-		return this.registerRoute("head", path, optionsOrHandler, handler);
-	}
-	all(path, optionsOrHandler, handler) {
-		return this.registerRoute("all", path, optionsOrHandler, handler);
-	}
-	registerRoute(method, path, optionsOrHandler, handler) {
-		const middlewares = [];
-		if (typeof optionsOrHandler === "object") {
-			const options = optionsOrHandler;
-			if (options.middleware) middlewares.push(...options.middleware);
-			if (options.bodySchema) middlewares.push(this.createBodyValidationMiddleware(options.bodySchema));
-			if (options.querySchema) middlewares.push(this.createQueryValidationMiddleware(options.querySchema));
-			middlewares.push(handler);
-		} else middlewares.push(optionsOrHandler);
-		this.router[method](path, ...middlewares);
-		return this;
-	}
-	createBodyValidationMiddleware(schema) {
-		return (req, res, next) => {
-			try {
-				req.body = schema.parse(req.body);
-				next();
-			} catch (error) {
-				if (error instanceof zod.z.ZodError) res.status(400).json({
-					error: "Validation failed",
-					details: error.errors
-				});
-				else next(error);
-			}
-		};
-	}
-	createQueryValidationMiddleware(schema) {
-		return (req, res, next) => {
-			try {
-				req.query = schema.parse(req.query);
-				next();
-			} catch (error) {
-				if (error instanceof zod.z.ZodError) res.status(400).json({
-					error: "Validation failed",
-					details: error.errors
-				});
-				else next(error);
-			}
-		};
-	}
-};
-/**
-* Create a new strongly-typed Express router instance.
-*
-* This is the simplest way to get started with @minisylar/express-typed-router.
-*
-* @example
-* import { createTypedRouter } from '@minisylar/express-typed-router';
-*
-* // Create a router and add a typed GET route
-* const router = createTypedRouter();
-* router.get('/hello/:name', (req, res) => {
-*   // req.params.name is typed as string
-*   res.json({ message: `Hello, ${req.params.name}!` });
-* });
-*
-* // Use with Express
-* import express from 'express';
-* const app = express();
-* app.use('/api', router.getRouter());
-*/
-function createTypedRouter() {
-	return new TypedRouter();
-}
-/**
-* Create a new typed router with optional configuration.
-*
-* Use this if you want to add a global error handler or future global options.
-*
-* @param config - Optional configuration for the router (e.g. error handler).
-* @returns A new TypedRouter instance.
-*
-* @example
-* import { createTypedRouterWithConfig } from '@minisylar/express-typed-router';
-*
-* const router = createTypedRouterWithConfig({
-*   errorHandler: (err, req, res, next) => {
-*     res.status(500).json({ error: 'Something went wrong', details: err });
-*   }
-* });
-*/
-function createTypedRouterWithConfig(config) {
-	const router = new TypedRouter();
-	if (config?.errorHandler) router.getRouter().use(config.errorHandler);
-	return router;
-}
-/**
-* Create a new typed router with pre-configured middleware.
-*
-* This is useful for setting up router-level middleware in a single call.
-*
-* @param middleware - One or more TypedMiddleware functions to apply to all routes.
-* @returns A new TypedRouter instance with the middleware applied.
-*
-* @example
-* import { createTypedRouterWithMiddleware } from '@minisylar/express-typed-router';
-*
-* const router = createTypedRouterWithMiddleware(authMiddleware, loggingMiddleware);
-*/
-function createTypedRouterWithMiddleware(...middleware) {
-	let router = new TypedRouter();
-	for (const mw of middleware) router = router.useTypedMiddleware(mw);
-	return router;
-}
-
-//#endregion
-exports.createTypedRouter = createTypedRouter;
-exports.createTypedRouterWithConfig = createTypedRouterWithConfig;
-exports.createTypedRouterWithMiddleware = createTypedRouterWithMiddleware;
+var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));const c=s(require(`express`)),l=s(require(`zod`));var u=class{router;constructor(){this.router=c.default.Router()}useMiddleware(e){return this.router.use(e),this}getRouter(){return this.router}get(e,t,n){return this.registerRoute(`get`,e,t,n)}post(e,t,n){return this.registerRoute(`post`,e,t,n)}put(e,t,n){return this.registerRoute(`put`,e,t,n)}patch(e,t,n){return this.registerRoute(`patch`,e,t,n)}delete(e,t,n){return this.registerRoute(`delete`,e,t,n)}options(e,t,n){return this.registerRoute(`options`,e,t,n)}head(e,t,n){return this.registerRoute(`head`,e,t,n)}all(e,t,n){return this.registerRoute(`all`,e,t,n)}registerRoute(e,t,n,r){let i=[];if(typeof n==`object`){let e=n;e.middleware&&i.push(...e.middleware),e.bodySchema&&i.push(this.createBodyValidationMiddleware(e.bodySchema)),e.querySchema&&i.push(this.createQueryValidationMiddleware(e.querySchema)),i.push(r)}else i.push(n);return this.router[e](t,...i),this}createBodyValidationMiddleware(e){return(t,n,r)=>{try{t.body=e.parse(t.body),r()}catch(e){e instanceof l.z.ZodError||e&&typeof e==`object`&&`issues`in e?n.status(400).json({error:`Validation failed`,details:e.errors||e.issues}):r(e)}}}createQueryValidationMiddleware(e){return(t,n,r)=>{try{t.query=e.parse(t.query),r()}catch(e){e instanceof l.z.ZodError||e&&typeof e==`object`&&`issues`in e?n.status(400).json({error:`Validation failed`,details:e.errors||e.issues}):r(e)}}}};function d(){return new u}function f(e){let t=new u;return e?.errorHandler&&t.getRouter().use(e.errorHandler),t}function p(...e){let t=new u;for(let n of e)t=t.useMiddleware(n);return t}exports.createTypedRouter=d,exports.createTypedRouterWithConfig=f,exports.createTypedRouterWithMiddleware=p;
 //# sourceMappingURL=zod-router.cjs.map