express-typed-routes 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Thomas Pregenzer
+
+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

@@ -0,0 +1,177 @@
+# express-typed-routes
+
+Type-safe middleware composition for Express with full TypeScript support.
+
+## Features
+
+- Type-safe middleware chaining with full TypeScript inference
+- Works with your existing Express apps and middleware
+- Errors automatically flow to Express error handlers
+- Zero dependencies
+
+## Installation
+
+```bash
+npm install express-typed-routes
+```
+
+## Quick Start
+
+```typescript
+import express from "express";
+import { route, middleware } from "express-typed-routes";
+
+const app = express();
+
+// Create typed middleware
+const requireAuth = middleware<{ userId: string }>((req) => {
+  const token = req.headers.authorization?.substring(7);
+  if (!token) throw new Error("Unauthorized");
+  return { userId: token };
+});
+
+// Use it in routes with full type safety
+app.get(
+  "/api/profile",
+  route()
+    .use(requireAuth)
+    .handler((req, res) => {
+      // TypeScript knows req.userId exists and is a string!
+      res.json({ userId: req.userId });
+    })
+);
+
+app.listen(3000);
+```
+
+## Why?
+
+Express middleware lose type information when applied to routes. `express-typed-routes` gives you full TypeScript inference for your request object.
+
+**No more custom type definitions like:**
+```typescript
+// types/express.d.ts
+declare global {
+  namespace Express {
+    interface Request {
+      userId?: string;
+    }
+  }
+}
+```
+
+**With this library:**
+```typescript
+app.get(
+  "/profile",
+  route()
+    .use(requireAuth)
+    .handler((req, res) => {
+      res.json({ userId: req.userId }); // ✅ TypeScript knows userId exists!
+    })
+);
+```
+
+## Why I built this
+
+I was building my first Express-based personal project and got frustrated having to override the Express Request type with optional fields for every middleware property. On top of that, I was using Zod and had to parse my schema manually in every single handler.
+
+I figured there had to be a better way - so I built this. Let me know what you think.
+
+## More Examples
+
+### Chaining Multiple Middleware
+
+```typescript
+app.post(
+  "/api/users",
+  route()
+    .use(requireAuth) // adds { userId: string }
+    .use(validateBody(userSchema)) // adds { body: UserType }
+    .handler((req, res) => {
+      // TypeScript knows about both userId and body!
+      res.json({ userId: req.userId, user: req.body });
+    })
+);
+```
+
+**See the [examples/](./examples) directory for more:**
+- [Authentication](./examples/auth.ts) - Direct middleware and optional auth patterns
+- [Zod Validation](./examples/zod-validation.ts) - Request body validation with type inference
+- [Error Handling](./examples/error-handling.ts) - Throwing errors that flow to Express handlers
+
+### Error Handling
+
+Middlewares can throw exceptions, and they'll automatically be caught and passed to Express error handlers:
+
+```typescript
+const requireAuth = middleware<{ userId: string }>((req) => {
+  const token = req.headers.authorization?.substring(7);
+  if (!token) {
+    throw new Error("Unauthorized"); // Automatically caught!
+  }
+  return { userId: token };
+});
+
+// Express error handler will catch the error
+app.use((err, req, res, next) => {
+  res.status(500).json({ error: err.message });
+});
+```
+
+This works seamlessly with async middleware too - rejected promises are automatically handled.
+
+## API
+
+### `route()`
+
+Creates a new route builder for chaining middleware.
+
+```typescript
+app.get(
+  "/path",
+  route()
+    .use(middleware1)
+    .use(middleware2)
+    .handler(finalHandler)
+);
+```
+
+### `middleware<TAdd>(fn)`
+
+Creates a typed middleware that adds properties to the request.
+
+**Parameters:**
+- `fn: (req: Request, res: Response) => TAdd | Promise<TAdd>` - Function that returns properties to add
+
+**Returns:** `Middleware<TAdd>`
+
+```typescript
+const myMiddleware = middleware<{ customProp: string }>((req, res) => {
+  return { customProp: "value" };
+});
+```
+
+### `Middleware<TReq>`
+
+Type for middleware functions that augment the request object.
+
+```typescript
+type Middleware<TReq = {}> = (
+  req: Omit<Request, keyof TReq> & TReq,
+  res: Response,
+  next: NextFunction
+) => void | Promise<void>;
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Found a bug or want to add a feature? Pull requests are welcome.
+
+## Author
+
+Thomas Pregenzer

package/dist/index.cjs

@@ -0,0 +1,74 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  middleware: () => middleware,
+  route: () => route
+});
+module.exports = __toCommonJS(index_exports);
+var RouteBuilder = class {
+  constructor() {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    this.middlewares = [];
+  }
+  /**
+   * Adds a middleware to the chain and merges its type into the request.
+   *
+   * @template TAdd - The type of properties this middleware adds to the request
+   * @param middleware - The middleware function to add
+   * @returns A new RouteBuilder with accumulated request types
+   */
+  use(middleware2) {
+    this.middlewares.push(middleware2);
+    return this;
+  }
+  /**
+   * Finalizes the route by adding the handler function.
+   * Returns an array of Express RequestHandlers ready to be used with app.get(), app.post(), etc.
+   *
+   * @param handler - The final route handler with access to all accumulated request properties
+   * @returns Array of RequestHandler functions to pass to Express route methods
+   *
+   * @example
+   * app.post('/api/users', route()
+   *   .use(authMiddleware)
+   *   .handler((req, res) => {
+   *     // Handler implementation
+   *   })
+   * );
+   */
+  handler(handler) {
+    return [...this.middlewares, handler];
+  }
+};
+var route = () => new RouteBuilder();
+var middleware = (fn) => {
+  return async (req, res, next) => {
+    const result = await fn(req, res);
+    Object.assign(req, result);
+    next();
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  middleware,
+  route
+});

package/dist/index.d.cts

@@ -0,0 +1,113 @@
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+
+/**
+ * Type-safe middleware function that can augment the Express Request object.
+ *
+ * @template TReq - The type representing additional properties added to the request object
+ *
+ * @example
+ * // See examples/auth.ts for a complete authentication middleware example
+ * const requireAuth: Middleware<{ userId: string }> = middleware((req) => {
+ *   const token = req.headers.authorization?.substring(7);
+ *   if (!token) throw new Error('Unauthorized');
+ *   return { userId: token };
+ * });
+ */
+type Middleware<TReq = {}> = (req: Omit<Request, keyof TReq> & TReq, res: Response, next: NextFunction) => void | Promise<void>;
+/**
+ * RouteBuilder provides an API for type-safe middleware chains.
+ *
+ * 1. Chain multiple middleware with `.use()`
+ * 2. Accumulate type information about request properties
+ * 3. Ensure the final handler has access to all augmented request properties
+ *
+ * @template TReq - Accumulated type of all request augmentations from chained middleware
+ *
+ * @example
+ * // See examples/auth.ts and examples/zod-validation.ts for complete examples
+ * const userSchema = z.object({ name: z.string(), email: z.string().email() });
+ *
+ * app.post('/api/users', route()
+ *   .use(requireAuth)              // adds { userId: string }
+ *   .use(validateBody(userSchema)) // adds { body: { name: string, email: string } }
+ *   .handler((req, res) => {
+ *     // TypeScript knows req.userId and req.body exist with correct types
+ *     res.json({ userId: req.userId, user: req.body });
+ *   })
+ * );
+ */
+declare class RouteBuilder<TReq = {}> {
+    private middlewares;
+    /**
+     * Adds a middleware to the chain and merges its type into the request.
+     *
+     * @template TAdd - The type of properties this middleware adds to the request
+     * @param middleware - The middleware function to add
+     * @returns A new RouteBuilder with accumulated request types
+     */
+    use<TAdd>(middleware: Middleware<TReq & TAdd>): RouteBuilder<TReq & TAdd>;
+    /**
+     * Finalizes the route by adding the handler function.
+     * Returns an array of Express RequestHandlers ready to be used with app.get(), app.post(), etc.
+     *
+     * @param handler - The final route handler with access to all accumulated request properties
+     * @returns Array of RequestHandler functions to pass to Express route methods
+     *
+     * @example
+     * app.post('/api/users', route()
+     *   .use(authMiddleware)
+     *   .handler((req, res) => {
+     *     // Handler implementation
+     *   })
+     * );
+     */
+    handler(handler: (req: Omit<Request, keyof TReq> & TReq, res: Response) => void | Promise<void>): RequestHandler[];
+}
+/**
+ * Creates a new RouteBuilder instance to start composing a type-safe middleware chain.
+ *
+ * @returns A new RouteBuilder with no middleware attached
+ *
+ * @example
+ * // See examples/auth.ts for complete middleware examples
+ * app.get('/api/profile', route()
+ *   .use(requireAuth)
+ *   .handler((req, res) => {
+ *     res.json({ userId: req.userId });
+ *   })
+ * );
+ */
+declare const route: () => RouteBuilder<{}>;
+/**
+ * Helper function to create a typed middleware that augments the request object.
+ *
+ * @template TAdd - The type of properties to add to the request
+ * @param fn - A function that returns the properties to add to the request
+ * @returns A Middleware function that merges the returned properties into req
+ *
+ * The middleware function:
+ * - Executes the provided function
+ * - Merges the returned object into the request using Object.assign
+ * - Calls next() to continue to the next middleware/handler
+ *
+ * @example
+ * // See examples/auth.ts and examples/zod-validation.ts for complete examples
+ * const requireAuth: Middleware<{ userId: string }> = middleware((req) => {
+ *   const authHeader = req.headers.authorization;
+ *   if (!authHeader || !authHeader.startsWith('Bearer ')) {
+ *     throw new Error('Missing or invalid authorization header');
+ *   }
+ *   const token = authHeader.substring(7);
+ *   return { userId: token };
+ * });
+ *
+ * // Use in routes
+ * route()
+ *   .use(requireAuth)
+ *   .handler((req, res) => {
+ *     res.json({ userId: req.userId });
+ *   });
+ */
+declare const middleware: <TAdd>(fn: (req: Request, res: Response) => Promise<TAdd> | TAdd) => Middleware<TAdd>;
+
+export { type Middleware, middleware, route };

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+
+/**
+ * Type-safe middleware function that can augment the Express Request object.
+ *
+ * @template TReq - The type representing additional properties added to the request object
+ *
+ * @example
+ * // See examples/auth.ts for a complete authentication middleware example
+ * const requireAuth: Middleware<{ userId: string }> = middleware((req) => {
+ *   const token = req.headers.authorization?.substring(7);
+ *   if (!token) throw new Error('Unauthorized');
+ *   return { userId: token };
+ * });
+ */
+type Middleware<TReq = {}> = (req: Omit<Request, keyof TReq> & TReq, res: Response, next: NextFunction) => void | Promise<void>;
+/**
+ * RouteBuilder provides an API for type-safe middleware chains.
+ *
+ * 1. Chain multiple middleware with `.use()`
+ * 2. Accumulate type information about request properties
+ * 3. Ensure the final handler has access to all augmented request properties
+ *
+ * @template TReq - Accumulated type of all request augmentations from chained middleware
+ *
+ * @example
+ * // See examples/auth.ts and examples/zod-validation.ts for complete examples
+ * const userSchema = z.object({ name: z.string(), email: z.string().email() });
+ *
+ * app.post('/api/users', route()
+ *   .use(requireAuth)              // adds { userId: string }
+ *   .use(validateBody(userSchema)) // adds { body: { name: string, email: string } }
+ *   .handler((req, res) => {
+ *     // TypeScript knows req.userId and req.body exist with correct types
+ *     res.json({ userId: req.userId, user: req.body });
+ *   })
+ * );
+ */
+declare class RouteBuilder<TReq = {}> {
+    private middlewares;
+    /**
+     * Adds a middleware to the chain and merges its type into the request.
+     *
+     * @template TAdd - The type of properties this middleware adds to the request
+     * @param middleware - The middleware function to add
+     * @returns A new RouteBuilder with accumulated request types
+     */
+    use<TAdd>(middleware: Middleware<TReq & TAdd>): RouteBuilder<TReq & TAdd>;
+    /**
+     * Finalizes the route by adding the handler function.
+     * Returns an array of Express RequestHandlers ready to be used with app.get(), app.post(), etc.
+     *
+     * @param handler - The final route handler with access to all accumulated request properties
+     * @returns Array of RequestHandler functions to pass to Express route methods
+     *
+     * @example
+     * app.post('/api/users', route()
+     *   .use(authMiddleware)
+     *   .handler((req, res) => {
+     *     // Handler implementation
+     *   })
+     * );
+     */
+    handler(handler: (req: Omit<Request, keyof TReq> & TReq, res: Response) => void | Promise<void>): RequestHandler[];
+}
+/**
+ * Creates a new RouteBuilder instance to start composing a type-safe middleware chain.
+ *
+ * @returns A new RouteBuilder with no middleware attached
+ *
+ * @example
+ * // See examples/auth.ts for complete middleware examples
+ * app.get('/api/profile', route()
+ *   .use(requireAuth)
+ *   .handler((req, res) => {
+ *     res.json({ userId: req.userId });
+ *   })
+ * );
+ */
+declare const route: () => RouteBuilder<{}>;
+/**
+ * Helper function to create a typed middleware that augments the request object.
+ *
+ * @template TAdd - The type of properties to add to the request
+ * @param fn - A function that returns the properties to add to the request
+ * @returns A Middleware function that merges the returned properties into req
+ *
+ * The middleware function:
+ * - Executes the provided function
+ * - Merges the returned object into the request using Object.assign
+ * - Calls next() to continue to the next middleware/handler
+ *
+ * @example
+ * // See examples/auth.ts and examples/zod-validation.ts for complete examples
+ * const requireAuth: Middleware<{ userId: string }> = middleware((req) => {
+ *   const authHeader = req.headers.authorization;
+ *   if (!authHeader || !authHeader.startsWith('Bearer ')) {
+ *     throw new Error('Missing or invalid authorization header');
+ *   }
+ *   const token = authHeader.substring(7);
+ *   return { userId: token };
+ * });
+ *
+ * // Use in routes
+ * route()
+ *   .use(requireAuth)
+ *   .handler((req, res) => {
+ *     res.json({ userId: req.userId });
+ *   });
+ */
+declare const middleware: <TAdd>(fn: (req: Request, res: Response) => Promise<TAdd> | TAdd) => Middleware<TAdd>;
+
+export { type Middleware, middleware, route };

package/dist/index.js

@@ -0,0 +1,48 @@
+// src/index.ts
+var RouteBuilder = class {
+  constructor() {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    this.middlewares = [];
+  }
+  /**
+   * Adds a middleware to the chain and merges its type into the request.
+   *
+   * @template TAdd - The type of properties this middleware adds to the request
+   * @param middleware - The middleware function to add
+   * @returns A new RouteBuilder with accumulated request types
+   */
+  use(middleware2) {
+    this.middlewares.push(middleware2);
+    return this;
+  }
+  /**
+   * Finalizes the route by adding the handler function.
+   * Returns an array of Express RequestHandlers ready to be used with app.get(), app.post(), etc.
+   *
+   * @param handler - The final route handler with access to all accumulated request properties
+   * @returns Array of RequestHandler functions to pass to Express route methods
+   *
+   * @example
+   * app.post('/api/users', route()
+   *   .use(authMiddleware)
+   *   .handler((req, res) => {
+   *     // Handler implementation
+   *   })
+   * );
+   */
+  handler(handler) {
+    return [...this.middlewares, handler];
+  }
+};
+var route = () => new RouteBuilder();
+var middleware = (fn) => {
+  return async (req, res, next) => {
+    const result = await fn(req, res);
+    Object.assign(req, result);
+    next();
+  };
+};
+export {
+  middleware,
+  route
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "express-typed-routes",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Type-safe middleware composition for Express",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "express",
+    "typescript",
+    "middleware",
+    "type-safe"
+  ],
+  "author": "Thomas Pregenzer",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PregOfficial/express-typed-routes"
+  },
+  "peerDependencies": {
+    "express": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^24.10.1",
+    "@typescript-eslint/eslint-plugin": "^8.48.1",
+    "@typescript-eslint/parser": "^8.48.1",
+    "eslint": "^9.39.1",
+    "express": "^5.2.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.48.1",
+    "vitest": "^4.0.15"
+  }
+}