clear-router 2.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Refkinscallv
+
+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,231 @@
+# @refkinscallv/express-routing
+
+Laravel-style routing system for Express.js in JavaScript. Clean route definitions, middleware support, and controller bindings with full TypeScript support.
+
+## Installation
+
+```bash
+npm install @refkinscallv/express-routing
+```
+
+## Features
+
+- Simple and clean route declarations (get, post, put, delete, patch, options, head)
+- Grouped routes with prefix
+- Middleware stack: per-route and group-level
+- Controller-method pair as route handler
+- Supports HttpContext style handlers: { req, res, next }
+- Auto-binds controller methods
+- Full CommonJS, ESM, and TypeScript support
+- Error handling delegated to Express
+- Route inspection with allRoutes method
+- Fully Express-compatible
+
+## Quick Start
+
+### CommonJS
+
+```javascript
+const express = require('express');
+const Routes = require('@refkinscallv/express-routing');
+
+const app = express();
+const router = express.Router();
+
+Routes.get('/hello', ({ res }) => {
+  res.send('Hello World');
+});
+
+Routes.apply(router);
+app.use(router);
+
+app.listen(3000);
+```
+
+### ESM
+
+```javascript
+import express from 'express';
+import Routes from '@refkinscallv/express-routing';
+
+const app = express();
+const router = express.Router();
+
+Routes.get('/hello', ({ res }) => {
+  res.send('Hello World');
+});
+
+await Routes.apply(router);
+app.use(router);
+
+app.listen(3000);
+```
+
+### TypeScript
+
+```typescript
+import express from 'express';
+import Routes from '@refkinscallv/express-routing';
+
+const app = express();
+const router = express.Router();
+
+Routes.get('/hello', ({ res }) => {
+  res.send('Hello World');
+});
+
+await Routes.apply(router);
+app.use(router);
+
+app.listen(3000);
+```
+
+## Usage Examples
+
+### Basic Route
+
+```javascript
+Routes.get('/hello', ({ res }) => {
+  res.send('Hello World');
+});
+```
+
+### With Middleware
+
+```javascript
+const authMiddleware = (req, res, next) => {
+  // auth logic
+  next();
+};
+
+Routes.post('/secure', ({ res }) => res.send('Protected'), [authMiddleware]);
+```
+
+### Controller Binding
+
+```javascript
+class UserController {
+  static index({ res }) {
+    res.send('User List');
+  }
+}
+
+Routes.get('/users', [UserController, 'index']);
+```
+
+Class-based handlers will auto-bind to static or instance methods.
+
+### Grouped Routes
+
+```javascript
+Routes.group('/admin', () => {
+  Routes.get('/dashboard', ({ res }) => res.send('Admin Panel'));
+});
+```
+
+With middleware:
+
+```javascript
+Routes.group('/secure', () => {
+  Routes.get('/data', ({ res }) => res.send('Secure Data'));
+}, [authMiddleware]);
+```
+
+### Global Middleware Scope
+
+```javascript
+Routes.middleware([authMiddleware], () => {
+  Routes.get('/profile', ({ res }) => res.send('My Profile'));
+});
+```
+
+### Multiple HTTP Methods
+
+```javascript
+Routes.add(['get', 'post'], '/handle', ({ req, res }) => {
+  res.send(`Method: ${req.method}`);
+});
+```
+
+### Inspecting Routes
+
+```javascript
+Routes.get('/hello', ({ res }) => res.send('Hello'));
+Routes.post('/world', ({ res }) => res.send('World'));
+
+const allRoutes = Routes.allRoutes();
+console.log(allRoutes);
+// Output:
+// [
+//   { methods: ['get'], path: '/hello', middlewareCount: 0, handlerType: 'function' },
+//   { methods: ['post'], path: '/world', middlewareCount: 0, handlerType: 'function' }
+// ]
+```
+
+## API Reference
+
+See [API.md](API.md) for complete API documentation.
+
+## Error Handling
+
+All errors during route execution are automatically passed to Express error handling middleware using `next(error)`. You can define your error handler:
+
+```javascript
+app.use((err, req, res, next) => {
+  console.error(err);
+  res.status(500).json({ error: err.message });
+});
+```
+
+## Middleware Execution Order
+
+```
+[ Global Middleware ] → [ Group Middleware ] → [ Route Middleware ]
+```
+
+## Handler Execution
+
+- If function: executed directly
+- If [Controller, 'method']: auto-instantiated (if needed), method is called
+
+## Testing
+
+```bash
+npm test              # Run all tests
+npm run test:cjs      # Test CommonJS
+npm run test:esm      # Test ESM
+npm run test:ts       # Test TypeScript
+```
+
+See [TESTING.md](TESTING.md) for detailed testing guide.
+
+## Examples
+
+```bash
+npm run example       # CommonJS example
+npm run example:esm   # ESM example
+npm run example:ts    # TypeScript example
+```
+
+Check `example/` directory for full working demos.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+## Requirements
+
+- Node.js >= 14.0.0
+- Express >= 5.0.0
+
+## License
+
+MIT License © 2026 Refkinscallv
+
+## Author
+
+Refkinscallv <refkinscallv@gmail.com>
+
+## Repository
+
+https://github.com/refkinscallv/express-routing

