clear-router 2.5.5 → 2.5.7

package/README.md

@@ -51,6 +51,7 @@ yarn add clear-router express
 - `clearRequest` is passed as second handler argument for controller handlers
 - Route handlers can return response values directly across Express, Fastify, Hono, H3, and Koa
 - Optional decorated container binding for controller method arguments
+- Plugin API for registering container bindings from external packages
 - Supports TS 5.2+ standard decorators with explicit `@Bind(...)` tokens
 - Optional `clear-router/decorators/setup` entry imports `reflect-metadata` and enables container binding defaults
 - Auto-binds controller methods

package/dist/core/index.cjs

@@ -1,7 +1,14 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_bindings = require('../bindings-DvV2DXWi.cjs');
-const require_router = require('../router-CCUF5FE7.cjs');
+const require_router = require('../router-BdMuUzGU.cjs');
 
+//#region src/core/plugins.ts
+function definePlugin(plugin) {
+	return plugin;
+}
+
+//#endregion
 exports.CoreRouter = require_router.CoreRouter;
 exports.Request = require_bindings.Request;
-exports.Response = require_bindings.Response;
+exports.Response = require_bindings.Response;
+exports.definePlugin = definePlugin;

package/dist/core/index.d.cts

@@ -1,2 +1,2 @@
-import { h as Response, n as Request, t as CoreRouter } from "../router-78fDk87B.cjs";
-export { CoreRouter, Request, Response };
+import { a as PluginBind, c as Request, i as ClearRouterPluginInput, n as ClearRouterPlugin, o as PluginSetupResult, r as ClearRouterPluginContext, s as definePlugin, t as CoreRouter, x as Response } from "../router-WAxKAcWR.cjs";
+export { ClearRouterPlugin, ClearRouterPluginContext, ClearRouterPluginInput, CoreRouter, PluginBind, PluginSetupResult, Request, Response, definePlugin };

package/dist/core/index.d.mts

@@ -1,2 +1,2 @@
-import { h as Response, n as Request, t as CoreRouter } from "../router-BdfAh1me.mjs";
-export { CoreRouter, Request, Response };
+import { a as PluginBind, c as Request, i as ClearRouterPluginInput, n as ClearRouterPlugin, o as PluginSetupResult, r as ClearRouterPluginContext, s as definePlugin, t as CoreRouter, x as Response } from "../router-D7R3G8w-.mjs";
+export { ClearRouterPlugin, ClearRouterPluginContext, ClearRouterPluginInput, CoreRouter, PluginBind, PluginSetupResult, Request, Response, definePlugin };

package/dist/core/index.mjs

@@ -1,4 +1,10 @@
 import { o as Response, s as Request } from "../bindings-DIanvIVd.mjs";
-import { t as CoreRouter } from "../router-BAWdklDQ.mjs";
+import { t as CoreRouter } from "../router-DzbF-ZV0.mjs";
 
-export { CoreRouter, Request, Response };
+//#region src/core/plugins.ts
+function definePlugin(plugin) {
+	return plugin;
+}
+
+//#endregion
+export { CoreRouter, Request, Response, definePlugin };

package/dist/decorators/index.d.cts

@@ -1,2 +1,2 @@
-import { a as BindValue, i as BindToken, n as BindDecorator, o as Container, r as BindFactory, t as Bind } from "../bindings-BL1d0dFY.cjs";
+import { a as BindValue, i as BindToken, n as BindDecorator, o as Container, r as BindFactory, t as Bind } from "../bindings-NV0CdqGl.cjs";
 export { Bind, type BindDecorator, type BindFactory, type BindToken, type BindValue, Container };

package/dist/decorators/index.d.mts

@@ -1,2 +1,2 @@
-import { a as BindValue, i as BindToken, n as BindDecorator, o as Container, r as BindFactory, t as Bind } from "../bindings-DqvZ9-YW.mjs";
+import { a as BindValue, i as BindToken, n as BindDecorator, o as Container, r as BindFactory, t as Bind } from "../bindings-CV1e5jho.mjs";
 export { Bind, type BindDecorator, type BindFactory, type BindToken, type BindValue, Container };

package/dist/decorators/setup.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_bindings = require('../bindings-DvV2DXWi.cjs');
-const require_router = require('../router-CCUF5FE7.cjs');
+const require_router = require('../router-BdMuUzGU.cjs');
 require('./index.cjs');
 require("reflect-metadata");
 

package/dist/decorators/setup.d.cts

@@ -1,2 +1,2 @@
-import { a as BindValue, i as BindToken, n as BindDecorator, o as Container, r as BindFactory, t as Bind } from "../bindings-BL1d0dFY.cjs";
+import { a as BindValue, i as BindToken, n as BindDecorator, o as Container, r as BindFactory, t as Bind } from "../bindings-NV0CdqGl.cjs";
 export { Bind, BindDecorator, BindFactory, BindToken, BindValue, Container };

package/dist/decorators/setup.d.mts

@@ -1,2 +1,2 @@
-import { a as BindValue, i as BindToken, n as BindDecorator, o as Container, r as BindFactory, t as Bind } from "../bindings-DqvZ9-YW.mjs";
+import { a as BindValue, i as BindToken, n as BindDecorator, o as Container, r as BindFactory, t as Bind } from "../bindings-CV1e5jho.mjs";
 export { Bind, BindDecorator, BindFactory, BindToken, BindValue, Container };

package/dist/decorators/setup.mjs

@@ -1,5 +1,5 @@
 import { n as Container, t as Bind } from "../bindings-DIanvIVd.mjs";
-import { t as CoreRouter } from "../router-BAWdklDQ.mjs";
+import { t as CoreRouter } from "../router-DzbF-ZV0.mjs";
 import "./index.mjs";
 import "reflect-metadata";
 

