@keq-request/nestjs 5.0.0-beta.13 → 5.0.0-beta.15

package/.turbo/turbo-build.log

@@ -1,10 +1,10 @@
 
-> @keq-request/nestjs@5.0.0-beta.13 build /home/runner/work/keq/keq/packages/nestjs
+> @keq-request/nestjs@5.0.0-beta.15 build /home/runner/work/keq/keq/packages/nestjs
 > tsdown
 
 ℹ tsdown v0.21.10 powered by rolldown v1.0.0-rc.17
 ℹ config file: /home/runner/work/keq/keq/packages/nestjs/tsdown.config.ts 
-(node:2744) [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file:///home/runner/work/keq/keq/packages/nestjs/tsdown.config.ts?no-cache=63d674a9-ded8-4584-ad0b-ff9b06a87e93 is not specified and it doesn't parse as CommonJS.
+(node:2727) [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file:///home/runner/work/keq/keq/packages/nestjs/tsdown.config.ts?no-cache=b289e4f8-de50-42cc-a1c8-4e34b36675d9 is not specified and it doesn't parse as CommonJS.
 Reparsing as ES module because module syntax was detected. This incurs a performance overhead.
 To eliminate this warning, add "type": "module" to /home/runner/work/keq/keq/packages/nestjs/package.json.
 (Use `node --trace-warnings ...` to show where the warning was created)
@@ -12,25 +12,23 @@ To eliminate this warning, add "type": "module" to /home/runner/work/keq/keq/pac
 ℹ target: node20
 ℹ tsconfig: tsconfig.lib.json
 ℹ Build start
-ℹ [CJS] dist/index.js      10.52 kB │ gzip: 3.95 kB
-ℹ [CJS] dist/index.js.map  15.05 kB │ gzip: 5.17 kB
-ℹ [CJS] 2 files, total: 25.57 kB
-[PLUGIN_TIMINGS] Warning: Your build spent significant time in plugin `tsdown:deps`. See https://rolldown.rs/options/checks#plugintimings for more details.
-
-ℹ [ESM] dist/index.mjs         9.19 kB │ gzip: 3.46 kB
-ℹ [ESM] dist/index.mjs.map    14.98 kB │ gzip: 5.14 kB
-ℹ [ESM] dist/index.d.mts.map   1.08 kB │ gzip: 0.47 kB
-ℹ [ESM] dist/index.d.mts       2.96 kB │ gzip: 1.38 kB
-ℹ [ESM] 4 files, total: 28.22 kB
-[PLUGIN_TIMINGS] Warning: Your build spent significant time in plugin `rolldown-plugin-dts:generate`. See https://rolldown.rs/options/checks#plugintimings for more details.
-
-✔ Build complete in 5612ms
-ℹ [CJS] dist/index.d.ts.map  1.08 kB │ gzip: 0.47 kB
-ℹ [CJS] dist/index.d.ts      2.96 kB │ gzip: 1.37 kB
-ℹ [CJS] 2 files, total: 4.04 kB
+ℹ [CJS] dist/index.js       8.01 kB │ gzip: 2.93 kB
+ℹ [CJS] dist/index.js.map  11.70 kB │ gzip: 3.78 kB
+ℹ [CJS] 2 files, total: 19.72 kB
+ℹ [CJS] dist/index.d.ts.map  1.39 kB │ gzip: 0.55 kB
+ℹ [CJS] dist/index.d.ts      3.81 kB │ gzip: 1.45 kB
+ℹ [CJS] 2 files, total: 5.20 kB
 [PLUGIN_TIMINGS] Warning: Your build spent significant time in plugins. Here is a breakdown:
-  - rolldown-plugin-dts:generate (48%)
-  - tsdown:deps (43%)
+  - rolldown-plugin-dts:generate (46%)
+  - tsdown:deps (41%)
 See https://rolldown.rs/options/checks#plugintimings for more details.
 
-✔ Build complete in 5614ms
+✔ Build complete in 5374ms
+ℹ [ESM] dist/index.mjs         6.58 kB │ gzip: 2.45 kB
+ℹ [ESM] dist/index.mjs.map    11.61 kB │ gzip: 3.75 kB
+ℹ [ESM] dist/index.d.mts.map   1.39 kB │ gzip: 0.55 kB
+ℹ [ESM] dist/index.d.mts       3.81 kB │ gzip: 1.46 kB
+ℹ [ESM] 4 files, total: 23.38 kB
+[PLUGIN_TIMINGS] Warning: Your build spent significant time in plugin `rolldown-plugin-dts:generate`. See https://rolldown.rs/options/checks#plugintimings for more details.
+
+✔ Build complete in 5376ms

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @keq-request/nestjs
 
+## 5.0.0-beta.15
+
+### Patch Changes
+
+- keq@5.0.0-beta.15
+
+## 5.0.0-beta.14
+
+### Major Changes
+
+- 23c971f: **BREAKING CHANGE:** Refactor NestJS middleware configuration from lifecycle hook pattern to dependency injection pattern, introducing `KeqMiddlewareConsumer` as an injectable service and `@InjectKeqConsumer()` decorator with `KeqConsumer<T>` for module-scoped middleware.
+
+  - Remove `KeqMiddlewareModule` interface and `configureKeqMiddleware()` lifecycle method. Middleware is now registered by injecting `KeqMiddlewareConsumer` or `KeqConsumer<T>` directly into services.
+  - Remove `KeqMiddlewareConsumer` interface — it is now a concrete `@Injectable()` class provided by `KeqModule`.
+  - Remove `hasConfigureKeqMiddleware()` utility function.
+  - Remove `forRoutes()` support for `KeqModuleClass` route targets. Use `KeqConsumer<T>` (injected via `@InjectKeqConsumer(ModuleClass)`) for module-scoped middleware.
+  - `KeqModuleClass` now requires a static `KEQ_CONSUMER: symbol` property in addition to `KEQ_REQUEST`.
+  - `KeqModule` no longer has a `register()` static method — it is now a bare `@Global()` module. Import `KeqModule` directly.
+  - Add `@InjectKeqConsumer(ModuleClass)` decorator, `KeqConsumer<T>` class, `KeqRouteTarget` type, and `KeqScopedConfigProxy<T>` interface.
+  - CLI-generated NestJS modules now expose `KEQ_CONSUMER` symbol and provide a `KeqConsumer` provider for `@InjectKeqConsumer()` injection.
+
+### Patch Changes
+
+- keq@5.0.0-beta.14
+
 ## 5.0.0-beta.13
 
 ### Patch Changes

package/__tests__/keq-module.spec.ts

@@ -1,155 +1,203 @@
 import 'reflect-metadata'
 import { expect, test } from '@jest/globals'
-import { Module } from '@nestjs/common'
-import type { ModulesContainer } from '@nestjs/core'
-import { KeqModule, validateConfigureKeqMiddlewareImports } from '../src/keq.module.js'
-
-/**
- * 模拟 NestJS Module wrapper 的运行时结构。
- * NestJS 在扫描阶段会将 DynamicModule 的 imports 解析为 Set<Module>，
- * 因此使用 imports Set 而非静态 Reflect.getMetadata 来校验。
- */
-function createMockModule(metatype: unknown, importsModules: Array<{ metatype: unknown }> = []) {
-  return {
-    metatype,
-    imports: new Set(importsModules),
-  }
-}
-
-function mockModulesContainer(
-  modules: Array<ReturnType<typeof createMockModule>>,
-): ModulesContainer {
-  const map = new Map()
-  for (const mod of modules) {
-    map.set(Symbol('module'), mod)
-  }
-  return map as unknown as ModulesContainer
-}
+import type { KeqMiddleware } from 'keq'
+import { KeqRequest } from 'keq'
+import { KeqMiddlewareConsumer } from '../src/keq-middleware-consumer.js'
+import { KeqConsumer } from '../src/keq-consumer.js'
+import { KEQ_ROUTES } from '../src/constants.js'
 
 
-test('throws when configureKeqMiddleware is declared without KeqModule in imports', () => {
-  @Module({ imports: [] })
-  class BadModule {
-    configureKeqMiddleware(): void {}
-  }
+test('applies global middleware via forRoutes(KEQ_ROUTES.ALL)', () => {
+  const keqRequest = new KeqRequest()
+  const consumer = new KeqMiddlewareConsumer(keqRequest)
 
-  const container = mockModulesContainer([
-    createMockModule(KeqModule),
-    createMockModule(BadModule),
-  ])
+  const middleware: KeqMiddleware = async (_ctx, next) => { await next() }
+  consumer.apply(middleware).forRoutes(KEQ_ROUTES.ALL)
 
-  expect(() => validateConfigureKeqMiddlewareImports(container)).toThrow(
-    /\[KeqModule\] 'BadModule' implements configureKeqMiddleware\(\)/,
-  )
+  expect(keqRequest.middlewares.length).toBe(1)
 })
 
-test('passes when configureKeqMiddleware is declared with KeqModule in imports', () => {
-  @Module({ imports: [KeqModule] })
-  class GoodModule {
-    configureKeqMiddleware(): void {}
-  }
+test('applies global middleware when forRoutes receives no arguments', () => {
+  const keqRequest = new KeqRequest()
+  const consumer = new KeqMiddlewareConsumer(keqRequest)
+
+  const middleware: KeqMiddleware = async (_ctx, next) => { await next() }
+  consumer.apply(middleware).forRoutes()
 
-  const keqModuleWrapper = createMockModule(KeqModule)
+  expect(keqRequest.middlewares.length).toBe(1)
+})
+
+test('applies route-specific middleware via forRoutes with KeqRouteInfo', () => {
+  const keqRequest = new KeqRequest()
+  const consumer = new KeqMiddlewareConsumer(keqRequest)
 
-  const container = mockModulesContainer([
-    keqModuleWrapper,
-    createMockModule(GoodModule, [keqModuleWrapper]),
-  ])
+  const middleware: KeqMiddleware = async (_ctx, next) => { await next() }
+  consumer.apply(middleware).forRoutes({ pathname: '/api/*' })
 
-  expect(() => validateConfigureKeqMiddlewareImports(container)).not.toThrow()
+  expect(keqRequest.middlewares.length).toBe(1)
 })
 
-test('passes when module does not implement configureKeqMiddleware', () => {
-  @Module({ imports: [] })
-  class PlainModule {}
+test('supports multiple middleware in single apply()', () => {
+  const keqRequest = new KeqRequest()
+  const consumer = new KeqMiddlewareConsumer(keqRequest)
 
-  const container = mockModulesContainer([
-    createMockModule(PlainModule),
-  ])
+  const mw1: KeqMiddleware = async (_ctx, next) => { await next() }
+  const mw2: KeqMiddleware = async (_ctx, next) => { await next() }
+  consumer.apply(mw1, mw2).forRoutes(KEQ_ROUTES.ALL)
 
-  expect(() => validateConfigureKeqMiddlewareImports(container)).not.toThrow()
+  expect(keqRequest.middlewares.length).toBe(2)
 })
 
-test('passes when KeqModule is imported as DynamicModule', () => {
-  @Module({ imports: [{ module: KeqModule }] })
-  class DynamicImportModule {
-    configureKeqMiddleware(): void {}
-  }
+test('supports multiple apply() calls', () => {
+  const keqRequest = new KeqRequest()
+  const consumer = new KeqMiddlewareConsumer(keqRequest)
 
-  // NestJS 在扫描阶段解析 DynamicModule，将 KeqModule wrapper 加入 imports Set
-  const keqModuleWrapper = createMockModule(KeqModule)
+  const mw1: KeqMiddleware = async (_ctx, next) => { await next() }
+  const mw2: KeqMiddleware = async (_ctx, next) => { await next() }
 
-  const container = mockModulesContainer([
-    keqModuleWrapper,
-    createMockModule(DynamicImportModule, [keqModuleWrapper]),
-  ])
+  consumer.apply(mw1).forRoutes(KEQ_ROUTES.ALL)
+  consumer.apply(mw2).forRoutes({ pathname: '/api/*' })
 
-  expect(() => validateConfigureKeqMiddlewareImports(container)).not.toThrow()
+  expect(keqRequest.middlewares.length).toBe(2)
 })
 
-test('passes when KeqModule is imported via forwardRef', () => {
-  const { forwardRef } = require('@nestjs/common')
-  @Module({ imports: [forwardRef(() => KeqModule)] })
-  class ForwardRefModule {
-    configureKeqMiddleware(): void {}
-  }
+test('supports exclude().forRoutes() chaining', () => {
+  const keqRequest = new KeqRequest()
+  const consumer = new KeqMiddlewareConsumer(keqRequest)
+
+  const middleware: KeqMiddleware = async (_ctx, next) => { await next() }
+  consumer.apply(middleware).exclude({ pathname: '/health' }).forRoutes(KEQ_ROUTES.ALL)
+
+  expect(keqRequest.middlewares.length).toBe(1)
+})
+
+test('middleware is applied synchronously at forRoutes() call time', () => {
+  const keqRequest = new KeqRequest()
+  const consumer = new KeqMiddlewareConsumer(keqRequest)
+
+  const middleware: KeqMiddleware = async (_ctx, next) => { await next() }
+
+  expect(keqRequest.middlewares.length).toBe(0)
+  consumer.apply(middleware).forRoutes(KEQ_ROUTES.ALL)
+  expect(keqRequest.middlewares.length).toBe(1)
+})
+
+test('supports chaining multiple apply() calls via forRoutes returning consumer', () => {
+  const keqRequest = new KeqRequest()
+  const consumer = new KeqMiddlewareConsumer(keqRequest)
+
+  const mw1: KeqMiddleware = async (_ctx, next) => { await next() }
+  const mw2: KeqMiddleware = async (_ctx, next) => { await next() }
+  const mw3: KeqMiddleware = async (_ctx, next) => { await next() }
+
+  consumer
+    .apply(mw1).forRoutes(KEQ_ROUTES.ALL)
+    .apply(mw2).forRoutes({ pathname: '/api/*' })
+    .apply(mw3).exclude({ pathname: '/health' }).forRoutes(KEQ_ROUTES.ALL)
+
+  expect(keqRequest.middlewares.length).toBe(3)
+})
+
+// ─── KeqConsumer（模块绑定）测试 ──────────────────────────
 
-  // NestJS 在扫描阶段解析 forwardRef，将 KeqModule wrapper 加入 imports Set
-  const keqModuleWrapper = createMockModule(KeqModule)
+test('KeqConsumer applies middleware to its own KeqRequest', () => {
+  const scopedKeqRequest = new KeqRequest()
+  const consumer = new KeqConsumer(scopedKeqRequest)
 
-  const container = mockModulesContainer([
-    keqModuleWrapper,
-    createMockModule(ForwardRefModule, [keqModuleWrapper]),
-  ])
+  const middleware: KeqMiddleware = async (_ctx, next) => { await next() }
+  consumer.apply(middleware).forRoutes(KEQ_ROUTES.ALL)
 
-  expect(() => validateConfigureKeqMiddlewareImports(container)).not.toThrow()
+  expect(scopedKeqRequest.middlewares.length).toBe(1)
 })
 
-test('passes when metatype is null', () => {
-  const container = mockModulesContainer([
-    createMockModule(null as unknown as undefined),
-  ])
+test('KeqConsumer does not affect other KeqRequest instances', () => {
+  const globalKeqRequest = new KeqRequest()
+  const scopedKeqRequest = new KeqRequest()
+
+  const globalConsumer = new KeqMiddlewareConsumer(globalKeqRequest)
+  const scopedConsumer = new KeqConsumer(scopedKeqRequest)
 
-  expect(() => validateConfigureKeqMiddlewareImports(container)).not.toThrow()
+  const middleware: KeqMiddleware = async (_ctx, next) => { await next() }
+  scopedConsumer.apply(middleware).forRoutes(KEQ_ROUTES.ALL)
+
+  expect(scopedKeqRequest.middlewares.length).toBe(1)
+  expect(globalKeqRequest.middlewares.length).toBe(0)
 })
 
-test('throws when module has configureKeqMiddleware but KeqModule is not in container', () => {
-  // KeqModule 未在 ModulesContainer 中注册时，任何实现了 configureKeqMiddleware
-  // 的模块都无法通过校验，因为缺少 KeqModule 来注册中间件
-  @Module({ imports: [] })
-  class SomeModule {
-    configureKeqMiddleware(): void {}
+// ─── KeqNestMiddleware 实例对象测试 ──────────────────────
+
+test('applies KeqNestMiddleware instance via apply()', () => {
+  const keqRequest = new KeqRequest()
+  const consumer = new KeqMiddlewareConsumer(keqRequest)
+
+  const middleware = {
+    use: async (_ctx: unknown, next: () => Promise<void>) => { await next() },
   }
+  consumer.apply(middleware).forRoutes(KEQ_ROUTES.ALL)
+
+  expect(keqRequest.middlewares.length).toBe(1)
+})
 
-  const container = mockModulesContainer([
-    createMockModule(SomeModule),
-  ])
+test('applies KeqNestMiddleware instance to specific route', () => {
+  const keqRequest = new KeqRequest()
+  const consumer = new KeqMiddlewareConsumer(keqRequest)
+
+  const middleware = {
+    use: async (_ctx: unknown, next: () => Promise<void>) => { await next() },
+  }
+  consumer.apply(middleware).forRoutes({ pathname: '/api/*' })
 
-  expect(() => validateConfigureKeqMiddlewareImports(container)).toThrow(
-    /\[KeqModule\] 'SomeModule'/,
-  )
+  expect(keqRequest.middlewares.length).toBe(1)
 })
 
-test('throws for one module while another is valid', () => {
-  @Module({ imports: [] })
-  class BadModule {
-    configureKeqMiddleware(): void {}
+test('mixes KeqMiddleware function and KeqNestMiddleware instance', () => {
+  const keqRequest = new KeqRequest()
+  const consumer = new KeqMiddlewareConsumer(keqRequest)
+
+  const fnMw: KeqMiddleware = async (_ctx, next) => { await next() }
+  const instanceMw = {
+    use: async (_ctx: unknown, next: () => Promise<void>) => { await next() },
   }
+  consumer.apply(fnMw, instanceMw).forRoutes(KEQ_ROUTES.ALL)
+
+  expect(keqRequest.middlewares.length).toBe(2)
+})
+
+test('KeqNestMiddleware instance receives ctx and next in use()', async () => {
+  const keqRequest = new KeqRequest()
+  const consumer = new KeqMiddlewareConsumer(keqRequest)
+
+  let capturedCtx: unknown = null
+  let capturedNext: unknown = null
 
-  @Module({ imports: [KeqModule] })
-  class GoodModule {
-    configureKeqMiddleware(): void {}
+  const middleware = {
+    use: async (ctx: unknown, next: () => Promise<void>) => {
+      capturedCtx = ctx
+      capturedNext = next
+      await next()
+    },
   }
+  consumer.apply(middleware).forRoutes(KEQ_ROUTES.ALL)
 
-  const keqModuleWrapper = createMockModule(KeqModule)
+  const middlewareFn = keqRequest.middlewares[0]
+  const mockCtx = { request: { url: { host: 'example.com', pathname: '/' }, method: 'GET' } }
+  const mockNext = async () => {}
 
-  const container = mockModulesContainer([
-    keqModuleWrapper,
-    createMockModule(GoodModule, [keqModuleWrapper]),
-    createMockModule(BadModule),
-  ])
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  await (middlewareFn as any)(mockCtx, mockNext)
+
+  expect(capturedCtx).toBe(mockCtx)
+  expect(typeof capturedNext).toBe('function')
+})
+
+test('KeqConsumer accepts KeqNestMiddleware instance', () => {
+  const scopedKeqRequest = new KeqRequest()
+  const consumer = new KeqConsumer(scopedKeqRequest)
+
+  const middleware = {
+    use: async (_ctx: unknown, next: () => Promise<void>) => { await next() },
+  }
+  consumer.apply(middleware).forRoutes(KEQ_ROUTES.ALL)
 
-  expect(() => validateConfigureKeqMiddlewareImports(container)).toThrow(
-    /'BadModule'/,
-  )
+  expect(scopedKeqRequest.middlewares.length).toBe(1)
 })

package/dist/index.d.mts

@@ -1,31 +1,8 @@
-import { OnModuleInit, Type } from "@nestjs/common";
-import { ModulesContainer } from "@nestjs/core";
+import { Type } from "@nestjs/common";
 import { KeqExecutionContext, KeqMiddleware, KeqNext, KeqRequest } from "keq";
 
 //#region src/keq.module.d.ts
-/**
- * 在 NestJS 模块初始化早期阶段校验 `configureKeqMiddleware` 的实现模块
- * 是否显式导入了 `KeqModule`。
- *
- * NestJS 初始化分为两个严格串行的阶段：
- * 1. 全量扫描 — 所有模块 wrapper 加入 ModulesContainer，metatype 已设置，
- *    DynamicModule 的 imports 已被解析并写入 moduleWrapper.imports Set
- * 2. 实例创建 — 按依赖顺序调用构造函数 → onModuleInit
- *
- * 此校验在阶段 2 开头（构造函数中）执行，早于所有 onModuleInit，
- * 确保中间件缺失问题在启动期就被捕获，而非在业务模块 onModuleInit 发请求时静默失效。
- *
- * 使用运行时 imports Set 而非 Reflect.getMetadata('imports', metatype) 的原因：
- * - DynamicModule 通过 register() 返回的 imports 不在静态装饰器元数据中
- * - 从 ModulesContainer 获取 KeqModule metatype 可避免 pnpm 重复包实例导致的 === 比对失败
- */
-declare function validateConfigureKeqMiddlewareImports(modulesContainer: ModulesContainer): void;
-declare class KeqModule implements OnModuleInit {
-  private readonly modulesContainer;
-  private readonly keqRequest;
-  constructor(modulesContainer: ModulesContainer, keqRequest: KeqRequest);
-  onModuleInit(): void;
-}
+declare class KeqModule {}
 //#endregion
 //#region src/constants.d.ts
 declare const KEQ_ROUTES: {
@@ -37,6 +14,30 @@ interface KeqNestMiddleware {
   use(ctx: KeqExecutionContext, next: KeqNext): void | PromiseLike<void>;
 }
 //#endregion
+//#region src/keq-consumer.d.ts
+/**
+ * 为指定 Keq 模块按路由注册中间件。
+ *
+ * Keq 模块由 `@keq-request/cli` 生成，通过
+ * {@link InjectKeqConsumer} 装饰器注入本实例。
+ *
+ * @typeParam T - 目标模块类
+ *
+ * @example
+ * ```ts
+ * constructor(
+ *   \@InjectKeqConsumer(GeneratedModule) consumer: KeqConsumer<GeneratedModule>,
+ * ) {
+ *   consumer.apply(authMw).forRoutes('*')
+ * }
+ * ```
+ */
+declare class KeqConsumer<T = KeqModuleClass> {
+  private readonly keqRequest;
+  constructor(keqRequest: KeqRequest);
+  apply(...middlewares: Array<KeqNestMiddleware | KeqMiddleware>): KeqScopedConfigProxy<T>;
+}
+//#endregion
 //#region src/interfaces/keq-middleware-consumer.interface.d.ts
 interface KeqRouteInfo {
   host?: string;
@@ -45,18 +46,39 @@ interface KeqRouteInfo {
 }
 interface KeqModuleClass extends Type<any> {
   readonly KEQ_REQUEST: symbol;
+  readonly KEQ_CONSUMER: symbol;
 }
+/** forRoutes() 接受的路由目标（不再包含 KeqModuleClass，模块绑定通过 @InjectKeqConsumer 实现） */
+type KeqRouteTarget = typeof KEQ_ROUTES.ALL | KeqRouteInfo;
 interface KeqMiddlewareConfigProxy {
   exclude(...routes: KeqRouteInfo[]): KeqMiddlewareConfigProxy;
-  forRoutes(...routes: Array<typeof KEQ_ROUTES.ALL | KeqRouteInfo | KeqModuleClass>): KeqMiddlewareConsumer;
+  forRoutes(...routes: KeqRouteTarget[]): KeqMiddlewareConsumer;
 }
-interface KeqMiddlewareConsumer {
-  apply(...middlewares: Array<Type<KeqNestMiddleware> | KeqMiddleware>): KeqMiddlewareConfigProxy;
+/** 模块绑定 Consumer 的配置代理，forRoutes() 返回 KeqConsumer<T> */
+interface KeqScopedConfigProxy<T = KeqModuleClass> {
+  exclude(...routes: KeqRouteInfo[]): KeqScopedConfigProxy<T>;
+  forRoutes(...routes: KeqRouteTarget[]): KeqConsumer<T>;
 }
 //#endregion
-//#region src/interfaces/keq-middleware-module.interface.d.ts
-interface KeqMiddlewareModule {
-  configureKeqMiddleware(consumer: KeqMiddlewareConsumer): void;
+//#region src/keq-middleware-consumer.d.ts
+/**
+ * 全局中间件消费者，提供 `.apply().forRoutes()` API。
+ *
+ * `forRoutes()` 返回 `KeqMiddlewareConsumer` 自身，支持链式注册：
+ *
+ * ```ts
+ * consumer
+ *   .apply(mw1).forRoutes(KEQ_ROUTES.ALL)
+ *   .apply(mw2).forRoutes({ pathname: '/api/*' })
+ * ```
+ *
+ * 模块级别的中间件请使用 `@InjectKeqConsumer(GeneratedModule)` 注入
+ * `KeqConsumer<GeneratedModule>`，其 `forRoutes()` 直接作用于目标模块。
+ */
+declare class KeqMiddlewareConsumer {
+  private readonly keqRequest;
+  constructor(keqRequest: KeqRequest);
+  apply(...middlewares: Array<KeqNestMiddleware | KeqMiddleware>): KeqMiddlewareConfigProxy;
 }
 //#endregion
 //#region src/interfaces/keq-module-options.interface.d.ts
@@ -65,5 +87,25 @@ interface KeqModuleOptions {
   isolate?: boolean;
 }
 //#endregion
-export { KEQ_ROUTES, type KeqMiddlewareConfigProxy, type KeqMiddlewareConsumer, type KeqMiddlewareModule, KeqModule, type KeqModuleClass, type KeqModuleOptions, type KeqNestMiddleware, type KeqRouteInfo, validateConfigureKeqMiddlewareImports };
+//#region src/decorators/inject-keq-consumer.decorator.d.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）
+ */
+declare function InjectKeqConsumer<T extends KeqModuleClass>(moduleClass: T): ParameterDecorator;
+//#endregion
+export { InjectKeqConsumer, KEQ_ROUTES, KeqConsumer, type KeqMiddlewareConfigProxy, KeqMiddlewareConsumer, KeqModule, type KeqModuleClass, type KeqModuleOptions, type KeqNestMiddleware, type KeqRouteInfo, type KeqRouteTarget, type KeqScopedConfigProxy };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/keq.module.ts","../src/constants.ts","../src/interfaces/keq-nest-middleware.interface.ts","../src/interfaces/keq-middleware-consumer.interface.ts","../src/interfaces/keq-middleware-module.interface.ts","../src/interfaces/keq-module-options.interface.ts"],"mappings":";;;;;;;AAoCA;;;;;AAkCA;;;;;;;;;iBAlCgB,qCAAA,CAAsC,gBAAA,EAAkB,gBAAA;AAAA,cAuC3D,SAAA,YAAqB,YAAA;EAAA,iBAEb,gBAAA;EAAA,iBACA,UAAA;cADA,gBAAA,EAAkB,gBAAA,EAClB,UAAA,EAAY,UAAA;EAK/B,YAAA,CAAA;AAAA;;;cCnFW,UAAA;EAAA,SAEH,GAAA;AAAA;;;UCCO,iBAAA;EACf,GAAA,CAAI,GAAA,EAAK,mBAAA,EAAqB,IAAA,EAAM,OAAA,UAAiB,WAAA;AAAA;;;UCEtC,YAAA;EACf,IAAA;EACA,MAAA;EACA,QAAA;AAAA;AAAA,UAGe,cAAA,SAAuB,IAAA;EAAA,SAC7B,WAAA;AAAA;AAAA,UAGM,wBAAA;EACf,OAAA,IAAW,MAAA,EAAQ,YAAA,KAAiB,wBAAA;EACpC,SAAA,IAAa,MAAA,EAAQ,KAAA,QAAa,UAAA,CAAW,GAAA,GAAM,YAAA,GAAe,cAAA,IAAkB,qBAAA;AAAA;AAAA,UAGrE,qBAAA;EACf,KAAA,IAAS,WAAA,EAAa,KAAA,CAAM,IAAA,CAAK,iBAAA,IAAqB,aAAA,IAAiB,wBAAA;AAAA;;;UCnBxD,mBAAA;EACf,sBAAA,CAAuB,QAAA,EAAU,qBAAA;AAAA;;;UCDlB,gBAAA;EACf,WAAA,GAAc,aAAA;EACd,OAAA;AAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/keq.module.ts","../src/constants.ts","../src/interfaces/keq-nest-middleware.interface.ts","../src/keq-consumer.ts","../src/interfaces/keq-middleware-consumer.interface.ts","../src/keq-middleware-consumer.ts","../src/interfaces/keq-module-options.interface.ts","../src/decorators/inject-keq-consumer.decorator.ts"],"mappings":";;;;cAaa,SAAA;;;cCbA,UAAA;EAAA,SAEH,GAAA;AAAA;;;UCCO,iBAAA;EACf,GAAA,CAAI,GAAA,EAAK,mBAAA,EAAqB,IAAA,EAAM,OAAA,UAAiB,WAAA;AAAA;;;AFCvD;;;;;;;;ACLA;;;;;;;;ACGA;AFEA,cGmBa,WAAA,KAAgB,cAAA;EAAA,iBACE,UAAA;cAAA,UAAA,EAAY,UAAA;EAEzC,KAAA,CAAA,GACK,WAAA,EAAa,KAAA,CAAM,iBAAA,GAAoB,aAAA,IACzC,oBAAA,CAAqB,CAAA;AAAA;;;UCvBT,YAAA;EACf,IAAA;EACA,MAAA;EACA,QAAA;AAAA;AAAA,UAGe,cAAA,SAAuB,IAAA;EAAA,SAC7B,WAAA;EAAA,SACA,YAAA;AAAA;;KAIC,cAAA,UAAwB,UAAA,CAAW,GAAA,GAAM,YAAA;AAAA,UAEpC,wBAAA;EACf,OAAA,IAAW,MAAA,EAAQ,YAAA,KAAiB,wBAAA;EACpC,SAAA,IAAa,MAAA,EAAQ,cAAA,KAAmB,qBAAA;AAAA;;UAIzB,oBAAA,KAAyB,cAAA;EACxC,OAAA,IAAW,MAAA,EAAQ,YAAA,KAAiB,oBAAA,CAAqB,CAAA;EACzD,SAAA,IAAa,MAAA,EAAQ,cAAA,KAAmB,WAAA,CAAY,CAAA;AAAA;;;AJvBtD;;;;;;;;ACLA;;;;;;ADKA,cKkBa,qBAAA;EAAA,iBACkB,UAAA;cAAA,UAAA,EAAY,UAAA;EAEzC,KAAA,CAAA,GACK,WAAA,EAAa,KAAA,CAAM,iBAAA,GAAoB,aAAA,IACzC,wBAAA;AAAA;;;UCzBY,gBAAA;EACf,WAAA,GAAc,aAAA;EACd,OAAA;AAAA;;;;;;ANAF;;;;;;;;ACLA;;;;;;iBMqBgB,iBAAA,WAA4B,cAAA,CAAA,CAC1C,WAAA,EAAa,CAAA,GACZ,kBAAA"}