package/dist/basic-BCxhZ1Wd.d.cts

@@ -0,0 +1,24 @@
+//#region types/basic.d.ts
+/**
+ * Controller method reference
+ */
+type ControllerHandler = [any, string];
+/**
+ * HTTP methods supported by the router
+ */
+type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head';
+/**
+ * Route information object
+ */
+interface RouteInfo {
+  methods: HttpMethod[];
+  path: string;
+  middlewareCount: number;
+  handlerType: 'function' | 'controller';
+}
+/**
+ * Common controller action names
+ */
+type ControllerAction = 'index' | 'show' | 'create' | 'update' | 'destroy';
+//#endregion
+export { RouteInfo as i, ControllerHandler as n, HttpMethod as r, ControllerAction as t };

package/dist/basic-POMY6a76.d.mts

@@ -0,0 +1,24 @@
+//#region types/basic.d.ts
+/**
+ * Controller method reference
+ */
+type ControllerHandler = [any, string];
+/**
+ * HTTP methods supported by the router
+ */
+type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head';
+/**
+ * Route information object
+ */
+interface RouteInfo {
+  methods: HttpMethod[];
+  path: string;
+  middlewareCount: number;
+  handlerType: 'function' | 'controller';
+}
+/**
+ * Common controller action names
+ */
+type ControllerAction = 'index' | 'show' | 'create' | 'update' | 'destroy';
+//#endregion
+export { RouteInfo as i, ControllerHandler as n, HttpMethod as r, ControllerAction as t };

package/dist/express/routes.cjs

