@sjoblomtobias/relay 1.0.2 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # relay
 
-A lightweight TypeScript framework for building structured Express applications with decorator-based routing and automatic route loading.
+A lightweight TypeScript framework for building structured Express applications with decorator-based routing.
 
 ## Installation
 
@@ -17,27 +17,27 @@ Extend the `Route` class and decorate it with `@Public` or `@Private`. Override
 ```ts
 // src/routes/users.ts
 import { Public, Route } from "@sjoblomtobias/relay";
-import type { Request, Response } from "express";
+import type { Request, Response, NextFunction } from "express";
 
 @Public("/users")
 export default class UsersRoute extends Route {
-  protected get(req: Request, res: Response): void {
+  protected get(req: Request, res: Response, next: NextFunction): void {
     res.json([{ id: 1, name: "Alice" }]);
   }
 
-  protected getById(req: Request, res: Response): void {
+  protected getById(req: Request, res: Response, next: NextFunction): void {
     res.json({ id: req.params.id });
   }
 
-  protected post(req: Request, res: Response): void {
+  protected post(req: Request, res: Response, next: NextFunction): void {
     res.status(201).json(req.body);
   }
 
-  protected patch(req: Request, res: Response): void {
+  protected patch(req: Request, res: Response, next: NextFunction): void {
     res.json({ id: req.params.id, ...req.body });
   }
 
-  protected delete(req: Request, res: Response): void {
+  protected delete(req: Request, res: Response, next: NextFunction): void {
     res.status(204).send();
   }
 }
@@ -51,28 +51,27 @@ export default class UsersRoute extends Route {
 | `@Private(path)` | Registers the route at `path`, applies `authMiddleware` if provided |
 | `@Location(path, isPrivate?)` | Base decorator used by `@Public` and `@Private` |
 
-### 3. Start the server
+### 3. Register routes and start the server
+
+Import each route class explicitly and pass it to `registerRoutes`. Routes are never loaded implicitly from the filesystem, so the set of registered routes is always visible directly in your code.
 
 ```ts
 // src/index.ts
 import { Server } from "@sjoblomtobias/relay";
+import UsersRoute from "./routes/users.js";
 
-const server = new Server(3000, "routes");
+const server = new Server(3000);
 
-await server.start(
-  async () => {
-    // Runs before the server binds — load routes, connect to DB, etc.
-    await server.loadRoutes(import.meta.dirname);
-  },
-  () => {
-    console.log("Ready!");
-  }
-);
+server.registerRoutes(UsersRoute);
+
+await server.start(undefined, () => {
+  console.log("Ready!");
+});
 ```
 
 ### 4. Authentication middleware
 
-Pass an Express `RequestHandler` as the third argument to `Server`. It will be applied to all routes decorated with `@Private`.
+Pass an Express `RequestHandler` as the second argument to `Server`. It will be applied to all routes decorated with `@Private`. A route decorated with `@Private` throws when it's registered without an `authMiddleware` in place — set it before calling `registerRoutes`.
 
 ```ts
 import { Server } from "@sjoblomtobias/relay";
@@ -82,13 +81,14 @@ const authMiddleware = (req, res, next) => {
   next();
 };
 
-const server = new Server(3000, "routes", authMiddleware);
+const server = new Server(3000, authMiddleware);
 ```
 
-You can also set or update it later:
+You can also set it separately, as long as it happens before `registerRoutes`:
 
 ```ts
 server.setAuthMiddleware(authMiddleware);
