@sjoblomtobias/relay 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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:
+
+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/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @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

@@ -0,0 +1,7 @@
+/**
+ * @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

@@ -0,0 +1,94 @@
+/**
+ * @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";
+/**
+ * Decorator to set the base path and authentication requirement for a route class.
+ * @param location - The base path for the route.
+ * @param isPrivate - Whether to use authentication middleware.
+ * @returns A decorator function.
+ */
+export declare function Location(location: string, isPrivate?: boolean): <T extends {
+    new (...args: any[]): object;
+}>(constructor: T) => {
+    new (...args: any[]): {};
+} & T;
+/**
+ * Decorator to mark a route class as private.
+ * @param location - The base path for the route.
+ * @returns A decorator function.
+ */
+export declare function Private(location: string): <T extends {
+    new (...args: any[]): object;
+}>(constructor: T) => {
+    new (...args: any[]): {};
+} & T;
+/**
+ * Decorator to mark a route class as public.
+ * @param location - The base path for the route.
+ * @returns A decorator function.
+ */
+export declare function Public(location: string): <T extends {
+    new (...args: any[]): object;
+}>(constructor: T) => {
+    new (...args: any[]): {};
+} & T;
+export type Endpoint = {
+    path?: string;
+    handler: ((req: Request, res: Response, next: NextFunction) => void) | undefined;
+    routerMethod: (path: string, ...handlers: Array<(req: Request, res: Response, next: NextFunction) => void>) => void;
+};
+export declare abstract class Route {
+    router: Router;
+    location: string;
+    isPrivate: boolean;
+    authMiddleware?: (req: Request, res: Response, next: NextFunction) => void;
+    constructor(location: string, isPrivate?: boolean, authMiddleware?: (req: Request, res: Response, next: NextFunction) => void);
+    /**
+     * Initializes the routes based on the implemented methods in the subclass.
+     */
+    protected initializeRoutes(): void;
+    /**
+     * Returns an array of endpoint configurations.
+     * @returns Array of endpoint configurations. Override in subclass to customize endpoint paths.
+     */
+    protected getEndpoints(): Array<Endpoint>;
+    /**
+     * Handles GET requests to retrieve a resource by ID.
+     * @param req - The Express request object.
+     * @param res - The Express response object.
+     * @param next - The next middleware function.
+     */
+    protected getById?(req: Request, res: Response, next: NextFunction): void;
+    /**
+     * Handles GET requests to retrieve a resource.
+     * @param req - The Express request object.
+     * @param res - The Express response object.
+     * @param next - The next middleware function.
+     */
+    protected get?(req: Request, res: Response, next: NextFunction): void;
+    /**
+     * Handles POST requests to create a new resource.
+     * @param req - The Express request object.
+     * @param res - The Express response object.
+     * @param next - The next middleware function.
+     */
+    protected post?(req: Request, res: Response, next: NextFunction): void;
+    /**
+     * Handles PATCH requests to update an existing resource.
+     * @param req - The Express request object.
+     * @param res - The Express response object.
+     * @param next - The next middleware function.
+     */
+    protected patch?(req: Request, res: Response, next: NextFunction): void;
+    /**
+     * Handles DELETE requests to remove a resource.
+     * @param req - The Express request object.
+     * @param res - The Express response object.
+     * @param next - The next middleware function.
+     */
+    protected delete?(req: Request, res: Response, next: NextFunction): void;
+}

package/dist/route.js

