@sjoblomtobias/relay 1.0.0 → 1.0.2

package/LICENSE

@@ -1,21 +1,20 @@
-MIT License
+Pirate License
 
-Copyright (c) 2025 Tobias Sjöblom
+Copyright (c) 2026 Tobias Sjöblom
 
-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:
+Avast! Permission be hereby granted, free o’ charge, to any scallywag obtainin’ a copy
+o’ this software and its associated treasure maps (the “Software”), to plunder and deal
+with it without restriction, includin’ without limit the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and sell
+copies o’ the Software, and to allow other swashbucklers to do the same,
+subject to the followin’ code of the sea:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be hoisted on all
+copies or substantial portions o’ 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
+THE SOFTWARE BE PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDIN’ BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, OR 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.
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISIN’ FROM,
+OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS THEREIN.

package/README.md

@@ -0,0 +1,123 @@
+# relay
+
+A lightweight TypeScript framework for building structured Express applications with decorator-based routing and automatic route loading.
+
+## Installation
+
+```bash
+npm install @sjoblomtobias/relay
+```
+
+## Usage
+
+### 1. Create a route
+
+Extend the `Route` class and decorate it with `@Public` or `@Private`. Override any of the built-in HTTP method handlers you need.
+
+```ts
+// src/routes/users.ts
+import { Public, Route } from "@sjoblomtobias/relay";
+import type { Request, Response } from "express";
+
+@Public("/users")
+export default class UsersRoute extends Route {
+  protected get(req: Request, res: Response): void {
+    res.json([{ id: 1, name: "Alice" }]);
+  }
+
+  protected getById(req: Request, res: Response): void {
+    res.json({ id: req.params.id });
+  }
+
+  protected post(req: Request, res: Response): void {
+    res.status(201).json(req.body);
+  }
+
+  protected patch(req: Request, res: Response): void {
+    res.json({ id: req.params.id, ...req.body });
+  }
+
+  protected delete(req: Request, res: Response): void {
+    res.status(204).send();
+  }
+}
+```
+
+### 2. Decorators
+
+| Decorator | Description |
+|-----------|-------------|
+| `@Public(path)` | Registers the route at `path` without authentication |
+| `@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
+
+```ts
+// src/index.ts
+import { Server } from "@sjoblomtobias/relay";
+
+const server = new Server(3000, "routes");
+
+await server.start(
+  async () => {
+    // Runs before the server binds — load routes, connect to DB, etc.
+    await server.loadRoutes(import.meta.dirname);
+  },
+  () => {
+    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`.
+
+```ts
+import { Server } from "@sjoblomtobias/relay";
+
+const authMiddleware = (req, res, next) => {
+  if (!req.headers.authorization) return res.status(401).send("Unauthorized");
+  next();
+};
+
+const server = new Server(3000, "routes", authMiddleware);
+```
+
+You can also set or update it later:
+
+```ts
+server.setAuthMiddleware(authMiddleware);
+```
+
+## API
+
+### `Server`
+
+| 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()` |
+| `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 |
+
+### `Route`
+
+Abstract base class. Override any of the following optional methods:
+
+| Method | HTTP method | Path |
+|--------|-------------|------|
+| `get` | GET | `/location` |
+| `getById` | GET | `/location/:id` |
+| `post` | POST | `/location` |
+| `patch` | PATCH | `/location/:id` |
+| `delete` | DELETE | `/location/:id` |
+
+Override `getEndpoints()` to fully customize the endpoint configuration.
+
+## License
+
+Pirate

package/dist/index.d.ts

@@ -1,7 +1,2 @@
-/**
- * @author Tobias Sjöblom
- * @since 1.0.0
- * @summary Entry point for the application.
- */
 export * from "./route.js";
 export * from "./server.js";

package/dist/index.js

@@ -1,7 +1,2 @@
-/**
- * @author Tobias Sjöblom
- * @since 1.0.0
- * @summary Entry point for the application.
- */
 export * from "./route.js";
 export * from "./server.js";

package/dist/route.d.ts

@@ -1,8 +1,3 @@
-/**
- * @author Tobias Sjöblom
- * @since 1.0.0
- * @summary Base class for defining routes in an Express application.
- */
 import { Router } from "express";
 import type { Request, Response, NextFunction } from "express";
 /**

package/dist/route.js

@@ -1,8 +1,3 @@
-/**
- * @author Tobias Sjöblom
- * @since 1.0.0
- * @summary Base class for defining routes in an Express application.
- */
 import { Router } from "express";
 /**
  * Decorator to set the base path and authentication requirement for a route class.

package/dist/server.d.ts

@@ -1,8 +1,3 @@
-/**
- * @author Tobias Sjöblom
- * @since 1.0.0
- * @summary Class representing an Express server that dynamically loads routes from a specified directory.
- */
 import express from "express";
 import type { RequestHandler } from "express";
 export declare class Server {
@@ -19,9 +14,10 @@ export declare class Server {
     constructor(port: number, routesDirectory: string, 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.
      */
-    loadRoutes(): Promise<void>;
+    loadRoutes(baseDir?: string): Promise<void>;
     /**
      * Adds middleware functions to the Express application.
      * @param handlers - Array of Express request handlers (middleware functions).
@@ -34,7 +30,9 @@ export declare class Server {
     getApp(): express.Express;
     /**
      * Starts the Express server.
+     * @param before Optional callback invoked before the server starts.
+     * @param after Optional callback invoked after the server has started.
      */
-    start(): void;
+    start(before?: () => void | Promise<void>, after?: () => void | Promise<void>): Promise<void>;
     setAuthMiddleware(middleware: RequestHandler): void;
 }

package/dist/server.js

@@ -1,8 +1,12 @@
-/**
- * @author Tobias Sjöblom
- * @since 1.0.0
- * @summary Class representing an Express server that dynamically loads routes from a specified directory.
- */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 import fs from "fs";
 import path from "path";
 import express from "express";
@@ -21,30 +25,35 @@ export class Server {
     }
     /**
      * 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.
      */
-    async loadRoutes() {
-        const routes = path.join(process.cwd(), this.routesDirectory);
-        if (!fs.existsSync(routes)) {
-            console.error(`Routes directory "${routes}" does not exist.`);
-            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;
-            // Pass authMiddleware to Route constructor
-            const routeInstance = new RouteClass(this.authMiddleware);
-            this.app.use(routeInstance.router);
-        }));
+    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);
+            })));
+        });
     }
     /**
      * Adds middleware functions to the Express application.
      * @param handlers - Array of Express request handlers (middleware functions).
      */
-    async use(...handlers) {
-        this.app.use(handlers);
+    use(...handlers) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.app.use(handlers);
+        });
     }
     /**
      * Gets the Express application instance.
@@ -55,10 +64,22 @@ 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.
      */
-    start() {
-        this.app.listen(this.port, () => {
-            console.log(`⚡ Server running on port: ${this.port}`);
+    start(before, after) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (before) {
+                yield before();
+            }
+            yield new Promise((resolve) => {
+                this.app.listen(this.port, () => {
+                    resolve();
+                });
+            });
+            if (after) {
+                yield after();
+            }
         });
     }
     setAuthMiddleware(middleware) {

package/eslint.config.mts

@@ -48,28 +48,11 @@ export default defineConfig([
 				}
 			],
 			"@typescript-eslint/consistent-type-imports": ["error", { prefer: "type-imports" }],
-			"capitalized-comments": ["error", "always", { ignoreConsecutiveComments: true }],
 			eqeqeq: ["error", "always"],
-			"no-console": "warn",
-			curly: ["error", "all"],
-			"no-restricted-imports": [
-				"error",
-				{
-					patterns: [".*"]
-				}
-			],
 			"import/order": [
 				"error",
 				{
 					groups: ["builtin", "external", "internal", "parent", "sibling", "index", "object", "type"],
-					pathGroups: [
-						{
-							pattern: "@/**",
-							group: "internal",
-							position: "before"
-						}
-					],
-					pathGroupsExcludedImportTypes: ["builtin"],
 					"newlines-between": "never",
 					alphabetize: {
 						order: "asc",
@@ -78,11 +61,5 @@ export default defineConfig([
 				}
 			]
 		}
-	},
-	{
-		files: ["test/**/*.{ts,mts,cts}"],
-		rules: {
-			"no-restricted-imports": "off"
-		}
 	}
 ]);

package/package.json

@@ -1,14 +1,17 @@
 {
 	"name": "@sjoblomtobias/relay",
-	"version": "1.0.0",
+	"version": "1.0.2",
 	"type": "module",
 	"main": "dist/index.js",
 	"scripts": {
-		"build": "tsc && tsc-alias"
+		"build": "tsc",
+		"dev": "tsx --watch test/index.ts",
+		"lint": "eslint src",
+		"format": "prettier --write src"
 	},
 	"author": "Tobias Sjöblom",
-	"license": "MIT",
-	"description": "",
+	"license": "Pirate",
+	"description": "A lightweight TypeScript framework for building structured Express applications with decorator-based routing and automatic route loading.",
 	"dependencies": {
 		"express": "^5.1.0"
 	},
@@ -25,11 +28,9 @@
 		"eslint-plugin-prettier": "^5.5.4",
 		"globals": "^16.4.0",
 		"jiti": "^2.5.1",
-		"nodemon": "^3.1.10",
 		"prettier": "^3.6.2",
-		"tsc-alias": "^1.8.16",
 		"tsx": "^4.20.5",
 		"typescript": "^5.9.2",
 		"typescript-eslint": "^8.44.0"
 	}
-}
+}

package/src/index.ts

@@ -1,7 +1,2 @@
-/**
- * @author Tobias Sjöblom
- * @since 1.0.0
- * @summary Entry point for the application.
- */
-export * from "@/route";
-export * from "@/server";
+export * from "./route.js";
+export * from "./server.js";

package/src/route.ts

@@ -1,8 +1,3 @@
-/**
- * @author Tobias Sjöblom
- * @since 1.0.0
- * @summary Base class for defining routes in an Express application.
- */
 import { Router } from "express";
 import type { Request, Response, NextFunction } from "express";
 

package/src/server.ts

@@ -1,9 +1,3 @@
-/**
- * @author Tobias Sjöblom
- * @since 1.0.0
- * @summary Class representing an Express server that dynamically loads routes from a specified directory.
- */
-
 import fs from "fs";
 import path from "path";
 import express from "express";
@@ -30,13 +24,13 @@ export class Server {
 
 	/**
 	 * 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.
 	 */
-	public async loadRoutes(): Promise<void> {
-		const routes = path.join(process.cwd(), this.routesDirectory);
+	public async loadRoutes(baseDir: string = process.cwd()): Promise<void> {
+		const routes = path.join(baseDir, this.routesDirectory);
 		if (!fs.existsSync(routes)) {
-			console.error(`Routes directory "${routes}" does not exist.`);
-			return;
+			throw new Error(`Routes directory "${routes}" does not exist.`);
 		}
 		const files = fs.readdirSync(routes);
 		await Promise.all(
@@ -70,11 +64,21 @@ 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.
 	 */
-	public start(): void {
-		this.app.listen(this.port, () => {
-			console.log(`⚡ Server running on port: ${this.port}`);
+	public async start(before?: () => void | Promise<void>, after?: () => void | Promise<void>): Promise<void> {
+		if (before) {
+			await before();
+		}
+		await new Promise<void>((resolve) => {
+			this.app.listen(this.port, () => {
+				resolve();
+			});
 		});
+		if (after) {
+			await after();
+		}
 	}
 
 	public setAuthMiddleware(middleware: RequestHandler) {

package/test/index.ts

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

package/test/routes/hello.ts

@@ -0,0 +1,9 @@
+import { Public, Route } from "../../src/route.js";
+import type { Request, Response } from "express";
+
+@Public("/hello")
+export default class HelloRoute extends Route {
+	protected get(req: Request, res: Response): void {
+		res.json({ message: "Hello from relay!" });
+	}
+}

package/tsconfig.json

@@ -1,13 +1,9 @@
 {
 	"compilerOptions": {
-		"baseUrl": ".",
 		"rootDir": "src",
-		"paths": {
-			"@/*": ["./src/*"]
-		},
-		"moduleResolution": "node",
+		"moduleResolution": "bundler",
 		"module": "esnext",
-		"target": "ES2020",
+		"target": "es6",
 		"esModuleInterop": true,
 		"allowSyntheticDefaultImports": true,
 		"strict": true,
@@ -21,9 +17,5 @@
 		"declaration": true
 	},
 	"include": ["src/**/*"],
-	"exclude": ["node_modules", "dist", "src/test"],
-	"tsc-alias": {
-		"resolveFullPaths": true,
-		"verbose": true
-	}
+	"exclude": ["node_modules", "dist", "src/test"]
 }