+server.registerRoutes(UsersRoute);
 ```
 
 ## API
@@ -97,12 +97,12 @@ server.setAuthMiddleware(authMiddleware);
 
 | Method | Description |
 |--------|-------------|
-| `new Server(port, routesDir, authMiddleware?)` | Creates a new server instance |
-| `loadRoutes(baseDir?)` | Dynamically imports all route files from `baseDir/routesDir`. Defaults `baseDir` to `process.cwd()` |
+| `new Server(port, authMiddleware?)` | Creates a new server instance |
+| `registerRoutes(...routeClasses)` | Registers one or more route classes. Throws if a `@Private` route is registered before `authMiddleware` is set |
 | `start(before?, after?)` | Starts the server. Awaits optional `before` callback, binds the port, then awaits optional `after` callback |
 | `use(...handlers)` | Adds Express middleware |
 | `getApp()` | Returns the underlying Express app |
-| `setAuthMiddleware(middleware)` | Sets or replaces the authentication middleware |
+| `setAuthMiddleware(middleware)` | Sets or replaces the authentication middleware. Must be called before `registerRoutes` for any `@Private` route |
 
 ### `Route`
 
@@ -118,6 +118,31 @@ Abstract base class. Override any of the following optional methods:
 
 Override `getEndpoints()` to fully customize the endpoint configuration.
 
+## Security
+
+`Server` ships with a couple of safe defaults: the `X-Powered-By` header is disabled, and unhandled route errors are caught and returned as a generic `500` (the error message and stack trace are only included in the response when `NODE_ENV=development`).
+
+Beyond that, relay is intentionally minimal and does not add any hardening middleware for you. Depending on what your app is exposed to, consider adding:
+
+- [`helmet`](https://www.npmjs.com/package/helmet) for standard security headers (CSP, HSTS, etc.)
+- A rate limiter such as [`express-rate-limit`](https://www.npmjs.com/package/express-rate-limit) to slow down brute-force and abuse
+- Body size limits on `express.json()` / `express.urlencoded()` to avoid oversized request payloads
+
+These can be registered like any other Express middleware via `server.use(...)`:
+
+```ts
+import helmet from "helmet";
+import rateLimit from "express-rate-limit";
+import express from "express";
+
+server.use(helmet(), rateLimit({ windowMs: 60_000, limit: 100 }), express.json({ limit: "100kb" }));
+```
+
+Also keep in mind:
+
+- `authMiddleware` must be set (via the `Server` constructor or `setAuthMiddleware`) **before** calling `registerRoutes` — registering a `@Private` route without it throws rather than silently serving the route unprotected.
+- Route classes are only ever registered explicitly via `registerRoutes`; nothing is loaded implicitly from the filesystem, so the set of exposed routes is always visible in your own code.
+
 ## License
 
 Pirate

package/dist/route.js

@@ -44,15 +44,12 @@ export class Route {
      * Initializes the routes based on the implemented methods in the subclass.
      */
     initializeRoutes() {
+        if (this.isPrivate && !this.authMiddleware) {
+            throw new Error(`Route "${this.location}" is marked private but no authMiddleware was provided. Refusing to register it unprotected.`);
+        }
         this.getEndpoints().forEach(({ path, handler, routerMethod }) => {
             if (typeof handler === "function") {
-                let handlers;
-                if (this.isPrivate && this.authMiddleware) {
-                    handlers = [this.authMiddleware, handler.bind(this)];
-                }
-                else {
-                    handlers = [handler.bind(this)];
-                }
+                const handlers = this.isPrivate && this.authMiddleware ? [this.authMiddleware, handler.bind(this)] : [handler.bind(this)];
                 const fullPath = path ? `${this.location}${path}` : `${this.location}`;
                 routerMethod(fullPath, ...handlers);
             }

package/dist/server.d.ts

@@ -1,23 +1,27 @@
 import express from "express";
+import type { Route } from "./route.js";
 import type { RequestHandler } from "express";
+export type RouteConstructor = new (authMiddleware?: RequestHandler) => Route;
 export declare class Server {
     private port;
-    private routesDirectory;
     private app;
     private authMiddleware?;
     /**
      * Creates an instance of the Server class.
      * @param port The port number on which the server will listen.
-     * @param routesDirectory The directory where route files are located.
      * @param authMiddleware Optional authentication middleware to be used for private routes.
      */
-    constructor(port: number, routesDirectory: string, authMiddleware?: RequestHandler);
+    constructor(port: number, authMiddleware?: RequestHandler);
     /**
-     * Loads all routes from the specified directory.
-     * @param baseDir The base directory to resolve the routes directory from. Defaults to process.cwd().
-     * @returns Promise that resolves when all routes are loaded.
+     * Default error handler. Returns a generic 500 response, only including
+     * the error message and stack trace when NODE_ENV is "development".
      */
-    loadRoutes(baseDir?: string): Promise<void>;
+    private readonly errorHandler;
+    /**
+     * Registers one or more route classes with the server.
+     * @param routeClasses - Route classes decorated with @Public or @Private.
+     */
+    registerRoutes(...routeClasses: Array<RouteConstructor>): void;
     /**
      * Adds middleware functions to the Express application.
      * @param handlers - Array of Express request handlers (middleware functions).

package/dist/server.js

@@ -7,43 +7,39 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import fs from "fs";
-import path from "path";
 import express from "express";
 export class Server {
     /**
      * Creates an instance of the Server class.
      * @param port The port number on which the server will listen.
-     * @param routesDirectory The directory where route files are located.
      * @param authMiddleware Optional authentication middleware to be used for private routes.
      */
-    constructor(port, routesDirectory, authMiddleware) {
+    constructor(port, authMiddleware) {
+        /**
+         * Default error handler. Returns a generic 500 response, only including
+         * the error message and stack trace when NODE_ENV is "development".
+         */
+        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 })));
+        };
         this.port = port;
-        this.routesDirectory = routesDirectory;
         this.app = express();
+        this.app.disable("x-powered-by");
         this.authMiddleware = authMiddleware;
     }
     /**
-     * Loads all routes from the specified directory.
-     * @param baseDir The base directory to resolve the routes directory from. Defaults to process.cwd().
-     * @returns Promise that resolves when all routes are loaded.
+     * Registers one or more route classes with the server.
+     * @param routeClasses - Route classes decorated with @Public or @Private.
      */
-    loadRoutes() {
-        return __awaiter(this, arguments, void 0, function* (baseDir = process.cwd()) {
-            const routes = path.join(baseDir, this.routesDirectory);
-            if (!fs.existsSync(routes)) {
-                console.error(`Routes directory "${routes}" does not exist.`);
-                return;
-            }
-            const files = fs.readdirSync(routes);
-            yield Promise.all(files.map((file) => __awaiter(this, void 0, void 0, function* () {
-                const modulePath = path.join(routes, file);
-                const module = yield import(modulePath);
-                const RouteClass = module.default;
-                // Pass authMiddleware to Route constructor
-                const routeInstance = new RouteClass(this.authMiddleware);
-                this.app.use(routeInstance.router);
-            })));
+    registerRoutes(...routeClasses) {
+        routeClasses.forEach((RouteClass) => {
+            const routeInstance = new RouteClass(this.authMiddleware);
+            this.app.use(routeInstance.router);
         });
     }
     /**
@@ -72,6 +68,7 @@ export class Server {
             if (before) {
                 yield before();
             }
+            this.app.use(this.errorHandler);
             yield new Promise((resolve) => {
                 this.app.listen(this.port, () => {
                     resolve();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sjoblomtobias/relay",
-	"version": "1.0.2",
+	"version": "2.0.0",
 	"type": "module",
 	"main": "dist/index.js",
 	"scripts": {
@@ -12,6 +12,24 @@
 	"author": "Tobias Sjöblom",
 	"license": "Pirate",
 	"description": "A lightweight TypeScript framework for building structured Express applications with decorator-based routing and automatic route loading.",
+	"keywords": [
+		"express",
+		"typescript",
+		"framework",
+		"decorators",
+		"routing",
+		"rest",
+		"api",
+		"server"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sjoblomtobias/relay.git"
+	},
+	"homepage": "https://github.com/sjoblomtobias/relay#readme",
+	"bugs": {
+		"url": "https://github.com/sjoblomtobias/relay/issues"
+	},
 	"dependencies": {
 		"express": "^5.1.0"
 	},

package/src/route.ts

@@ -61,14 +61,12 @@ export abstract class Route {
 	 * Initializes the routes based on the implemented methods in the subclass.
 	 */
 	protected initializeRoutes() {
+		if (this.isPrivate && !this.authMiddleware) {
+			throw new Error(`Route "${this.location}" is marked private but no authMiddleware was provided. Refusing to register it unprotected.`);
+		}
 		this.getEndpoints().forEach(({ path, handler, routerMethod }) => {
 			if (typeof handler === "function") {
-				let handlers;
-				if (this.isPrivate && this.authMiddleware) {
-					handlers = [this.authMiddleware, handler.bind(this)];
-				} else {
-					handlers = [handler.bind(this)];
-				}
+				const handlers = this.isPrivate && this.authMiddleware ? [this.authMiddleware, handler.bind(this)] : [handler.bind(this)];
 				const fullPath = path ? `${this.location}${path}` : `${this.location}`;
 				routerMethod(fullPath, ...handlers);
 			}

package/src/server.ts

@@ -1,49 +1,51 @@
-import fs from "fs";
-import path from "path";
 import express from "express";
-import type { RequestHandler } from "express";
+import type { Route } from "./route.js";
+import type { ErrorRequestHandler, RequestHandler } from "express";
+
+export type RouteConstructor = new (authMiddleware?: RequestHandler) => Route;
 
 export class Server {
 	private port: number;
-	private routesDirectory: string;
 	private app: express.Express;
 	private authMiddleware?: RequestHandler;
 
 	/**
 	 * Creates an instance of the Server class.
 	 * @param port The port number on which the server will listen.
-	 * @param routesDirectory The directory where route files are located.
 	 * @param authMiddleware Optional authentication middleware to be used for private routes.
 	 */
-	constructor(port: number, routesDirectory: string, authMiddleware?: RequestHandler) {
+	constructor(port: number, authMiddleware?: RequestHandler) {
 		this.port = port;
-		this.routesDirectory = routesDirectory;
 		this.app = express();
+		this.app.disable("x-powered-by");
 		this.authMiddleware = authMiddleware;
 	}
 
 	/**
-	 * Loads all routes from the specified directory.
-	 * @param baseDir The base directory to resolve the routes directory from. Defaults to process.cwd().
-	 * @returns Promise that resolves when all routes are loaded.
+	 * Default error handler. Returns a generic 500 response, only including
+	 * the error message and stack trace when NODE_ENV is "development".
 	 */
-	public async loadRoutes(baseDir: string = process.cwd()): Promise<void> {
-		const routes = path.join(baseDir, this.routesDirectory);
-		if (!fs.existsSync(routes)) {
-			throw new Error(`Routes directory "${routes}" does not exist.`);
+	private readonly errorHandler: ErrorRequestHandler = (err, req, res, next) => {
+		if (res.headersSent) {
+			next(err);
+			return;
 		}
-		const files = fs.readdirSync(routes);
-		await Promise.all(
-			files.map(async (file) => {
-				const modulePath = path.join(routes, file);
-				const module = await import(modulePath);
-				const RouteClass = module.default;
+		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 })
+		});
+	};
 
-				// Pass authMiddleware to Route constructor
-				const routeInstance = new RouteClass(this.authMiddleware);
-				this.app.use(routeInstance.router);
-			})
-		);
+	/**
+	 * Registers one or more route classes with the server.
+	 * @param routeClasses - Route classes decorated with @Public or @Private.
+	 */
+	public registerRoutes(...routeClasses: Array<RouteConstructor>): void {
+		routeClasses.forEach((RouteClass) => {
+			const routeInstance = new RouteClass(this.authMiddleware);
+			this.app.use(routeInstance.router);
+		});
 	}
 
 	/**
@@ -71,6 +73,7 @@ export class Server {
 		if (before) {
 			await before();
 		}
+		this.app.use(this.errorHandler);
 		await new Promise<void>((resolve) => {
 			this.app.listen(this.port, () => {
 				resolve();

package/test/index.ts

@@ -1,13 +1,15 @@
 import { Server } from "../src/server.js";
+import HelloRoute from "./routes/hello.js";
 
-const server = new Server(3000, "routes");
+const server = new Server(3000);
+
+server.registerRoutes(HelloRoute);
 
 server.start(
 	() => {
-		console.log("Before start: loading routes...");
-		return server.loadRoutes(import.meta.dirname);
+		console.log("Before start: registering routes...");
 	},
 	() => {
-		console.log(`⚡ Server running on port: ${server['port']}`);
+		console.log(`⚡ Server running on port: ${server["port"]}`);
 	}
 );