clear-router 2.8.9 → 2.9.0

package/dist/Route.mjs

@@ -1,11 +1,39 @@
 //#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 = {};
@@ -22,6 +50,9 @@ var Route = class {
 	actionName;
 	handlerType;
 	middlewareCount;
+	domainPattern;
+	domainParameters;
+	constraints = {};
 	constructor(methods, path, handler, middlewares = [], options = {}) {
 		this.methods = methods;
 		this.path = path;
@@ -33,16 +64,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;
@@ -51,10 +131,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);
@@ -63,13 +229,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();
@@ -82,8 +267,10 @@ var Route = class {
 			}
 			return `${segment.startsWith("/") ? "/" : ""}${encodeURIComponent(String(resolved))}`;
 		}) || "/";
+		if (!this.domainPattern) return resolved;
+		return `//${this.resolveDomainHost(params)}${resolved}`;
 	}
 };
 
 //#endregion
-export { Route };
+export { Route, parseDomainParameters };

package/dist/RouteGroup.cjs

@@ -69,6 +69,7 @@ var RouteGroup = class {
 		const nextContext = {
 			prefix: this.options.normalizePath(fullPrefix),
 			groupMiddlewares: [...previousMiddlewares, ...this.options.middlewares || []],
+			domain: this.options.domain ?? current?.domain,
 			routeCollectors: [...current?.routeCollectors ?? [], this.routes]
 		};
 		await this.options.context.run(nextContext, async () => {

package/dist/RouteGroup.mjs

@@ -69,6 +69,7 @@ var RouteGroup = class {
 		const nextContext = {
 			prefix: this.options.normalizePath(fullPrefix),
 			groupMiddlewares: [...previousMiddlewares, ...this.options.middlewares || []],
+			domain: this.options.domain ?? current?.domain,
 			routeCollectors: [...current?.routeCollectors ?? [], this.routes]
 		};
 		await this.options.context.run(nextContext, async () => {

package/dist/RouteRegistrar.cjs

@@ -0,0 +1,68 @@
+
+//#region src/RouteRegistrar.ts
+/**
+* @class clear-router RouteRegistrar
+* @description Fluent builder returned by `Router.domain()` that lets routes be
+* grouped under a shared host pattern (and optionally a prefix/middlewares),
+* mirroring Laravel's route attribute registrar.
+* @author 3m1n3nc3
+* @repository https://github.com/arkstack-hq/clear-router
+*/
+var RouteRegistrar = class {
+	attributes;
+	constructor(makeGroup, attributes = {}) {
+		this.makeGroup = makeGroup;
+		this.attributes = {
+			domain: attributes.domain,
+			prefix: attributes.prefix ?? "",
+			middlewares: attributes.middlewares ?? []
+		};
+	}
+	/**
+	* Constrain the grouped routes to a host pattern such as `{account}.example.com`.
+	*
+	* @param pattern
+	* @returns
+	*/
+	domain(pattern) {
+		this.attributes.domain = pattern;
+		return this;
+	}
+	/**
+	* Prepend a path prefix to the grouped routes.
+	*
+	* @param prefix
+	* @returns
+	*/
+	prefix(prefix) {
+		this.attributes.prefix = prefix;
+		return this;
+	}
+	/**
+	* Register one or more middleware shared by the grouped routes.
+	*
+	* @param middlewares
+	* @returns
+	*/
+	middleware(middlewares) {
+		this.attributes.middlewares = [...this.attributes.middlewares, ...Array.isArray(middlewares) ? middlewares : [middlewares]];
+		return this;
+	}
+	group(prefixOrSource, sourceOrMiddlewares, middlewares) {
+		let prefix = this.attributes.prefix;
+		let source;
+		let extraMiddlewares;
+		if (typeof prefixOrSource === "string") {
+			prefix = prefixOrSource;
+			source = sourceOrMiddlewares;
+			extraMiddlewares = middlewares;
+		} else {
+			source = prefixOrSource;
+			extraMiddlewares = sourceOrMiddlewares;
+		}
+		return this.makeGroup(prefix, source, [...this.attributes.middlewares, ...extraMiddlewares ?? []], { domain: this.attributes.domain });
+	}
+};
+
+//#endregion
+exports.RouteRegistrar = RouteRegistrar;

package/dist/RouteRegistrar.d.cts

@@ -0,0 +1,62 @@
+import { RouteGroupSource } from "./types/basic.cjs";
+import { RouteGroup } from "./RouteGroup.cjs";
+
+//#region src/RouteRegistrar.d.ts
+/**
+ * Factory used by the registrar to build a route group while carrying the
+ * accumulated attributes (domain, prefix, middlewares).
+ */
+type RouteRegistrarGroupFactory = (prefix: string, source: RouteGroupSource, middlewares: any[] | undefined, extra: {
+  domain?: string;
+}) => RouteGroup<any, any, any, any>;
+/**
+ * @class clear-router RouteRegistrar
+ * @description Fluent builder returned by `Router.domain()` that lets routes be
+ * grouped under a shared host pattern (and optionally a prefix/middlewares),
+ * mirroring Laravel's route attribute registrar.
+ * @author 3m1n3nc3
+ * @repository https://github.com/arkstack-hq/clear-router
+ */
+declare class RouteRegistrar {
+  private readonly makeGroup;
+  private attributes;
+  constructor(makeGroup: RouteRegistrarGroupFactory, attributes?: {
+    domain?: string;
+    prefix?: string;
+    middlewares?: any[];
+  });
+  /**
+   * Constrain the grouped routes to a host pattern such as `{account}.example.com`.
+   *
+   * @param pattern
+   * @returns
+   */
+  domain(pattern: string): this;
+  /**
+   * Prepend a path prefix to the grouped routes.
+   *
+   * @param prefix
+   * @returns
+   */
+  prefix(prefix: string): this;
+  /**
+   * Register one or more middleware shared by the grouped routes.
+   *
+   * @param middlewares
+   * @returns
+   */
+  middleware(middlewares: any[] | any): this;
+  /**
+   * Register the grouped routes. A leading string is treated as a path prefix
+   * (matching `Router.group(prefix, source, middlewares?)`); otherwise the first
+   * argument is the source and the registrar's own prefix is used.
+   *
+   * @param source
+   * @param middlewares
+   * @returns
+   */
+  group<S extends RouteGroupSource = RouteGroupSource>(source: S, middlewares?: any[]): RouteGroup<any, any, any, S>;
+  group<S extends RouteGroupSource = RouteGroupSource>(prefix: string, source: S, middlewares?: any[]): RouteGroup<any, any, any, S>;
+}
+//#endregion
+export { RouteRegistrar, RouteRegistrarGroupFactory };

package/dist/RouteRegistrar.d.mts

@@ -0,0 +1,62 @@
+import { RouteGroupSource } from "./types/basic.mjs";
+import { RouteGroup } from "./RouteGroup.mjs";
+
+//#region src/RouteRegistrar.d.ts
+/**
+ * Factory used by the registrar to build a route group while carrying the
+ * accumulated attributes (domain, prefix, middlewares).
+ */
+type RouteRegistrarGroupFactory = (prefix: string, source: RouteGroupSource, middlewares: any[] | undefined, extra: {
+  domain?: string;
+}) => RouteGroup<any, any, any, any>;
+/**
+ * @class clear-router RouteRegistrar
+ * @description Fluent builder returned by `Router.domain()` that lets routes be
+ * grouped under a shared host pattern (and optionally a prefix/middlewares),
+ * mirroring Laravel's route attribute registrar.
+ * @author 3m1n3nc3
+ * @repository https://github.com/arkstack-hq/clear-router
+ */
+declare class RouteRegistrar {
+  private readonly makeGroup;
+  private attributes;
+  constructor(makeGroup: RouteRegistrarGroupFactory, attributes?: {
+    domain?: string;
+    prefix?: string;
+    middlewares?: any[];
+  });
+  /**
+   * Constrain the grouped routes to a host pattern such as `{account}.example.com`.
+   *
+   * @param pattern
+   * @returns
+   */
+  domain(pattern: string): this;
+  /**
+   * Prepend a path prefix to the grouped routes.
+   *
+   * @param prefix
+   * @returns
+   */
+  prefix(prefix: string): this;
+  /**
+   * Register one or more middleware shared by the grouped routes.
+   *
+   * @param middlewares
+   * @returns
+   */
+  middleware(middlewares: any[] | any): this;
+  /**
+   * Register the grouped routes. A leading string is treated as a path prefix
+   * (matching `Router.group(prefix, source, middlewares?)`); otherwise the first
+   * argument is the source and the registrar's own prefix is used.
+   *
+   * @param source
+   * @param middlewares
+   * @returns
+   */
+  group<S extends RouteGroupSource = RouteGroupSource>(source: S, middlewares?: any[]): RouteGroup<any, any, any, S>;
+  group<S extends RouteGroupSource = RouteGroupSource>(prefix: string, source: S, middlewares?: any[]): RouteGroup<any, any, any, S>;
+}
+//#endregion
+export { RouteRegistrar, RouteRegistrarGroupFactory };

package/dist/RouteRegistrar.mjs

@@ -0,0 +1,67 @@
+//#region src/RouteRegistrar.ts
+/**
+* @class clear-router RouteRegistrar
+* @description Fluent builder returned by `Router.domain()` that lets routes be
+* grouped under a shared host pattern (and optionally a prefix/middlewares),
+* mirroring Laravel's route attribute registrar.
+* @author 3m1n3nc3
+* @repository https://github.com/arkstack-hq/clear-router
+*/
+var RouteRegistrar = class {
+	attributes;
+	constructor(makeGroup, attributes = {}) {
+		this.makeGroup = makeGroup;
+		this.attributes = {
+			domain: attributes.domain,
+			prefix: attributes.prefix ?? "",
+			middlewares: attributes.middlewares ?? []
+		};
+	}
+	/**
+	* Constrain the grouped routes to a host pattern such as `{account}.example.com`.
+	*
+	* @param pattern
+	* @returns
+	*/
+	domain(pattern) {
+		this.attributes.domain = pattern;
+		return this;
+	}
+	/**
+	* Prepend a path prefix to the grouped routes.
+	*
+	* @param prefix
+	* @returns
+	*/
+	prefix(prefix) {
+		this.attributes.prefix = prefix;
+		return this;
+	}
+	/**
+	* Register one or more middleware shared by the grouped routes.
+	*
+	* @param middlewares
+	* @returns
+	*/
+	middleware(middlewares) {
+		this.attributes.middlewares = [...this.attributes.middlewares, ...Array.isArray(middlewares) ? middlewares : [middlewares]];
+		return this;
+	}
+	group(prefixOrSource, sourceOrMiddlewares, middlewares) {
+		let prefix = this.attributes.prefix;
+		let source;
+		let extraMiddlewares;
+		if (typeof prefixOrSource === "string") {
+			prefix = prefixOrSource;
+			source = sourceOrMiddlewares;
+			extraMiddlewares = middlewares;
+		} else {
+			source = prefixOrSource;
+			extraMiddlewares = sourceOrMiddlewares;
+		}
+		return this.makeGroup(prefix, source, [...this.attributes.middlewares, ...extraMiddlewares ?? []], { domain: this.attributes.domain });
+	}
+};
+
+//#endregion
+export { RouteRegistrar };