@sjoblomtobias/relay 2.0.0 → 3.0.0

package/dist/server.d.ts

@@ -1,20 +1,30 @@
 import express from "express";
 import type { Route } from "./route.js";
 import type { RequestHandler } from "express";
-export type RouteConstructor = new (authMiddleware?: RequestHandler) => Route;
+export type RouteConstructor = new (...args: any[]) => Route;
+export type ServerOptions = {
+    /** Include error message and stack trace in 500 responses. Never enable in production. Defaults to false. */
+    exposeErrors?: boolean;
+    /** Maximum time in milliseconds a client has to send a complete request. Defaults to 30000. */
+    requestTimeoutMs?: number;
+};
 export declare class Server {
     private port;
     private app;
+    private stack;
     private authMiddleware?;
+    private routesRegistered;
+    private readonly options;
     /**
      * Creates an instance of the Server class.
      * @param port The port number on which the server will listen.
      * @param authMiddleware Optional authentication middleware to be used for private routes.
+     * @param options Optional server settings.
      */
-    constructor(port: number, authMiddleware?: RequestHandler);
+    constructor(port: number, authMiddleware?: RequestHandler, options?: ServerOptions);
     /**
-     * Default error handler. Returns a generic 500 response, only including
-     * the error message and stack trace when NODE_ENV is "development".
+     * Default error handler. Client errors (4xx) keep their status; everything else is a
+     * generic 500 and is logged. Error details are only sent when `exposeErrors` is enabled.
      */
     private readonly errorHandler;
     /**
@@ -23,7 +33,8 @@ export declare class Server {
      */
     registerRoutes(...routeClasses: Array<RouteConstructor>): void;
     /**
-     * Adds middleware functions to the Express application.
+     * Adds middleware functions to the Express application. Use this instead of
+     * `getApp().use()` so errors from the middleware reach the error handler.
      * @param handlers - Array of Express request handlers (middleware functions).
      */
     use(...handlers: Array<express.RequestHandler>): Promise<void>;
@@ -36,7 +47,12 @@ export declare class Server {
      * Starts the Express server.
      * @param before Optional callback invoked before the server starts.
      * @param after Optional callback invoked after the server has started.
+     * @throws If the server cannot listen, e.g. the port is already in use.
      */
     start(before?: () => void | Promise<void>, after?: () => void | Promise<void>): Promise<void>;
+    /**
+     * Sets the authentication middleware for private routes. Must be called before
+     * registerRoutes(), since routes capture the middleware when they are registered.
+     */
     setAuthMiddleware(middleware: RequestHandler): void;
 }

package/dist/server.js

@@ -7,29 +7,58 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+import { STATUS_CODES } from "node:http";
 import express from "express";
+const securityHeaders = (req, res, next) => {
+    res.set({
+        "X-Content-Type-Options": "nosniff",
+        "X-Frame-Options": "DENY",
+        "Referrer-Policy": "no-referrer"
+    });
+    next();
+};
+/**
+ * Returns the 4xx status carried by an error (e.g. from body parsing), or 500 for anything else.
+ */
+function errorStatus(err) {
+    const { status, statusCode } = (err !== null && err !== void 0 ? err : {});
+    const candidate = status !== null && status !== void 0 ? status : statusCode;
+    return typeof candidate === "number" && candidate >= 400 && candidate < 500 ? candidate : 500;
+}
 export class Server {
     /**
      * Creates an instance of the Server class.
      * @param port The port number on which the server will listen.
      * @param authMiddleware Optional authentication middleware to be used for private routes.
+     * @param options Optional server settings.
      */
-    constructor(port, authMiddleware) {
+    constructor(port, authMiddleware, options = {}) {
+        this.routesRegistered = false;
         /**
-         * Default error handler. Returns a generic 500 response, only including
-         * the error message and stack trace when NODE_ENV is "development".
+         * Default error handler. Client errors (4xx) keep their status; everything else is a
+         * generic 500 and is logged. Error details are only sent when `exposeErrors` is enabled.
          */
         this.errorHandler = (err, req, res, next) => {
             if (res.headersSent) {
                 next(err);
                 return;
             }
-            const isDevelopment = process.env.NODE_ENV === "development";
-            res.status(500).json(Object.assign({ error: "Internal Server Error" }, (isDevelopment && { message: err instanceof Error ? err.message : String(err), stack: err instanceof Error ? err.stack : undefined })));
+            const status = errorStatus(err);
+            if (status === 500) {
+                console.error(err);
+            }
+            res.status(status).json(Object.assign({ error: STATUS_CODES[status] }, (status === 500 && this.options.exposeErrors && { message: err instanceof Error ? err.message : String(err), stack: err instanceof Error ? err.stack : undefined })));
         };
         this.port = port;
+        this.options = Object.assign({ exposeErrors: false, requestTimeoutMs: 30000 }, options);
         this.app = express();
         this.app.disable("x-powered-by");
+        this.app.use(securityHeaders);
+        // Routes and middleware live in an inner router so the error handler, mounted
+        // after it, always runs last and catches errors from everything registered via this class.
+        this.stack = express.Router();
+        this.app.use(this.stack);
+        this.app.use(this.errorHandler);
         this.authMiddleware = authMiddleware;
     }
     /**
@@ -37,18 +66,20 @@ export class Server {
      * @param routeClasses - Route classes decorated with @Public or @Private.
      */
     registerRoutes(...routeClasses) {
+        this.routesRegistered = true;
         routeClasses.forEach((RouteClass) => {
             const routeInstance = new RouteClass(this.authMiddleware);
-            this.app.use(routeInstance.router);
+            this.stack.use(routeInstance.router);
         });
     }
     /**
-     * Adds middleware functions to the Express application.
+     * Adds middleware functions to the Express application. Use this instead of
+     * `getApp().use()` so errors from the middleware reach the error handler.
      * @param handlers - Array of Express request handlers (middleware functions).
      */
     use(...handlers) {
         return __awaiter(this, void 0, void 0, function* () {
-            this.app.use(handlers);
+            this.stack.use(handlers);
         });
     }
     /**
@@ -62,24 +93,31 @@ export class Server {
      * Starts the Express server.
      * @param before Optional callback invoked before the server starts.
      * @param after Optional callback invoked after the server has started.
+     * @throws If the server cannot listen, e.g. the port is already in use.
      */
     start(before, after) {
         return __awaiter(this, void 0, void 0, function* () {
             if (before) {
                 yield before();
             }
-            this.app.use(this.errorHandler);
-            yield new Promise((resolve) => {
-                this.app.listen(this.port, () => {
-                    resolve();
-                });
+            yield new Promise((resolve, reject) => {
+                // Express 5 passes listen errors (e.g. EADDRINUSE) to the callback.
+                const httpServer = this.app.listen(this.port, (err) => (err ? reject(err) : resolve()));
+                httpServer.requestTimeout = this.options.requestTimeoutMs;
             });
             if (after) {
                 yield after();
             }
         });
     }
+    /**
+     * Sets the authentication middleware for private routes. Must be called before
+     * registerRoutes(), since routes capture the middleware when they are registered.
+     */
     setAuthMiddleware(middleware) {
+        if (this.routesRegistered) {
+            throw new Error("setAuthMiddleware() must be called before registerRoutes(); already registered routes would not use it.");
+        }
         this.authMiddleware = middleware;
     }
 }

package/package.json

@@ -1,17 +1,19 @@
 {
 	"name": "@sjoblomtobias/relay",
-	"version": "2.0.0",
+	"version": "3.0.0",
 	"type": "module",
 	"main": "dist/index.js",
 	"scripts": {
 		"build": "tsc",
 		"dev": "tsx --watch test/index.ts",
 		"lint": "eslint src",
-		"format": "prettier --write src"
+		"format": "prettier --write src",
+		"typecheck:test": "tsc -p tsconfig.test.json",
+		"prepublishOnly": "npm run build && npm run lint && npm run typecheck:test"
 	},
 	"author": "Tobias Sjöblom",
 	"license": "Pirate",
-	"description": "A lightweight TypeScript framework for building structured Express applications with decorator-based routing and automatic route loading.",
+	"description": "A lightweight TypeScript framework for building structured Express applications with decorator-based routing.",
 	"keywords": [
 		"express",
 		"typescript",

package/src/server.ts

@@ -1,39 +1,80 @@
+import { STATUS_CODES } from "node:http";
 import express from "express";
 import type { Route } from "./route.js";
 import type { ErrorRequestHandler, RequestHandler } from "express";
 
-export type RouteConstructor = new (authMiddleware?: RequestHandler) => Route;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type RouteConstructor = new (...args: any[]) => Route;
+
+export type ServerOptions = {
+	/** Include error message and stack trace in 500 responses. Never enable in production. Defaults to false. */
+	exposeErrors?: boolean;
+	/** Maximum time in milliseconds a client has to send a complete request. Defaults to 30000. */
+	requestTimeoutMs?: number;
+};
+
+const securityHeaders: RequestHandler = (req, res, next) => {
+	res.set({
+		"X-Content-Type-Options": "nosniff",
+		"X-Frame-Options": "DENY",
+		"Referrer-Policy": "no-referrer"
+	});
+	next();
+};
+
+/**
+ * Returns the 4xx status carried by an error (e.g. from body parsing), or 500 for anything else.
+ */
+function errorStatus(err: unknown): number {
+	const { status, statusCode } = (err ?? {}) as { status?: unknown; statusCode?: unknown };
+	const candidate = status ?? statusCode;
+	return typeof candidate === "number" && candidate >= 400 && candidate < 500 ? candidate : 500;
+}
 
 export class Server {
 	private port: number;
 	private app: express.Express;
+	private stack: express.Router;
 	private authMiddleware?: RequestHandler;
+	private routesRegistered = false;
+	private readonly options: Required<ServerOptions>;
 
 	/**
 	 * Creates an instance of the Server class.
 	 * @param port The port number on which the server will listen.
 	 * @param authMiddleware Optional authentication middleware to be used for private routes.
+	 * @param options Optional server settings.
 	 */
-	constructor(port: number, authMiddleware?: RequestHandler) {
+	constructor(port: number, authMiddleware?: RequestHandler, options: ServerOptions = {}) {
 		this.port = port;
+		this.options = { exposeErrors: false, requestTimeoutMs: 30_000, ...options };
 		this.app = express();
 		this.app.disable("x-powered-by");
+		this.app.use(securityHeaders);
+		// Routes and middleware live in an inner router so the error handler, mounted
+		// after it, always runs last and catches errors from everything registered via this class.
+		this.stack = express.Router();
+		this.app.use(this.stack);
+		this.app.use(this.errorHandler);
 		this.authMiddleware = authMiddleware;
 	}
 
 	/**
-	 * Default error handler. Returns a generic 500 response, only including
-	 * the error message and stack trace when NODE_ENV is "development".
+	 * Default error handler. Client errors (4xx) keep their status; everything else is a
+	 * generic 500 and is logged. Error details are only sent when `exposeErrors` is enabled.
 	 */
 	private readonly errorHandler: ErrorRequestHandler = (err, req, res, next) => {
 		if (res.headersSent) {
 			next(err);
 			return;
 		}
-		const isDevelopment = process.env.NODE_ENV === "development";
-		res.status(500).json({
-			error: "Internal Server Error",
-			...(isDevelopment && { message: err instanceof Error ? err.message : String(err), stack: err instanceof Error ? err.stack : undefined })
+		const status = errorStatus(err);
+		if (status === 500) {
+			console.error(err);
+		}
+		res.status(status).json({
+			error: STATUS_CODES[status],
+			...(status === 500 && this.options.exposeErrors && { message: err instanceof Error ? err.message : String(err), stack: err instanceof Error ? err.stack : undefined })
 		});
 	};
 
@@ -42,18 +83,20 @@ export class Server {
 	 * @param routeClasses - Route classes decorated with @Public or @Private.
 	 */
 	public registerRoutes(...routeClasses: Array<RouteConstructor>): void {
+		this.routesRegistered = true;
 		routeClasses.forEach((RouteClass) => {
 			const routeInstance = new RouteClass(this.authMiddleware);
-			this.app.use(routeInstance.router);
+			this.stack.use(routeInstance.router);
 		});
 	}
 
 	/**
-	 * Adds middleware functions to the Express application.
+	 * Adds middleware functions to the Express application. Use this instead of
+	 * `getApp().use()` so errors from the middleware reach the error handler.
 	 * @param handlers - Array of Express request handlers (middleware functions).
 	 */
 	public async use(...handlers: Array<express.RequestHandler>): Promise<void> {
-		this.app.use(handlers);
+		this.stack.use(handlers);
 	}
 
 	/**
@@ -68,23 +111,30 @@ export class Server {
 	 * Starts the Express server.
 	 * @param before Optional callback invoked before the server starts.
 	 * @param after Optional callback invoked after the server has started.
+	 * @throws If the server cannot listen, e.g. the port is already in use.
 	 */
 	public async start(before?: () => void | Promise<void>, after?: () => void | Promise<void>): Promise<void> {
 		if (before) {
 			await before();
 		}
-		this.app.use(this.errorHandler);
-		await new Promise<void>((resolve) => {
-			this.app.listen(this.port, () => {
-				resolve();
-			});
+		await new Promise<void>((resolve, reject) => {
+			// Express 5 passes listen errors (e.g. EADDRINUSE) to the callback.
+			const httpServer = this.app.listen(this.port, (err?: Error) => (err ? reject(err) : resolve()));
+			httpServer.requestTimeout = this.options.requestTimeoutMs;
 		});
 		if (after) {
 			await after();
 		}
 	}
 
+	/**
+	 * Sets the authentication middleware for private routes. Must be called before
+	 * registerRoutes(), since routes capture the middleware when they are registered.
+	 */
 	public setAuthMiddleware(middleware: RequestHandler) {
+		if (this.routesRegistered) {
+			throw new Error("setAuthMiddleware() must be called before registerRoutes(); already registered routes would not use it.");
+		}
 		this.authMiddleware = middleware;
 	}
 }

package/tsconfig.test.json

@@ -0,0 +1,10 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"rootDir": ".",
+		"noEmit": true,
+		"declaration": false
+	},
+	"include": ["src/**/*", "test/**/*"],
+	"exclude": ["node_modules", "dist"]
+}