@@ -0,0 +1,79 @@
+/**
+ * @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.
+ * @param location - The base path for the route.
+ * @param isPrivate - Whether to use authentication middleware.
+ * @returns A decorator function.
+ */
+export function Location(location, isPrivate = false) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return function (constructor) {
+        return class extends constructor {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            constructor(...args) {
+                super(location, isPrivate, ...args);
+            }
+        };
+    };
+}
+/**
+ * Decorator to mark a route class as private.
+ * @param location - The base path for the route.
+ * @returns A decorator function.
+ */
+export function Private(location) {
+    return Location(location, true);
+}
+/**
+ * Decorator to mark a route class as public.
+ * @param location - The base path for the route.
+ * @returns A decorator function.
+ */
+export function Public(location) {
+    return Location(location, false);
+}
+export class Route {
+    constructor(location, isPrivate = false, authMiddleware) {
+        this.router = Router();
+        this.location = location;
+        this.isPrivate = isPrivate;
+        this.authMiddleware = authMiddleware;
+        this.initializeRoutes();
+    }
+    /**
+     * Initializes the routes based on the implemented methods in the subclass.
+     */
+    initializeRoutes() {
+        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 fullPath = path ? `${this.location}${path}` : `${this.location}`;
+                routerMethod(fullPath, ...handlers);
+            }
+        });
+    }
+    /**
+     * Returns an array of endpoint configurations.
+     * @returns Array of endpoint configurations. Override in subclass to customize endpoint paths.
+     */
+    getEndpoints() {
+        return [
+            { path: "/:id", handler: this.getById, routerMethod: this.router.get.bind(this.router) },
+            { handler: this.get, routerMethod: this.router.get.bind(this.router) },
+            { handler: this.post, routerMethod: this.router.post.bind(this.router) },
+            { path: "/:id", handler: this.patch, routerMethod: this.router.patch.bind(this.router) },
+            { path: "/:id", handler: this.delete, routerMethod: this.router.delete.bind(this.router) }
+        ];
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @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 {
+    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);
+    /**
+     * Loads all routes from the specified directory.
+     * @returns Promise that resolves when all routes are loaded.
+     */
+    loadRoutes(): Promise<void>;
+    /**
+     * Adds middleware functions to the Express application.
+     * @param handlers - Array of Express request handlers (middleware functions).
+     */
+    use(...handlers: Array<express.RequestHandler>): Promise<void>;
+    /**
+     * Gets the Express application instance.
+     * @returns The Express application instance.
+     */
+    getApp(): express.Express;
+    /**
+     * Starts the Express server.
+     */
+    start(): void;
+    setAuthMiddleware(middleware: RequestHandler): void;
+}

package/dist/server.js

@@ -0,0 +1,67 @@
+/**
+ * @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";
+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) {
+        this.port = port;
+        this.routesDirectory = routesDirectory;
+        this.app = express();
+        this.authMiddleware = authMiddleware;
+    }
+    /**
+     * Loads all routes from the specified directory.
+     * @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);
+        }));
+    }
+    /**
+     * Adds middleware functions to the Express application.
+     * @param handlers - Array of Express request handlers (middleware functions).
+     */
+    async use(...handlers) {
+        this.app.use(handlers);
+    }
+    /**
+     * Gets the Express application instance.
+     * @returns The Express application instance.
+     */
+    getApp() {
+        return this.app;
+    }
+    /**
+     * Starts the Express server.
+     */
+    start() {
+        this.app.listen(this.port, () => {
+            console.log(`⚡ Server running on port: ${this.port}`);
+        });
+    }
+    setAuthMiddleware(middleware) {
+        this.authMiddleware = middleware;
+    }
+}

package/eslint.config.mts

@@ -0,0 +1,88 @@
+import js from "@eslint/js";
+import { defineConfig } from "eslint/config";
+import importPlugin from "eslint-plugin-import";
+import prettierConfig from "eslint-plugin-prettier/recommended";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+
+export default defineConfig([
+	{
+		languageOptions: {
+			globals: { ...globals.node }
+		}
+	},
+	js.configs.recommended,
+	tseslint.configs.recommended,
+	prettierConfig,
+	{
+		files: ["**/*.{ts,mts,cts}"],
+		plugins: {
+			"@typescript-eslint": tseslint.plugin,
+			import: importPlugin
+		},
+		languageOptions: {
+			parser: tseslint.parser,
+			parserOptions: { ecmaVersion: "latest", sourceType: "module" }
+		},
+		settings: {
+			"import/resolver": {
+				typescript: {
+					alwaysTryTypes: true,
+					project: "./tsconfig.json"
+				}
+			}
+		},
+		rules: {
+			"@typescript-eslint/no-explicit-any": "warn",
+			"no-unused-vars": "off",
+			"@typescript-eslint/no-unused-vars": [
+				"error",
+				{
+					vars: "all",
+					args: "after-used",
+					caughtErrors: "all",
+					argsIgnorePattern: "^_",
+					caughtErrorsIgnorePattern: "^_",
+					destructuredArrayIgnorePattern: "^_",
+					varsIgnorePattern: "^_"
+				}
+			],
+			"@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",
+						caseInsensitive: true
+					}
+				}
+			]
+		}
+	},
+	{
+		files: ["test/**/*.{ts,mts,cts}"],
+		rules: {
+			"no-restricted-imports": "off"
+		}
+	}
+]);

