@keq-request/nestjs 5.0.0-beta.8 → 5.0.0

package/dist/index.mjs

@@ -1,7 +1,114 @@
-import { KeqRequest } from "keq";
-import { ConfigurableModuleBuilder, Global } from "@nestjs/common";
-//#region src/keq.module-definition.ts
-const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } = new ConfigurableModuleBuilder().build();
+import { Global, Inject, Injectable, Module } from "@nestjs/common";
+import { KeqRequest, composeRoute } from "keq";
+import picomatch from "picomatch";
+//#region src/constants.ts
+const KEQ_ROUTES = { ALL: Symbol("KEQ_ROUTES.ALL") };
+//#endregion
+//#region src/keq-middleware-collector.ts
+/**
+* 中间件收集器，收集中间件配置条目并应用到指定的 {@link KeqRequest} 实例。
+*
+* 通过 `apply()` → `forRoutes()` 链式 API 收集多组中间件条目，
+* 在 `forRoutes()` 被调用时立即将中间件绑定到目标请求。
+*
+* 注意：该类并非 `@Injectable()`，由 Consumer 内部手动创建。
+*
+* @typeParam TConsumer - Consumer 类型（`KeqMiddlewareConsumer` 或 `KeqConsumer<T>`）
+*/
+var KeqMiddlewareCollector = class {
+	entries = [];
+	constructor(keqRequest, consumer) {
+		this.keqRequest = keqRequest;
+		this.consumer = consumer;
+	}
+	apply(middlewares) {
+		const entry = {
+			middlewares,
+			routes: []
+		};
+		const excludedRouteInfos = [];
+		this.entries.push(entry);
+		const { keqRequest, consumer } = this;
+		const proxy = {
+			exclude: (...routes) => {
+				excludedRouteInfos.push(...routes);
+				return proxy;
+			},
+			forRoutes: (...routes) => {
+				entry.routes = routes;
+				if (excludedRouteInfos.length > 0) entry.excludedRouteInfos = excludedRouteInfos;
+				this.applyTo(keqRequest);
+				return consumer;
+			}
+		};
+		return proxy;
+	}
+	/**
+	* 将收集的所有中间件条目解析并应用到指定的 {@link KeqRequest} 实例。
+	*/
+	applyTo(keqRequest) {
+		for (const entry of this.entries) {
+			let resolved = entry.middlewares.map((m) => this.normalizeMiddleware(m));
+			if (entry.excludedRouteInfos && entry.excludedRouteInfos.length > 0) {
+				const excludedRoutes = entry.excludedRouteInfos.map((info) => this.buildRoute(info));
+				resolved = resolved.map((mw) => this.wrapWithExclusion(mw, excludedRoutes));
+			}
+			if (entry.routes.length === 0 || entry.routes.some((r) => r === KEQ_ROUTES.ALL)) for (const mw of resolved) keqRequest.use(mw);
+			else for (const routeTarget of entry.routes) {
+				if (routeTarget === KEQ_ROUTES.ALL) continue;
+				const route = this.buildRoute(routeTarget);
+				keqRequest.useRouter().route(route, resolved);
+			}
+		}
+	}
+	/**
+	* 标准化中间件：将不同形式的中间件统一为 {@link KeqMiddleware} 函数。
+	* - 若已是 {@link KeqMiddleware} 函数 → 直接返回
+	* - 若为 {@link KeqNestMiddleware} 实例对象 → 包装 `use` 方法为中间件函数
+	*/
+	normalizeMiddleware(m) {
+		if (this.isNestMiddlewareInstance(m)) return async (ctx, next) => {
+			await m.use(ctx, next);
+		};
+		return m;
+	}
+	isNestMiddlewareInstance(m) {
+		return typeof m === "object" && m !== null && "use" in m;
+	}
+	buildRoute(info) {
+		const routes = [];
+		if (info.host) {
+			const host = info.host;
+			routes.push((ctx) => ctx.request.url.host === host);
+		}
+		if (info.method) {
+			const method = info.method.toLowerCase();
+			routes.push((ctx) => ctx.request.method.toLowerCase() === method);
+		}
+		if (info.pathname) {
+			const isMatch = picomatch(info.pathname);
+			routes.push((ctx) => isMatch(ctx.request.url.pathname));
+		}
+		if (routes.length === 1) return routes[0];
+		return composeRoute(routes);
+	}
+	wrapWithExclusion(middleware, excludedRoutes) {
+		const excluded = async (ctx, next) => {
+			if (await this.checkExcluded(ctx, excludedRoutes)) return next();
+			return middleware(ctx, next);
+		};
+		return excluded;
+	}
+	async checkExcluded(ctx, excludedRoutes) {
+		for (const route of excludedRoutes) if (await route(ctx)) return true;
+		return false;
+	}
+};
+//#endregion
+//#region \0@oxc-project+runtime@0.127.0/helpers/decorateMetadata.js
+function __decorateMetadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
 //#endregion
 //#region \0@oxc-project+runtime@0.127.0/helpers/decorate.js
 function __decorate(decorators, target, key, desc) {
@@ -11,47 +118,77 @@ function __decorate(decorators, target, key, desc) {
 	return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 //#endregion
+//#region src/keq-middleware-consumer.ts
+var _ref;
+let KeqMiddlewareConsumer = class KeqMiddlewareConsumer {
+	constructor(keqRequest) {
+		this.keqRequest = keqRequest;
+	}
+	apply(...middlewares) {
+		return new KeqMiddlewareCollector(this.keqRequest, this).apply(middlewares);
+	}
+};
+KeqMiddlewareConsumer = __decorate([Injectable(), __decorateMetadata("design:paramtypes", [typeof (_ref = typeof KeqRequest !== "undefined" && KeqRequest) === "function" ? _ref : Object])], KeqMiddlewareConsumer);
+//#endregion
 //#region src/keq.module.ts
+let KeqModule = class KeqModule {};
+KeqModule = __decorate([Global(), Module({
+	providers: [{
+		provide: KeqRequest,
+		useFactory: () => new KeqRequest()
+	}, KeqMiddlewareConsumer],
+	exports: [KeqRequest, KeqMiddlewareConsumer]
+})], KeqModule);
+//#endregion
+//#region src/keq-consumer.ts
 /**
-* Provider that creates and configures a KeqRequest instance
-* Applies any middlewares defined in the module options
+* 为指定 Keq 模块按路由注册中间件。
+*
+* Keq 模块由 `@keq-request/cli` 生成，通过
+* {@link InjectKeqConsumer} 装饰器注入本实例。
+*
+* @typeParam T - 目标模块类
+*
+* @example
+* ```ts
+* constructor(
+*   \@InjectKeqConsumer(GeneratedModule) consumer: KeqConsumer<GeneratedModule>,
+* ) {
+*   consumer.apply(authMw).forRoutes('*')
+* }
+* ```
 */
-const requestProvider = {
-	provide: KeqRequest,
-	useFactory: (config) => {
-		const request = new KeqRequest();
-		if (config.middlewares) for (const middleware of config.middlewares) request.use(middleware);
-		return request;
-	},
-	inject: [MODULE_OPTIONS_TOKEN]
-};
-let KeqModule = class KeqModule extends ConfigurableModuleClass {
-	/**
-	* Register the module with synchronous options
-	* @param options - Configuration options including middlewares
-	* @returns DynamicModule with KeqRequest provider
-	*/
-	static register(options) {
-		const mo = super.register(options);
-		mo.providers.push(requestProvider);
-		mo.global = true;
-		return mo;
+var KeqConsumer = class {
+	constructor(keqRequest) {
+		this.keqRequest = keqRequest;
 	}
-	/**
-	* Register the module with asynchronous options
-	* Useful when you need to inject dependencies like ConfigService
-	* @param options - Async configuration options
-	* @returns DynamicModule with KeqRequest provider
-	*/
-	static registerAsync(options) {
-		const mo = super.registerAsync(options);
-		mo.providers.push(requestProvider);
-		mo.global = true;
-		return mo;
+	apply(...middlewares) {
+		return new KeqMiddlewareCollector(this.keqRequest, this).apply(middlewares);
 	}
 };
-KeqModule = __decorate([Global()], KeqModule);
 //#endregion
-export { KeqModule };
+//#region src/decorators/inject-keq-consumer.decorator.ts
+/**
+* 注入绑定到指定 Keq Module 的 `KeqConsumer<T>`。
+*
+* 被注入的 Module Class 必须同时包含 `KEQ_REQUEST` 和 `KEQ_CONSUMER` 静态属性，
+* 两者均由 keq CLI 生成。
+*
+* 使用方式：
+* ```ts
+* constructor(
+*   \@InjectKeqConsumer(GeneratedModule) consumer: KeqConsumer<GeneratedModule>,
+* ) {
+*   consumer.apply(mw).forRoutes('*')
+* }
+* ```
+*
+* @param moduleClass - 目标 KeqModule 类（需具有 `KEQ_REQUEST` 和 `KEQ_CONSUMER` symbol）
+*/
+function InjectKeqConsumer(moduleClass) {
+	return Inject(moduleClass.KEQ_CONSUMER);
+}
+//#endregion
+export { InjectKeqConsumer, KEQ_ROUTES, KeqConsumer, KeqMiddlewareConsumer, KeqModule };
 
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/keq.module-definition.ts","../src/keq.module.ts"],"sourcesContent":["\nimport { ConfigurableModuleBuilder } from '@nestjs/common'\nimport { KeqModuleOptions } from './types/keq-module-options'\n\n\nexport const {\n  ConfigurableModuleClass,\n  MODULE_OPTIONS_TOKEN,\n  OPTIONS_TYPE,\n  ASYNC_OPTIONS_TYPE,\n} = new ConfigurableModuleBuilder<KeqModuleOptions>().build()\n","\nimport { KeqRequest } from 'keq'\nimport { DynamicModule, Global, Provider } from '@nestjs/common'\nimport { ASYNC_OPTIONS_TYPE, ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } from './keq.module-definition.js'\nimport { KeqModuleOptions } from './types/index.js'\n\n\n/**\n * Provider that creates and configures a KeqRequest instance\n * Applies any middlewares defined in the module options\n */\nconst requestProvider: Provider = {\n  provide: KeqRequest,\n  useFactory: (config: KeqModuleOptions) => {\n    const request = new KeqRequest()\n\n    if (config.middlewares) {\n      for (const middleware of config.middlewares) {\n        request.use(middleware)\n      }\n    }\n\n    return request\n  },\n  inject: [MODULE_OPTIONS_TOKEN],\n}\n\n/**\n * KeqModule - Dynamic module for integrating Keq HTTP client with NestJS\n *\n * This module is global, so KeqRequest can be injected anywhere in your application\n * without needing to import the module in every feature module.\n *\n * @example\n * ```typescript\n * // Synchronous registration\n * KeqModule.register({\n *   middlewares: [...]\n * })\n *\n * // Asynchronous registration\n * KeqModule.registerAsync({\n *   imports: [ConfigModule],\n *   useFactory: (config: ConfigService) => ({\n *     middlewares: [...]\n *   }),\n *   inject: [ConfigService]\n * })\n *\n * // Inject in service\n * class UserService {\n *   constructor(private readonly keqRequest: KeqRequest) {}\n *   async getUser(id: string) {\n *     return await this.keqRequest.get(`/users/${id}`).resolveWith('json')\n *   }\n * }\n * ```\n */\n@Global()\nexport class KeqModule extends ConfigurableModuleClass {\n  /**\n   * Register the module with synchronous options\n   * @param options - Configuration options including middlewares\n   * @returns DynamicModule with KeqRequest provider\n   */\n  static register(options: typeof OPTIONS_TYPE): DynamicModule {\n    const mo = super.register(options)\n    mo.providers!.push(requestProvider)\n    mo.global = true\n\n    return mo\n  }\n\n  /**\n   * Register the module with asynchronous options\n   * Useful when you need to inject dependencies like ConfigService\n   * @param options - Async configuration options\n   * @returns DynamicModule with KeqRequest provider\n   */\n  static registerAsync(options: typeof ASYNC_OPTIONS_TYPE): DynamicModule {\n    const mo = super.registerAsync(options)\n    mo.providers!.push(requestProvider)\n    mo.global = true\n\n    return mo\n  }\n}\n"],"mappings":";;;AAKA,MAAa,EACX,yBACA,sBACA,cACA,uBACE,IAAI,2BAA6C,CAAC,OAAO;;;;;;;;;;;;;;;ACC7D,MAAM,kBAA4B;CAChC,SAAS;CACT,aAAa,WAA6B;EACxC,MAAM,UAAU,IAAI,YAAY;AAEhC,MAAI,OAAO,YACT,MAAK,MAAM,cAAc,OAAO,YAC9B,SAAQ,IAAI,WAAW;AAI3B,SAAO;;CAET,QAAQ,CAAC,qBAAqB;CAC/B;AAkCM,IAAA,YAAA,MAAM,kBAAkB,wBAAwB;;;;;;CAMrD,OAAO,SAAS,SAA6C;EAC3D,MAAM,KAAK,MAAM,SAAS,QAAQ;AAClC,KAAG,UAAW,KAAK,gBAAgB;AACnC,KAAG,SAAS;AAEZ,SAAO;;;;;;;;CAST,OAAO,cAAc,SAAmD;EACtE,MAAM,KAAK,MAAM,cAAc,QAAQ;AACvC,KAAG,UAAW,KAAK,gBAAgB;AACnC,KAAG,SAAS;AAEZ,SAAO;;;wBA1BV,QAAQ,CAAA,EAAA,UAAA"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/constants.ts","../src/keq-middleware-collector.ts","../src/keq-middleware-consumer.ts","../src/keq.module.ts","../src/keq-consumer.ts","../src/decorators/inject-keq-consumer.decorator.ts"],"sourcesContent":["export const KEQ_ROUTES = {\n  ALL: Symbol('KEQ_ROUTES.ALL'),\n} as const\n","import type { KeqExecutionContext, KeqMiddleware, KeqRoute } from 'keq'\nimport { composeRoute, KeqRequest } from 'keq'\nimport picomatch from 'picomatch'\nimport { KEQ_ROUTES } from './constants.js'\nimport type { KeqMiddlewareConfigProxy, KeqRouteTarget, KeqRouteInfo } from './interfaces/keq-middleware-consumer.interface.js'\nimport type { KeqNestMiddleware } from './interfaces/keq-nest-middleware.interface.js'\n\n\n/** 单条中间件注册条目 */\ninterface MiddlewareEntry {\n  middlewares: Array<KeqNestMiddleware | KeqMiddleware>\n  routes: KeqRouteTarget[]\n  excludedRouteInfos?: KeqRouteInfo[]\n}\n\n/**\n * 中间件收集器，收集中间件配置条目并应用到指定的 {@link KeqRequest} 实例。\n *\n * 通过 `apply()` → `forRoutes()` 链式 API 收集多组中间件条目，\n * 在 `forRoutes()` 被调用时立即将中间件绑定到目标请求。\n *\n * 注意：该类并非 `@Injectable()`，由 Consumer 内部手动创建。\n *\n * @typeParam TConsumer - Consumer 类型（`KeqMiddlewareConsumer` 或 `KeqConsumer<T>`）\n */\nexport class KeqMiddlewareCollector<TConsumer extends object = object> {\n  private entries: MiddlewareEntry[] = []\n\n  constructor(\n    private readonly keqRequest: KeqRequest,\n    private readonly consumer: TConsumer,\n  ) {}\n\n  apply(\n    middlewares: Array<KeqNestMiddleware | KeqMiddleware>,\n  ): KeqMiddlewareConfigProxy {\n    const entry: MiddlewareEntry = { middlewares, routes: [] }\n    const excludedRouteInfos: KeqRouteInfo[] = []\n    this.entries.push(entry)\n\n    const { keqRequest, consumer } = this\n\n    const proxy = {\n      exclude: (...routes: KeqRouteInfo[]) => {\n        excludedRouteInfos.push(...routes)\n        return proxy\n      },\n      forRoutes: (...routes: KeqRouteTarget[]) => {\n        entry.routes = routes\n        if (excludedRouteInfos.length > 0) {\n          entry.excludedRouteInfos = excludedRouteInfos\n        }\n        this.applyTo(keqRequest)\n        return consumer\n      },\n    }\n    return proxy as unknown as KeqMiddlewareConfigProxy\n  }\n\n  /**\n   * 将收集的所有中间件条目解析并应用到指定的 {@link KeqRequest} 实例。\n   */\n  applyTo(keqRequest: KeqRequest): void {\n    for (const entry of this.entries) {\n      let resolved = entry.middlewares.map((m) => this.normalizeMiddleware(m))\n\n      if (entry.excludedRouteInfos && entry.excludedRouteInfos.length > 0) {\n        const excludedRoutes = entry.excludedRouteInfos.map((info) => this.buildRoute(info))\n        resolved = resolved.map((mw) => this.wrapWithExclusion(mw, excludedRoutes))\n      }\n\n      const isGlobal\n        = entry.routes.length === 0 || entry.routes.some((r) => r === KEQ_ROUTES.ALL)\n\n      if (isGlobal) {\n        for (const mw of resolved) keqRequest.use(mw)\n      } else {\n        for (const routeTarget of entry.routes) {\n          if (routeTarget === KEQ_ROUTES.ALL) continue\n          const route = this.buildRoute(routeTarget as KeqRouteInfo)\n          keqRequest.useRouter().route(route, resolved)\n        }\n      }\n    }\n  }\n\n  // ─── 中间件标准化 ────────────────────────────────────\n\n  /**\n   * 标准化中间件：将不同形式的中间件统一为 {@link KeqMiddleware} 函数。\n   * - 若已是 {@link KeqMiddleware} 函数 → 直接返回\n   * - 若为 {@link KeqNestMiddleware} 实例对象 → 包装 `use` 方法为中间件函数\n   */\n  private normalizeMiddleware(\n    m: KeqNestMiddleware | KeqMiddleware,\n  ): KeqMiddleware {\n    if (this.isNestMiddlewareInstance(m)) {\n      return async (ctx, next) => {\n        await m.use(ctx, next)\n      }\n    }\n    return m\n  }\n\n  private isNestMiddlewareInstance(\n    m: KeqNestMiddleware | KeqMiddleware,\n  ): m is KeqNestMiddleware {\n    return typeof m === 'object' && m !== null && 'use' in m\n  }\n\n  // ─── 路由构建 ─────────────────────────────────────────\n\n  private buildRoute(info: KeqRouteInfo): KeqRoute {\n    const routes: KeqRoute[] = []\n    if (info.host) {\n      const host = info.host\n      routes.push((ctx) => ctx.request.url.host === host)\n    }\n    if (info.method) {\n      const method = info.method.toLowerCase()\n      routes.push((ctx) => ctx.request.method.toLowerCase() === method)\n    }\n    if (info.pathname) {\n      const isMatch: (test: string) => boolean = picomatch(info.pathname)\n      routes.push((ctx) => isMatch(ctx.request.url.pathname))\n    }\n    if (routes.length === 1) return routes[0]\n    return composeRoute(routes)\n  }\n\n  private wrapWithExclusion(middleware: KeqMiddleware, excludedRoutes: KeqRoute[]): KeqMiddleware {\n    const excluded: KeqMiddleware = async (ctx, next) => {\n      if (await this.checkExcluded(ctx, excludedRoutes)) {\n        return next()\n      }\n      return middleware(ctx, next)\n    }\n    return excluded\n  }\n\n  private async checkExcluded(\n    ctx: KeqExecutionContext,\n    excludedRoutes: KeqRoute[],\n  ): Promise<boolean> {\n    for (const route of excludedRoutes) {\n      if (await route(ctx)) return true\n    }\n    return false\n  }\n}\n","import { Injectable } from '@nestjs/common'\nimport type { KeqMiddleware } from 'keq'\nimport { KeqRequest } from 'keq'\nimport type { KeqMiddlewareConfigProxy } from './interfaces/keq-middleware-consumer.interface.js'\nimport type { KeqNestMiddleware } from './interfaces/keq-nest-middleware.interface.js'\nimport { KeqMiddlewareCollector } from './keq-middleware-collector.js'\n\n\n/**\n * 全局中间件消费者，提供 `.apply().forRoutes()` API。\n *\n * `forRoutes()` 返回 `KeqMiddlewareConsumer` 自身，支持链式注册：\n *\n * ```ts\n * consumer\n *   .apply(mw1).forRoutes(KEQ_ROUTES.ALL)\n *   .apply(mw2).forRoutes({ pathname: '/api/*' })\n * ```\n *\n * 模块级别的中间件请使用 `@InjectKeqConsumer(GeneratedModule)` 注入\n * `KeqConsumer<GeneratedModule>`，其 `forRoutes()` 直接作用于目标模块。\n */\n@Injectable()\nexport class KeqMiddlewareConsumer {\n  constructor(private readonly keqRequest: KeqRequest) {}\n\n  apply(\n    ...middlewares: Array<KeqNestMiddleware | KeqMiddleware>\n  ): KeqMiddlewareConfigProxy {\n    const collector = new KeqMiddlewareCollector(this.keqRequest, this)\n    return collector.apply(middlewares)\n  }\n}\n","import { Global, Module } from '@nestjs/common'\nimport { KeqRequest } from 'keq'\nimport { KeqMiddlewareConsumer } from './keq-middleware-consumer.js'\n\n\n@Global()\n@Module({\n  providers: [\n    { provide: KeqRequest, useFactory: () => new KeqRequest() },\n    KeqMiddlewareConsumer,\n  ],\n  exports: [KeqRequest, KeqMiddlewareConsumer],\n})\nexport class KeqModule {}\n","import type { KeqMiddleware } from 'keq'\nimport { KeqRequest } from 'keq'\nimport type { KeqModuleClass, KeqScopedConfigProxy } from './interfaces/keq-middleware-consumer.interface.js'\nimport type { KeqNestMiddleware } from './interfaces/keq-nest-middleware.interface.js'\nimport { KeqMiddlewareCollector } from './keq-middleware-collector.js'\n\n\n/**\n * 为指定 Keq 模块按路由注册中间件。\n *\n * Keq 模块由 `@keq-request/cli` 生成，通过\n * {@link InjectKeqConsumer} 装饰器注入本实例。\n *\n * @typeParam T - 目标模块类\n *\n * @example\n * ```ts\n * constructor(\n *   \\@InjectKeqConsumer(GeneratedModule) consumer: KeqConsumer<GeneratedModule>,\n * ) {\n *   consumer.apply(authMw).forRoutes('*')\n * }\n * ```\n */\nexport class KeqConsumer<T = KeqModuleClass> {\n  constructor(private readonly keqRequest: KeqRequest) {}\n\n  apply(\n    ...middlewares: Array<KeqNestMiddleware | KeqMiddleware>\n  ): KeqScopedConfigProxy<T> {\n    const collector = new KeqMiddlewareCollector(this.keqRequest, this)\n    return collector.apply(middlewares) as unknown as KeqScopedConfigProxy<T>\n  }\n}\n","import { Inject } from '@nestjs/common'\nimport type { KeqModuleClass } from '../interfaces/keq-middleware-consumer.interface.js'\n\n\n/**\n * 注入绑定到指定 Keq Module 的 `KeqConsumer<T>`。\n *\n * 被注入的 Module Class 必须同时包含 `KEQ_REQUEST` 和 `KEQ_CONSUMER` 静态属性，\n * 两者均由 keq CLI 生成。\n *\n * 使用方式：\n * ```ts\n * constructor(\n *   \\@InjectKeqConsumer(GeneratedModule) consumer: KeqConsumer<GeneratedModule>,\n * ) {\n *   consumer.apply(mw).forRoutes('*')\n * }\n * ```\n *\n * @param moduleClass - 目标 KeqModule 类（需具有 `KEQ_REQUEST` 和 `KEQ_CONSUMER` symbol）\n */\nexport function InjectKeqConsumer<T extends KeqModuleClass>(\n  moduleClass: T,\n): ParameterDecorator {\n  return Inject(moduleClass.KEQ_CONSUMER)\n}\n"],"mappings":"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"}

package/jest.config.cts

@@ -5,6 +5,16 @@ import { compilerOptions } from './tsconfig.json'
 
 // eslint-disable-next-line @typescript-eslint/require-await
 export default async (): Promise<Config> => ({
-  preset: 'ts-jest',
-  moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths, { prefix: '<rootDir>/src', useESM: true }),
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', {
+      tsconfig: {
+        noEmitOnError: false,
+      },
+    }],
+  },
+  testMatch: [
+    '<rootDir>/__tests__/**/*.spec.ts',
+    '<rootDir>/src/**/*.spec.ts',
+  ],
+  moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths, { prefix: '<rootDir>', useESM: true }),
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keq-request/nestjs",
-  "version": "5.0.0-beta.8",
+  "version": "5.0.0",
   "description": "Request API write by Typescript for flexibility, readability, and a low learning curve.",
   "keywords": [
     "request",
@@ -33,14 +33,22 @@
     "type": "git",
     "url": "git+https://github.com/keq-request/keq.git"
   },
