clear-router 2.8.9 → 2.9.0

package/dist/core/CoreRouter.d.mts

@@ -6,6 +6,7 @@ import { ClearRouterPluginArgumentsContext, ClearRouterPluginInput, ClearRouterP
 import { Controller } from "../Controller.mjs";
 import { ResourceRoutes } from "../ResourceRoutes.mjs";
 import { RouteGroup } from "../RouteGroup.mjs";
+import { RouteRegistrar } from "../RouteRegistrar.mjs";
 import { AsyncLocalStorage } from "node:async_hooks";
 
 //#region src/core/CoreRouter.d.ts
@@ -26,6 +27,9 @@ declare abstract class CoreRouter {
   private static readonly pluginArgumentResolversKey;
   private static requestProvider?;
   private static responseProvider?;
+  private static readonly domainMatcherCache;
+  private static readonly constraintRegexCache;
+  static routePatterns: Map<string, string | RegExp>;
   static config: RouterConfig;
   protected static groupContext: AsyncLocalStorage<RouteGroupContext>;
   protected static pluginRequestContext: AsyncLocalStorage<ClearRouterPluginRequestContext<any>>;
@@ -111,6 +115,149 @@ declare abstract class CoreRouter {
   }>;
   protected static expandRoutePath(path: string): string[];
   protected static routeRegistrationPaths(path: string): string[];
+  /**
+   * Compile a host pattern such as `{account}.example.com` into a matcher and
+   * the ordered list of placeholder names it captures. Results are memoized.
+   *
+   * @param pattern
+   * @returns
+   */
+  protected static compileDomain(pattern: string): {
+    regex: RegExp;
+    params: string[];
+  };
+  /**
+   * Match a host against a domain pattern, returning the captured parameters or
+   * `null` when the host does not match.
+   *
+   * @param pattern
+   * @param host
+   * @returns
+   */
+  static matchDomain(pattern: string, host?: string | null): Record<string, string> | null;
+  /**
+   * Best-effort extraction of the request host across every supported adapter
+   * context shape (Express/Fastify plain headers, H3 `Headers`, Hono accessor,
+   * Koa context).
+   *
+   * @param ctx
+   * @returns
+   */
+  protected static extractHost(ctx: any): string;
+  /**
+   * Resolve the domain parameters for a route given the active request context.
+   * Returns `null` when the route is not domain-constrained, `false` when it is
+   * but the host does not match, or the captured parameters on a match.
+   *
+   * @param route
+   * @param ctx
+   * @returns
+   */
+  protected static matchRouteDomain(route: Route<any, any, any>, ctx: any): Record<string, string> | null | false;
+  /**
+   * Register a global pattern applied to every route parameter sharing the
+   * given name (equivalent to Laravel's `Route::pattern`).
+   *
+   * @param name
+   * @param pattern
+   */
+  static pattern(name: string, pattern: string | RegExp): void;
+  /**
+   * Register multiple global parameter patterns at once.
+   *
+   * @param patterns
+   */
+  static patterns(patterns: Record<string, string | RegExp>): void;
+  /**
+   * Merge the global parameter patterns with the route's own constraints. Route
+   * level constraints take precedence over global patterns.
+   *
+   * @param route
+   * @returns
+   */
+  protected static resolveConstraints(route: Route<any, any, any>): Record<string, string | RegExp>;
+  /**
+   * Compile a constraint pattern into a fully-anchored regular expression.
+   *
+   * @param pattern
+   * @returns
+   */
+  protected static toConstraintRegex(pattern: string | RegExp): RegExp;
+  /**
+   * Determine whether the resolved parameters satisfy the route's constraints.
+   * Absent parameters (e.g. optional ones) are ignored.
+   *
+   * @param route
+   * @param params
+   * @returns
+   */
+  protected static satisfiesConstraints(route: Route<any, any, any>, params: Record<string, any>): boolean;
+  /**
+   * Determine which of a route's parameters are allowed to span multiple path
+   * segments (i.e. their constraint matches an encoded forward slash). These are
+   * registered with the adapter's catch-all syntax.
+   *
+   * @param route
+   * @returns
+   */
+  protected static wildcardParameters(route: Route<any, any, any>): Set<string>;
+  /**
+   * Render a single wildcard (slash-spanning) parameter for the underlying
+   * router's registration path. Overridden per adapter; the base form keeps the
+   * plain `:name` placeholder.
+   *
+   * @param name
+   * @returns
+   */
+  protected static formatWildcardParam(name: string): string;
+  /**
+   * Rewrite a route's registration paths so any wildcard parameters use the
+   * adapter's catch-all syntax. Non-wildcard routes are returned unchanged.
+   *
+   * @param route
+   * @returns
+   */
+  protected static resolveRegistrationPaths(route: Route<any, any, any>): string[];
+  /**
+   * Resolve the final parameters for a dispatched route, applying domain
+   * matching and constraint validation. Returns the merged parameters, or
+   * `false` when the route should not handle the request (host mismatch or a
+   * constraint failure) so the adapter can fall through.
+   *
+   * @param route
+   * @param ctx
+   * @param baseParams
+   * @returns
+   */
+  protected static matchRoute(route: Route<any, any, any>, ctx: any, baseParams?: Record<string, any>): Record<string, any> | false;
+  /**
+   * Normalize wildcard (slash-spanning) parameters into a single string keyed by
+   * the declared parameter name, smoothing over the differing shapes adapters
+   * return (Express yields an array of segments, Fastify keys it under `*`).
+   *
+   * @param route
+   * @param params
+   */
+  protected static normalizeWildcardParams(route: Route<any, any, any>, params: Record<string, any>): void;
+  /**
+   * Get the route currently being dispatched, if any.
+   *
+   * @returns
+   */
+  static current(): Route<any, any, any> | undefined;
+  /**
+   * Get the name of the route currently being dispatched.
+   *
+   * @returns
+   */
+  static currentRouteName(): string;
+  /**
+   * Get the action (`Controller@method` or `Closure`) of the route currently
+   * being dispatched.
+   *
+   * @returns
+   */
+  static currentRouteAction(): string;
   /**
    * Configures the router with the given options, such as method override settings.
    *
@@ -215,6 +362,27 @@ declare abstract class CoreRouter {
    * @param middlewares
    */
   static group<S extends RouteGroupSource>(prefix: string, source: S, middlewares?: any[]): RouteGroup<any, any, any, S>;
+  /**
+   * Build a route group, optionally constrained to a host pattern. Shared by
+   * `group` and the `domain` registrar.
+   *
+   * @param prefix
+   * @param source
+   * @param middlewares
+   * @param extra
+   */
+  protected static makeGroup<S extends RouteGroupSource>(prefix: string, source: S, middlewares?: any[], extra?: {
+    domain?: string;
+  }): RouteGroup<any, any, any, S>;
+  /**
+   * Begin a route registration constrained to a host pattern such as
+   * `{account}.example.com`. Returns a registrar whose `.group()` registers the
+   * routes under that domain (matched parameters become route parameters).
+   *
+   * @param pattern
+   * @returns
+   */
+  static domain(pattern: string): RouteRegistrar;
   /**
    * Adds global middlewares to the router, which will be applied to all routes.
    *

package/dist/core/CoreRouter.mjs

@@ -1,5 +1,6 @@
 import { Route } from "../Route.mjs";
 import { RouteGroup } from "../RouteGroup.mjs";
+import { RouteRegistrar } from "../RouteRegistrar.mjs";
 import { Request } from "./Request.mjs";
 import { Response } from "./Response.mjs";
 import { Container, getBindingMetadataFromTargets, getDesignParamTypes, getStandardMetadata, isClass } from "./bindings.mjs";
@@ -25,6 +26,9 @@ var CoreRouter = class {
 	static pluginArgumentResolversKey = Symbol.for("clear-router:plugin-argument-resolvers");
 	static requestProvider;
 	static responseProvider;
+	static domainMatcherCache = /* @__PURE__ */ new Map();
+	static constraintRegexCache = /* @__PURE__ */ new Map();
+	static routePatterns = /* @__PURE__ */ new Map();
 	static config = {
 		inferParamName: false,
 		methodOverride: {
@@ -111,6 +115,7 @@ var CoreRouter = class {
 		this.routesByPathMethod.clear();
 		this.routesByMethod.clear();
 		this.routesByName.clear();
+		this.routePatterns.clear();
 		return this;
 	}
 	static createBaseConfig() {
@@ -436,6 +441,271 @@ var CoreRouter = class {
 		return this.expandRoutePath(path);
 	}
 	/**
+	* Compile a host pattern such as `{account}.example.com` into a matcher and
+	* the ordered list of placeholder names it captures. Results are memoized.
+	*
+	* @param pattern
+	* @returns
+	*/
+	static compileDomain(pattern) {
+		const cached = this.domainMatcherCache.get(pattern);
+		if (cached) return cached;
+		const cleanPattern = pattern.split(":", 1)[0].trim();
+		const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, (match) => `\\${match}`);
+		const placeholder = /\{([^{}]+)\}/g;
+		const params = [];
+		let source = "^";
+		let lastIndex = 0;
+		let match;
+		while ((match = placeholder.exec(cleanPattern)) !== null) {
+			source += escape(cleanPattern.slice(lastIndex, match.index));
+			const raw = match[1].trim();
+			const optional = raw.endsWith("?");
+			const name = (optional ? raw.slice(0, -1) : raw).split(":", 1)[0].trim();
+			params.push(name);
+			source += optional ? "([^.]*)" : "([^.]+)";
+			lastIndex = match.index + match[0].length;
+		}
+		source += escape(cleanPattern.slice(lastIndex));
+		source += "$";
+		const compiled = {
+			regex: new RegExp(source, "i"),
+			params
+		};
+		this.domainMatcherCache.set(pattern, compiled);
+		return compiled;
+	}
+	/**
+	* Match a host against a domain pattern, returning the captured parameters or
+	* `null` when the host does not match.
+	*
+	* @param pattern
+	* @param host
+	* @returns
+	*/
+	static matchDomain(pattern, host) {
+		if (!pattern) return null;
+		const cleanHost = String(host ?? "").split(":", 1)[0].trim().toLowerCase();
+		const { regex, params } = this.compileDomain(pattern);
+		const match = regex.exec(cleanHost);
+		if (!match) return null;
+		const result = {};
+		params.forEach((name, index) => {
+			const value = match[index + 1];
+			if (typeof value !== "undefined") result[name] = decodeURIComponent(value);
+		});
+		return result;
+	}
+	/**
+	* Best-effort extraction of the request host across every supported adapter
+	* context shape (Express/Fastify plain headers, H3 `Headers`, Hono accessor,
+	* Koa context).
+	*
+	* @param ctx
+	* @returns
+	*/
+	static extractHost(ctx) {
+		const headers = ctx?.req?.headers ?? ctx?.headers;
+		let host;
+		if (headers) host = typeof headers.get === "function" ? headers.get("host") ?? headers.get(":authority") : headers.host ?? headers[":authority"];
+		if (!host && typeof ctx?.req?.header === "function") host = ctx.req.header("host");
+		if (!host && typeof ctx?.host === "string") host = ctx.host;
+		if (Array.isArray(host)) host = host[0];
+		return String(host ?? "").split(",", 1)[0].trim();
+	}
+	/**
+	* Resolve the domain parameters for a route given the active request context.
+	* Returns `null` when the route is not domain-constrained, `false` when it is
+	* but the host does not match, or the captured parameters on a match.
+	*
+	* @param route
+	* @param ctx
+	* @returns
+	*/
+	static matchRouteDomain(route, ctx) {
+		if (!route.domainPattern) return null;
+		return this.matchDomain(route.domainPattern, this.extractHost(ctx)) ?? false;
+	}
+	/**
+	* Register a global pattern applied to every route parameter sharing the
+	* given name (equivalent to Laravel's `Route::pattern`).
+	*
+	* @param name
+	* @param pattern
+	*/
+	static pattern(name, pattern) {
+		this.ensureState();
+		this.routePatterns.set(name, pattern);
+	}
+	/**
+	* Register multiple global parameter patterns at once.
+	*
+	* @param patterns
+	*/
+	static patterns(patterns) {
+		for (const [name, pattern] of Object.entries(patterns)) this.pattern(name, pattern);
+	}
+	/**
+	* Merge the global parameter patterns with the route's own constraints. Route
+	* level constraints take precedence over global patterns.
+	*
+	* @param route
+	* @returns
+	*/
+	static resolveConstraints(route) {
+		if (!this.routePatterns.size && !Object.keys(route.constraints).length) return route.constraints;
+		return {
+			...Object.fromEntries(this.routePatterns),
+			...route.constraints
+		};
+	}
+	/**
+	* Compile a constraint pattern into a fully-anchored regular expression.
+	*
+	* @param pattern
+	* @returns
+	*/
+	static toConstraintRegex(pattern) {
+		if (pattern instanceof RegExp) return new RegExp(`^(?:${pattern.source})$`, pattern.flags.replace("g", ""));
+		const cached = this.constraintRegexCache.get(pattern);
+		if (cached) return cached;
+		const regex = new RegExp(`^(?:${pattern})$`);
+		this.constraintRegexCache.set(pattern, regex);
+		return regex;
+	}
+	/**
+	* Determine whether the resolved parameters satisfy the route's constraints.
+	* Absent parameters (e.g. optional ones) are ignored.
+	*
+	* @param route
+	* @param params
+	* @returns
+	*/
+	static satisfiesConstraints(route, params) {
+		const constraints = this.resolveConstraints(route);
+		for (const name of Object.keys(constraints)) {
+			const value = params[name];
+			if (typeof value === "undefined" || value === null) continue;
+			const values = Array.isArray(value) ? value : [value];
+			const regex = this.toConstraintRegex(constraints[name]);
+			if (!values.every((entry) => regex.test(String(entry)))) return false;
+		}
+		return true;
+	}
+	/**
+	* Determine which of a route's parameters are allowed to span multiple path
+	* segments (i.e. their constraint matches an encoded forward slash). These are
+	* registered with the adapter's catch-all syntax.
+	*
+	* @param route
+	* @returns
+	*/
+	static wildcardParameters(route) {
+		const wildcards = /* @__PURE__ */ new Set();
+		const constraints = this.resolveConstraints(route);
+		const declared = new Set(route.parameters.map((parameter) => parameter.name));
+		for (const name of Object.keys(constraints)) {
+			if (!declared.has(name)) continue;
+			if (this.toConstraintRegex(constraints[name]).test("a/b")) wildcards.add(name);
+		}
+		return wildcards;
+	}
+	/**
+	* Render a single wildcard (slash-spanning) parameter for the underlying
+	* router's registration path. Overridden per adapter; the base form keeps the
+	* plain `:name` placeholder.
+	*
+	* @param name
+	* @returns
+	*/
+	static formatWildcardParam(name) {
+		return `:${name}`;
+	}
+	/**
+	* Rewrite a route's registration paths so any wildcard parameters use the
+	* adapter's catch-all syntax. Non-wildcard routes are returned unchanged.
+	*
+	* @param route
+	* @returns
+	*/
+	static resolveRegistrationPaths(route) {
+		const wildcards = this.wildcardParameters(route);
+		if (!wildcards.size) return route.registrationPaths;
+		return route.registrationPaths.map((path) => path.split("/").map((segment) => {
+			const name = segment.startsWith(":") ? segment.slice(1) : "";
+			return name && wildcards.has(name) ? this.formatWildcardParam(name) : segment;
+		}).join("/"));
+	}
+	/**
+	* Resolve the final parameters for a dispatched route, applying domain
+	* matching and constraint validation. Returns the merged parameters, or
+	* `false` when the route should not handle the request (host mismatch or a
+	* constraint failure) so the adapter can fall through.
+	*
+	* @param route
+	* @param ctx
+	* @param baseParams
+	* @returns
+	*/
+	static matchRoute(route, ctx, baseParams = {}) {
+		const params = { ...baseParams ?? {} };
+		if (route.domainPattern) {
+			const domainParams = this.matchDomain(route.domainPattern, this.extractHost(ctx));
+			if (!domainParams) return false;
+			Object.assign(params, domainParams);
+		}
+		this.normalizeWildcardParams(route, params);
+		if (!this.satisfiesConstraints(route, params)) return false;
+		return params;
+	}
+	/**
+	* Normalize wildcard (slash-spanning) parameters into a single string keyed by
+	* the declared parameter name, smoothing over the differing shapes adapters
+	* return (Express yields an array of segments, Fastify keys it under `*`).
+	*
+	* @param route
+	* @param params
+	*/
+	static normalizeWildcardParams(route, params) {
+		const wildcards = this.wildcardParameters(route);
+		if (!wildcards.size) return;
+		for (const name of wildcards) {
+			let value = params[name];
+			if (typeof value === "undefined" && typeof params["*"] !== "undefined") {
+				value = params["*"];
+				delete params["*"];
+			}
+			if (Array.isArray(value)) value = value.join("/");
+			if (typeof value !== "undefined") params[name] = value;
+		}
+	}
+	/**
+	* Get the route currently being dispatched, if any.
+	*
+	* @returns
+	*/
+	static current() {
+		const store = this.pluginRequestContext.getStore();
+		return store?.request?.route ?? store?.ctx?.clearRequest?.route;
+	}
+	/**
+	* Get the name of the route currently being dispatched.
+	*
+	* @returns
+	*/
+	static currentRouteName() {
+		return this.current()?.routeName ?? "";
+	}
+	/**
+	* Get the action (`Controller@method` or `Closure`) of the route currently
+	* being dispatched.
+	*
+	* @returns
+	*/
+	static currentRouteAction() {
+		return this.current()?.action ?? "";
+	}
+	/**
 	* Configures the router with the given options, such as method override settings.
 	* 
 	* @param this 
@@ -507,6 +777,7 @@ var CoreRouter = class {
 		const context = this.groupContext.getStore();
 		const activePrefix = context?.prefix ?? this.prefix;
 		const activeGroupMiddlewares = context?.groupMiddlewares ?? this.groupMiddlewares;
+		const activeDomain = context?.domain;
 		methods = Array.isArray(methods) ? methods : [methods];
 		middlewares = middlewares ? Array.isArray(middlewares) ? middlewares : [middlewares] : void 0;
 		const fullPath = this.normalizePath(`${activePrefix}/${path}`);
@@ -523,6 +794,7 @@ var CoreRouter = class {
 		]), {
 			registrationPaths,
 			parameters,
+			domain: activeDomain,
 			onName: (name, route, previousName) => {
 				if (previousName && this.routesByName.get(previousName) === route) this.routesByName.delete(previousName);
 				this.routesByName.set(name, route);
@@ -643,11 +915,24 @@ var CoreRouter = class {
 	* @param middlewares 
 	*/
 	static group(prefix, source, middlewares) {
+		return this.makeGroup(prefix, source, middlewares);
+	}
+	/**
+	* Build a route group, optionally constrained to a host pattern. Shared by
+	* `group` and the `domain` registrar.
+	*
+	* @param prefix
+	* @param source
+	* @param middlewares
+	* @param extra
+	*/
+	static makeGroup(prefix, source, middlewares, extra) {
 		this.ensureState();
 		return new RouteGroup({
 			prefix,
 			source,
 			middlewares,
+			domain: extra?.domain,
 			context: this.groupContext,
 			defaultPrefix: this.prefix,
 			defaultMiddlewares: this.groupMiddlewares,
@@ -656,6 +941,18 @@ var CoreRouter = class {
 		});
 	}
 	/**
+	* Begin a route registration constrained to a host pattern such as
+	* `{account}.example.com`. Returns a registrar whose `.group()` registers the
+	* routes under that domain (matched parameters become route parameters).
+	*
+	* @param pattern
+	* @returns
+	*/
+	static domain(pattern) {
+		this.ensureState();
+		return new RouteRegistrar((prefix, source, middlewares, extra) => this.makeGroup(prefix, source, middlewares, extra), { domain: pattern });
+	}
+	/**
 	* Adds global middlewares to the router, which will be applied to all routes.
 	* 
 	* @param this 
@@ -831,6 +1128,16 @@ var CoreRouter = class {
 		instance.clearRequest = clearRequest;
 	}
 };
+/**
+* Expose the active request's route through the `Route` facade (`Route.current()`,
+* `Route.currentRouteName()`, `Route.currentRouteAction()`) by delegating to the
+* shared router request context.
+*/
+Route.bindCurrentResolvers({
+	current: () => CoreRouter.current(),
+	currentRouteName: () => CoreRouter.currentRouteName(),
+	currentRouteAction: () => CoreRouter.currentRouteAction()
+});
 
 //#endregion
 export { CoreRouter };

package/dist/decorators/setup.d.mts

@@ -1,3 +1,2 @@
 import { Bind, BindDecorator, BindFactory, BindToken, BindValue, Container } from "../core/bindings.mjs";
-import "reflect-metadata";
 export { Bind, BindDecorator, BindFactory, BindToken, BindValue, Container };

package/dist/express/router.cjs

@@ -11,6 +11,9 @@ const require_responses = require('../core/responses.cjs');
 */
 var Router = class Router extends require_CoreRouter.CoreRouter {
 	static routerStateNamespace = "clear-router:express";
+	static formatWildcardParam(name) {
+		return `*${name}`;
+	}
 	static ensureRequestBodyAccessor(req) {
 		if (typeof req.getBody !== "function") req.getBody = () => req.body ?? {};
 	}
@@ -196,7 +199,7 @@ var Router = class Router extends require_CoreRouter.CoreRouter {
 					console.error("[ROUTES]", error.message);
 					throw error;
 				}
-				for (const registrationPath of route.registrationPaths) router[method](registrationPath, (req, _res, next) => {
+				for (const registrationPath of this.resolveRegistrationPaths(route)) router[method](registrationPath, (req, _res, next) => {
 					Router.ensureRequestBodyAccessor(req);
 					const override = Router.resolveMethodOverride(req.method, req.headers, req.body);
 					if (method === "post" && override && override !== "post") return next("route");
@@ -210,10 +213,13 @@ var Router = class Router extends require_CoreRouter.CoreRouter {
 							next
 						};
 						const inst = instance ?? route;
+						const params = Router.matchRoute(route, ctx, ctx.req.params);
+						if (params === false) return next("route");
+						Object.assign(ctx.req.params, params);
 						Router.bindRequestToInstance(ctx, inst, route, {
 							body: ctx.req.getBody(),
 							query: ctx.req.query,
-							params: ctx.req.params,
+							params,
 							method
 						});
 						const result = await Router.callHandler(handlerFunction, ctx, bindingTarget, bindingMethod, bindingHandler, bindingMetadata);
@@ -228,7 +234,7 @@ var Router = class Router extends require_CoreRouter.CoreRouter {
 					"put",
 					"patch",
 					"delete"
-				].includes(method)) for (const registrationPath of route.registrationPaths) router.post(registrationPath, (req, _res, next) => {
+				].includes(method)) for (const registrationPath of this.resolveRegistrationPaths(route)) router.post(registrationPath, (req, _res, next) => {
 					Router.ensureRequestBodyAccessor(req);
 					if (Router.resolveMethodOverride(req.method, req.headers, req.body) !== method) return next("route");
 					req.method = method.toUpperCase();
@@ -242,10 +248,13 @@ var Router = class Router extends require_CoreRouter.CoreRouter {
 							next
 						};
 						const inst = instance ?? route;
+						const params = Router.matchRoute(route, ctx, ctx.req.params);
+						if (params === false) return next("route");
+						Object.assign(ctx.req.params, params);
 						Router.bindRequestToInstance(ctx, inst, route, {
 							body: ctx.req.getBody(),
 							query: ctx.req.query,
-							params: ctx.req.params,
+							params,
 							method
 						});
 						const result = await Router.callHandler(handlerFunction, ctx, bindingTarget, bindingMethod, bindingHandler, bindingMetadata);

package/dist/express/router.d.cts

@@ -16,6 +16,7 @@ import { Router } from "express";
  */
 declare class Router$1 extends CoreRouter {
   protected static routerStateNamespace: string;
+  protected static formatWildcardParam(name: string): string;
   private static ensureRequestBodyAccessor;
   private static sendReturnValue;
   /**

package/dist/express/router.d.mts

@@ -16,6 +16,7 @@ import { Router } from "express";
  */
 declare class Router$1 extends CoreRouter {
   protected static routerStateNamespace: string;
+  protected static formatWildcardParam(name: string): string;
   private static ensureRequestBodyAccessor;
   private static sendReturnValue;
   /**