clear-router 2.9.0 → 2.9.2

package/dist/core/bindings.mjs

@@ -1,54 +1,189 @@
 import { Request } from "./Request.mjs";
 import { Response } from "./Response.mjs";
+import { AsyncLocalStorage } from "node:async_hooks";
 
 //#region src/core/bindings.ts
 const metadataKey = Symbol.for("clear-router:binding-metadata");
 const bindings = /* @__PURE__ */ new WeakMap();
-var Container = class {
-	static registry = /* @__PURE__ */ new Map();
-	static bind(token, value) {
-		this.registry.set(token, value);
+var InjectionToken = class {
+	key;
+	constructor(description) {
+		this.description = description;
+		this.key = Symbol(description);
+	}
+	toString() {
+		return `InjectionToken(${this.description})`;
+	}
+};
+var ContainerResolutionError = class extends Error {
+	constructor(message, path) {
+		super(`${message}\nResolution path: ${path.map(describeToken).join(" -> ")}`);
+		this.path = path;
+		this.name = "ContainerResolutionError";
+	}
+};
+var Container = class Container {
+	static activeScope = new AsyncLocalStorage();
+	static containers = /* @__PURE__ */ new Set();
+	static globalContainer = new Container();
+	registry = /* @__PURE__ */ new Map();
+	instances = /* @__PURE__ */ new Map();
+	pending = /* @__PURE__ */ new Map();
+	constructor(parent, context, requestScope = false) {
+		this.parent = parent;
+		this.context = context;
+		this.requestScope = requestScope;
+	}
+	static get global() {
+		return this.globalContainer;
+	}
+	static current() {
+		return this.activeScope.getStore() ?? this.globalContainer;
+	}
+	static run(container, callback) {
+		return this.activeScope.run(container, callback);
+	}
+	static create(parent = this.globalContainer) {
+		const container = new Container(parent);
+		this.containers.add(container);
+		return container;
+	}
+	createRequestScope(ctx) {
+		return new Container(this, ctx, true);
+	}
+	static bind(token, value, options) {
+		this.globalContainer.bind(token, value, options);
 	}
 	static unbind(token) {
-		this.registry.delete(token);
+		this.globalContainer.unbind(token);
 	}
 	static clear() {
-		this.registry.clear();
+		this.globalContainer.clear();
+		for (const container of this.containers) container.clear();
 	}
 	static has(token) {
-		return this.registry.has(token) || Boolean(this.findEquivalentToken(token));
+		return this.current().has(token);
 	}
 	static bindings() {
-		return Object.fromEntries(this.registry.entries());
+		return this.current().bindings();
 	}
 	static async resolve(token, ctx, autoDiscover = false) {
-		if (token === Request) return ctx.clearRequest;
-		if (token === Response) return ctx.clearResponse;
-		const binding = this.getBinding(token);
-		if (binding) return this.resolveBinding(binding, ctx, autoDiscover);
-		if (autoDiscover && typeof token === "function") return new token();
-	}
-	static getBinding(token) {
-		if (this.registry.has(token)) return this.registry.get(token);
+		return this.current().resolve(token, ctx, autoDiscover);
+	}
+	bind(token, value, options) {
+		this.registry.set(token, normalizeProvider(value, options));
+		this.instances.delete(token);
+	}
+	unbind(token) {
+		this.registry.delete(token);
+		this.instances.delete(token);
+	}
+	clear() {
+		this.registry.clear();
+		this.instances.clear();
+		this.pending.clear();
+	}
+	has(token) {
+		return Boolean(this.findProvider(token));
+	}
+	entries() {
+		const entries = /* @__PURE__ */ new Map();
+		for (const container of this.lineage().reverse()) for (const [token, provider] of container.registry) entries.set(token, provider);
+		return entries;
+	}
+	bindings() {
+		return Object.fromEntries(Array.from(this.entries(), ([token, provider]) => [describeToken(token), provider]));
+	}
+	async resolve(token, ctx = this.context, autoDiscover = false) {
+		return this.resolveToken(token, ctx, {
+			autoDiscover,
+			stack: []
+		});
+	}
+	async resolveOrFail(token, ctx = this.context, autoDiscover = false) {
+		const resolved = await this.resolve(token, ctx, autoDiscover);
+		if (typeof resolved === "undefined") throw new ContainerResolutionError(`Cannot resolve ${describeToken(token)}`, [token]);
+		return resolved;
+	}
+	async resolveToken(token, ctx, state) {
+		if (token === Request) return ctx?.clearRequest;
+		if (token === Response) return ctx?.clearResponse;
+		if (state.stack.includes(token)) throw new ContainerResolutionError(`Circular dependency detected while resolving ${describeToken(token)}`, [...state.stack, token]);
+		const nextState = {
+			...state,
+			stack: [...state.stack, token]
+		};
+		const found = this.findProvider(token);
+		if (found) return this.resolveProvider(found.token, found.provider, found.owner, ctx, nextState);
+		if (state.autoDiscover && typeof token === "function") return this.instantiate(token, void 0, ctx, nextState);
+	}
+	findProvider(token) {
+		if (this.registry.has(token)) return {
+			token,
+			provider: this.registry.get(token),
+			owner: this
+		};
 		const equivalent = this.findEquivalentToken(token);
-		return equivalent ? this.registry.get(equivalent) : void 0;
+		if (equivalent) return {
+			token: equivalent,
+			provider: this.registry.get(equivalent),
+			owner: this
+		};
+		return this.parent?.findProvider(token);
+	}
+	async resolveProvider(token, provider, owner, ctx, state) {
+		if ("useExisting" in provider) return this.resolveToken(provider.useExisting, ctx, state);
+		const cache = provider.scope === "singleton" ? owner : provider.scope === "request" ? this.findRequestScope() : void 0;
+		if (cache?.instances.has(token)) return cache.instances.get(token);
+		if (cache?.pending.has(token)) return cache.pending.get(token);
+		const create = async () => {
+			if ("useValue" in provider) return provider.useValue;
+			if ("useClass" in provider) return this.instantiate(provider.useClass, provider.dependencies, ctx, state);
+			return provider.useFactory(ctx);
+		};
+		if (!cache) return create();
+		const promise = create();
+		cache.pending.set(token, promise);
+		try {
+			const resolved = await promise;
+			if (typeof resolved !== "undefined") cache.instances.set(token, resolved);
+			return resolved;
+		} finally {
+			cache.pending.delete(token);
+		}
+	}
+	async instantiate(Type, dependencies, ctx, state) {
+		const tokens = dependencies ?? getInjectTokens(Type);
+		const args = [];
+		for (const dependency of tokens) {
+			const resolved = await this.resolveToken(dependency, ctx, state);
+			if (typeof resolved === "undefined") throw new ContainerResolutionError(`Cannot resolve ${describeToken(dependency)} required by ${describeToken(Type)}`, [...state.stack, dependency]);
+			args.push(resolved);
+		}
+		return new Type(...args);
 	}
-	static findEquivalentToken(token) {
+	findRequestScope() {
+		if (this.requestScope) return this;
+		return this.parent?.findRequestScope();
+	}
+	lineage() {
+		return [this, ...this.parent?.lineage() ?? []];
+	}
+	findEquivalentToken(token) {
+		if (typeof token !== "function") return void 0;
 		const name = token.name;
-		if (!name) return;
+		if (!name) return void 0;
 		const tokenParent = Object.getPrototypeOf(token);
 		const tokenProps = this.getComparableStaticProps(token);
 		for (const registered of this.registry.keys()) {
-			if (registered === token) continue;
-			if (registered.name !== name) continue;
+			if (typeof registered !== "function" || registered === token || registered.name !== name) continue;
 			const registeredParent = Object.getPrototypeOf(registered);
 			if (tokenParent && registeredParent && tokenParent.name !== registeredParent.name) continue;
 			const registeredProps = this.getComparableStaticProps(registered);
-			if (!this.staticPropsMatch(token, registered, tokenProps, registeredProps)) continue;
-			return registered;
+			if (this.staticPropsMatch(token, registered, tokenProps, registeredProps)) return registered;
 		}
 	}
-	static getComparableStaticProps(token) {
+	getComparableStaticProps(token) {
 		return Object.getOwnPropertyNames(token).filter((prop) => {
 			return ![
 				"length",
@@ -59,23 +194,38 @@ var Container = class {
 			].includes(prop);
 		});
 	}
-	static staticPropsMatch(token, registered, tokenProps, registeredProps) {
+	staticPropsMatch(token, registered, tokenProps, registeredProps) {
 		if (tokenProps.length !== registeredProps.length) return false;
-		for (const prop of tokenProps) {
-			if (!registeredProps.includes(prop)) return false;
-			if (Reflect.get(token, prop) !== Reflect.get(registered, prop)) return false;
-		}
+		for (const prop of tokenProps) if (!registeredProps.includes(prop) || Reflect.get(token, prop) !== Reflect.get(registered, prop)) return false;
 		return true;
 	}
-	static async resolveBinding(binding, ctx, autoDiscover) {
-		if (!binding) return void 0;
-		if (typeof binding !== "function") return binding;
-		if (isClass(binding)) return new binding();
-		const resolved = await binding(ctx);
-		if (typeof resolved === "function" && autoDiscover && isClass(resolved)) return new resolved();
-		return resolved;
-	}
 };
+function normalizeProvider(value, options) {
+	if (isProvider(value)) return {
+		scope: "transient",
+		...value
+	};
+	if (isClass(value)) return {
+		useClass: value,
+		scope: options?.scope ?? "transient"
+	};
+	if (typeof value === "function") return {
+		useFactory: value,
+		scope: options?.scope ?? "transient"
+	};
+	return { useValue: value };
+}
+function isProvider(value) {
+	return Boolean(value && typeof value === "object" && ("useValue" in value || "useClass" in value || "useFactory" in value || "useExisting" in value));
+}
+function getInjectTokens(Type) {
+	return Type.inject ?? getDesignParamTypes(Type);
+}
+function describeToken(token) {
+	if (token instanceof InjectionToken) return token.toString();
+	if (typeof token === "symbol") return token.description ?? token.toString();
+	return token.name || "<anonymous class>";
+}
 function Bind(...tokens) {
 	return ((target, propertyKeyOrContext) => {
 		if (isStandardClassContext(propertyKeyOrContext)) {
@@ -103,6 +253,9 @@ function Bind(...tokens) {
 		});
 	});
 }
+function getMetadataKey() {
+	return metadataKey;
+}
 function getStandardMetadata(metadata, propertyKey) {
 	const store = metadata && metadata[metadataKey];
 	if (!store) return void 0;
@@ -151,4 +304,4 @@ function isClass(value) {
 }
 
 //#endregion
-export { Bind, Container, getBindingMetadataFromTargets, getDesignParamTypes, getStandardMetadata, isClass };
+export { Bind, Container, ContainerResolutionError, InjectionToken, getBindingMetadata, getBindingMetadataFromTargets, getDesignParamTypes, getMetadataKey, getStandardMetadata, isClass, setBindingMetadata, setStandardMetadata };

package/dist/core/index.cjs

@@ -3,13 +3,29 @@ const require_helpers = require('./helpers.cjs');
 const require_RouteGroup = require('../RouteGroup.cjs');
 const require_Request = require('./Request.cjs');
 const require_Response = require('./Response.cjs');
+const require_bindings = require('./bindings.cjs');
 const require_plugins = require('./plugins.cjs');
+const require_middleware = require('../decorators/middleware.cjs');
 const require_CoreRouter = require('./CoreRouter.cjs');
 
+exports.Bind = require_bindings.Bind;
+exports.Container = require_bindings.Container;
+exports.ContainerResolutionError = require_bindings.ContainerResolutionError;
 exports.CoreRouter = require_CoreRouter.CoreRouter;
+exports.InjectionToken = require_bindings.InjectionToken;
 exports.Request = require_Request.Request;
 exports.Response = require_Response.Response;
 exports.RouteGroup = require_RouteGroup.RouteGroup;
 exports.definePlugin = require_plugins.definePlugin;
+exports.getBindingMetadata = require_bindings.getBindingMetadata;
+exports.getBindingMetadataFromTargets = require_bindings.getBindingMetadataFromTargets;
+exports.getControllerMiddlewares = require_middleware.getControllerMiddlewares;
+exports.getDesignParamTypes = require_bindings.getDesignParamTypes;
+exports.getMetadataKey = require_bindings.getMetadataKey;
+exports.getStandardMetadata = require_bindings.getStandardMetadata;
 exports.importFile = require_helpers.importFile;
+exports.isClass = require_bindings.isClass;
+exports.middleware = require_middleware.middleware;
+exports.setBindingMetadata = require_bindings.setBindingMetadata;
+exports.setStandardMetadata = require_bindings.setStandardMetadata;
 exports.wrap = require_helpers.wrap;

package/dist/core/index.d.cts

@@ -1,7 +1,9 @@
 import { Response } from "./Response.cjs";
 import { Request } from "./Request.cjs";
+import { Bind, BindClass, BindDecorator, BindFactory, BindProvider, BindToken, BindValue, BindingOptions, BindingScope, ClassProvider, Container, ContainerResolutionError, ExistingProvider, FactoryProvider, InjectionToken, ValueProvider, getBindingMetadata, getBindingMetadataFromTargets, getDesignParamTypes, getMetadataKey, getStandardMetadata, isClass, setBindingMetadata, setStandardMetadata } from "./bindings.cjs";
 import { ClearRouterPlugin, ClearRouterPluginArgumentsContext, ClearRouterPluginContext, ClearRouterPluginInput, ClearRouterPluginRequestContext, PluginArgumentsResolver, PluginBind, PluginBindFactory, PluginBindValue, PluginSetupResult, definePlugin } from "./plugins.cjs";
+import { MiddlewareDecorator, MiddlewareInput, getControllerMiddlewares, middleware } from "../decorators/middleware.cjs";
 import { RouteGroup } from "../RouteGroup.cjs";
 import { CoreRouter } from "./CoreRouter.cjs";
 import { importFile, wrap } from "./helpers.cjs";
-export { ClearRouterPlugin, ClearRouterPluginArgumentsContext, ClearRouterPluginContext, ClearRouterPluginInput, ClearRouterPluginRequestContext, CoreRouter, PluginArgumentsResolver, PluginBind, PluginBindFactory, PluginBindValue, PluginSetupResult, Request, Response, RouteGroup, definePlugin, importFile, wrap };
+export { Bind, BindClass, BindDecorator, BindFactory, BindProvider, BindToken, BindValue, BindingOptions, BindingScope, ClassProvider, ClearRouterPlugin, ClearRouterPluginArgumentsContext, ClearRouterPluginContext, ClearRouterPluginInput, ClearRouterPluginRequestContext, Container, ContainerResolutionError, CoreRouter, ExistingProvider, FactoryProvider, InjectionToken, MiddlewareDecorator, MiddlewareInput, PluginArgumentsResolver, PluginBind, PluginBindFactory, PluginBindValue, PluginSetupResult, Request, Response, RouteGroup, ValueProvider, definePlugin, getBindingMetadata, getBindingMetadataFromTargets, getControllerMiddlewares, getDesignParamTypes, getMetadataKey, getStandardMetadata, importFile, isClass, middleware, setBindingMetadata, setStandardMetadata, wrap };

package/dist/core/index.d.mts

@@ -1,7 +1,9 @@
 import { Response } from "./Response.mjs";
 import { Request } from "./Request.mjs";
+import { Bind, BindClass, BindDecorator, BindFactory, BindProvider, BindToken, BindValue, BindingOptions, BindingScope, ClassProvider, Container, ContainerResolutionError, ExistingProvider, FactoryProvider, InjectionToken, ValueProvider, getBindingMetadata, getBindingMetadataFromTargets, getDesignParamTypes, getMetadataKey, getStandardMetadata, isClass, setBindingMetadata, setStandardMetadata } from "./bindings.mjs";
 import { ClearRouterPlugin, ClearRouterPluginArgumentsContext, ClearRouterPluginContext, ClearRouterPluginInput, ClearRouterPluginRequestContext, PluginArgumentsResolver, PluginBind, PluginBindFactory, PluginBindValue, PluginSetupResult, definePlugin } from "./plugins.mjs";
+import { MiddlewareDecorator, MiddlewareInput, getControllerMiddlewares, middleware } from "../decorators/middleware.mjs";
 import { RouteGroup } from "../RouteGroup.mjs";
 import { CoreRouter } from "./CoreRouter.mjs";
 import { importFile, wrap } from "./helpers.mjs";
-export { ClearRouterPlugin, ClearRouterPluginArgumentsContext, ClearRouterPluginContext, ClearRouterPluginInput, ClearRouterPluginRequestContext, CoreRouter, PluginArgumentsResolver, PluginBind, PluginBindFactory, PluginBindValue, PluginSetupResult, Request, Response, RouteGroup, definePlugin, importFile, wrap };
+export { Bind, BindClass, BindDecorator, BindFactory, BindProvider, BindToken, BindValue, BindingOptions, BindingScope, ClassProvider, ClearRouterPlugin, ClearRouterPluginArgumentsContext, ClearRouterPluginContext, ClearRouterPluginInput, ClearRouterPluginRequestContext, Container, ContainerResolutionError, CoreRouter, ExistingProvider, FactoryProvider, InjectionToken, MiddlewareDecorator, MiddlewareInput, PluginArgumentsResolver, PluginBind, PluginBindFactory, PluginBindValue, PluginSetupResult, Request, Response, RouteGroup, ValueProvider, definePlugin, getBindingMetadata, getBindingMetadataFromTargets, getControllerMiddlewares, getDesignParamTypes, getMetadataKey, getStandardMetadata, importFile, isClass, middleware, setBindingMetadata, setStandardMetadata, wrap };

package/dist/core/index.mjs

@@ -2,7 +2,9 @@ import { importFile, wrap } from "./helpers.mjs";
 import { RouteGroup } from "../RouteGroup.mjs";
 import { Request } from "./Request.mjs";
 import { Response } from "./Response.mjs";
+import { Bind, Container, ContainerResolutionError, InjectionToken, getBindingMetadata, getBindingMetadataFromTargets, getDesignParamTypes, getMetadataKey, getStandardMetadata, isClass, setBindingMetadata, setStandardMetadata } from "./bindings.mjs";
 import { definePlugin } from "./plugins.mjs";
+import { getControllerMiddlewares, middleware } from "../decorators/middleware.mjs";
 import { CoreRouter } from "./CoreRouter.mjs";
 
-export { CoreRouter, Request, Response, RouteGroup, definePlugin, importFile, wrap };
+export { Bind, Container, ContainerResolutionError, CoreRouter, InjectionToken, Request, Response, RouteGroup, definePlugin, getBindingMetadata, getBindingMetadataFromTargets, getControllerMiddlewares, getDesignParamTypes, getMetadataKey, getStandardMetadata, importFile, isClass, middleware, setBindingMetadata, setStandardMetadata, wrap };

package/dist/core/plugins.d.cts

@@ -1,7 +1,7 @@
 import { Response } from "./Response.cjs";
 import { RouterConfig } from "../types/basic.cjs";
 import { Request } from "./Request.cjs";
-import { BindToken, BindValue, Container } from "./bindings.cjs";
+import { BindToken, BindValue, BindingOptions, Container } from "./bindings.cjs";
 
 //#region src/core/plugins.d.ts
 type PluginSetupResult = void | Promise<void>;
@@ -22,13 +22,13 @@ interface ClearRouterPluginArgumentsContext<X = any> extends ClearRouterPluginRe
 }
 type PluginBindFactory<T = any, X = any> = (ctx: ClearRouterPluginRequestContext<X>) => T | Promise<T>;
 type PluginBindValue<T = any, X = any> = BindValue<T> | PluginBindFactory<T, X>;
-type PluginBind<X = any> = <T>(token: BindToken<T>, value: PluginBindValue<T, X>) => void;
+type PluginBind<X = any> = <T>(token: BindToken<T>, value: PluginBindValue<T, X>, options?: BindingOptions) => void;
 type PluginArgumentsResolver<HttpContext = any> = (ctx: ClearRouterPluginArgumentsContext<HttpContext>) => any[] | undefined | Promise<any[] | undefined>;
 interface ClearRouterPluginContext<Options = any, HttpContext = any> {
   /**
    * The service container
    */
-  container: typeof Container;
+  container: Container;
   /**
    * Register service container bindings
    */
@@ -97,7 +97,7 @@ interface ClearRouterPlugin<Options = any, HttpContext = any> {
    */
   setup: (ctx: ClearRouterPluginContext<Options, HttpContext>) => PluginSetupResult;
 }
-type ClearRouterPluginInput<Options = any, HttpContext = any> = ClearRouterPlugin<Options> | ((ctx: ClearRouterPluginContext<Options, HttpContext>) => PluginSetupResult);
+type ClearRouterPluginInput<Options = any, HttpContext = any> = ClearRouterPlugin<Options, HttpContext> | ((ctx: ClearRouterPluginContext<Options, HttpContext>) => PluginSetupResult);
 /**
  * Creates a new plugin
  *

package/dist/core/plugins.d.mts

@@ -1,7 +1,7 @@
 import { Response } from "./Response.mjs";
 import { RouterConfig } from "../types/basic.mjs";
 import { Request } from "./Request.mjs";
-import { BindToken, BindValue, Container } from "./bindings.mjs";
+import { BindToken, BindValue, BindingOptions, Container } from "./bindings.mjs";
 
 //#region src/core/plugins.d.ts
 type PluginSetupResult = void | Promise<void>;
@@ -22,13 +22,13 @@ interface ClearRouterPluginArgumentsContext<X = any> extends ClearRouterPluginRe
 }
 type PluginBindFactory<T = any, X = any> = (ctx: ClearRouterPluginRequestContext<X>) => T | Promise<T>;
 type PluginBindValue<T = any, X = any> = BindValue<T> | PluginBindFactory<T, X>;
-type PluginBind<X = any> = <T>(token: BindToken<T>, value: PluginBindValue<T, X>) => void;
+type PluginBind<X = any> = <T>(token: BindToken<T>, value: PluginBindValue<T, X>, options?: BindingOptions) => void;
 type PluginArgumentsResolver<HttpContext = any> = (ctx: ClearRouterPluginArgumentsContext<HttpContext>) => any[] | undefined | Promise<any[] | undefined>;
 interface ClearRouterPluginContext<Options = any, HttpContext = any> {
   /**
    * The service container
    */
-  container: typeof Container;
+  container: Container;
   /**
    * Register service container bindings
    */
@@ -97,7 +97,7 @@ interface ClearRouterPlugin<Options = any, HttpContext = any> {
    */
   setup: (ctx: ClearRouterPluginContext<Options, HttpContext>) => PluginSetupResult;
 }
-type ClearRouterPluginInput<Options = any, HttpContext = any> = ClearRouterPlugin<Options> | ((ctx: ClearRouterPluginContext<Options, HttpContext>) => PluginSetupResult);
+type ClearRouterPluginInput<Options = any, HttpContext = any> = ClearRouterPlugin<Options, HttpContext> | ((ctx: ClearRouterPluginContext<Options, HttpContext>) => PluginSetupResult);
 /**
  * Creates a new plugin
  *

package/dist/decorators/index.cjs

@@ -1,5 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_bindings = require('../core/bindings.cjs');
+const require_middleware = require('./middleware.cjs');
 
 exports.Bind = require_bindings.Bind;
-exports.Container = require_bindings.Container;
+exports.Container = require_bindings.Container;
+exports.ContainerResolutionError = require_bindings.ContainerResolutionError;
+exports.InjectionToken = require_bindings.InjectionToken;
+exports.getControllerMiddlewares = require_middleware.getControllerMiddlewares;
+exports.middleware = require_middleware.middleware;

package/dist/decorators/index.d.cts

@@ -1,2 +1,3 @@
-import { Bind, BindDecorator, BindFactory, BindToken, BindValue, Container } from "../core/bindings.cjs";
-export { Bind, type BindDecorator, type BindFactory, type BindToken, type BindValue, Container };
+import { Bind, BindClass, BindDecorator, BindFactory, BindProvider, BindToken, BindValue, BindingOptions, BindingScope, ClassProvider, Container, ContainerResolutionError, ExistingProvider, FactoryProvider, InjectionToken, ValueProvider } from "../core/bindings.cjs";
+import { MiddlewareDecorator, MiddlewareInput, getControllerMiddlewares, middleware } from "./middleware.cjs";
+export { Bind, type BindClass, type BindDecorator, type BindFactory, type BindProvider, type BindToken, type BindValue, type BindingOptions, type BindingScope, type ClassProvider, Container, ContainerResolutionError, type ExistingProvider, type FactoryProvider, InjectionToken, type MiddlewareDecorator, type MiddlewareInput, type ValueProvider, getControllerMiddlewares, middleware };

package/dist/decorators/index.d.mts

@@ -1,2 +1,3 @@
-import { Bind, BindDecorator, BindFactory, BindToken, BindValue, Container } from "../core/bindings.mjs";
-export { Bind, type BindDecorator, type BindFactory, type BindToken, type BindValue, Container };
+import { Bind, BindClass, BindDecorator, BindFactory, BindProvider, BindToken, BindValue, BindingOptions, BindingScope, ClassProvider, Container, ContainerResolutionError, ExistingProvider, FactoryProvider, InjectionToken, ValueProvider } from "../core/bindings.mjs";
+import { MiddlewareDecorator, MiddlewareInput, getControllerMiddlewares, middleware } from "./middleware.mjs";
+export { Bind, type BindClass, type BindDecorator, type BindFactory, type BindProvider, type BindToken, type BindValue, type BindingOptions, type BindingScope, type ClassProvider, Container, ContainerResolutionError, type ExistingProvider, type FactoryProvider, InjectionToken, type MiddlewareDecorator, type MiddlewareInput, type ValueProvider, getControllerMiddlewares, middleware };

package/dist/decorators/index.mjs

@@ -1,3 +1,4 @@
-import { Bind, Container } from "../core/bindings.mjs";
+import { Bind, Container, ContainerResolutionError, InjectionToken } from "../core/bindings.mjs";
+import { getControllerMiddlewares, middleware } from "./middleware.mjs";
 
-export { Bind, Container };
+export { Bind, Container, ContainerResolutionError, InjectionToken, getControllerMiddlewares, middleware };

package/dist/decorators/middleware.cjs

@@ -0,0 +1,100 @@
+
+//#region src/decorators/middleware.ts
+const CLASS_KEY = "__class__";
+const metadataKey = Symbol.for("clear-router:middleware-metadata");
+const store = /* @__PURE__ */ new WeakMap();
+/**
+* Attach one or more middleware to a controller class or a controller method.
+*
+* @example
+* ```ts
+* @Middleware([auth])
+* class AccountController {}
+*
+* class LoginController {
+*     @Middleware(GuestMiddleware)
+*     create () {}
+* }
+* ```
+*
+* Accepts the middleware variadically or as arrays, and every supported
+* middleware shape: callbacks, middleware classes, or instances exposing a
+* `handle` method.
+*
+* @param middlewares
+* @returns
+*/
+function middleware(...middlewares) {
+	const flattened = middlewares.flat();
+	return ((target, propertyKeyOrContext) => {
+		if (isStandardClassContext(propertyKeyOrContext)) {
+			setClassMiddlewareMetadata(target, flattened);
+			setStandardMetadata(propertyKeyOrContext.metadata, CLASS_KEY, flattened);
+			return;
+		}
+		if (isStandardMethodContext(propertyKeyOrContext)) {
+			setStandardMetadata(propertyKeyOrContext.metadata, propertyKeyOrContext.name, flattened);
+			return;
+		}
+		if (typeof propertyKeyOrContext === "undefined") {
+			setClassMiddlewareMetadata(target, flattened);
+			return;
+		}
+		setMiddlewareMetadata(target, propertyKeyOrContext, flattened);
+	});
+}
+/**
+* Collect the decorator-declared middleware for a controller route handler,
+* ordered class-level first then method-level. Returns an empty array for
+* non-controller (callback) handlers or handlers without any decorators.
+*
+* @param handler
+* @returns
+*/
+function getControllerMiddlewares(handler) {
+	if (!Array.isArray(handler) || handler.length !== 2) return [];
+	const [controller, method] = handler;
+	if (!controller) return [];
+	const constructor = typeof controller === "function" ? controller : controller.constructor;
+	const prototype = typeof controller === "function" ? controller.prototype : Object.getPrototypeOf(controller);
+	const standardMetadata = constructor?.[Symbol.metadata];
+	const classMiddlewares = getMiddlewareMetadata(constructor, CLASS_KEY) ?? getMiddlewareMetadata(prototype, CLASS_KEY) ?? getStandardMetadata(standardMetadata, CLASS_KEY) ?? [];
+	const methodMiddlewares = getMiddlewareMetadata(prototype, method) ?? getMiddlewareMetadata(constructor, method) ?? getStandardMetadata(standardMetadata, method) ?? [];
+	return [...classMiddlewares, ...methodMiddlewares];
+}
+function setClassMiddlewareMetadata(target, middlewares) {
+	setMiddlewareMetadata(target, CLASS_KEY, middlewares);
+	const prototype = target.prototype;
+	if (prototype) setMiddlewareMetadata(prototype, CLASS_KEY, middlewares);
+}
+function setMiddlewareMetadata(target, propertyKey, middlewares) {
+	const map = store.get(target) ?? /* @__PURE__ */ new Map();
+	const existing = map.get(propertyKey);
+	map.set(propertyKey, existing ? [...existing, ...middlewares] : middlewares);
+	store.set(target, map);
+}
+function getMiddlewareMetadata(target, propertyKey) {
+	if (!target) return void 0;
+	return store.get(target)?.get(propertyKey);
+}
+function setStandardMetadata(metadata, propertyKey, middlewares) {
+	if (!metadata) return;
+	const record = metadata;
+	record[metadataKey] = record[metadataKey] ?? {};
+	const existing = record[metadataKey][propertyKey];
+	record[metadataKey][propertyKey] = existing ? [...existing, ...middlewares] : middlewares;
+}
+function getStandardMetadata(metadata, propertyKey) {
+	const record = metadata && metadata[metadataKey];
+	return record ? record[propertyKey] : void 0;
+}
+function isStandardMethodContext(value) {
+	return Boolean(value && typeof value === "object" && value.kind === "method" && typeof value.name !== "undefined");
+}
+function isStandardClassContext(value) {
+	return Boolean(value && typeof value === "object" && value.kind === "class" && typeof value.name !== "undefined");
+}
+
+//#endregion
+exports.getControllerMiddlewares = getControllerMiddlewares;
+exports.middleware = middleware;

package/dist/decorators/middleware.d.cts

@@ -0,0 +1,51 @@
+import { ClassMiddleware, MiddlewareHandle } from "../types/basic.cjs";
+
+//#region src/decorators/middleware.d.ts
+/**
+ * Any value accepted as a middleware by the router: a plain callback, a class
+ * exposing a `handle` method, or an already-instantiated object exposing one.
+ */
+type MiddlewareInput = MiddlewareHandle | ClassMiddleware;
+/**
+ * Decorator produced by {@link Middleware}. Works both as a class decorator (to
+ * apply the middleware to every action of a controller) and as a method
+ * decorator (to apply it to a single action). Supports the legacy
+ * (`experimentalDecorators`) and TC39 standard decorator signatures.
+ */
+type MiddlewareDecorator = MethodDecorator & ClassDecorator & {
+  <This, Value extends (this: This, ...args: any[]) => any>(value: Value, context: ClassMethodDecoratorContext<This, Value>): void | Value;
+  <Value extends abstract new (...args: any[]) => any>(value: Value, context: ClassDecoratorContext<Value>): void | Value;
+};
+/**
+ * Attach one or more middleware to a controller class or a controller method.
+ *
+ * @example
+ * ```ts
+ * @Middleware([auth])
+ * class AccountController {}
+ *
+ * class LoginController {
+ *     @Middleware(GuestMiddleware)
+ *     create () {}
+ * }
+ * ```
+ *
+ * Accepts the middleware variadically or as arrays, and every supported
+ * middleware shape: callbacks, middleware classes, or instances exposing a
+ * `handle` method.
+ *
+ * @param middlewares
+ * @returns
+ */
+declare function middleware(...middlewares: Array<MiddlewareInput | MiddlewareInput[]>): MiddlewareDecorator;
+/**
+ * Collect the decorator-declared middleware for a controller route handler,
+ * ordered class-level first then method-level. Returns an empty array for
+ * non-controller (callback) handlers or handlers without any decorators.
+ *
+ * @param handler
+ * @returns
+ */
+declare function getControllerMiddlewares(handler: any): MiddlewareInput[];
+//#endregion
+export { MiddlewareDecorator, MiddlewareInput, getControllerMiddlewares, middleware };

package/dist/decorators/middleware.d.mts

@@ -0,0 +1,51 @@
+import { ClassMiddleware, MiddlewareHandle } from "../types/basic.mjs";
+
+//#region src/decorators/middleware.d.ts
+/**
+ * Any value accepted as a middleware by the router: a plain callback, a class
+ * exposing a `handle` method, or an already-instantiated object exposing one.
+ */
+type MiddlewareInput = MiddlewareHandle | ClassMiddleware;
+/**
+ * Decorator produced by {@link Middleware}. Works both as a class decorator (to
+ * apply the middleware to every action of a controller) and as a method
+ * decorator (to apply it to a single action). Supports the legacy
+ * (`experimentalDecorators`) and TC39 standard decorator signatures.
+ */
+type MiddlewareDecorator = MethodDecorator & ClassDecorator & {
+  <This, Value extends (this: This, ...args: any[]) => any>(value: Value, context: ClassMethodDecoratorContext<This, Value>): void | Value;
+  <Value extends abstract new (...args: any[]) => any>(value: Value, context: ClassDecoratorContext<Value>): void | Value;
+};
+/**
+ * Attach one or more middleware to a controller class or a controller method.
+ *
+ * @example
+ * ```ts
+ * @Middleware([auth])
+ * class AccountController {}
+ *
+ * class LoginController {
+ *     @Middleware(GuestMiddleware)
+ *     create () {}
+ * }
+ * ```
+ *
+ * Accepts the middleware variadically or as arrays, and every supported
+ * middleware shape: callbacks, middleware classes, or instances exposing a
+ * `handle` method.
+ *
+ * @param middlewares
+ * @returns
+ */
+declare function middleware(...middlewares: Array<MiddlewareInput | MiddlewareInput[]>): MiddlewareDecorator;
+/**
+ * Collect the decorator-declared middleware for a controller route handler,
+ * ordered class-level first then method-level. Returns an empty array for
+ * non-controller (callback) handlers or handlers without any decorators.
+ *
+ * @param handler
+ * @returns
+ */
+declare function getControllerMiddlewares(handler: any): MiddlewareInput[];
+//#endregion
+export { MiddlewareDecorator, MiddlewareInput, getControllerMiddlewares, middleware };