@@ -0,0 +1,249 @@
+
+//#region src/express/routes.ts
+/**
+* @class clear-router
+* @description Laravel-style routing system for Express.js and H3 with support for CommonJS, ESM, and TypeScript
+* @author Refkinscallv
+* @author 3m1n3nc3
+* @repository https://github.com/toneflix/clear-router
+*/
+var Routes = class {
+	/**
+	* All registered routes
+	*/
+	static routes = [];
+	/**
+	* Current route prefix
+	*/
+	static prefix = "";
+	/**
+	* Group-level middlewares
+	*/
+	static groupMiddlewares = [];
+	/**
+	* Global-level middlewares
+	*/
+	static globalMiddlewares = [];
+	/**
+	* Normalize path by removing duplicate slashes and ensuring leading slash
+	* @param path - Path to normalize
+	* @returns Normalized path
+	*/
+	static normalizePath(path) {
+		return "/" + path.split("/").filter(Boolean).join("/");
+	}
+	/**
+	* Add a route with specified HTTP methods, path, handler, and middlewares
+	* @param methods - HTTP method(s) for the route
+	* @param path - Route path
+	* @param handler - Route handler function or controller reference
+	* @param middlewares - Array of middleware functions
+	*/
+	static add(methods, path, handler, middlewares) {
+		const methodArray = Array.isArray(methods) ? methods : [methods];
+		const fullPath = this.normalizePath(`${this.prefix}/${path}`);
+		this.routes.push({
+			methods: methodArray,
+			path: fullPath,
+			handler,
+			middlewares: [
+				...this.globalMiddlewares,
+				...this.groupMiddlewares,
+				...middlewares || []
+			]
+		});
+	}
+	/**
+	* Register RESTful API resource routes for a controller with optional action filtering
+	* 
+	* @param basePath - Base path for the resource
+	* @param controller - Controller object containing action methods
+	* @param options - Optional filtering options for actions
+	*/
+	static apiResource(basePath, controller, options) {
+		const actions = {
+			index: {
+				method: "get",
+				path: "/"
+			},
+			show: {
+				method: "get",
+				path: "/:id"
+			},
+			create: {
+				method: "post",
+				path: "/"
+			},
+			update: {
+				method: "put",
+				path: "/:id"
+			},
+			destroy: {
+				method: "delete",
+				path: "/:id"
+			}
+		};
+		const only = options?.only || Object.keys(actions);
+		const except = options?.except || [];
+		for (const action of only) {
+			if (except.includes(action)) continue;
+			if (typeof controller[action] === "function") {
+				const { method, path } = actions[action];
+				this.add(method, `${basePath}${path}`, [controller, action]);
+			}
+		}
+	}
+	/**
+	* Register a GET route
+	* @param path - Route path
+	* @param handler - Route handler
+	* @param middlewares - Middleware functions
+	*/
+	static get(path, handler, middlewares) {
+		this.add("get", path, handler, middlewares);
+	}
+	/**
+	* Register a POST route
+	* @param path - Route path
+	* @param handler - Route handler
+	* @param middlewares - Middleware functions
+	*/
+	static post(path, handler, middlewares) {
+		this.add("post", path, handler, middlewares);
+	}
+	/**
+	* Register a PUT route
+	* @param path - Route path
+	* @param handler - Route handler
+	* @param middlewares - Middleware functions
+	*/
+	static put(path, handler, middlewares) {
+		this.add("put", path, handler, middlewares);
+	}
+	/**
+	* Register a DELETE route
+	* @param path - Route path
+	* @param handler - Route handler
+	* @param middlewares - Middleware functions
+	*/
+	static delete(path, handler, middlewares) {
+		this.add("delete", path, handler, middlewares);
+	}
+	/**
+	* Register a PATCH route
+	* @param path - Route path
+	* @param handler - Route handler
+	* @param middlewares - Middleware functions
+	*/
+	static patch(path, handler, middlewares) {
+		this.add("patch", path, handler, middlewares);
+	}
+	/**
+	* Register an OPTIONS route
+	* @param path - Route path
+	* @param handler - Route handler
+	* @param middlewares - Middleware functions
+	*/
+	static options(path, handler, middlewares) {
+		this.add("options", path, handler, middlewares);
+	}
+	/**
+	* Register a HEAD route
+	* @param path - Route path
+	* @param handler - Route handler
+	* @param middlewares - Middleware functions
+	*/
+	static head(path, handler, middlewares) {
+		this.add("head", path, handler, middlewares);
+	}
+	/**
+	* Group routes with a common prefix and middlewares
+	* @param prefix - URL prefix for grouped routes
+	* @param callback - Function containing route definitions
+	* @param middlewares - Middleware functions applied to all routes in group
+	*/
+	static group(prefix, callback, middlewares) {
+		const previousPrefix = this.prefix;
+		const previousMiddlewares = this.groupMiddlewares;
+		const fullPrefix = [previousPrefix, prefix].filter(Boolean).join("/");
+		this.prefix = this.normalizePath(fullPrefix);
+		this.groupMiddlewares = [...previousMiddlewares, ...middlewares || []];
+		callback();
+		this.prefix = previousPrefix;
+		this.groupMiddlewares = previousMiddlewares;
+	}
+	/**
+	* Apply global middlewares for the duration of the callback
+	* @param middlewares - Middleware functions
+	* @param callback - Function containing route definitions
+	*/
+	static middleware(middlewares, callback) {
+		const prevMiddlewares = this.globalMiddlewares;
+		this.globalMiddlewares = [...prevMiddlewares, ...middlewares || []];
+		callback();
+		this.globalMiddlewares = prevMiddlewares;
+	}
+	/**
+	* Get all registered routes with their information
+	* @returns Array of route information objects
+	*/
+	static allRoutes() {
+		return this.routes.map((route) => ({
+			methods: route.methods,
+			path: route.path,
+			middlewareCount: route.middlewares.length,
+			handlerType: typeof route.handler === "function" ? "function" : "controller"
+		}));
+	}
+	static async apply(router) {
+		for (const route of this.routes) {
+			let handlerFunction = null;
+			try {
+				if (typeof route.handler === "function") handlerFunction = route.handler;
+				else if (Array.isArray(route.handler) && route.handler.length === 2) {
+					const [Controller, method] = route.handler;
+					if (typeof Controller === "function" && typeof Controller[method] === "function") handlerFunction = Controller[method].bind(Controller);
+					else if (typeof Controller === "function") {
+						const instance = new Controller();
+						if (typeof instance[method] === "function") handlerFunction = instance[method].bind(instance);
+						else throw new Error(`Method "${method}" not found in controller instance "${Controller.name}"`);
+					} else throw new Error(`Invalid controller type for route: ${route.path}`);
+				} else throw new Error(`Invalid handler format for route: ${route.path}`);
+			} catch (error) {
+				console.error(`[ROUTES] Error setting up route ${route.path}:`, error.message);
+				throw error;
+			}
+			if (!handlerFunction) continue;
+			for (const method of route.methods) {
+				if (![
+					"get",
+					"post",
+					"put",
+					"delete",
+					"patch",
+					"options",
+					"head"
+				].includes(method)) {
+					const error = /* @__PURE__ */ new Error(`Invalid HTTP method: ${method} for route: ${route.path}`);
+					console.error(`[ROUTES]`, error.message);
+					throw error;
+				}
+				router[method](route.path, ...route.middlewares || [], async (req, res, next) => {
+					try {
+						const result = handlerFunction({
+							req,
+							res,
+							next
+						});
+						await Promise.resolve(result);
+					} catch (error) {
+						next(error);
+					}
+				});
+			}
+		}
+	}
+};
+
+//#endregion
+module.exports = Routes;