+  "dependencies": {
+    "picomatch": "^4.0.0"
+  },
   "devDependencies": {
     "@nestjs/common": "^11.1.19",
+    "@nestjs/core": "^11.1.19",
+    "@nestjs/testing": "^11.1.27",
     "@types/node": "^20.19.39",
-    "keq": "5.0.0-beta.8"
+    "@types/picomatch": "^4.0.0",
+    "reflect-metadata": "^0.2.2",
+    "keq": "5.0.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^11.0.0",
-    "keq": "^5.0.0-beta.8"
+    "@nestjs/core": "^11.0.0",
+    "keq": "^5.0.0"
   },
   "engines": {
     "node": ">=20.0.0"

package/src/constants.ts

@@ -0,0 +1,3 @@
+export const KEQ_ROUTES = {
+  ALL: Symbol('KEQ_ROUTES.ALL'),
+} as const

package/src/decorators/inject-keq-consumer.decorator.ts

@@ -0,0 +1,26 @@
+import { Inject } from '@nestjs/common'
+import type { KeqModuleClass } from '../interfaces/keq-middleware-consumer.interface.js'
+
+
+/**
+ * 注入绑定到指定 Keq Module 的 `KeqConsumer<T>`。
+ *
+ * 被注入的 Module Class 必须同时包含 `KEQ_REQUEST` 和 `KEQ_CONSUMER` 静态属性，
+ * 两者均由 keq CLI 生成。
+ *
+ * 使用方式：
+ * ```ts
+ * constructor(
+ *   \@InjectKeqConsumer(GeneratedModule) consumer: KeqConsumer<GeneratedModule>,
+ * ) {
+ *   consumer.apply(mw).forRoutes('*')
+ * }
+ * ```
+ *
+ * @param moduleClass - 目标 KeqModule 类（需具有 `KEQ_REQUEST` 和 `KEQ_CONSUMER` symbol）
+ */
+export function InjectKeqConsumer<T extends KeqModuleClass>(
+  moduleClass: T,
+): ParameterDecorator {
+  return Inject(moduleClass.KEQ_CONSUMER)
+}

package/src/index.ts

@@ -1,2 +1,6 @@
 export * from './keq.module.js'
-export * from './types/index.js'
+export * from './keq-middleware-consumer.js'
+export * from './keq-consumer.js'
+export * from './constants.js'
+export * from './interfaces/index.js'
+export { InjectKeqConsumer } from './decorators/inject-keq-consumer.decorator.js'

package/src/interfaces/index.ts

@@ -0,0 +1,9 @@
+export type { KeqNestMiddleware } from './keq-nest-middleware.interface.js'
+export type {
+  KeqMiddlewareConfigProxy,
+  KeqScopedConfigProxy,
+  KeqRouteInfo,
+  KeqRouteTarget,
+  KeqModuleClass,
+} from './keq-middleware-consumer.interface.js'
+export type { KeqModuleOptions } from './keq-module-options.interface.js'

package/src/interfaces/keq-middleware-consumer.interface.ts

@@ -0,0 +1,30 @@
+import type { Type } from '@nestjs/common'
+import type { KEQ_ROUTES } from '../constants.js'
+import type { KeqMiddlewareConsumer } from '../keq-middleware-consumer.js'
+import type { KeqConsumer } from '../keq-consumer.js'
+
+
+export interface KeqRouteInfo {
+  host?: string
+  method?: string
+  pathname?: string
+}
+
+export interface KeqModuleClass extends Type<any> {
+  readonly KEQ_REQUEST: symbol
+  readonly KEQ_CONSUMER: symbol
+}
+
+/** forRoutes() 接受的路由目标（不再包含 KeqModuleClass，模块绑定通过 @InjectKeqConsumer 实现） */
+export type KeqRouteTarget = typeof KEQ_ROUTES.ALL | KeqRouteInfo
+
+export interface KeqMiddlewareConfigProxy {
+  exclude(...routes: KeqRouteInfo[]): KeqMiddlewareConfigProxy
+  forRoutes(...routes: KeqRouteTarget[]): KeqMiddlewareConsumer
+}
+
+/** 模块绑定 Consumer 的配置代理，forRoutes() 返回 KeqConsumer<T> */
+export interface KeqScopedConfigProxy<T = KeqModuleClass> {
+  exclude(...routes: KeqRouteInfo[]): KeqScopedConfigProxy<T>
+  forRoutes(...routes: KeqRouteTarget[]): KeqConsumer<T>
+}

package/src/{types/keq-module-options.ts → interfaces/keq-module-options.interface.ts}

@@ -1,6 +1,7 @@
-import { KeqMiddleware } from 'keq'
+import type { KeqMiddleware } from 'keq'
 
 
 export interface KeqModuleOptions {
   middlewares?: KeqMiddleware[]
+  isolate?: boolean
 }

package/src/interfaces/keq-nest-middleware.interface.ts

@@ -0,0 +1,6 @@
+import type { KeqExecutionContext, KeqNext } from 'keq'
+
+
+export interface KeqNestMiddleware {
+  use(ctx: KeqExecutionContext, next: KeqNext): void | PromiseLike<void>
+}

package/src/keq-consumer.ts

@@ -0,0 +1,34 @@
+import type { KeqMiddleware } from 'keq'
+import { KeqRequest } from 'keq'
+import type { KeqModuleClass, KeqScopedConfigProxy } from './interfaces/keq-middleware-consumer.interface.js'
+import type { KeqNestMiddleware } from './interfaces/keq-nest-middleware.interface.js'
+import { KeqMiddlewareCollector } from './keq-middleware-collector.js'
+
+
+/**
+ * 为指定 Keq 模块按路由注册中间件。
+ *
+ * Keq 模块由 `@keq-request/cli` 生成，通过
+ * {@link InjectKeqConsumer} 装饰器注入本实例。
+ *
+ * @typeParam T - 目标模块类
+ *
+ * @example
+ * ```ts
+ * constructor(
+ *   \@InjectKeqConsumer(GeneratedModule) consumer: KeqConsumer<GeneratedModule>,
+ * ) {
+ *   consumer.apply(authMw).forRoutes('*')
+ * }
+ * ```
+ */
+export class KeqConsumer<T = KeqModuleClass> {
+  constructor(private readonly keqRequest: KeqRequest) {}
+
+  apply(
+    ...middlewares: Array<KeqNestMiddleware | KeqMiddleware>
+  ): KeqScopedConfigProxy<T> {
+    const collector = new KeqMiddlewareCollector(this.keqRequest, this)
+    return collector.apply(middlewares) as unknown as KeqScopedConfigProxy<T>
+  }
+}

package/src/keq-middleware-collector.ts

@@ -0,0 +1,150 @@
+import type { KeqExecutionContext, KeqMiddleware, KeqRoute } from 'keq'
+import { composeRoute, KeqRequest } from 'keq'
+import picomatch from 'picomatch'
+import { KEQ_ROUTES } from './constants.js'
+import type { KeqMiddlewareConfigProxy, KeqRouteTarget, KeqRouteInfo } from './interfaces/keq-middleware-consumer.interface.js'
+import type { KeqNestMiddleware } from './interfaces/keq-nest-middleware.interface.js'
+
+
+/** 单条中间件注册条目 */
+interface MiddlewareEntry {
+  middlewares: Array<KeqNestMiddleware | KeqMiddleware>
+  routes: KeqRouteTarget[]
+  excludedRouteInfos?: KeqRouteInfo[]
+}
+
+/**
+ * 中间件收集器，收集中间件配置条目并应用到指定的 {@link KeqRequest} 实例。
+ *
+ * 通过 `apply()` → `forRoutes()` 链式 API 收集多组中间件条目，
+ * 在 `forRoutes()` 被调用时立即将中间件绑定到目标请求。
+ *
+ * 注意：该类并非 `@Injectable()`，由 Consumer 内部手动创建。
+ *
+ * @typeParam TConsumer - Consumer 类型（`KeqMiddlewareConsumer` 或 `KeqConsumer<T>`）
+ */
+export class KeqMiddlewareCollector<TConsumer extends object = object> {
+  private entries: MiddlewareEntry[] = []
+
+  constructor(
+    private readonly keqRequest: KeqRequest,
+    private readonly consumer: TConsumer,
+  ) {}
+
+  apply(
+    middlewares: Array<KeqNestMiddleware | KeqMiddleware>,
+  ): KeqMiddlewareConfigProxy {
+    const entry: MiddlewareEntry = { middlewares, routes: [] }
+    const excludedRouteInfos: KeqRouteInfo[] = []
+    this.entries.push(entry)
+
+    const { keqRequest, consumer } = this
+
+    const proxy = {
+      exclude: (...routes: KeqRouteInfo[]) => {
+        excludedRouteInfos.push(...routes)
+        return proxy
+      },
+      forRoutes: (...routes: KeqRouteTarget[]) => {
+        entry.routes = routes
+        if (excludedRouteInfos.length > 0) {
+          entry.excludedRouteInfos = excludedRouteInfos
+        }
+        this.applyTo(keqRequest)
+        return consumer
+      },
+    }
+    return proxy as unknown as KeqMiddlewareConfigProxy
+  }
+
+  /**
+   * 将收集的所有中间件条目解析并应用到指定的 {@link KeqRequest} 实例。
+   */
+  applyTo(keqRequest: KeqRequest): void {
+    for (const entry of this.entries) {
+      let resolved = entry.middlewares.map((m) => this.normalizeMiddleware(m))
+
+      if (entry.excludedRouteInfos && entry.excludedRouteInfos.length > 0) {
+        const excludedRoutes = entry.excludedRouteInfos.map((info) => this.buildRoute(info))
+        resolved = resolved.map((mw) => this.wrapWithExclusion(mw, excludedRoutes))
+      }
+
+      const isGlobal
+        = entry.routes.length === 0 || entry.routes.some((r) => r === KEQ_ROUTES.ALL)
+
+      if (isGlobal) {
+        for (const mw of resolved) keqRequest.use(mw)
+      } else {
+        for (const routeTarget of entry.routes) {
+          if (routeTarget === KEQ_ROUTES.ALL) continue
+          const route = this.buildRoute(routeTarget as KeqRouteInfo)
+          keqRequest.useRouter().route(route, resolved)
+        }
+      }
+    }
+  }
+
+  // ─── 中间件标准化 ────────────────────────────────────
+
+  /**
+   * 标准化中间件：将不同形式的中间件统一为 {@link KeqMiddleware} 函数。
+   * - 若已是 {@link KeqMiddleware} 函数 → 直接返回
+   * - 若为 {@link KeqNestMiddleware} 实例对象 → 包装 `use` 方法为中间件函数
+   */
+  private normalizeMiddleware(
+    m: KeqNestMiddleware | KeqMiddleware,
+  ): KeqMiddleware {
+    if (this.isNestMiddlewareInstance(m)) {
+      return async (ctx, next) => {
+        await m.use(ctx, next)
+      }
+    }
+    return m
+  }
+
+  private isNestMiddlewareInstance(
+    m: KeqNestMiddleware | KeqMiddleware,
+  ): m is KeqNestMiddleware {
+    return typeof m === 'object' && m !== null && 'use' in m
+  }
+
+  // ─── 路由构建 ─────────────────────────────────────────
+
+  private buildRoute(info: KeqRouteInfo): KeqRoute {
+    const routes: KeqRoute[] = []
+    if (info.host) {
+      const host = info.host
+      routes.push((ctx) => ctx.request.url.host === host)
+    }
+    if (info.method) {
+      const method = info.method.toLowerCase()
+      routes.push((ctx) => ctx.request.method.toLowerCase() === method)
+    }
+    if (info.pathname) {
+      const isMatch: (test: string) => boolean = picomatch(info.pathname)
+      routes.push((ctx) => isMatch(ctx.request.url.pathname))
+    }
+    if (routes.length === 1) return routes[0]
+    return composeRoute(routes)
+  }
+
+  private wrapWithExclusion(middleware: KeqMiddleware, excludedRoutes: KeqRoute[]): KeqMiddleware {
+    const excluded: KeqMiddleware = async (ctx, next) => {
+      if (await this.checkExcluded(ctx, excludedRoutes)) {
+        return next()
+      }
+      return middleware(ctx, next)
+    }
+    return excluded
+  }
+
+  private async checkExcluded(
+    ctx: KeqExecutionContext,
+    excludedRoutes: KeqRoute[],
+  ): Promise<boolean> {
+    for (const route of excludedRoutes) {
+      if (await route(ctx)) return true
+    }
+    return false
+  }
+}

package/src/keq-middleware-consumer.ts

@@ -0,0 +1,33 @@
+import { Injectable } from '@nestjs/common'
+import type { KeqMiddleware } from 'keq'
+import { KeqRequest } from 'keq'
+import type { KeqMiddlewareConfigProxy } from './interfaces/keq-middleware-consumer.interface.js'
+import type { KeqNestMiddleware } from './interfaces/keq-nest-middleware.interface.js'
+import { KeqMiddlewareCollector } from './keq-middleware-collector.js'
+
+
+/**
+ * 全局中间件消费者，提供 `.apply().forRoutes()` API。
+ *
+ * `forRoutes()` 返回 `KeqMiddlewareConsumer` 自身，支持链式注册：
+ *
+ * ```ts
+ * consumer
+ *   .apply(mw1).forRoutes(KEQ_ROUTES.ALL)
+ *   .apply(mw2).forRoutes({ pathname: '/api/*' })
+ * ```
+ *
+ * 模块级别的中间件请使用 `@InjectKeqConsumer(GeneratedModule)` 注入
+ * `KeqConsumer<GeneratedModule>`，其 `forRoutes()` 直接作用于目标模块。
+ */
+@Injectable()
+export class KeqMiddlewareConsumer {
+  constructor(private readonly keqRequest: KeqRequest) {}
+
+  apply(
+    ...middlewares: Array<KeqNestMiddleware | KeqMiddleware>
+  ): KeqMiddlewareConfigProxy {
+    const collector = new KeqMiddlewareCollector(this.keqRequest, this)
+    return collector.apply(middlewares)
+  }
+}