clear-router 2.2.0 → 2.3.1

package/README.md

@@ -6,7 +6,7 @@
 [![Publish to NPM](https://github.com/arkstack-hq/clear-router/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/arkstack-hq/clear-router/actions/workflows/npm-publish.yml)
 [![Run Tests](https://github.com/arkstack-hq/clear-router/actions/workflows/ci.yml/badge.svg)](https://github.com/arkstack-hq/clear-router/actions/workflows/ci.yml)
 
-Laravel-style routing system for H3 and Express.js, with clean route definitions, middleware support, controller bindings and full TypeScript support.
+Laravel-style routing for Node.js with support for Express, H3, Fastify, and Hono, including CommonJS, ESM, and TypeScript support.
 
 ## Installation
 
@@ -51,20 +51,30 @@ yarn add clear-router express
 - `clearRequest` is passed as second handler argument for controller handlers
 - Auto-binds controller methods
 - Full CommonJS, ESM, and TypeScript support
-- Error handling delegated to Express | H3
+- Error handling delegated to Express | H3 | Fastify | Hono
 - Route inspection with the `allRoutes` method
 - Fully Express-compatible
 - Fully H3-compatible
+- Fully Fastify-compatible
+- Fully Hono-compatible
 
 ## Quick Start
 
 ### Express JS
 
-See the [Express JS documentation](https://arkstack-hq.github.io/clear-router/express) for details.
+See the [Express JS documentation](https://arkstack-hq.github.io/clear-router/guide/express) for details.
 
 ### H3
 
-See the [H3 documentation](https://arkstack-hq.github.io/clear-router/h3) for details.
+See the [H3 documentation](https://arkstack-hq.github.io/clear-router/guide/h3) for details.
+
+### Fastify
+
+See the [Fastify documentation](https://arkstack-hq.github.io/clear-router/guide/fastify) for details.
+
+### Hono
+
+See the [Hono documentation](https://arkstack-hq.github.io/clear-router/guide/hono) for details.
 
 ## API Reference
 
@@ -92,7 +102,7 @@ npm run test:esm      # Test ESM
 npm run test:ts       # Test TypeScript
 ```
 
-See [TESTING.md](https://arkstack-hq.github.io/clear-router/TESTING.md) for a detailed testing guide.
+See [TESTING.md](https://arkstack-hq.github.io/clear-router/testing) for a detailed testing guide.
 
 ## Examples
 

package/dist/core/index.cjs

@@ -1,4 +1,4 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_router = require('../router-BNVIrTi3.cjs');
+const require_router = require('../router-Ba2MVNn-.cjs');
 
 exports.CoreRouter = require_router.CoreRouter;

package/dist/core/index.d.cts

@@ -1,2 +1,2 @@
-import { t as CoreRouter } from "../router-CZIh1ZPJ.cjs";
+import { t as CoreRouter } from "../router-DLmimm_U.cjs";
 export { CoreRouter };

package/dist/core/index.d.mts

@@ -1,2 +1,2 @@
-import { t as CoreRouter } from "../router-C1jVRytA.mjs";
+import { t as CoreRouter } from "../router-cWYmcfTX.mjs";
 export { CoreRouter };

package/dist/core/index.mjs

@@ -1,3 +1,3 @@
-import { t as CoreRouter } from "../router-BiCuy5TZ.mjs";
+import { t as CoreRouter } from "../router-Bug2IE_u.mjs";
 
 export { CoreRouter };

package/dist/express/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_router = require('../router-BNVIrTi3.cjs');
+const require_router = require('../router-Ba2MVNn-.cjs');
 
 //#region src/express/router.ts
 /**

package/dist/express/index.d.cts

@@ -1,4 +1,4 @@
-import { a as Handler, c as Route, i as HttpMethod, n as ApiResourceMiddleware, o as HttpContext, r as ControllerAction, s as Middleware, t as CoreRouter } from "../router-CZIh1ZPJ.cjs";
+import { c as Handler, d as ApiResourceMiddleware, f as ControllerAction, l as HttpContext, m as HttpMethod, r as Route, t as CoreRouter, u as Middleware } from "../router-DLmimm_U.cjs";
 import { Router as Router$1 } from "express";
 
 //#region src/express/router.d.ts

package/dist/express/index.d.mts

@@ -1,4 +1,4 @@
-import { a as Handler, c as Route, i as HttpMethod, n as ApiResourceMiddleware, o as HttpContext, r as ControllerAction, s as Middleware, t as CoreRouter } from "../router-C1jVRytA.mjs";
+import { c as Handler, d as ApiResourceMiddleware, f as ControllerAction, l as HttpContext, m as HttpMethod, r as Route, t as CoreRouter, u as Middleware } from "../router-cWYmcfTX.mjs";
 import { Router as Router$1 } from "express";
 
 //#region src/express/router.d.ts

package/dist/express/index.mjs

@@ -1,4 +1,4 @@
-import { t as CoreRouter } from "../router-BiCuy5TZ.mjs";
+import { t as CoreRouter } from "../router-Bug2IE_u.mjs";
 
 //#region src/express/router.ts
 /**

package/dist/fastify/index.cjs

@@ -0,0 +1,213 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_router = require('../router-Ba2MVNn-.cjs');
+
+//#region src/fastify/router.ts
+/**
+* @class clear-router Fastify Router
+* @description Laravel-style routing system for Fastify using shared clear-router core
+* @author 3m1n3nc3
+* @repository https://github.com/toneflix/clear-router
+*/
+var Router = class Router extends require_router.CoreRouter {
+	static ensureRequestBodyAccessor(req) {
+		if (typeof req.getBody !== "function") req.getBody = () => req.body ?? {};
+	}
+	/**
+	* Add a route to the router
+	* 
+	* @param methods       HTTP methods for the route
+	* @param path          Route path
+	* @param handler       Route handler function
+	* @param middlewares   Optional middlewares for the route
+	*/
+	static add(methods, path, handler, middlewares) {
+		super.add(methods, path, handler, middlewares);
+	}
+	/**
+	* Define a resourceful API controller with standard CRUD routes
+	* 
+	* @param basePath     Base path for the resource
+	* @param controller   Controller class or instance
+	* @param options      Optional configuration for the resource
+	*/
+	static apiResource(basePath, controller, options) {
+		super.apiResource(basePath, controller, options);
+	}
+	/**
+	* Define a GET route
+	* 
+	* @param path 
+	* @param handler 
+	* @param middlewares 
+	*/
+	static get(path, handler, middlewares) {
+		super.get(path, handler, middlewares);
+	}
+	/**
+	* Define a POST route
+	* 
+	* @param path 
+	* @param handler 
+	* @param middlewares 
+	*/
+	static post(path, handler, middlewares) {
+		super.post(path, handler, middlewares);
+	}
+	/**
+	* Define a PUT route
+	* 
+	* @param path 
+	* @param handler 
+	* @param middlewares 
+	*/
+	static put(path, handler, middlewares) {
+		super.put(path, handler, middlewares);
+	}
+	/**
+	* Define a DELETE route
+	* 
+	* @param path 
+	* @param handler 
+	* @param middlewares 
+	*/
+	static delete(path, handler, middlewares) {
+		super.delete(path, handler, middlewares);
+	}
+	/**
+	* Define a PATCH route
+	* 
+	* @param path 
+	* @param handler 
+	* @param middlewares 
+	*/
+	static patch(path, handler, middlewares) {
+		super.patch(path, handler, middlewares);
+	}
+	/**
+	* Define an OPTIONS route
+	* 
+	* @param path 
+	* @param handler 
+	* @param middlewares 
+	*/
+	static options(path, handler, middlewares) {
+		super.options(path, handler, middlewares);
+	}
+	/**
+	* Define a HEAD route
+	* 
+	* @param path 
+	* @param handler 
+	* @param middlewares 
+	*/
+	static head(path, handler, middlewares) {
+		super.head(path, handler, middlewares);
+	}
+	/**
+	* Define a group of routes with a common prefix and optional middlewares
+	* 
+	* @param prefix 
+	* @param callback 
+	* @param middlewares 
+	*/
+	static async group(prefix, callback, middlewares) {
+		await super.group(prefix, callback, middlewares);
+	}
+	/**
+	* Apply middlewares to a group of routes defined within the callback
+	* 
+	* @param middlewares 
+	* @param callback 
+	*/
+	static middleware(middlewares, callback) {
+		super.middleware(middlewares, callback);
+	}
+	static allRoutes(type) {
+		return super.allRoutes(type);
+	}
+	/**
+	* Apply the defined routes to a Fastify application instance
+	* 
+	* @param app  - The Fastify application instance
+	* @returns    The Fastify application instance with the applied routes
+	*/
+	static apply(app) {
+		for (const route of this.routes) {
+			let handlerFunction = null;
+			let instance = null;
+			try {
+				const resolved = this.resolveHandler(route);
+				handlerFunction = resolved.handlerFunction;
+				instance = resolved.instance;
+			} catch (error) {
+				console.error(`[ROUTES] Error setting up route ${route.path}:`, error.message);
+				throw error;
+			}
+			if (!handlerFunction) continue;
+			for (const method of route.methods) {
+				const allowedMethods = [
+					"get",
+					"post",
+					"put",
+					"delete",
+					"patch",
+					"options",
+					"head"
+				];
+				if (method === "options" && route.methods.length > 1) continue;
+				if (!allowedMethods.includes(method)) throw new Error(`Invalid HTTP method: ${method} for route: ${route.path}`);
+				app.route({
+					method: method.toUpperCase(),
+					url: route.path,
+					preHandler: route.middlewares,
+					handler: async (req, reply) => {
+						Router.ensureRequestBodyAccessor(req);
+						const override = Router.resolveMethodOverride(req.method, req.headers, req.body);
+						if (method === "post" && override && override !== "post") return reply.code(404).send();
+						const ctx = {
+							req,
+							reply
+						};
+						const inst = instance ?? route;
+						Router.bindRequestToInstance(ctx, inst, route, {
+							body: ctx.req.getBody(),
+							query: ctx.req.query ?? {},
+							params: ctx.req.params ?? {}
+						});
+						const result = handlerFunction(ctx, inst.clearRequest);
+						return await Promise.resolve(result);
+					}
+				});
+				if ([
+					"put",
+					"patch",
+					"delete"
+				].includes(method)) app.route({
+					method: "POST",
+					url: route.path,
+					preHandler: route.middlewares,
+					handler: async (req, reply) => {
+						Router.ensureRequestBodyAccessor(req);
+						if (Router.resolveMethodOverride(req.method, req.headers, req.body) !== method) return reply.code(404).send();
+						const ctx = {
+							req,
+							reply
+						};
+						const inst = instance ?? route;
+						Router.bindRequestToInstance(ctx, inst, route, {
+							body: ctx.req.getBody(),
+							query: ctx.req.query ?? {},
+							params: ctx.req.params ?? {}
+						});
+						const result = handlerFunction(ctx, inst.clearRequest);
+						return await Promise.resolve(result);
+					}
+				});
+			}
+		}
+		return app;
+	}
+};
+
+//#endregion
+exports.Router = Router;

package/dist/fastify/index.d.cts

@@ -0,0 +1,137 @@
+import { d as ApiResourceMiddleware, f as ControllerAction, m as HttpMethod, n as ClearRequest, p as ControllerHandler, r as Route, t as CoreRouter } from "../router-DLmimm_U.cjs";
+import { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+
+//#region types/fastify.d.ts
+interface RequestWithGetBody extends FastifyRequest {
+  getBody: () => Record<string, any>;
+}
+interface HttpContext {
+  req: RequestWithGetBody;
+  reply: FastifyReply;
+}
+type RouteHandler = (ctx: HttpContext, req: ClearRequest) => any | Promise<any>;
+type Handler = RouteHandler | ControllerHandler;
+type NextFunction = (err?: Error) => void;
+type Middleware = (req: RequestWithGetBody, reply: FastifyReply, next: NextFunction) => any | Promise<any>;
+type FastifyApp = FastifyInstance;
+//#endregion
+//#region src/fastify/router.d.ts
+/**
+ * @class clear-router Fastify Router
+ * @description Laravel-style routing system for Fastify using shared clear-router core
+ * @author 3m1n3nc3
+ * @repository https://github.com/toneflix/clear-router
+ */
+declare class Router extends CoreRouter {
+  private static ensureRequestBodyAccessor;
+  /**
+   * Add a route to the router
+   *
+   * @param methods       HTTP methods for the route
+   * @param path          Route path
+   * @param handler       Route handler function
+   * @param middlewares   Optional middlewares for the route
+   */
+  static add(methods: HttpMethod | HttpMethod[], path: string, handler: Handler, middlewares?: Middleware[] | Middleware): void;
+  /**
+   * Define a resourceful API controller with standard CRUD routes
+   *
+   * @param basePath     Base path for the resource
+   * @param controller   Controller class or instance
+   * @param options      Optional configuration for the resource
+   */
+  static apiResource(basePath: string, controller: any, options?: {
+    only?: ControllerAction[];
+    except?: ControllerAction[];
+    middlewares?: ApiResourceMiddleware<Middleware>;
+  }): void;
+  /**
+   * Define a GET route
+   *
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static get(path: string, handler: Handler, middlewares?: Middleware[] | Middleware): void;
+  /**
+   * Define a POST route
+   *
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static post(path: string, handler: Handler, middlewares?: Middleware[] | Middleware): void;
+  /**
+   * Define a PUT route
+   *
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static put(path: string, handler: Handler, middlewares?: Middleware[] | Middleware): void;
+  /**
+   * Define a DELETE route
+   *
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static delete(path: string, handler: Handler, middlewares?: Middleware[] | Middleware): void;
+  /**
+   * Define a PATCH route
+   *
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static patch(path: string, handler: Handler, middlewares?: Middleware[] | Middleware): void;
+  /**
+   * Define an OPTIONS route
+   *
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static options(path: string, handler: Handler, middlewares?: Middleware[] | Middleware): void;
+  /**
+   * Define a HEAD route
+   *
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static head(path: string, handler: Handler, middlewares?: Middleware[] | Middleware): void;
+  /**
+   * Define a group of routes with a common prefix and optional middlewares
+   *
+   * @param prefix
+   * @param callback
+   * @param middlewares
+   */
+  static group(prefix: string, callback: () => void | Promise<void>, middlewares?: Middleware[]): Promise<void>;
+  /**
+   * Apply middlewares to a group of routes defined within the callback
+   *
+   * @param middlewares
+   * @param callback
+   */
+  static middleware(middlewares: Middleware[], callback: () => void): void;
+  static allRoutes(): Array<Route<HttpContext, Middleware, Handler>>;
+  /**
+   * @param type  - 'path' to get routes organized by path
+   */
+  static allRoutes(type: 'path'): Record<string, Route<HttpContext, Middleware, Handler>>;
+  /**
+   * @param type  - 'method' to get routes organized by method
+   */
+  static allRoutes(type: 'method'): { [method in Uppercase<HttpMethod>]?: Array<Route<HttpContext, Middleware, Handler>> };
+  /**
+   * Apply the defined routes to a Fastify application instance
+   *
+   * @param app  - The Fastify application instance
+   * @returns    The Fastify application instance with the applied routes
+   */
+  static apply(app: FastifyApp): FastifyApp;
+}
+//#endregion
+export { Router };

package/dist/fastify/index.d.mts

@@ -0,0 +1,137 @@
+import { d as ApiResourceMiddleware, f as ControllerAction, m as HttpMethod, n as ClearRequest, p as ControllerHandler, r as Route, t as CoreRouter } from "../router-cWYmcfTX.mjs";
+import { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+
+//#region types/fastify.d.ts
+interface RequestWithGetBody extends FastifyRequest {
+  getBody: () => Record<string, any>;
+}
+interface HttpContext {
+  req: RequestWithGetBody;
+  reply: FastifyReply;
+}
+type RouteHandler = (ctx: HttpContext, req: ClearRequest) => any | Promise<any>;
+type Handler = RouteHandler | ControllerHandler;
+type NextFunction = (err?: Error) => void;
+type Middleware = (req: RequestWithGetBody, reply: FastifyReply, next: NextFunction) => any | Promise<any>;
+type FastifyApp = FastifyInstance;
+//#endregion
+//#region src/fastify/router.d.ts
+/**
+ * @class clear-router Fastify Router
+ * @description Laravel-style routing system for Fastify using shared clear-router core
+ * @author 3m1n3nc3
+ * @repository https://github.com/toneflix/clear-router
+ */
+declare class Router extends CoreRouter {
+  private static ensureRequestBodyAccessor;
+  /**
+   * Add a route to the router
+   *
+   * @param methods       HTTP methods for the route
+   * @param path          Route path
+   * @param handler       Route handler function
+   * @param middlewares   Optional middlewares for the route
+   */
+  static add(methods: HttpMethod | HttpMethod[], path: string, handler: Handler, middlewares?: Middleware[] | Middleware): void;
+  /**
+   * Define a resourceful API controller with standard CRUD routes
+   *
+   * @param basePath     Base path for the resource
+   * @param controller   Controller class or instance
+   * @param options      Optional configuration for the resource
+   */
+  static apiResource(basePath: string, controller: any, options?: {
+    only?: ControllerAction[];
+    except?: ControllerAction[];
+    middlewares?: ApiResourceMiddleware<Middleware>;
+  }): void;
+  /**
+   * Define a GET route
+   *
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static get(path: string, handler: Handler, middlewares?: Middleware[] | Middleware): void;
+  /**
+   * Define a POST route
+   *
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static post(path: string, handler: Handler, middlewares?: Middleware[] | Middleware): void;
+  /**
+   * Define a PUT route
+   *
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static put(path: string, handler: Handler, middlewares?: Middleware[] | Middleware): void;
+  /**
+   * Define a DELETE route
+   *
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static delete(path: string, handler: Handler, middlewares?: Middleware[] | Middleware): void;
+  /**
+   * Define a PATCH route
+   *
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static patch(path: string, handler: Handler, middlewares?: Middleware[] | Middleware): void;
+  /**
+   * Define an OPTIONS route
+   *
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static options(path: string, handler: Handler, middlewares?: Middleware[] | Middleware): void;
+  /**
+   * Define a HEAD route
+   *
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static head(path: string, handler: Handler, middlewares?: Middleware[] | Middleware): void;
+  /**
+   * Define a group of routes with a common prefix and optional middlewares
+   *
+   * @param prefix
+   * @param callback
+   * @param middlewares
+   */
+  static group(prefix: string, callback: () => void | Promise<void>, middlewares?: Middleware[]): Promise<void>;
+  /**
+   * Apply middlewares to a group of routes defined within the callback
+   *
+   * @param middlewares
+   * @param callback
+   */
+  static middleware(middlewares: Middleware[], callback: () => void): void;
+  static allRoutes(): Array<Route<HttpContext, Middleware, Handler>>;
+  /**
+   * @param type  - 'path' to get routes organized by path
+   */
+  static allRoutes(type: 'path'): Record<string, Route<HttpContext, Middleware, Handler>>;
+  /**
+   * @param type  - 'method' to get routes organized by method
+   */
+  static allRoutes(type: 'method'): { [method in Uppercase<HttpMethod>]?: Array<Route<HttpContext, Middleware, Handler>> };
+  /**
+   * Apply the defined routes to a Fastify application instance
+   *
+   * @param app  - The Fastify application instance
+   * @returns    The Fastify application instance with the applied routes
+   */
+  static apply(app: FastifyApp): FastifyApp;
+}
+//#endregion
+export { Router };