package/dist/express/routes.d.cts

@@ -0,0 +1,158 @@
+import { i as RouteInfo, n as ControllerHandler, r as HttpMethod, t as ControllerAction } from "../basic-BCxhZ1Wd.cjs";
+import { NextFunction, Request, Response, Router } from "express";
+
+//#region types/express.d.ts
+/**
+ * HTTP context passed to route handlers
+ */
+interface HttpContext {
+  req: Request;
+  res: Response;
+  next: NextFunction;
+}
+/**
+ * Route handler function type
+ */
+type RouteHandler = (ctx: HttpContext) => any | Promise<any>;
+/**
+ * Handler can be either a function or controller reference
+ */
+type Handler = RouteHandler | ControllerHandler;
+/**
+ * Middleware function type
+ */
+type Middleware = (req: Request, res: Response, next: NextFunction) => any | Promise<any>;
+//#endregion
+//#region src/express/routes.d.ts
+/**
+ * @class clear-router
+ * @description Laravel-style routing system for Express.js and H3 with support for CommonJS, ESM, and TypeScript
+ * @author Refkinscallv
+ * @author 3m1n3nc3
+ * @repository https://github.com/toneflix/clear-router
+ */
+declare class Routes {
+  /**
+   * All registered routes
+   */
+  static routes: Array<{
+    methods: HttpMethod[];
+    path: string;
+    handler: Handler;
+    middlewares: Middleware[];
+  }>;
+  /**
+   * Current route prefix
+   */
+  static prefix: string;
+  /**
+   * Group-level middlewares
+   */
+  static groupMiddlewares: Middleware[];
+  /**
+   * Global-level middlewares
+   */
+  static globalMiddlewares: Middleware[];
+  /**
+   * Normalize path by removing duplicate slashes and ensuring leading slash
+   * @param path - Path to normalize
+   * @returns Normalized path
+   */
+  static normalizePath(path: string): string;
+  /**
+    * Add a route with specified HTTP methods, path, handler, and middlewares
+    * @param methods - HTTP method(s) for the route
+    * @param path - Route path
+    * @param handler - Route handler function or controller reference
+    * @param middlewares - Array of middleware functions
+    */
+  static add(methods: HttpMethod | HttpMethod[], path: string, handler: Handler, middlewares?: Middleware[]): void;
+  /**
+   * Register RESTful API resource routes for a controller with optional action filtering
+   *
+   * @param basePath - Base path for the resource
+   * @param controller - Controller object containing action methods
+   * @param options - Optional filtering options for actions
+   */
+  static apiResource(basePath: string, controller: any, options?: {
+    only?: ControllerAction[];
+    except?: ControllerAction[];
+  }): void;
+  /**
+   * Register a GET route
+   * @param path - Route path
+   * @param handler - Route handler
+   * @param middlewares - Middleware functions
+   */
+  static get(path: string, handler: Handler, middlewares?: Middleware[]): void;
+  /**
+   * Register a POST route
+   * @param path - Route path
+   * @param handler - Route handler
+   * @param middlewares - Middleware functions
+   */
+  static post(path: string, handler: Handler, middlewares?: Middleware[]): void;
+  /**
+   * Register a PUT route
+   * @param path - Route path
+   * @param handler - Route handler
+   * @param middlewares - Middleware functions
+   */
+  static put(path: string, handler: Handler, middlewares?: Middleware[]): void;
+  /**
+   * Register a DELETE route
+   * @param path - Route path
+   * @param handler - Route handler
+   * @param middlewares - Middleware functions
+   */
+  static delete(path: string, handler: Handler, middlewares?: Middleware[]): void;
+  /**
+   * Register a PATCH route
+   * @param path - Route path
+   * @param handler - Route handler
+   * @param middlewares - Middleware functions
+   */
+  static patch(path: string, handler: Handler, middlewares?: Middleware[]): void;
+  /**
+   * Register an OPTIONS route
+   * @param path - Route path
+   * @param handler - Route handler
+   * @param middlewares - Middleware functions
+   */
+  static options(path: string, handler: Handler, middlewares?: Middleware[]): void;
+  /**
+   * Register a HEAD route
+   * @param path - Route path
+   * @param handler - Route handler
+   * @param middlewares - Middleware functions
+   */
+  static head(path: string, handler: Handler, middlewares?: Middleware[]): void;
+  /**
+   * Group routes with a common prefix and middlewares
+   * @param prefix - URL prefix for grouped routes
+   * @param callback - Function containing route definitions
+   * @param middlewares - Middleware functions applied to all routes in group
+   */
+  static group(prefix: string, callback: () => void, middlewares?: Middleware[]): void;
+  /**
+   * Apply global middlewares for the duration of the callback
+   * @param middlewares - Middleware functions
+   * @param callback - Function containing route definitions
+   */
+  static middleware(middlewares: Middleware[], callback: () => void): void;
+  /**
+   * Get all registered routes with their information
+   * @returns Array of route information objects
+   */
+  static allRoutes(): RouteInfo[];
+  /**
+   * Apply all registered routes to the provided Express Router instance
+   * Handles controller-method binding and middleware application
+   * All errors are thrown to Express error handling middleware
+   *
+   * @param router - Express Router instance
+   */
+  static apply(router: Router): void;
+  static apply(router: Router): Promise<void>;
+}
+export = Routes;