package/dist/express/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 require('../bindings-DvV2DXWi.cjs');
-const require_router = require('../router-CCUF5FE7.cjs');
+const require_router = require('../router-BdMuUzGU.cjs');
 const require_responses = require('../responses-JzXstGU5.cjs');
 
 //#region src/express/router.ts

package/dist/express/index.d.cts

@@ -1,4 +1,4 @@
-import { c as Handler, d as ApiResourceMiddleware, f as ControllerAction, l as HttpContext, m as HttpMethod, r as Route, t as CoreRouter, u as Middleware } from "../router-78fDk87B.cjs";
+import { _ as ApiResourceMiddleware, b as HttpMethod, g as Middleware, h as HttpContext, l as Route, m as Handler, t as CoreRouter, v as ControllerAction } from "../router-WAxKAcWR.cjs";
 import { Router as Router$1 } from "express";
 
 //#region src/express/router.d.ts

package/dist/express/index.d.mts

@@ -1,4 +1,4 @@
-import { c as Handler, d as ApiResourceMiddleware, f as ControllerAction, l as HttpContext, m as HttpMethod, r as Route, t as CoreRouter, u as Middleware } from "../router-BdfAh1me.mjs";
+import { _ as ApiResourceMiddleware, b as HttpMethod, g as Middleware, h as HttpContext, l as Route, m as Handler, t as CoreRouter, v as ControllerAction } from "../router-D7R3G8w-.mjs";
 import { Router as Router$1 } from "express";
 
 //#region src/express/router.d.ts

package/dist/express/index.mjs

@@ -1,5 +1,5 @@
 import "../bindings-DIanvIVd.mjs";
-import { t as CoreRouter } from "../router-BAWdklDQ.mjs";
+import { t as CoreRouter } from "../router-DzbF-ZV0.mjs";
 import { n as resolveResponseMeta, r as responseWasSent, t as isFetchResponse } from "../responses-_II3dOJ5.mjs";
 
 //#region src/express/router.ts

package/dist/fastify/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 require('../bindings-DvV2DXWi.cjs');
-const require_router = require('../router-CCUF5FE7.cjs');
+const require_router = require('../router-BdMuUzGU.cjs');
 const require_responses = require('../responses-JzXstGU5.cjs');
 
 //#region src/fastify/router.ts

package/dist/fastify/index.d.cts

