@buenojs/bueno 0.8.0

package/src/router/index.ts

@@ -0,0 +1,339 @@
+/**
+ * Router System with Auto-Selection
+ *
+ * Automatically selects the optimal router implementation based on route count:
+ * - LinearRouter: ≤10 routes (O(1) static, O(n) dynamic)
+ * - RegexRouter: 11-50 routes (compiled regex patterns)
+ * - TreeRouter: >50 routes (O(log n) radix tree)
+ *
+ * You can also explicitly choose a router type for specific use cases.
+ */
+
+import type {
+	HTTPMethod,
+	MiddlewareHandler,
+	PathParams,
+	RouteHandler,
+} from "../types";
+import { LinearRouter } from "./linear";
+import { RegexRouter } from "./regex";
+import { TreeRouter } from "./tree";
+
+// ============= Types =============
+
+export interface RouteMatch {
+	handler: RouteHandler;
+	params: PathParams;
+	middleware?: MiddlewareHandler[];
+	name?: string;
+}
+
+export interface RouteOptions {
+	name?: string;
+	middleware?: MiddlewareHandler | MiddlewareHandler[];
+}
+
+export type RouterType = "auto" | "linear" | "regex" | "tree";
+
+export interface RouterConfig {
+	type?: RouterType;
+	linearThreshold?: number;
+	regexThreshold?: number;
+}
+
+interface RouterLike {
+	match(method: HTTPMethod | "ALL", pathname: string): RouteMatch | undefined;
+	group(
+		prefix: string,
+		options?: { middleware?: MiddlewareHandler | MiddlewareHandler[] },
+	): RouterLike;
+	getRoutes(): Array<{
+		method: HTTPMethod | "ALL";
+		pattern: string;
+		name?: string;
+	}>;
+	getRouterType(): string;
+	get(pattern: string, handler: RouteHandler, options?: RouteOptions): void;
+	post(pattern: string, handler: RouteHandler, options?: RouteOptions): void;
+	put(pattern: string, handler: RouteHandler, options?: RouteOptions): void;
+	patch(pattern: string, handler: RouteHandler, options?: RouteOptions): void;
+	delete(pattern: string, handler: RouteHandler, options?: RouteOptions): void;
+	head(pattern: string, handler: RouteHandler, options?: RouteOptions): void;
+	options(pattern: string, handler: RouteHandler, options?: RouteOptions): void;
+	all(pattern: string, handler: RouteHandler, options?: RouteOptions): void;
+}
+
+// ============= Thresholds =============
+
+const DEFAULT_LINEAR_THRESHOLD = 10;
+const DEFAULT_REGEX_THRESHOLD = 50;
+
+// ============= AutoRouter Class =============
+
+export class Router {
+	private router: RouterLike;
+	private config: Required<RouterConfig>;
+	private pendingRoutes: Array<{
+		method: HTTPMethod | "ALL";
+		pattern: string;
+		handler: RouteHandler;
+		options?: RouteOptions;
+	}> = [];
+	private isBuilt = false;
+	private groupPrefix = "";
+	private groupMiddleware: MiddlewareHandler[] = [];
+
+	constructor(config: RouterConfig = {}) {
+		this.config = {
+			type: config.type ?? "auto",
+			linearThreshold: config.linearThreshold ?? DEFAULT_LINEAR_THRESHOLD,
+			regexThreshold: config.regexThreshold ?? DEFAULT_REGEX_THRESHOLD,
+		};
+
+		if (this.config.type !== "auto") {
+			this.router = this.createRouter(this.config.type);
+		} else {
+			this.router = new LinearRouter();
+		}
+	}
+
+	private createRouter(type: RouterType): RouterLike {
+		switch (type) {
+			case "linear":
+				return new LinearRouter();
+			case "regex":
+				return new RegexRouter();
+			case "tree":
+				return new TreeRouter();
+			default:
+				return new LinearRouter();
+		}
+	}
+
+	private getOptimalRouterType(count: number): "linear" | "regex" | "tree" {
+		if (count <= this.config.linearThreshold) {
+			return "linear";
+		}
+		if (count <= this.config.regexThreshold) {
+			return "regex";
+		}
+		return "tree";
+	}
+
+	private migrateRouter(newType: "linear" | "regex" | "tree"): void {
+		this.router = this.createRouter(newType);
+
+		for (const route of this.pendingRoutes) {
+			this.addToRouter(
+				route.method,
+				route.pattern,
+				route.handler,
+				route.options,
+			);
+		}
+	}
+
+	private addToRouter(
+		method: HTTPMethod | "ALL",
+		pattern: string,
+		handler: RouteHandler,
+		options?: RouteOptions,
+	): void {
+		switch (method) {
+			case "GET":
+				this.router.get(pattern, handler, options);
+				break;
+			case "POST":
+				this.router.post(pattern, handler, options);
+				break;
+			case "PUT":
+				this.router.put(pattern, handler, options);
+				break;
+			case "PATCH":
+				this.router.patch(pattern, handler, options);
+				break;
+			case "DELETE":
+				this.router.delete(pattern, handler, options);
+				break;
+			case "HEAD":
+				this.router.head(pattern, handler, options);
+				break;
+			case "OPTIONS":
+				this.router.options(pattern, handler, options);
+				break;
+			case "ALL":
+				this.router.all(pattern, handler, options);
+				break;
+		}
+	}
+
+	private addRoute(
+		method: HTTPMethod | "ALL",
+		pattern: string,
+		handler: RouteHandler,
+		options?: RouteOptions,
+	): void {
+		const fullPattern = this.groupPrefix + pattern;
+
+		const optsMiddleware = options?.middleware;
+		const routeMiddleware: MiddlewareHandler[] = optsMiddleware
+			? Array.isArray(optsMiddleware)
+				? optsMiddleware
+				: [optsMiddleware]
+			: [];
+
+		const allMiddleware = [...this.groupMiddleware, ...routeMiddleware];
+		const fullOptions: RouteOptions | undefined =
+			options?.name || allMiddleware.length > 0
+				? {
+						name: options?.name,
+						middleware: allMiddleware,
+					}
+				: undefined;
+
+		this.pendingRoutes.push({
+			method,
+			pattern: fullPattern,
+			handler,
+			options: fullOptions,
+		});
+
+		this.addToRouter(method, fullPattern, handler, fullOptions);
+
+		if (this.config.type === "auto" && !this.isBuilt) {
+			const routeCount = this.pendingRoutes.length;
+			const optimalType = this.getOptimalRouterType(routeCount);
+			const currentType = this.router.getRouterType();
+
+			if (currentType !== optimalType) {
+				this.migrateRouter(optimalType);
+			}
+		}
+	}
+
+	match(method: HTTPMethod | "ALL", pathname: string): RouteMatch | undefined {
+		this.isBuilt = true;
+		return this.router.match(method, pathname);
+	}
+
+	group(
+		prefix: string,
+		options?: { middleware?: MiddlewareHandler | MiddlewareHandler[] },
+	): Router {
+		const childRouter = new Router(this.config);
+
+		(childRouter as unknown as { router: RouterLike }).router = this.router;
+		childRouter.pendingRoutes = this.pendingRoutes;
+		childRouter.groupPrefix = this.groupPrefix + prefix;
+		childRouter.isBuilt = this.isBuilt;
+
+		const optsMiddleware = options?.middleware;
+		const middlewareArray: MiddlewareHandler[] = optsMiddleware
+			? Array.isArray(optsMiddleware)
+				? optsMiddleware
+				: [optsMiddleware]
+			: [];
+
+		childRouter.groupMiddleware = [...this.groupMiddleware, ...middlewareArray];
+
+		return childRouter;
+	}
+
+	getRoutes(): Array<{
+		method: HTTPMethod | "ALL";
+		pattern: string;
+		name?: string;
+	}> {
+		return this.router.getRoutes();
+	}
+
+	getRouterType(): string {
+		return this.router.getRouterType();
+	}
+
+	getRouteCount(): number {
+		return this.pendingRoutes.length;
+	}
+
+	getConfig(): Required<RouterConfig> {
+		return { ...this.config };
+	}
+
+	get(pattern: string, handler: RouteHandler, options?: RouteOptions): void {
+		this.addRoute("GET", pattern, handler, options);
+	}
+
+	post(pattern: string, handler: RouteHandler, options?: RouteOptions): void {
+		this.addRoute("POST", pattern, handler, options);
+	}
+
+	put(pattern: string, handler: RouteHandler, options?: RouteOptions): void {
+		this.addRoute("PUT", pattern, handler, options);
+	}
+
+	patch(pattern: string, handler: RouteHandler, options?: RouteOptions): void {
+		this.addRoute("PATCH", pattern, handler, options);
+	}
+
+	delete(pattern: string, handler: RouteHandler, options?: RouteOptions): void {
+		this.addRoute("DELETE", pattern, handler, options);
+	}
+
+	head(pattern: string, handler: RouteHandler, options?: RouteOptions): void {
+		this.addRoute("HEAD", pattern, handler, options);
+	}
+
+	options(
+		pattern: string,
+		handler: RouteHandler,
+		options?: RouteOptions,
+	): void {
+		this.addRoute("OPTIONS", pattern, handler, options);
+	}
+
+	all(pattern: string, handler: RouteHandler, options?: RouteOptions): void {
+		this.addRoute("ALL", pattern, handler, options);
+	}
+}
+
+// ============= Re-export Router Types =============
+
+export { LinearRouter } from "./linear";
+export { RegexRouter } from "./regex";
+export { TreeRouter } from "./tree";
+
+// ============= Utility: Route URL Generation =============
+
+export function generateUrl(pattern: string, params: PathParams = {}): string {
+	return pattern
+		.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)\?/g, (_, name) => params[name] ?? "")
+		.replace(
+			/:([a-zA-Z_][a-zA-Z0-9_]*)<[^>]+>/g,
+			(_, name) => params[name] ?? "",
+		)
+		.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, name) => {
+			if (params[name] === undefined) {
+				throw new Error(`Missing required parameter: ${name}`);
+			}
+			return params[name];
+		})
+		.replace(/\*/g, () => params["*"] ?? "");
+}
+
+// ============= Factory Functions =============
+
+export function createRouter(config?: RouterConfig): Router {
+	return new Router(config);
+}
+
+export function createLinearRouter(): LinearRouter {
+	return new LinearRouter();
+}
+
+export function createRegexRouter(): RegexRouter {
+	return new RegexRouter();
+}
+
+export function createTreeRouter(): TreeRouter {
+	return new TreeRouter();
+}