package/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "@sjoblomtobias/relay",
+	"version": "1.0.0",
+	"type": "module",
+	"main": "dist/index.js",
+	"scripts": {
+		"build": "tsc && tsc-alias"
+	},
+	"author": "Tobias Sjöblom",
+	"license": "MIT",
+	"description": "",
+	"dependencies": {
+		"express": "^5.1.0"
+	},
+	"devDependencies": {
+		"@eslint/js": "^9.35.0",
+		"@types/express": "^5.0.3",
+		"@types/node": "^24.5.2",
+		"@typescript-eslint/eslint-plugin": "^8.44.0",
+		"@typescript-eslint/parser": "^8.42.0",
+		"eslint": "^9.35.0",
+		"eslint-config-prettier": "^10.1.8",
+		"eslint-import-resolver-typescript": "^4.4.4",
+		"eslint-plugin-import": "^2.32.0",
+		"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/prettier.config.js

@@ -0,0 +1,11 @@
+const config = {
+	semi: true,
+	singleQuote: false,
+	tabWidth: 4,
+	trailingComma: "none",
+	useTabs: true,
+	vueIndentScriptAndStyle: true,
+	printWidth: 256
+};
+
+export default config;

package/src/index.ts

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

package/src/route.ts

@@ -0,0 +1,136 @@
+/**
+ * @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";
+
+/**
+ * Decorator to set the base path and authentication requirement for a route class.
+ * @param location - The base path for the route.
+ * @param isPrivate - Whether to use authentication middleware.
+ * @returns A decorator function.
+ */
+export function Location(location: string, isPrivate: boolean = false) {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	return function <T extends { new (...args: any[]): object }>(constructor: T) {
+		return class extends constructor {
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+			constructor(...args: any[]) {
+				super(location, isPrivate, ...args);
+			}
+		};
+	};
+}
+
+/**
+ * Decorator to mark a route class as private.
+ * @param location - The base path for the route.
+ * @returns A decorator function.
+ */
+export function Private(location: string) {
+	return Location(location, true);
+}
+
+/**
+ * Decorator to mark a route class as public.
+ * @param location - The base path for the route.
+ * @returns A decorator function.
+ */
+export function Public(location: string) {
+	return Location(location, false);
+}
+
+export type Endpoint = {
+	path?: string;
+	handler: ((req: Request, res: Response, next: NextFunction) => void) | undefined;
+	routerMethod: (path: string, ...handlers: Array<(req: Request, res: Response, next: NextFunction) => void>) => void;
+};
+
+export abstract class Route {
+	public router: Router;
+	public location: string;
+	public isPrivate: boolean;
+	public authMiddleware?: (req: Request, res: Response, next: NextFunction) => void;
+
+	constructor(location: string, isPrivate: boolean = false, authMiddleware?: (req: Request, res: Response, next: NextFunction) => void) {
+		this.router = Router();
+		this.location = location;
+		this.isPrivate = isPrivate;
+		this.authMiddleware = authMiddleware;
+		this.initializeRoutes();
+	}
+
+	/**
+	 * Initializes the routes based on the implemented methods in the subclass.
+	 */
+	protected initializeRoutes() {
+		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 fullPath = path ? `${this.location}${path}` : `${this.location}`;
+				routerMethod(fullPath, ...handlers);
+			}
+		});
+	}
+
+	/**
+	 * Returns an array of endpoint configurations.
+	 * @returns Array of endpoint configurations. Override in subclass to customize endpoint paths.
+	 */
+	protected getEndpoints(): Array<Endpoint> {
+		return [
+			{ path: "/:id", handler: this.getById, routerMethod: this.router.get.bind(this.router) },
+			{ handler: this.get, routerMethod: this.router.get.bind(this.router) },
+			{ handler: this.post, routerMethod: this.router.post.bind(this.router) },
+			{ path: "/:id", handler: this.patch, routerMethod: this.router.patch.bind(this.router) },
+			{ path: "/:id", handler: this.delete, routerMethod: this.router.delete.bind(this.router) }
+		];
+	}
+
+	/**
+	 * Handles GET requests to retrieve a resource by ID.
+	 * @param req - The Express request object.
+	 * @param res - The Express response object.
+	 * @param next - The next middleware function.
+	 */
+	protected getById?(req: Request, res: Response, next: NextFunction): void;
+
+	/**
+	 * Handles GET requests to retrieve a resource.
+	 * @param req - The Express request object.
+	 * @param res - The Express response object.
+	 * @param next - The next middleware function.
+	 */
+	protected get?(req: Request, res: Response, next: NextFunction): void;
+
+	/**
+	 * Handles POST requests to create a new resource.
+	 * @param req - The Express request object.
+	 * @param res - The Express response object.
+	 * @param next - The next middleware function.
+	 */
+	protected post?(req: Request, res: Response, next: NextFunction): void;
+
+	/**
+	 * Handles PATCH requests to update an existing resource.
+	 * @param req - The Express request object.
+	 * @param res - The Express response object.
+	 * @param next - The next middleware function.
+	 */
+	protected patch?(req: Request, res: Response, next: NextFunction): void;
+
+	/**
+	 * Handles DELETE requests to remove a resource.
+	 * @param req - The Express request object.
+	 * @param res - The Express response object.
+	 * @param next - The next middleware function.
+	 */
+	protected delete?(req: Request, res: Response, next: NextFunction): void;
+}

