clear-router 2.8.8 → 2.9.0

package/dist/Route.cjs

@@ -1,12 +1,40 @@
 
 //#region src/Route.ts
 /**
+* Parse the placeholder parameters declared in a domain/host pattern such as
+* `{account}.example.com`. Mirrors the path parameter syntax (supporting the
+* optional `{name?}` form) so domain parameters feel consistent with path ones.
+*
+* @param pattern
+* @returns
+*/
+const parseDomainParameters = (pattern) => {
+	if (!pattern) return [];
+	const parameters = [];
+	const seen = /* @__PURE__ */ new Set();
+	const matcher = /\{([^{}]+)\}/g;
+	let match;
+	while ((match = matcher.exec(pattern)) !== null) {
+		const raw = match[1].trim();
+		const optional = raw.endsWith("?");
+		const [name, field] = (optional ? raw.slice(0, -1) : raw).split(":", 2).map((part) => part.trim());
+		if (!name || seen.has(name)) continue;
+		seen.add(name);
+		parameters.push({
+			name,
+			field: field || void 0,
+			optional
+		});
+	}
+	return parameters;
+};
+/**
 * @class clear-router Route
 * @description A route describes a single enpoint on clear-router
 * @author 3m1n3nc3
 * @repository https://github.com/arkstack-hq/clear-router
 */