package/src/router/linear.ts

@@ -0,0 +1,371 @@
+/**
+ * LinearRouter
+ *
+ * Optimized for applications with ≤10 routes.
+ * - O(1) static route lookups via Map
+ * - Simple O(n) iteration for dynamic routes
+ * - Zero startup cost (no tree building)
+ *
+ * Best for: Microservices, development mode, small APIs
+ */
+
+import type {
+	HTTPMethod,
+	MiddlewareHandler,
+	PathParams,
+	RouteHandler,
+} from "../types";
+
+// ============= Types =============
+
+export interface RouteMatch {
+	handler: RouteHandler;
+	params: PathParams;
+	middleware?: MiddlewareHandler[];
+	name?: string;
+}
+
+interface DynamicRoute {
+	method: HTTPMethod | "ALL";
+	pattern: string;
+	handler: RouteHandler;
+	middleware?: MiddlewareHandler[];
+	name?: string;
+	regex: RegExp;
+	paramNames: string[];
+	priority: number;
+}
+
+export interface RouteOptions {
+	name?: string;
+	middleware?: MiddlewareHandler | MiddlewareHandler[];
+}
+
+type StaticRouteKey = `${HTTPMethod | "ALL"}:${string}`;
+
+// ============= Pattern Utilities =============
+
+function patternToRegex(pattern: string): {
+	regex: RegExp;
+	paramNames: string[];
+	isStatic: boolean;
+	hasWildcard: boolean;
+} {
+	const paramNames: string[] = [];
+	let isStatic = true;
+	let hasWildcard = false;
+
+	const segments: string[] = [];
+	let i = 0;
+
+	while (i < pattern.length) {
+		if (pattern[i] === ":") {
+			i++;
+
+			let name = "";
+			while (i < pattern.length && /[a-zA-Z0-9_]/.test(pattern[i])) {
+				name += pattern[i];
+				i++;
+			}
+
+			let optional = false;
+			if (i < pattern.length && pattern[i] === "?") {
+				optional = true;
+				i++;
+			}
+
+			let customRegex = "";
+			if (i < pattern.length && pattern[i] === "<") {
+				i++;
+				while (i < pattern.length && pattern[i] !== ">") {
+					customRegex += pattern[i];
+					i++;
+				}
+				i++;
+			}
+
+			paramNames.push(name);
+			isStatic = false;
+
+			if (optional) {
+				if (segments.length > 0 && segments[segments.length - 1] === "/") {
+					segments.pop();
+				}
+				segments.push("(?:/([^/]*))?");
+			} else if (customRegex) {
+				segments.push(`(${customRegex})`);
+			} else {
+				segments.push("([^/]+)");
+			}
+		} else if (pattern[i] === "*") {
+			hasWildcard = true;
+			isStatic = false;
+			paramNames.push("*");
+			segments.push("(.*)");
+			i++;
+		} else {
+			const char = pattern[i];
+			if (/[.+^${}()|[\]\\]/.test(char)) {
+				segments.push(`\\${char}`);
+			} else {
+				segments.push(char);
+			}
+			i++;
+		}
+	}
+
+	const regexStr = `^${segments.join("")}/?$`;
+
+	return {
+		regex: new RegExp(regexStr, "i"),
+		paramNames,
+		isStatic,
+		hasWildcard,
+	};
+}
+
+function extractParams(
+	regex: RegExp,
+	paramNames: string[],
+	pathname: string,
+): PathParams {
+	const params: PathParams = {};
+	const match = pathname.match(regex);
+
+	if (match) {
+		paramNames.forEach((name, index) => {
+			if (match[index + 1] !== undefined) {
+				params[name] = match[index + 1];
+			}
+		});
+	}
+
+	return params;
+}
+
+// ============= LinearRouter Class =============
+
+export class LinearRouter {
+	private staticRoutes: Map<
+		StaticRouteKey,
+		{
+			handler: RouteHandler;
+			middleware?: MiddlewareHandler[];
+			name?: string;
+		}
+	> = new Map();
+
+	private dynamicRoutes: DynamicRoute[] = [];
+
+	private groupPrefix = "";
+	private groupMiddleware: MiddlewareHandler[] = [];
+	private routeCounter = 0;
+
+	private addRoute(
+		method: HTTPMethod | "ALL",
+		pattern: string,
+		handler: RouteHandler,
+		options?: RouteOptions,
+	): void {
+		const fullPattern = this.groupPrefix + pattern;
+		const { regex, paramNames, isStatic } = patternToRegex(fullPattern);
+
+		const optsMiddleware = options?.middleware;
+		const routeMiddleware: MiddlewareHandler[] = optsMiddleware
+			? Array.isArray(optsMiddleware)
+				? optsMiddleware
+				: [optsMiddleware]
+			: [];
+
+		const middleware = [...this.groupMiddleware, ...routeMiddleware];
+
+		if (isStatic) {
+			const normalizedPath = fullPattern.toLowerCase();
+			const key: StaticRouteKey = `${method}:${normalizedPath}`;
+
+			this.staticRoutes.set(key, { handler, middleware, name: options?.name });
+
+			if (!normalizedPath.endsWith("/")) {
+				this.staticRoutes.set(`${method}:${normalizedPath}/`, {
+					handler,
+					middleware,
+					name: options?.name,
+				});
+			} else if (normalizedPath.length > 1) {
+				this.staticRoutes.set(`${method}:${normalizedPath.slice(0, -1)}`, {
+					handler,
+					middleware,
+					name: options?.name,
+				});
+			}
+		} else {
+			this.dynamicRoutes.push({
+				method,
+				pattern: fullPattern,
+				handler,
+				middleware,
+				name: options?.name,
+				regex,
+				paramNames,
+				priority: this.routeCounter++,
+			});
+
+			this.sortDynamicRoutes();
+		}
+	}
+
+	private sortDynamicRoutes(): void {
+		this.dynamicRoutes.sort((a, b) => {
+			if (a.paramNames.length !== b.paramNames.length) {
+				return a.paramNames.length - b.paramNames.length;
+			}
+			return a.priority - b.priority;
+		});
+	}
+
+	match(method: HTTPMethod | "ALL", pathname: string): RouteMatch | undefined {
+		const normalizedPath = pathname.toLowerCase();
+
+		const staticKey: StaticRouteKey = `${method}:${normalizedPath}`;
+		const staticRoute = this.staticRoutes.get(staticKey);
+
+		if (staticRoute) {
+			return {
+				handler: staticRoute.handler,
+				params: {},
+				middleware: staticRoute.middleware,
+				name: staticRoute.name,
+			};
+		}
+
+		const allKey: StaticRouteKey = `ALL:${normalizedPath}`;
+		const allRoute = this.staticRoutes.get(allKey);
+
+		if (allRoute) {
+			return {
+				handler: allRoute.handler,
+				params: {},
+				middleware: allRoute.middleware,
+				name: allRoute.name,
+			};
+		}
+
+		for (const route of this.dynamicRoutes) {
+			if (route.method !== "ALL" && route.method !== method) {
+				continue;
+			}
+
+			if (route.regex.test(pathname)) {
+				const params = extractParams(route.regex, route.paramNames, pathname);
+				return {
+					handler: route.handler,
+					params,
+					middleware: route.middleware,
+					name: route.name,
+				};
+			}
+		}
+
+		return undefined;
+	}
+
+	group(
+		prefix: string,
+		options?: { middleware?: MiddlewareHandler | MiddlewareHandler[] },
+	): LinearRouter {
+		const childRouter = new LinearRouter();
+
+		childRouter.staticRoutes = this.staticRoutes;
+		childRouter.dynamicRoutes = this.dynamicRoutes;
+		childRouter.groupPrefix = this.groupPrefix + prefix;
+
+		const optsMiddleware = options?.middleware;
+		const middlewareArray: MiddlewareHandler[] = optsMiddleware
+			? Array.isArray(optsMiddleware)
+				? optsMiddleware
+				: [optsMiddleware]
+			: [];
+
+		childRouter.groupMiddleware = [...this.groupMiddleware, ...middlewareArray];
+		childRouter.routeCounter = this.routeCounter;
+
+		return childRouter;
+	}
+
+	getRoutes(): Array<{
+		method: HTTPMethod | "ALL";
+		pattern: string;
+		name?: string;
+	}> {
+		const routes: Array<{
+			method: HTTPMethod | "ALL";
+			pattern: string;
+			name?: string;
+		}> = [];
+		const seenPatterns = new Set<string>();
+
+		for (const [key, value] of this.staticRoutes) {
+			const [method, path] = key.split(":") as [HTTPMethod | "ALL", string];
+			const pattern =
+				path.endsWith("/") && path.length > 1 ? path.slice(0, -1) : path;
+			const dedupeKey = `${method}:${pattern}`;
+
+			if (!seenPatterns.has(dedupeKey)) {
+				seenPatterns.add(dedupeKey);
+				routes.push({ method, pattern: pattern || "/", name: value.name });
+			}
+		}
+
+		for (const route of this.dynamicRoutes) {
+			routes.push({
+				method: route.method,
+				pattern: route.pattern,
+				name: route.name,
+			});
+		}
+
+		return routes;
+	}
+
+	getRouterType(): "linear" {
+		return "linear";
+	}
+
+	getRouteCount(): { static: number; dynamic: number; total: number } {
+		const staticCount = Math.floor(this.staticRoutes.size / 2);
+		return {
+			static: staticCount,
+			dynamic: this.dynamicRoutes.length,
+			total: staticCount + this.dynamicRoutes.length,
+		};
+	}
+
+	get(pattern: string, handler: RouteHandler, options?: RouteOptions): void {
+		this.addRoute("GET", pattern, handler, options);
+	}
+	post(pattern: string, handler: RouteHandler, options?: RouteOptions): void {
+		this.addRoute("POST", pattern, handler, options);
+	}
+	put(pattern: string, handler: RouteHandler, options?: RouteOptions): void {
+		this.addRoute("PUT", pattern, handler, options);
+	}
+	patch(pattern: string, handler: RouteHandler, options?: RouteOptions): void {
+		this.addRoute("PATCH", pattern, handler, options);
+	}
+	delete(pattern: string, handler: RouteHandler, options?: RouteOptions): void {
+		this.addRoute("DELETE", pattern, handler, options);
+	}
+	head(pattern: string, handler: RouteHandler, options?: RouteOptions): void {
+		this.addRoute("HEAD", pattern, handler, options);
+	}
+	options(
+		pattern: string,
+		handler: RouteHandler,
+		options?: RouteOptions,
+	): void {
+		this.addRoute("OPTIONS", pattern, handler, options);
+	}
+	all(pattern: string, handler: RouteHandler, options?: RouteOptions): void {
+		this.addRoute("ALL", pattern, handler, options);
+	}
+}