package/src/server.ts

@@ -0,0 +1,83 @@
+/**
+ * @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";
+import type { RequestHandler } from "express";
+
+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) {
+		this.port = port;
+		this.routesDirectory = routesDirectory;
+		this.app = express();
+		this.authMiddleware = authMiddleware;
+	}
+
+	/**
+	 * Loads all routes from the specified directory.
+	 * @returns Promise that resolves when all routes are loaded.
+	 */
+	public async loadRoutes(): Promise<void> {
+		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);
+			})
+		);
+	}
+
+	/**
+	 * Adds middleware functions to the Express application.
+	 * @param handlers - Array of Express request handlers (middleware functions).
+	 */
+	public async use(...handlers: Array<express.RequestHandler>): Promise<void> {
+		this.app.use(handlers);
+	}
+
+	/**
+	 * Gets the Express application instance.
+	 * @returns The Express application instance.
+	 */
+	public getApp(): express.Express {
+		return this.app;
+	}
+
+	/**
+	 * Starts the Express server.
+	 */
+	public start(): void {
+		this.app.listen(this.port, () => {
+			console.log(`⚡ Server running on port: ${this.port}`);
+		});
+	}
+
+	public setAuthMiddleware(middleware: RequestHandler) {
+		this.authMiddleware = middleware;
+	}
+}

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+	"compilerOptions": {
+		"baseUrl": ".",
+		"rootDir": "src",
+		"paths": {
+			"@/*": ["./src/*"]
+		},
+		"moduleResolution": "node",
+		"module": "esnext",
+		"target": "ES2020",
+		"esModuleInterop": true,
+		"allowSyntheticDefaultImports": true,
+		"strict": true,
+		"skipLibCheck": true,
+		"outDir": "dist",
+		"incremental": false,
+		"typeRoots": ["./node_modules/@types", "./src/types"],
+		"types": ["node"],
+		"experimentalDecorators": true,
+		"emitDecoratorMetadata": true,
+		"declaration": true
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist", "src/test"],
+	"tsc-alias": {
+		"resolveFullPaths": true,
+		"verbose": true
+	}
+}