clear-router 2.7.6 → 2.8.0

package/dist/{router-C6W-k6sS.cjs → core/router.cjs}

@@ -1,63 +1,11 @@
-const require_bindings = require('./bindings-CLsZjOEy.cjs');
+const require_Request = require('./Request.cjs');
+const require_Response = require('./Response.cjs');
+const require_bindings = require('./bindings.cjs');
+const require_ResourceRoutes = require('../ResourceRoutes.cjs');
+const require_Route = require('../Route.cjs');
 let node_async_hooks = require("node:async_hooks");
 let node_module = require("node:module");
 
-//#region src/Route.ts
-var Route = class {
-	ctx;
-	body = {};
-	query = {};
-	params = {};
-	clearRequest;
-	methods;
-	path;
-	registrationPaths;
-	parameters;
-	routeName;
-	handler;
-	middlewares;
-	controllerName;
-	actionName;
-	handlerType;
-	middlewareCount;
-	constructor(methods, path, handler, middlewares = [], options = {}) {
-		this.methods = methods;
-		this.path = path;
-		this.registrationPaths = options.registrationPaths || [path];
-		this.parameters = options.parameters || [];
-		this.handler = handler;
-		this.middlewares = middlewares;
-		this.handlerType = Array.isArray(handler) ? "controller" : "function";
-		this.middlewareCount = middlewares.length;
-		this.controllerName = Array.isArray(handler) ? handler[0]?.name : void 0;
-		this.actionName = Array.isArray(handler) ? handler[1] : typeof handler === "function" ? handler.constructor.name ?? handler.name : void 0;
-		this.onName = options.onName;
-	}
-	onName;
-	name(name) {
-		const previousName = this.routeName;
-		this.routeName = name;
-		this.onName?.(name, this, previousName);
-		return this;
-	}
-	toPath(params = {}) {
-		return this.path.replace(/\/?\{([^{}]+)\}/g, (segment, raw) => {
-			const optional = raw.endsWith("?");
-			const [rawName, rawField] = (optional ? raw.slice(0, -1) : raw).split(":", 2);
-			const name = rawName.trim();
-			const field = rawField?.trim();
-			const value = params[name];
-			const resolved = field && value && typeof value === "object" ? value[field] : value;
-			if (typeof resolved === "undefined" || resolved === null || resolved === "") {
-				if (optional) return "";
-				throw new Error(`Missing required route parameter: ${name}`);
-			}
-			return `${segment.startsWith("/") ? "/" : ""}${encodeURIComponent(String(resolved))}`;
-		}) || "/";
-	}
-};
-
-//#endregion
 //#region src/core/router.ts
 /**
 * @class clear-router CoreRouter
@@ -98,6 +46,51 @@ var CoreRouter = class {
 	static groupMiddlewares = [];
 	static globalMiddlewares = [];
 	/**
+	* Resolve middlewares before assigning to adapter
+	* 
+	* @param middleware 
+	* @returns 
+	*/
+	static resolveMiddleware(middleware) {
+		if (!middleware || typeof middleware === "function" && !require_bindings.isClass(middleware)) return middleware;
+		const instance = require_bindings.isClass(middleware) ? new middleware() : middleware;
+		if (instance && typeof instance.handle === "function") return instance.handle.bind(instance);
+		return middleware;
+	}
+	static resolveMiddlewares(middlewares = []) {
+		return middlewares.map((middleware) => this.resolveMiddleware(middleware));
+	}
+	static routeSpecificity(route) {
+		const path = route.registrationPaths.slice().sort((left, right) => right.length - left.length)[0] ?? route.path;
+		const segments = this.normalizePath(path).split("/").filter(Boolean);
+		return [
+			segments.filter((segment) => !segment.startsWith(":")).length,
+			segments.length,
+			path.length
+		];
+	}
+	static orderedRoutes() {
+		return Array.from(this.routes).sort((left, right) => {
+			const leftScore = this.routeSpecificity(left);
+			const rightScore = this.routeSpecificity(right);
+			for (let index = 0; index < leftScore.length; index++) {
+				const difference = rightScore[index] - leftScore[index];
+				if (difference !== 0) return difference;
+			}
+			return 0;
+		});
+	}
+	static removeRouteMethod(route, method, path) {
+		route.methods = route.methods.filter((existingMethod) => existingMethod !== method);
+		this.routesByPathMethod.delete(`${method.toUpperCase()} ${path}`);
+		const methodKey = method.toUpperCase();
+		this.routesByMethod.set(methodKey, (this.routesByMethod.get(methodKey) ?? []).filter((existingRoute) => existingRoute !== route));
+		if (!route.methods.some((existingMethod) => existingMethod !== "options")) {
+			this.routes.delete(route);
+			if (route.routeName && this.routesByName.get(route.routeName) === route) this.routesByName.delete(route.routeName);
+		}
+	}
+	/**
 	* Resets the router to it's default state
 	*/
 	static reset() {
@@ -509,17 +502,22 @@ var CoreRouter = class {
 		const fullPath = this.normalizePath(`${activePrefix}/${path}`);
 		const registrationPaths = this.routeRegistrationPaths(fullPath);
 		const parameters = this.parseRouteParameters(fullPath);
-		const route = new Route(methods.includes("options") ? methods : methods.concat("options"), fullPath, handler, [
+		for (const method of methods) {
+			const existing = this.routesByPathMethod.get(`${method.toUpperCase()} ${fullPath}`);
+			if (existing) this.removeRouteMethod(existing, method, fullPath);
+		}
+		const route = new require_Route.Route(methods.includes("options") ? methods : methods.concat("options"), fullPath, handler, this.resolveMiddlewares([
 			...this.globalMiddlewares,
 			...activeGroupMiddlewares,
 			...middlewares || []
-		], {
+		]), {
 			registrationPaths,
 			parameters,
 			onName: (name, route, previousName) => {
 				if (previousName && this.routesByName.get(previousName) === route) this.routesByName.delete(previousName);
 				this.routesByName.set(name, route);
-			}
+			},
+			normalizeMiddleware: (middleware) => this.resolveMiddleware(middleware)
 		});
 		if (!methods.includes("options") && !this.routesByPathMethod.get(`OPTIONS ${fullPath}`)) this.options(path, this.createDefaultOptionsHandler());
 		this.routes.add(route);
@@ -539,6 +537,7 @@ var CoreRouter = class {
 	* @param options 
 	*/
 	static apiResource(basePath, controller, options) {
+		const resourceRoutes = {};
 		let paramName = "id";
 		if (!!this.config.inferParamName && this.hasPackageInstalled("@h3ravel/support")) {
 			const { str } = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)("@h3ravel/support");
@@ -575,9 +574,10 @@ var CoreRouter = class {
 				const { method, path } = actions[action];
 				const actionMiddlewares = typeof options?.middlewares === "object" && !Array.isArray(options.middlewares) ? options.middlewares[action] : options?.middlewares;
 				const name = `${basePath}${path}`.replace(/\/:[^/]+|\/\{[^}]+\}/g, "").replace(/\{(\w+):[^}]+\}/g, "$1").replace(/\/|:|[{}]/g, ".").replace(/\.{2,}/g, ".").replace(/^\.|\.$/g, "");
-				this.add(method, `${basePath}${path}`, [controller, action], Array.isArray(actionMiddlewares) ? actionMiddlewares : actionMiddlewares ? [actionMiddlewares] : void 0).name(name + "." + action.toLowerCase());
+				resourceRoutes[action] = this.add(method, `${basePath}${path}`, [controller, action], Array.isArray(actionMiddlewares) ? actionMiddlewares : actionMiddlewares ? [actionMiddlewares] : void 0).name(name + "." + action.toLowerCase());
 			}
 		}
+		return new require_ResourceRoutes.ResourceRoutes(resourceRoutes);
 	}
 	/**
 	* Adds a new GET route to the router.
@@ -823,7 +823,7 @@ var CoreRouter = class {
 		});
 	}
 	static bindRequestToInstance(ctx, instance, route, payload) {
-		const clearRequest = ctx.clearRequest instanceof require_bindings.Request ? ctx.clearRequest : this.initializeInstance(require_bindings.Request, {
+		const clearRequest = ctx.clearRequest instanceof require_Request.Request ? ctx.clearRequest : this.initializeInstance(require_Request.Request, {
 			ctx,
 			route,
 			body: payload.body,
@@ -841,10 +841,10 @@ var CoreRouter = class {
 		clearRequest.query = payload.query;
 		clearRequest.params = payload.params;
 		ctx.clearRequest = clearRequest;
-		require_bindings.Container.bind(require_bindings.Request, ctx.clearRequest);
-		if (!(ctx.clearResponse instanceof require_bindings.Response)) {
-			ctx.clearResponse = this.initializeInstance(require_bindings.Response, ctx.response ?? ctx.reply ?? ctx.res);
-			require_bindings.Container.bind(require_bindings.Response, ctx.clearResponse);
+		require_bindings.Container.bind(require_Request.Request, ctx.clearRequest);
+		if (!(ctx.clearResponse instanceof require_Response.Response)) {
+			ctx.clearResponse = this.initializeInstance(require_Response.Response, ctx.response ?? ctx.reply ?? ctx.res);
+			require_bindings.Container.bind(require_Response.Response, ctx.clearResponse);
 		}
 		if (!instance) return;
 		instance.ctx = ctx;
@@ -856,9 +856,4 @@ var CoreRouter = class {
 };
 
 //#endregion
-Object.defineProperty(exports, 'CoreRouter', {
-  enumerable: true,
-  get: function () {
-    return CoreRouter;
-  }
-});
+exports.CoreRouter = CoreRouter;

package/dist/core/router.d.cts

@@ -0,0 +1,286 @@
+import { ApiResourceMiddleware, ControllerAction, HttpMethod, RouterConfig } from "../types/basic.cjs";
+import { Response } from "./Response.cjs";
+import { Route } from "../Route.cjs";
+import { Request } from "./Request.cjs";
+import { ClearRouterPluginArgumentsContext, ClearRouterPluginInput, ClearRouterPluginRequestContext, PluginArgumentsResolver, PluginBind } from "./plugins.cjs";
+import { Controller } from "../Controller.cjs";
+import { ResourceRoutes } from "../ResourceRoutes.cjs";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+//#region src/core/router.d.ts
+/**
+ * @class clear-router CoreRouter
+ * @description Core routing logic for clear-router, shared between all supported adapters (Express.js, H3, etc.)
+ * @author 3m1n3nc3
+ * @repository https://github.com/arkstack-tmp/clear-router
+ */
+declare abstract class CoreRouter {
+  protected static routerStateNamespace: string;
+  private static readonly stateStoreKey;
+  private static readonly stateBoundKey;
+  private static readonly defaultConfigKey;
+  private static readonly pluginStoreKey;
+  private static readonly pluginPendingKey;
+  private static readonly pluginHttpCtxResolversKey;
+  private static readonly pluginArgumentResolversKey;
+  private static requestProvider?;
+  private static responseProvider?;
+  static config: RouterConfig;
+  protected static groupContext: AsyncLocalStorage<{
+    prefix: string;
+    groupMiddlewares: any[];
+  }>;
+  protected static pluginRequestContext: AsyncLocalStorage<ClearRouterPluginRequestContext<any>>;
+  static routes: Set<Route<any, any, any>>;
+  static routesByPathMethod: Map<string, Route<any, any, any>>;
+  static routesByMethod: Map<"GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS" | "HEAD", Route<any, any, any>[]>;
+  static routesByName: Map<string, Route<any, any, any>>;
+  static prefix: string;
+  static groupMiddlewares: any[];
+  static globalMiddlewares: any[];
+  /**
+   * Resolve middlewares before assigning to adapter
+   *
+   * @param middleware
+   * @returns
+   */
+  protected static resolveMiddleware(middleware: any): any;
+  protected static resolveMiddlewares(middlewares?: any[]): any[];
+  protected static routeSpecificity(route: Route<any, any, any>): [number, number, number];
+  protected static orderedRoutes(): Array<Route<any, any, any>>;
+  protected static removeRouteMethod(route: Route<any, any, any>, method: HttpMethod, path: string): void;
+  /**
+   * Resets the router to it's default state
+   */
+  static reset(): typeof CoreRouter;
+  protected static createBaseConfig(): RouterConfig;
+  protected static mergeConfig(target: RouterConfig, source?: RouterConfig): RouterConfig;
+  protected static getDefaultConfig(): RouterConfig;
+  protected static resolveStateNamespace(): string;
+  protected static getStateStore(): Record<string, any>;
+  protected static getPluginStore(): Set<string>;
+  protected static getPluginPendingStore(): Set<Promise<void>>;
+  protected static getPluginArgumentResolvers(): Set<PluginArgumentsResolver>;
+  protected static getPluginHttpCtxResolvers(): Set<PluginArgumentsResolver>;
+  protected static createDefaultState(): {
+    config: RouterConfig;
+    groupContext: AsyncLocalStorage<{
+      prefix: string;
+      groupMiddlewares: any[];
+    }>;
+    routes: Set<never>;
+    routesByPathMethod: Map<any, any>;
+    routesByMethod: Map<any, any>;
+    routesByName: Map<any, any>;
+    prefix: string;
+    groupMiddlewares: any[];
+    globalMiddlewares: any[];
+  };
+  protected static bindStateAccessors(): void;
+  protected static createDefaultOptionsHandler(): any;
+  /**
+   * Default configuration used for everytime the router is reset
+   *
+   * @param options
+   */
+  static configureDefaults(options?: RouterConfig): void;
+  /**
+   * Use a registered plugin
+   *
+   * @param this
+   * @param plugin
+   * @param options
+   * @returns
+   */
+  static use<Options = any>(plugin: ClearRouterPluginInput<Options>, options?: Options): Promise<void>;
+  protected static pluginsReady(): Promise<void>;
+  protected static getCurrentPluginRequestContext(): ClearRouterPluginRequestContext | undefined;
+  protected static createPluginRequestContext(ctx: any): ClearRouterPluginRequestContext;
+  protected static createPluginBind(): PluginBind;
+  protected static resolvePluginArguments(ctx: any, routeContext: Omit<ClearRouterPluginArgumentsContext, keyof ClearRouterPluginRequestContext>): Promise<any[] | undefined>;
+  protected static resolvePluginHttpCtx(ctx: any): Promise<void>;
+  protected static ensureState(): void;
+  /**
+   * Normalizes a path by ensuring it starts with a single slash and does not have trailing
+   * slashes, while preserving dynamic segments and parameters.
+   *
+   * @param path  The path to normalize.
+   * @returns     The normalized path.
+   */
+  static normalizePath(path: string): string;
+  protected static parseRouteParameters(path: string): Array<{
+    name: string;
+    field?: string;
+    optional: boolean;
+  }>;
+  protected static expandRoutePath(path: string): string[];
+  protected static routeRegistrationPaths(path: string): string[];
+  /**
+   * Configures the router with the given options, such as method override settings.
+   *
+   * @param this
+   * @param options
+   * @returns
+   */
+  static configure(this: any, options?: RouterConfig): void;
+  protected static resolveMethodOverride(method: string, headers: Headers | Record<string, any>, body: unknown): HttpMethod | null;
+  /**
+   * Adds a new route to the router.
+   *
+   * @param this
+   * @param methods
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static add(methods: HttpMethod | HttpMethod[], path: string, handler: any, middlewares?: any[] | any): Route<any, any, any>;
+  /**
+   * Define a resourceful API controller with standard CRUD routes.
+   *
+   * @param this
+   * @param basePath
+   * @param controller
+   * @param options
+   */
+  static apiResource(basePath: string, controller: any, options?: {
+    only?: ControllerAction[];
+    except?: ControllerAction[];
+    middlewares?: ApiResourceMiddleware<any>;
+  }): ResourceRoutes<any, any, any>;
+  /**
+   * Adds a new GET route to the router.
+   *
+   * @param this          The router instance.
+   * @param path          The path for the GET route.
+   * @param handler       The handler function for the GET route.
+   * @param middlewares   Optional middlewares to apply to the GET route.
+   */
+  static get(path: string, handler: any, middlewares?: any[] | any): Route<any, any, any>;
+  /**
+   * Adds a new POST route to the router.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static post(path: string, handler: any, middlewares?: any[] | any): Route<any, any, any>;
+  /**
+   * Adds a new PUT route to the router.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static put(path: string, handler: any, middlewares?: any[] | any): Route<any, any, any>;
+  /**
+   * Adds a new DELETE route to the router.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static delete(path: string, handler: any, middlewares?: any[] | any): Route<any, any, any>;
+  /**
+   * Adds a new PATCH route to the router.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static patch(path: string, handler: any, middlewares?: any[] | any): Route<any, any, any>;
+  /**
+   * Adds a new OPTIONS route to the router.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static options(path: string, handler: any, middlewares?: any[] | any): Route<any, any, any>;
+  /**
+   * Adds a new HEAD route to the router.
+   *
+   * @param this
+   * @param path
+   * @param handler
+   * @param middlewares
+   */
+  static head(path: string, handler: any, middlewares?: any[] | any): Route<any, any, any>;
+  /**
+   * Defines a group of routes with a common prefix.
+   *
+   * @param this
+   * @param prefix
+   * @param callback
+   * @param middlewares
+   */
+  static group(prefix: string, callback: () => void | Promise<void>, middlewares?: any[]): Promise<void>;
+  /**
+   * Adds global middlewares to the router, which will be applied to all routes.
+   *
+   * @param this
+   * @param middlewares
+   * @param callback
+   */
+  static middleware(middlewares: any[], callback: () => void): void;
+  /**
+   * Retrieves all registered routes in the router, optionally organized by path or method
+   * for easier access and management.
+   *
+   * @param this
+   */
+  static allRoutes(): Array<Route<any, any, any>>;
+  /**
+   * @param this
+   * @param type  - 'path' to get routes organized by path
+   */
+  static allRoutes(type: 'path'): Record<string, Route<any, any, any>>;
+  /**
+   * @param this
+   * @param type  - 'method' to get routes organized by method
+   */
+  static allRoutes(type: 'method'): { [method in Uppercase<HttpMethod>]?: Array<Route<any, any, any>> };
+  static allRoutes(type: 'name'): Record<string, Route<any, any, any>>;
+  static route(name: string): Route<any, any, any> | undefined;
+  static url(name: string, params?: Record<string, any>): string | undefined;
+  /**
+   * Provide a class that will overide the base Request instance
+   *
+   * @param provider
+   */
+  static setRequestProvider(provider: typeof Request): void;
+  /**
+   * Provide a class that will overide the base Response instance
+   *
+   * @param provider
+   */
+  static setResponseProvider(provider: typeof Response): void;
+  private static hasPackageInstalled;
+  /**
+   * Provide a class that will overide the base Response instance
+   *
+   * @param provider
+   */
+  private static initializeInstance;
+  protected static resolveHandler(route: Route<any, any, any>): {
+    handlerFunction: ((ctx: any, req: Request) => any | Promise<any>) | null;
+    instance: Controller<any> | null;
+    bindingTarget?: object;
+    bindingMethod?: PropertyKey;
+    bindingHandler?: object;
+    bindingMetadata?: object;
+  };
+  protected static callHandler(handlerFunction: (ctx: any, req: Request) => any | Promise<any>, ctx: any, bindingTarget?: object, bindingMethod?: PropertyKey, bindingHandler?: object, bindingMetadata?: object): Promise<any>;
+  protected static bindRequestToInstance(ctx: any, instance: Controller<any> | Route<any, any, any> | null, route: Route<any, any, any>, payload: {
+    body: Record<string, any>;
+    query: Record<string, any>;
+    params: Record<string, any>;
+    method?: HttpMethod | string;
+  }): void;
+}
+//#endregion
+export { CoreRouter };