@@ -1,4 +1,4 @@
-import { d as ApiResourceMiddleware, f as ControllerAction, h as Response, m as HttpMethod, n as Request, p as ControllerHandler, r as Route, t as CoreRouter } from "../router-78fDk87B.cjs";
+import { _ as ApiResourceMiddleware, b as HttpMethod, c as Request, l as Route, t as CoreRouter, v as ControllerAction, x as Response, y as ControllerHandler } from "../router-WAxKAcWR.cjs";
 import { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 
 //#region types/fastify.d.ts

package/dist/fastify/index.d.mts

@@ -1,4 +1,4 @@
-import { d as ApiResourceMiddleware, f as ControllerAction, h as Response, m as HttpMethod, n as Request, p as ControllerHandler, r as Route, t as CoreRouter } from "../router-BdfAh1me.mjs";
+import { _ as ApiResourceMiddleware, b as HttpMethod, c as Request, l as Route, t as CoreRouter, v as ControllerAction, x as Response, y as ControllerHandler } from "../router-D7R3G8w-.mjs";
 import { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 
 //#region types/fastify.d.ts

package/dist/fastify/index.mjs

@@ -1,5 +1,5 @@
 import "../bindings-DIanvIVd.mjs";
-import { t as CoreRouter } from "../router-BAWdklDQ.mjs";
+import { t as CoreRouter } from "../router-DzbF-ZV0.mjs";
 import { n as resolveResponseMeta, r as responseWasSent, t as isFetchResponse } from "../responses-_II3dOJ5.mjs";
 
 //#region src/fastify/router.ts

package/dist/h3/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 require('../bindings-DvV2DXWi.cjs');
-const require_router = require('../router-CCUF5FE7.cjs');
+const require_router = require('../router-BdMuUzGU.cjs');
 const require_responses = require('../responses-JzXstGU5.cjs');
 let h3 = require("h3");
 

package/dist/h3/index.d.cts

@@ -1,4 +1,4 @@
-import { a as Handler, d as ApiResourceMiddleware, f as ControllerAction, i as H3App, m as HttpMethod, o as HttpContext, r as Route, s as Middleware, t as CoreRouter } from "../router-78fDk87B.cjs";
+import { _ as ApiResourceMiddleware, b as HttpMethod, d as Handler, f as HttpContext, l as Route, p as Middleware, t as CoreRouter, u as H3App, v as ControllerAction } from "../router-WAxKAcWR.cjs";
 import { H3 } from "h3";
 
 //#region src/h3/router.d.ts

package/dist/h3/index.d.mts

@@ -1,4 +1,4 @@
-import { a as Handler, d as ApiResourceMiddleware, f as ControllerAction, i as H3App, m as HttpMethod, o as HttpContext, r as Route, s as Middleware, t as CoreRouter } from "../router-BdfAh1me.mjs";
+import { _ as ApiResourceMiddleware, b as HttpMethod, d as Handler, f as HttpContext, l as Route, p as Middleware, t as CoreRouter, u as H3App, v as ControllerAction } from "../router-D7R3G8w-.mjs";
 import { H3 } from "h3";
 
 //#region src/h3/router.d.ts

package/dist/h3/index.mjs

@@ -1,5 +1,5 @@
 import "../bindings-DIanvIVd.mjs";
-import { t as CoreRouter } from "../router-BAWdklDQ.mjs";
+import { t as CoreRouter } from "../router-DzbF-ZV0.mjs";
 import { n as resolveResponseMeta } from "../responses-_II3dOJ5.mjs";
 import { HTTPResponse, getQuery, getRouterParams, readBody } from "h3";
 

package/dist/hono/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 require('../bindings-DvV2DXWi.cjs');
-const require_router = require('../router-CCUF5FE7.cjs');
+const require_router = require('../router-BdMuUzGU.cjs');
 const require_responses = require('../responses-JzXstGU5.cjs');
 
 //#region src/hono/router.ts

package/dist/hono/index.d.cts

@@ -1,4 +1,4 @@
-import { d as ApiResourceMiddleware, f as ControllerAction, h as Response, m as HttpMethod, n as Request, p as ControllerHandler, r as Route, t as CoreRouter } from "../router-78fDk87B.cjs";
+import { _ as ApiResourceMiddleware, b as HttpMethod, c as Request, l as Route, t as CoreRouter, v as ControllerAction, x as Response, y as ControllerHandler } from "../router-WAxKAcWR.cjs";
 import { Context, HonoRequest, MiddlewareHandler } from "hono";
 
 //#region types/hono.d.ts

package/dist/hono/index.d.mts

@@ -1,4 +1,4 @@
-import { d as ApiResourceMiddleware, f as ControllerAction, h as Response, m as HttpMethod, n as Request, p as ControllerHandler, r as Route, t as CoreRouter } from "../router-BdfAh1me.mjs";
+import { _ as ApiResourceMiddleware, b as HttpMethod, c as Request, l as Route, t as CoreRouter, v as ControllerAction, x as Response, y as ControllerHandler } from "../router-D7R3G8w-.mjs";
 import { Context, HonoRequest, MiddlewareHandler } from "hono";
 
 //#region types/hono.d.ts

package/dist/hono/index.mjs

@@ -1,5 +1,5 @@
 import "../bindings-DIanvIVd.mjs";
-import { t as CoreRouter } from "../router-BAWdklDQ.mjs";
+import { t as CoreRouter } from "../router-DzbF-ZV0.mjs";
 import { n as resolveResponseMeta } from "../responses-_II3dOJ5.mjs";
 
 //#region src/hono/router.ts

package/dist/index.cjs

@@ -141,6 +141,12 @@ var Response = class {
 	}
 };
 
+//#endregion
+//#region src/core/plugins.ts
+function definePlugin(plugin) {
+	return plugin;
+}
+
 //#endregion
 //#region src/core/bindings.ts
 const metadataKey = Symbol.for("clear-router:binding-metadata");
@@ -212,6 +218,8 @@ var CoreRouter = class {
 	static stateStoreKey = Symbol.for("clear-router:router-state");
 	static stateBoundKey = Symbol.for("clear-router:router-state-bound");
 	static defaultConfigKey = Symbol.for("clear-router:default-config");
+	static pluginStoreKey = Symbol.for("clear-router:plugins");
+	static pluginPendingKey = Symbol.for("clear-router:plugin-promises");
 	static createBaseConfig() {
 		return {
 			methodOverride: {
@@ -253,6 +261,16 @@ var CoreRouter = class {
 		if (!g[this.stateStoreKey]) g[this.stateStoreKey] = Object.create(null);
 		return g[this.stateStoreKey];
 	}
+	static getPluginStore() {
+		const g = globalThis;
+		if (!g[this.pluginStoreKey]) g[this.pluginStoreKey] = /* @__PURE__ */ new Set();
+		return g[this.pluginStoreKey];
+	}
+	static getPluginPendingStore() {
+		const g = globalThis;
+		if (!g[this.pluginPendingKey]) g[this.pluginPendingKey] = /* @__PURE__ */ new Set();
+		return g[this.pluginPendingKey];
+	}
 	static createDefaultState() {
 		return {
 			config: this.getDefaultConfig(),
@@ -350,6 +368,47 @@ var CoreRouter = class {
 		const store = this.getStateStore();
 		for (const state of Object.values(store)) state.config = this.mergeConfig(state.config || this.createBaseConfig(), options);
 	}
+	/**
+	* Use a registered plugin
+	* 
+	* @param this 
+	* @param plugin 
+	* @param options 
+	* @returns 
+	*/
+	static async use(plugin, options) {
+		const name = typeof plugin === "function" ? plugin.name : plugin.name;
+		const store = this.getPluginStore();
+		if (name && store.has(name)) return;
+		if (name) store.add(name);
+		const setup = async () => {
+			const ctx = {
+				container: Container,
+				bind: Container.bind.bind(Container),
+				configure: this.configure.bind(this),
+				configureDefaults: this.configureDefaults.bind(this),
+				options
+			};
+			if (typeof plugin === "function") await plugin(ctx);
+			else await plugin.setup(ctx);
+		};
+		const pending = this.getPluginPendingStore();
+		const promise = setup();
+		pending.add(promise);
+		try {
+			await promise;
+		} catch (error) {
+			if (name) store.delete(name);
+			throw error;
+		} finally {
+			pending.delete(promise);
+		}
+	}
+	static async pluginsReady() {
+		const pending = Array.from(this.getPluginPendingStore());
+		if (!pending.length) return;
+		await Promise.all(pending);
+	}
 	static groupContext = new node_async_hooks.AsyncLocalStorage();
 	static routes = [];
 	static routesByPathMethod = {};
@@ -671,6 +730,7 @@ var CoreRouter = class {
 		};
 	}
 	static async callHandler(handlerFunction, ctx, bindingTarget, bindingMethod, bindingHandler, bindingMetadata) {
+		await this.pluginsReady();
 		if (!this.config.container?.enabled) return handlerFunction(ctx, ctx.clearRequest);
 		const metadata = getBindingMetadataFromTargets([
 			{
@@ -730,4 +790,5 @@ exports.Controller = Controller;
 exports.CoreRouter = CoreRouter;
 exports.Request = Request;
 exports.Response = Response;
-exports.Route = Route;
+exports.Route = Route;
+exports.definePlugin = definePlugin;

package/dist/index.d.cts

@@ -128,6 +128,37 @@ declare abstract class Controller<X = any> {
   clearRequest: ClearRequest;
 }
 //#endregion
+//#region src/core/bindings.d.ts
+type BindToken<T = any> = abstract new (...args: any[]) => T;
+type BindFactory<T = any> = (ctx: any) => T | Promise<T>;
+type BindValue<T = any> = T | BindFactory<T> | BindToken<T>;
+declare class Container {
+  private static readonly registry;
+  static bind<T>(token: BindToken<T>, value: BindValue<T>): void;
+  static unbind<T>(token: BindToken<T>): void;
+  static clear(): void;
+  static has<T>(token: BindToken<T>): boolean;
+  static resolve<T>(token: BindToken<T>, ctx: any, autoDiscover?: boolean): Promise<T | undefined>;
+  private static resolveBinding;
+}
+//#endregion
+//#region src/core/plugins.d.ts
+type PluginSetupResult = void | Promise<void>;
+type PluginBind = <T>(token: BindToken<T>, value: BindValue<T>) => void;
+interface ClearRouterPluginContext<Options = any> {
+  container: typeof Container;
+  bind: PluginBind;
+  configure: (options: RouterConfig) => void;
+  configureDefaults: (options: RouterConfig) => void;
+  options: Options;
+}
+interface ClearRouterPlugin<Options = any> {
+  name?: string;
+  setup: (ctx: ClearRouterPluginContext<Options>) => PluginSetupResult;
+}
+type ClearRouterPluginInput<Options = any> = ClearRouterPlugin<Options> | ((ctx: ClearRouterPluginContext<Options>) => PluginSetupResult);
+declare function definePlugin<Options = any>(plugin: ClearRouterPlugin<Options>): ClearRouterPlugin<Options>;
+//#endregion
 //#region src/core/router.d.ts
 /**
  * @class clear-router CoreRouter
@@ -140,11 +171,15 @@ declare abstract class CoreRouter {
   private static readonly stateStoreKey;
   private static readonly stateBoundKey;
   private static readonly defaultConfigKey;
+  private static readonly pluginStoreKey;
+  private static readonly pluginPendingKey;
   protected static createBaseConfig(): RouterConfig;
   protected static mergeConfig(target: RouterConfig, source?: RouterConfig): RouterConfig;
   protected static getDefaultConfig(): RouterConfig;
   protected static resolveStateNamespace(this: any): string;
   protected static getStateStore(): Record<string, any>;
+  protected static getPluginStore(): Set<string>;
+  protected static getPluginPendingStore(): Set<Promise<void>>;
   protected static createDefaultState(): {
     config: RouterConfig;
     groupContext: AsyncLocalStorage<{
@@ -162,6 +197,16 @@ declare abstract class CoreRouter {
   protected static createDefaultOptionsHandler(): any;
   static config: RouterConfig;
   static configureDefaults(this: any, options?: RouterConfig): void;
+  /**
+   * Use a registered plugin
+   *
+   * @param this
+   * @param plugin
+   * @param options
+   * @returns
+   */
+  static use<Options = any>(this: any, plugin: ClearRouterPluginInput<Options>, options?: Options): Promise<void>;
+  protected static pluginsReady(this: any): Promise<void>;
   protected static groupContext: AsyncLocalStorage<{
     prefix: string;
     groupMiddlewares: any[];
@@ -327,4 +372,4 @@ declare abstract class CoreRouter {
   }): void;
 }
 //#endregion
-export { ClearRequest, Controller, CoreRouter, Request, Response$1 as Response, Route };
+export { ClearRequest, ClearRouterPlugin, ClearRouterPluginContext, ClearRouterPluginInput, Controller, CoreRouter, PluginBind, PluginSetupResult, Request, Response$1 as Response, Route, definePlugin };

package/dist/index.d.mts

@@ -128,6 +128,37 @@ declare abstract class Controller<X = any> {
   clearRequest: ClearRequest;
 }
 //#endregion
+//#region src/core/bindings.d.ts
+type BindToken<T = any> = abstract new (...args: any[]) => T;
+type BindFactory<T = any> = (ctx: any) => T | Promise<T>;
+type BindValue<T = any> = T | BindFactory<T> | BindToken<T>;
+declare class Container {
+  private static readonly registry;
+  static bind<T>(token: BindToken<T>, value: BindValue<T>): void;
+  static unbind<T>(token: BindToken<T>): void;
+  static clear(): void;
+  static has<T>(token: BindToken<T>): boolean;
+  static resolve<T>(token: BindToken<T>, ctx: any, autoDiscover?: boolean): Promise<T | undefined>;
+  private static resolveBinding;
+}
+//#endregion
+//#region src/core/plugins.d.ts
+type PluginSetupResult = void | Promise<void>;
+type PluginBind = <T>(token: BindToken<T>, value: BindValue<T>) => void;
+interface ClearRouterPluginContext<Options = any> {
+  container: typeof Container;
+  bind: PluginBind;
+  configure: (options: RouterConfig) => void;
+  configureDefaults: (options: RouterConfig) => void;
+  options: Options;
+}
+interface ClearRouterPlugin<Options = any> {
+  name?: string;
+  setup: (ctx: ClearRouterPluginContext<Options>) => PluginSetupResult;
+}
+type ClearRouterPluginInput<Options = any> = ClearRouterPlugin<Options> | ((ctx: ClearRouterPluginContext<Options>) => PluginSetupResult);
+declare function definePlugin<Options = any>(plugin: ClearRouterPlugin<Options>): ClearRouterPlugin<Options>;
+//#endregion
 //#region src/core/router.d.ts
 /**
  * @class clear-router CoreRouter
@@ -140,11 +171,15 @@ declare abstract class CoreRouter {
   private static readonly stateStoreKey;
   private static readonly stateBoundKey;
   private static readonly defaultConfigKey;
+  private static readonly pluginStoreKey;
+  private static readonly pluginPendingKey;
   protected static createBaseConfig(): RouterConfig;
   protected static mergeConfig(target: RouterConfig, source?: RouterConfig): RouterConfig;
   protected static getDefaultConfig(): RouterConfig;
   protected static resolveStateNamespace(this: any): string;
   protected static getStateStore(): Record<string, any>;
+  protected static getPluginStore(): Set<string>;
+  protected static getPluginPendingStore(): Set<Promise<void>>;
   protected static createDefaultState(): {
     config: RouterConfig;
     groupContext: AsyncLocalStorage<{
@@ -162,6 +197,16 @@ declare abstract class CoreRouter {
   protected static createDefaultOptionsHandler(): any;
   static config: RouterConfig;
   static configureDefaults(this: any, options?: RouterConfig): void;
+  /**
+   * Use a registered plugin
+   *
+   * @param this
+   * @param plugin
+   * @param options
+   * @returns
+   */
+  static use<Options = any>(this: any, plugin: ClearRouterPluginInput<Options>, options?: Options): Promise<void>;
+  protected static pluginsReady(this: any): Promise<void>;
   protected static groupContext: AsyncLocalStorage<{
     prefix: string;
     groupMiddlewares: any[];
@@ -327,4 +372,4 @@ declare abstract class CoreRouter {
   }): void;
 }
 //#endregion
-export { ClearRequest, Controller, CoreRouter, Request, Response$1 as Response, Route };
+export { ClearRequest, ClearRouterPlugin, ClearRouterPluginContext, ClearRouterPluginInput, Controller, CoreRouter, PluginBind, PluginSetupResult, Request, Response$1 as Response, Route, definePlugin };

package/dist/index.mjs

@@ -140,6 +140,12 @@ var Response = class {
 	}
 };
 
+//#endregion
+//#region src/core/plugins.ts
+function definePlugin(plugin) {
+	return plugin;
+}
+
 //#endregion
 //#region src/core/bindings.ts
 const metadataKey = Symbol.for("clear-router:binding-metadata");
@@ -211,6 +217,8 @@ var CoreRouter = class {
 	static stateStoreKey = Symbol.for("clear-router:router-state");
 	static stateBoundKey = Symbol.for("clear-router:router-state-bound");
 	static defaultConfigKey = Symbol.for("clear-router:default-config");
+	static pluginStoreKey = Symbol.for("clear-router:plugins");
+	static pluginPendingKey = Symbol.for("clear-router:plugin-promises");
 	static createBaseConfig() {
 		return {
 			methodOverride: {
@@ -252,6 +260,16 @@ var CoreRouter = class {
 		if (!g[this.stateStoreKey]) g[this.stateStoreKey] = Object.create(null);
 		return g[this.stateStoreKey];
 	}
+	static getPluginStore() {
+		const g = globalThis;
+		if (!g[this.pluginStoreKey]) g[this.pluginStoreKey] = /* @__PURE__ */ new Set();
+		return g[this.pluginStoreKey];
+	}
+	static getPluginPendingStore() {
+		const g = globalThis;
+		if (!g[this.pluginPendingKey]) g[this.pluginPendingKey] = /* @__PURE__ */ new Set();
+		return g[this.pluginPendingKey];
+	}
 	static createDefaultState() {
 		return {
 			config: this.getDefaultConfig(),
@@ -349,6 +367,47 @@ var CoreRouter = class {
 		const store = this.getStateStore();
 		for (const state of Object.values(store)) state.config = this.mergeConfig(state.config || this.createBaseConfig(), options);
 	}
+	/**
+	* Use a registered plugin
+	* 
+	* @param this 
+	* @param plugin 
+	* @param options 
+	* @returns 
+	*/
+	static async use(plugin, options) {
+		const name = typeof plugin === "function" ? plugin.name : plugin.name;
+		const store = this.getPluginStore();
+		if (name && store.has(name)) return;
+		if (name) store.add(name);
+		const setup = async () => {
+			const ctx = {
+				container: Container,
+				bind: Container.bind.bind(Container),
+				configure: this.configure.bind(this),
+				configureDefaults: this.configureDefaults.bind(this),
+				options
+			};
+			if (typeof plugin === "function") await plugin(ctx);
+			else await plugin.setup(ctx);
+		};
+		const pending = this.getPluginPendingStore();
+		const promise = setup();
+		pending.add(promise);
+		try {
+			await promise;
+		} catch (error) {
+			if (name) store.delete(name);
+			throw error;
+		} finally {
+			pending.delete(promise);
+		}
+	}
+	static async pluginsReady() {
+		const pending = Array.from(this.getPluginPendingStore());
+		if (!pending.length) return;
+		await Promise.all(pending);
+	}
 	static groupContext = new AsyncLocalStorage();
 	static routes = [];
 	static routesByPathMethod = {};
@@ -670,6 +729,7 @@ var CoreRouter = class {
 		};
 	}
 	static async callHandler(handlerFunction, ctx, bindingTarget, bindingMethod, bindingHandler, bindingMetadata) {
+		await this.pluginsReady();
 		if (!this.config.container?.enabled) return handlerFunction(ctx, ctx.clearRequest);
 		const metadata = getBindingMetadataFromTargets([
 			{
@@ -724,4 +784,4 @@ var CoreRouter = class {
 };
 
 //#endregion
-export { ClearRequest, Controller, CoreRouter, Request, Response, Route };
+export { ClearRequest, Controller, CoreRouter, Request, Response, Route, definePlugin };

package/dist/koa/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 require('../bindings-DvV2DXWi.cjs');
-const require_router = require('../router-CCUF5FE7.cjs');
+const require_router = require('../router-BdMuUzGU.cjs');
 const require_responses = require('../responses-JzXstGU5.cjs');
 
 //#region src/koa/router.ts

package/dist/koa/index.d.cts

@@ -1,4 +1,4 @@
-import { d as ApiResourceMiddleware, f as ControllerAction, h as Response, m as HttpMethod, n as Request, p as ControllerHandler, r as Route, t as CoreRouter } from "../router-78fDk87B.cjs";
+import { _ as ApiResourceMiddleware, b as HttpMethod, c as Request, l as Route, t as CoreRouter, v as ControllerAction, x as Response, y as ControllerHandler } from "../router-WAxKAcWR.cjs";
 import Koa from "koa";
 import Router$1 from "@koa/router";
 

package/dist/koa/index.d.mts

@@ -1,4 +1,4 @@
-import { d as ApiResourceMiddleware, f as ControllerAction, h as Response, m as HttpMethod, n as Request, p as ControllerHandler, r as Route, t as CoreRouter } from "../router-BdfAh1me.mjs";
+import { _ as ApiResourceMiddleware, b as HttpMethod, c as Request, l as Route, t as CoreRouter, v as ControllerAction, x as Response, y as ControllerHandler } from "../router-D7R3G8w-.mjs";
 import Koa from "koa";
 import Router$1 from "@koa/router";
 

package/dist/koa/index.mjs

@@ -1,5 +1,5 @@
 import "../bindings-DIanvIVd.mjs";
-import { t as CoreRouter } from "../router-BAWdklDQ.mjs";
+import { t as CoreRouter } from "../router-DzbF-ZV0.mjs";
 import { n as resolveResponseMeta, t as isFetchResponse } from "../responses-_II3dOJ5.mjs";
 
 //#region src/koa/router.ts

package/dist/{router-CCUF5FE7.cjs → router-BdMuUzGU.cjs}

@@ -41,6 +41,8 @@ var CoreRouter = class {
 	static stateStoreKey = Symbol.for("clear-router:router-state");
 	static stateBoundKey = Symbol.for("clear-router:router-state-bound");
 	static defaultConfigKey = Symbol.for("clear-router:default-config");
+	static pluginStoreKey = Symbol.for("clear-router:plugins");
+	static pluginPendingKey = Symbol.for("clear-router:plugin-promises");
 	static createBaseConfig() {
 		return {
 			methodOverride: {
@@ -82,6 +84,16 @@ var CoreRouter = class {
 		if (!g[this.stateStoreKey]) g[this.stateStoreKey] = Object.create(null);
 		return g[this.stateStoreKey];
 	}
+	static getPluginStore() {
+		const g = globalThis;
+		if (!g[this.pluginStoreKey]) g[this.pluginStoreKey] = /* @__PURE__ */ new Set();
+		return g[this.pluginStoreKey];
+	}
+	static getPluginPendingStore() {
+		const g = globalThis;
+		if (!g[this.pluginPendingKey]) g[this.pluginPendingKey] = /* @__PURE__ */ new Set();
+		return g[this.pluginPendingKey];
+	}
 	static createDefaultState() {
 		return {
 			config: this.getDefaultConfig(),
@@ -179,6 +191,47 @@ var CoreRouter = class {
 		const store = this.getStateStore();
 		for (const state of Object.values(store)) state.config = this.mergeConfig(state.config || this.createBaseConfig(), options);
 	}
+	/**
+	* Use a registered plugin
+	* 
+	* @param this 
+	* @param plugin 
+	* @param options 
+	* @returns 
+	*/
+	static async use(plugin, options) {
+		const name = typeof plugin === "function" ? plugin.name : plugin.name;
+		const store = this.getPluginStore();
+		if (name && store.has(name)) return;
+		if (name) store.add(name);
+		const setup = async () => {
+			const ctx = {
+				container: require_bindings.Container,
+				bind: require_bindings.Container.bind.bind(require_bindings.Container),
+				configure: this.configure.bind(this),
+				configureDefaults: this.configureDefaults.bind(this),
+				options
+			};
+			if (typeof plugin === "function") await plugin(ctx);
+			else await plugin.setup(ctx);
+		};
+		const pending = this.getPluginPendingStore();
+		const promise = setup();
+		pending.add(promise);
+		try {
+			await promise;
+		} catch (error) {
+			if (name) store.delete(name);
+			throw error;
+		} finally {
+			pending.delete(promise);
+		}
+	}
+	static async pluginsReady() {
+		const pending = Array.from(this.getPluginPendingStore());
+		if (!pending.length) return;
+		await Promise.all(pending);
+	}
 	static groupContext = new node_async_hooks.AsyncLocalStorage();
 	static routes = [];
 	static routesByPathMethod = {};
@@ -500,6 +553,7 @@ var CoreRouter = class {
 		};
 	}
 	static async callHandler(handlerFunction, ctx, bindingTarget, bindingMethod, bindingHandler, bindingMetadata) {
+		await this.pluginsReady();
 		if (!this.config.container?.enabled) return handlerFunction(ctx, ctx.clearRequest);
 		const metadata = require_bindings.getBindingMetadataFromTargets([
 			{

package/dist/{router-BdfAh1me.d.mts → router-D7R3G8w-.d.mts}

@@ -1,3 +1,4 @@
+import { a as BindValue, i as BindToken, o as Container } from "./bindings-CV1e5jho.mjs";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { EventHandlerRequest, H3, H3Event, Middleware, TypedServerRequest } from "h3";
 import { NextFunction, Request, Response as Response$1 } from "express";
@@ -188,6 +189,23 @@ declare class Request$1<X = any, M = any> extends ClearRequest<X, M> {
   is(method: HttpMethod | string): boolean;
 }
 //#endregion
+//#region src/core/plugins.d.ts
+type PluginSetupResult = void | Promise<void>;
+type PluginBind = <T>(token: BindToken<T>, value: BindValue<T>) => void;
+interface ClearRouterPluginContext<Options = any> {
+  container: typeof Container;
+  bind: PluginBind;
+  configure: (options: RouterConfig) => void;
+  configureDefaults: (options: RouterConfig) => void;
+  options: Options;
+}
+interface ClearRouterPlugin<Options = any> {
+  name?: string;
+  setup: (ctx: ClearRouterPluginContext<Options>) => PluginSetupResult;
+}
+type ClearRouterPluginInput<Options = any> = ClearRouterPlugin<Options> | ((ctx: ClearRouterPluginContext<Options>) => PluginSetupResult);
+declare function definePlugin<Options = any>(plugin: ClearRouterPlugin<Options>): ClearRouterPlugin<Options>;
+//#endregion
 //#region src/Controller.d.ts
 declare abstract class Controller<X = any> {
   [x: string]: any;
@@ -210,11 +228,15 @@ declare abstract class CoreRouter {
   private static readonly stateStoreKey;
   private static readonly stateBoundKey;
   private static readonly defaultConfigKey;
+  private static readonly pluginStoreKey;
+  private static readonly pluginPendingKey;
   protected static createBaseConfig(): RouterConfig;
   protected static mergeConfig(target: RouterConfig, source?: RouterConfig): RouterConfig;
   protected static getDefaultConfig(): RouterConfig;
   protected static resolveStateNamespace(this: any): string;
   protected static getStateStore(): Record<string, any>;
+  protected static getPluginStore(): Set<string>;
+  protected static getPluginPendingStore(): Set<Promise<void>>;
   protected static createDefaultState(): {
     config: RouterConfig;
     groupContext: AsyncLocalStorage<{
@@ -232,6 +254,16 @@ declare abstract class CoreRouter {
   protected static createDefaultOptionsHandler(): any;
   static config: RouterConfig;
   static configureDefaults(this: any, options?: RouterConfig): void;
+  /**
+   * Use a registered plugin
+   *
+   * @param this
+   * @param plugin
+   * @param options
+   * @returns
+   */
+  static use<Options = any>(this: any, plugin: ClearRouterPluginInput<Options>, options?: Options): Promise<void>;
+  protected static pluginsReady(this: any): Promise<void>;
   protected static groupContext: AsyncLocalStorage<{
     prefix: string;
     groupMiddlewares: any[];
@@ -397,4 +429,4 @@ declare abstract class CoreRouter {
   }): void;
 }
 //#endregion
-export { Handler as a, Handler$1 as c, ApiResourceMiddleware as d, ControllerAction as f, Response$2 as h, H3App as i, HttpContext$1 as l, HttpMethod as m, Request$1 as n, HttpContext as o, ControllerHandler as p, Route as r, Middleware as s, CoreRouter as t, Middleware$1 as u };
+export { ApiResourceMiddleware as _, PluginBind as a, HttpMethod as b, Request$1 as c, Handler as d, HttpContext as f, Middleware$1 as g, HttpContext$1 as h, ClearRouterPluginInput as i, Route as l, Handler$1 as m, ClearRouterPlugin as n, PluginSetupResult as o, Middleware as p, ClearRouterPluginContext as r, definePlugin as s, CoreRouter as t, H3App as u, ControllerAction as v, Response$2 as x, ControllerHandler as y };

package/dist/{router-BAWdklDQ.mjs → router-DzbF-ZV0.mjs}

@@ -41,6 +41,8 @@ var CoreRouter = class {
 	static stateStoreKey = Symbol.for("clear-router:router-state");
 	static stateBoundKey = Symbol.for("clear-router:router-state-bound");
 	static defaultConfigKey = Symbol.for("clear-router:default-config");
+	static pluginStoreKey = Symbol.for("clear-router:plugins");
+	static pluginPendingKey = Symbol.for("clear-router:plugin-promises");
 	static createBaseConfig() {
 		return {
 			methodOverride: {
@@ -82,6 +84,16 @@ var CoreRouter = class {
 		if (!g[this.stateStoreKey]) g[this.stateStoreKey] = Object.create(null);
 		return g[this.stateStoreKey];
 	}
+	static getPluginStore() {
+		const g = globalThis;
+		if (!g[this.pluginStoreKey]) g[this.pluginStoreKey] = /* @__PURE__ */ new Set();
+		return g[this.pluginStoreKey];
+	}
+	static getPluginPendingStore() {
+		const g = globalThis;
+		if (!g[this.pluginPendingKey]) g[this.pluginPendingKey] = /* @__PURE__ */ new Set();
+		return g[this.pluginPendingKey];
+	}
 	static createDefaultState() {
 		return {
 			config: this.getDefaultConfig(),
@@ -179,6 +191,47 @@ var CoreRouter = class {
 		const store = this.getStateStore();
 		for (const state of Object.values(store)) state.config = this.mergeConfig(state.config || this.createBaseConfig(), options);
 	}
+	/**
+	* Use a registered plugin
+	* 
+	* @param this 
+	* @param plugin 
+	* @param options 
+	* @returns 
+	*/
+	static async use(plugin, options) {
+		const name = typeof plugin === "function" ? plugin.name : plugin.name;
+		const store = this.getPluginStore();
+		if (name && store.has(name)) return;
+		if (name) store.add(name);
+		const setup = async () => {
+			const ctx = {
+				container: Container,
+				bind: Container.bind.bind(Container),
+				configure: this.configure.bind(this),
+				configureDefaults: this.configureDefaults.bind(this),
+				options
+			};
+			if (typeof plugin === "function") await plugin(ctx);
+			else await plugin.setup(ctx);
+		};
+		const pending = this.getPluginPendingStore();
+		const promise = setup();
+		pending.add(promise);
+		try {
+			await promise;
+		} catch (error) {
+			if (name) store.delete(name);
+			throw error;
+		} finally {
+			pending.delete(promise);
+		}
+	}
+	static async pluginsReady() {
+		const pending = Array.from(this.getPluginPendingStore());
+		if (!pending.length) return;
+		await Promise.all(pending);
+	}
 	static groupContext = new AsyncLocalStorage();
 	static routes = [];
 	static routesByPathMethod = {};
@@ -500,6 +553,7 @@ var CoreRouter = class {
 		};
 	}
 	static async callHandler(handlerFunction, ctx, bindingTarget, bindingMethod, bindingHandler, bindingMetadata) {
+		await this.pluginsReady();
 		if (!this.config.container?.enabled) return handlerFunction(ctx, ctx.clearRequest);
 		const metadata = getBindingMetadataFromTargets([
 			{

package/dist/{router-78fDk87B.d.cts → router-WAxKAcWR.d.cts}

@@ -1,3 +1,4 @@
+import { a as BindValue, i as BindToken, o as Container } from "./bindings-NV0CdqGl.cjs";
 import { NextFunction, Request, Response as Response$1 } from "express";
 import { EventHandlerRequest, H3, H3Event, Middleware, TypedServerRequest } from "h3";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -188,6 +189,23 @@ declare class Request$1<X = any, M = any> extends ClearRequest<X, M> {
   is(method: HttpMethod | string): boolean;
 }
 //#endregion
+//#region src/core/plugins.d.ts
+type PluginSetupResult = void | Promise<void>;
+type PluginBind = <T>(token: BindToken<T>, value: BindValue<T>) => void;
+interface ClearRouterPluginContext<Options = any> {
+  container: typeof Container;
+  bind: PluginBind;
+  configure: (options: RouterConfig) => void;
+  configureDefaults: (options: RouterConfig) => void;
+  options: Options;
+}
+interface ClearRouterPlugin<Options = any> {
+  name?: string;
+  setup: (ctx: ClearRouterPluginContext<Options>) => PluginSetupResult;
+}
+type ClearRouterPluginInput<Options = any> = ClearRouterPlugin<Options> | ((ctx: ClearRouterPluginContext<Options>) => PluginSetupResult);
+declare function definePlugin<Options = any>(plugin: ClearRouterPlugin<Options>): ClearRouterPlugin<Options>;
+//#endregion
 //#region src/Controller.d.ts
 declare abstract class Controller<X = any> {
   [x: string]: any;
@@ -210,11 +228,15 @@ declare abstract class CoreRouter {
   private static readonly stateStoreKey;
   private static readonly stateBoundKey;
   private static readonly defaultConfigKey;
+  private static readonly pluginStoreKey;
+  private static readonly pluginPendingKey;
   protected static createBaseConfig(): RouterConfig;
   protected static mergeConfig(target: RouterConfig, source?: RouterConfig): RouterConfig;
   protected static getDefaultConfig(): RouterConfig;
   protected static resolveStateNamespace(this: any): string;
   protected static getStateStore(): Record<string, any>;
+  protected static getPluginStore(): Set<string>;
+  protected static getPluginPendingStore(): Set<Promise<void>>;
   protected static createDefaultState(): {
     config: RouterConfig;
     groupContext: AsyncLocalStorage<{
@@ -232,6 +254,16 @@ declare abstract class CoreRouter {
   protected static createDefaultOptionsHandler(): any;
   static config: RouterConfig;
   static configureDefaults(this: any, options?: RouterConfig): void;
+  /**
+   * Use a registered plugin
+   *
+   * @param this
+   * @param plugin
+   * @param options
+   * @returns
+   */
+  static use<Options = any>(this: any, plugin: ClearRouterPluginInput<Options>, options?: Options): Promise<void>;
+  protected static pluginsReady(this: any): Promise<void>;
   protected static groupContext: AsyncLocalStorage<{
     prefix: string;
     groupMiddlewares: any[];
@@ -397,4 +429,4 @@ declare abstract class CoreRouter {
   }): void;
 }
 //#endregion
-export { Handler as a, Handler$1 as c, ApiResourceMiddleware as d, ControllerAction as f, Response$2 as h, H3App as i, HttpContext$1 as l, HttpMethod as m, Request$1 as n, HttpContext as o, ControllerHandler as p, Route as r, Middleware as s, CoreRouter as t, Middleware$1 as u };
+export { ApiResourceMiddleware as _, PluginBind as a, HttpMethod as b, Request$1 as c, Handler as d, HttpContext as f, Middleware$1 as g, HttpContext$1 as h, ClearRouterPluginInput as i, Route as l, Handler$1 as m, ClearRouterPlugin as n, PluginSetupResult as o, Middleware as p, ClearRouterPluginContext as r, definePlugin as s, CoreRouter as t, H3App as u, ControllerAction as v, Response$2 as x, ControllerHandler as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clear-router",
-  "version": "2.5.5",
+  "version": "2.5.7",
   "description": "Laravel-style routing for Node.js with support for Express, H3, Fastify, Hono, and Koa, including CommonJS, ESM, and TypeScript support.",
   "keywords": [
     "h3",