-var Route = class {
+var Route = class Route {
 	ctx;
 	body = {};
 	query = {};
@@ -23,6 +51,9 @@ var Route = class {
 	actionName;
 	handlerType;
 	middlewareCount;
+	domainPattern;
+	domainParameters;
+	constraints = {};
 	constructor(methods, path, handler, middlewares = [], options = {}) {
 		this.methods = methods;
 		this.path = path;
@@ -34,16 +65,65 @@ var Route = class {
 		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.domainPattern = options.domain;
+		this.domainParameters = parseDomainParameters(options.domain);
 		this.onName = options.onName;
 		this.normalizeMiddleware = options.normalizeMiddleware;
 	}
 	onName;
 	normalizeMiddleware;
+	static currentResolvers;
+	/**
+	* Wire the resolvers used by the static `current*` accessors. Called once by
+	* `CoreRouter` so `Route.current()` reflects the active request.
+	*
+	* @internal
+	* @param resolvers
+	*/
+	static bindCurrentResolvers(resolvers) {
+		Route.currentResolvers = resolvers;
+	}
+	/**
+	* Get the route currently being dispatched, if any.
+	*
+	* @returns
+	*/
+	static current() {
+		return Route.currentResolvers?.current();
+	}
+	/**
+	* Get the name of the route currently being dispatched.
+	*
+	* @returns
+	*/
+	static currentRouteName() {
+		return Route.currentResolvers?.currentRouteName() ?? "";
+	}
+	/**
+	* Get the action (controller@method or `Closure`) of the route currently
+	* being dispatched.
+	*
+	* @returns
+	*/
+	static currentRouteAction() {
+		return Route.currentResolvers?.currentRouteAction() ?? "";
+	}
+	/**
+	* The route action expressed as `Controller@method` for controller routes or
+	* `Closure` for callback routes.
+	*/
+	get action() {
+		if (this.handlerType === "controller") {
+			const method = String(this.actionName ?? "");
+			return this.controllerName ? `${this.controllerName}@${method}` : method;
+		}
+		return "Closure";
+	}
 	/**
 	* Set the route name
-	* 
-	* @param name 
-	* @returns 
+	*
+	* @param name
+	* @returns
 	*/
 	name(name) {
 		const previousName = this.routeName;
@@ -52,10 +132,96 @@ var Route = class {
 		return this;
 	}
 	/**
+	* Constrain the route to a host pattern such as `{account}.example.com`.
+	* Any `{placeholder}` segments are exposed as route parameters once matched.
+	*
+	* @param pattern
+	* @returns
+	*/
+	domain(pattern) {
+		this.domainPattern = pattern;
+		this.domainParameters = parseDomainParameters(pattern);
+		return this;
+	}
+	/**
+	* Constrain one or more route parameters with a regular expression. Accepts
+	* either `where(name, pattern)` or `where({ name: pattern, ... })`.
+	*
+	* @param name
+	* @param pattern
+	* @returns
+	*/
+	where(name, pattern) {
+		if (typeof name === "object") Object.assign(this.constraints, name);
+		else if (typeof pattern !== "undefined") this.constraints[name] = pattern;
+		return this;
+	}
+	/**
+	* Constrain the given parameters to numeric values.
+	*
+	* @param names
+	* @returns
+	*/
+	whereNumber(...names) {
+		return this.applyConstraint(names, "[0-9]+");
+	}
+	/**
+	* Constrain the given parameters to alphabetic values.
+	*
+	* @param names
+	* @returns
+	*/
+	whereAlpha(...names) {
+		return this.applyConstraint(names, "[a-zA-Z]+");
+	}
+	/**
+	* Constrain the given parameters to alphanumeric values.
+	*
+	* @param names
+	* @returns
+	*/
+	whereAlphaNumeric(...names) {
+		return this.applyConstraint(names, "[a-zA-Z0-9]+");
+	}
+	/**
+	* Constrain the given parameters to UUID values.
+	*
+	* @param names
+	* @returns
+	*/
+	whereUuid(...names) {
+		return this.applyConstraint(names, "[\\da-fA-F]{8}-[\\da-fA-F]{4}-[\\da-fA-F]{4}-[\\da-fA-F]{4}-[\\da-fA-F]{12}");
+	}
+	/**
+	* Constrain the given parameters to ULID values.
+	*
+	* @param names
+	* @returns
+	*/
+	whereUlid(...names) {
+		return this.applyConstraint(names, "[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}");
+	}
+	/**
+	* Constrain a parameter to one of the given values.
+	*
+	* @param name
+	* @param values
+	* @returns
+	*/
+	whereIn(name, values) {
+		const escaped = values.map((value) => String(value).replace(/[.*+?^${}()|[\]\\]/g, (match) => `\\${match}`));
+		this.constraints[name] = escaped.join("|");
+		return this;
+	}
+	applyConstraint(names, pattern) {
+		for (const name of names) this.constraints[name] = pattern;
+		return this;
+	}
+	/**
 	* Register one or more middleware that will be executed before the route.
-	* 
-	* @param middlewares 
-	* @returns 
+	*
+	* @param middlewares
+	* @returns
 	*/
 	middleware(middlewares) {
 		const normalized = (Array.isArray(middlewares) ? middlewares : [middlewares]).map((middleware) => this.normalizeMiddleware?.(middleware) ?? middleware);
@@ -64,13 +230,32 @@ var Route = class {
 		return this;
 	}
 	/**
+	* Resolve the route's domain pattern into a concrete host using the given
+	* parameters.
+	*
+	* @param params
+	* @returns
+	*/
+	resolveDomainHost(params) {
+		return this.domainPattern.replace(/\{([^{}]+)\}/g, (_, raw) => {
+			const optional = raw.endsWith("?");
+			const name = (optional ? raw.slice(0, -1) : raw).split(":", 2)[0].trim();
+			const value = params[name];
+			if (typeof value === "undefined" || value === null || value === "") {
+				if (optional) return "";
+				throw new Error(`Missing required route domain parameter: ${name}`);
+			}
+			return encodeURIComponent(String(value));
+		});
+	}
+	/**
 	* Get the path generated and accessible by this route
-	* 
-	* @param params 
-	* @returns 
+	*
+	* @param params
+	* @returns
 	*/
 	toPath(params = {}) {
-		return this.path.replace(/\/?\{([^{}]+)\}/g, (segment, raw) => {
+		const resolved = 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();
@@ -83,8 +268,11 @@ var Route = class {
 			}
 			return `${segment.startsWith("/") ? "/" : ""}${encodeURIComponent(String(resolved))}`;
 		}) || "/";
+		if (!this.domainPattern) return resolved;
+		return `//${this.resolveDomainHost(params)}${resolved}`;
 	}
 };
 
 //#endregion
-exports.Route = Route;
+exports.Route = Route;
+exports.parseDomainParameters = parseDomainParameters;

package/dist/Route.d.cts

@@ -5,6 +5,24 @@ import { ClearRequest } from "./ClearRequest.cjs";
 import { HttpMethod, RequestData } from "./types/basic.cjs";
 
 //#region src/Route.d.ts
+/**
+ * Parse the placeholder parameters declared in a domain/host pattern such as
+ * `{account}.example.com`. Mirrors the path parameter syntax (supporting the
+ * optional `{name?}` form) so domain parameters feel consistent with path ones.
+ *
+ * @param pattern
+ * @returns
+ */
+declare const parseDomainParameters: (pattern?: string) => RouteParameter[];
+/**
+ * Resolvers wired up by `CoreRouter` so the `Route` facade can expose the
+ * currently dispatching route without depending on the router directly.
+ */
+interface CurrentRouteResolvers {
+  current: () => Route<any, any, any> | undefined;
+  currentRouteName: () => string;
+  currentRouteAction: () => string;
+}
 /**
  * @class clear-router Route
  * @description A route describes a single enpoint on clear-router
@@ -28,14 +46,51 @@ declare class Route<X = any, M = Middleware$1 | Middleware, H = any> {
   actionName?: string;
   handlerType: 'function' | 'controller';
   middlewareCount: number;
+  domainPattern?: string;
+  domainParameters: RouteParameter[];
+  constraints: Record<string, string | RegExp>;
   constructor(methods: HttpMethod[], path: string, handler: H, middlewares?: M[], options?: {
     registrationPaths?: string[];
     parameters?: RouteParameter[];
+    domain?: string;
     onName?: (name: string, route: Route<X, M, H>, previousName?: string) => void;
     normalizeMiddleware?: (middleware: M) => M;
   });
   private onName?;
   private normalizeMiddleware?;
+  private static currentResolvers?;
+  /**
+   * Wire the resolvers used by the static `current*` accessors. Called once by
+   * `CoreRouter` so `Route.current()` reflects the active request.
+   *
+   * @internal
+   * @param resolvers
+   */
+  static bindCurrentResolvers(resolvers: CurrentRouteResolvers): 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;
+  /**
+   * The route action expressed as `Controller@method` for controller routes or
+   * `Closure` for callback routes.
+   */
+  get action(): string;
   /**
    * Set the route name
    *
@@ -43,6 +98,67 @@ declare class Route<X = any, M = Middleware$1 | Middleware, H = any> {
    * @returns
    */
   name(name: string): this;
+  /**
+   * Constrain the route to a host pattern such as `{account}.example.com`.
+   * Any `{placeholder}` segments are exposed as route parameters once matched.
+   *
+   * @param pattern
+   * @returns
+   */
+  domain(pattern: string): this;
+  /**
+   * Constrain one or more route parameters with a regular expression. Accepts
+   * either `where(name, pattern)` or `where({ name: pattern, ... })`.
+   *
+   * @param name
+   * @param pattern
+   * @returns
+   */
+  where(name: string | Record<string, string | RegExp>, pattern?: string | RegExp): this;
+  /**
+   * Constrain the given parameters to numeric values.
+   *
+   * @param names
+   * @returns
+   */
+  whereNumber(...names: string[]): this;
+  /**
+   * Constrain the given parameters to alphabetic values.
+   *
+   * @param names
+   * @returns
+   */
+  whereAlpha(...names: string[]): this;
+  /**
+   * Constrain the given parameters to alphanumeric values.
+   *
+   * @param names
+   * @returns
+   */
+  whereAlphaNumeric(...names: string[]): this;
+  /**
+   * Constrain the given parameters to UUID values.
+   *
+   * @param names
+   * @returns
+   */
+  whereUuid(...names: string[]): this;
+  /**
+   * Constrain the given parameters to ULID values.
+   *
+   * @param names
+   * @returns
+   */
+  whereUlid(...names: string[]): this;
+  /**
+   * Constrain a parameter to one of the given values.
+   *
+   * @param name
+   * @param values
+   * @returns
+   */
+  whereIn(name: string, values: Array<string | number>): this;
+  private applyConstraint;
   /**
    * Register one or more middleware that will be executed before the route.
    *
@@ -50,6 +166,14 @@ declare class Route<X = any, M = Middleware$1 | Middleware, H = any> {
    * @returns
    */
   middleware(middlewares: M[] | M): this;
+  /**
+   * Resolve the route's domain pattern into a concrete host using the given
+   * parameters.
+   *
+   * @param params
+   * @returns
+   */
+  private resolveDomainHost;
   /**
    * Get the path generated and accessible by this route
    *
@@ -59,4 +183,4 @@ declare class Route<X = any, M = Middleware$1 | Middleware, H = any> {
   toPath(params?: RequestData): string;
 }
 //#endregion
-export { Route };
+export { Route, parseDomainParameters };

package/dist/Route.d.mts

@@ -5,6 +5,24 @@ import { ClearRequest } from "./ClearRequest.mjs";
 import { HttpMethod, RequestData } from "./types/basic.mjs";
 
 //#region src/Route.d.ts
+/**
+ * Parse the placeholder parameters declared in a domain/host pattern such as
+ * `{account}.example.com`. Mirrors the path parameter syntax (supporting the
+ * optional `{name?}` form) so domain parameters feel consistent with path ones.
+ *
+ * @param pattern
+ * @returns
+ */
+declare const parseDomainParameters: (pattern?: string) => RouteParameter[];
+/**
+ * Resolvers wired up by `CoreRouter` so the `Route` facade can expose the
+ * currently dispatching route without depending on the router directly.
+ */
+interface CurrentRouteResolvers {
+  current: () => Route<any, any, any> | undefined;
+  currentRouteName: () => string;
+  currentRouteAction: () => string;
+}
 /**
  * @class clear-router Route
  * @description A route describes a single enpoint on clear-router
@@ -28,14 +46,51 @@ declare class Route<X = any, M = Middleware$1 | Middleware, H = any> {
   actionName?: string;
   handlerType: 'function' | 'controller';
   middlewareCount: number;
+  domainPattern?: string;
+  domainParameters: RouteParameter[];
+  constraints: Record<string, string | RegExp>;
   constructor(methods: HttpMethod[], path: string, handler: H, middlewares?: M[], options?: {
     registrationPaths?: string[];
     parameters?: RouteParameter[];
+    domain?: string;
     onName?: (name: string, route: Route<X, M, H>, previousName?: string) => void;
     normalizeMiddleware?: (middleware: M) => M;
   });
   private onName?;
   private normalizeMiddleware?;
+  private static currentResolvers?;
+  /**
+   * Wire the resolvers used by the static `current*` accessors. Called once by
+   * `CoreRouter` so `Route.current()` reflects the active request.
+   *
+   * @internal
+   * @param resolvers
+   */
+  static bindCurrentResolvers(resolvers: CurrentRouteResolvers): 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;
+  /**
+   * The route action expressed as `Controller@method` for controller routes or
+   * `Closure` for callback routes.
+   */
+  get action(): string;
   /**
    * Set the route name
    *
@@ -43,6 +98,67 @@ declare class Route<X = any, M = Middleware$1 | Middleware, H = any> {
    * @returns
    */
   name(name: string): this;
+  /**
+   * Constrain the route to a host pattern such as `{account}.example.com`.
+   * Any `{placeholder}` segments are exposed as route parameters once matched.
+   *
+   * @param pattern
+   * @returns
+   */
+  domain(pattern: string): this;
+  /**
+   * Constrain one or more route parameters with a regular expression. Accepts
+   * either `where(name, pattern)` or `where({ name: pattern, ... })`.
+   *
+   * @param name
+   * @param pattern
+   * @returns
+   */
+  where(name: string | Record<string, string | RegExp>, pattern?: string | RegExp): this;
+  /**
+   * Constrain the given parameters to numeric values.
+   *
+   * @param names
+   * @returns
+   */
+  whereNumber(...names: string[]): this;
+  /**
+   * Constrain the given parameters to alphabetic values.
+   *
+   * @param names
+   * @returns
+   */
+  whereAlpha(...names: string[]): this;
+  /**
+   * Constrain the given parameters to alphanumeric values.
+   *
+   * @param names
+   * @returns
+   */
+  whereAlphaNumeric(...names: string[]): this;
+  /**
+   * Constrain the given parameters to UUID values.
+   *
+   * @param names
+   * @returns
+   */
+  whereUuid(...names: string[]): this;
+  /**
+   * Constrain the given parameters to ULID values.
+   *
+   * @param names
+   * @returns
+   */
+  whereUlid(...names: string[]): this;
+  /**
+   * Constrain a parameter to one of the given values.
+   *
+   * @param name
+   * @param values
+   * @returns
+   */
+  whereIn(name: string, values: Array<string | number>): this;
+  private applyConstraint;
   /**
    * Register one or more middleware that will be executed before the route.
    *
@@ -50,6 +166,14 @@ declare class Route<X = any, M = Middleware$1 | Middleware, H = any> {
    * @returns
    */
   middleware(middlewares: M[] | M): this;
+  /**
+   * Resolve the route's domain pattern into a concrete host using the given
+   * parameters.
+   *
+   * @param params
+   * @returns
+   */
+  private resolveDomainHost;
   /**
    * Get the path generated and accessible by this route
    *
@@ -59,4 +183,4 @@ declare class Route<X = any, M = Middleware$1 | Middleware, H = any> {
   toPath(params?: RequestData): string;
 }
 //#endregion
-export { Route };
+export { Route, parseDomainParameters };