@keq-request/nestjs 5.0.0-beta.12 → 5.0.0-beta.14

package/src/interfaces/index.ts

@@ -1,4 +1,9 @@
 export type { KeqNestMiddleware } from './keq-nest-middleware.interface.js'
-export type { KeqMiddlewareModule } from './keq-middleware-module.interface.js'
-export type { KeqMiddlewareConsumer, KeqMiddlewareConfigProxy, KeqRouteInfo, KeqModuleClass } from './keq-middleware-consumer.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

@@ -1,7 +1,7 @@
 import type { Type } from '@nestjs/common'
-import type { KeqMiddleware } from 'keq'
 import type { KEQ_ROUTES } from '../constants.js'
-import type { KeqNestMiddleware } from './keq-nest-middleware.interface.js'
+import type { KeqMiddlewareConsumer } from '../keq-middleware-consumer.js'
+import type { KeqConsumer } from '../keq-consumer.js'
 
 
 export interface KeqRouteInfo {
@@ -10,15 +10,21 @@ export interface KeqRouteInfo {
   pathname?: string
 }
 
-export interface KeqModuleClass {
+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: Array<typeof KEQ_ROUTES.ALL | KeqRouteInfo | KeqModuleClass>): KeqMiddlewareConsumer
+  forRoutes(...routes: KeqRouteTarget[]): KeqMiddlewareConsumer
 }
 
-export interface KeqMiddlewareConsumer {
-  apply(...middlewares: Array<Type<KeqNestMiddleware> | KeqMiddleware>): KeqMiddlewareConfigProxy
+/** 模块绑定 Consumer 的配置代理，forRoutes() 返回 KeqConsumer<T> */
+export interface KeqScopedConfigProxy<T = KeqModuleClass> {
+  exclude(...routes: KeqRouteInfo[]): KeqScopedConfigProxy<T>
+  forRoutes(...routes: KeqRouteTarget[]): KeqConsumer<T>
 }

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

@@ -1,129 +1,33 @@
-import type { Type } from '@nestjs/common'
-import type { ModuleRef } from '@nestjs/core'
-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, KeqMiddlewareConsumer, KeqModuleClass, KeqRouteInfo } from './interfaces/keq-middleware-consumer.interface.js'
+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'
-
-
-interface MiddlewareEntry {
-  middlewares: Array<Type<KeqNestMiddleware> | KeqMiddleware>
-  routes: Array<typeof KEQ_ROUTES.ALL | KeqRouteInfo | KeqModuleClass>
-  excludedRouteInfos?: KeqRouteInfo[]
-}
-
-export class KeqMiddlewareConsumerImpl implements KeqMiddlewareConsumer {
-  private entries: MiddlewareEntry[] = []
-
-  apply(...middlewares: Array<Type<KeqNestMiddleware> | KeqMiddleware>): KeqMiddlewareConfigProxy {
-    const entry: MiddlewareEntry = { middlewares, routes: [] }
-    const excludedRouteInfos: KeqRouteInfo[] = []
-    this.entries.push(entry)
-
-    const proxy: KeqMiddlewareConfigProxy = {
-      exclude: (...routes) => {
-        excludedRouteInfos.push(...routes)
-        return proxy
-      },
-      forRoutes: (...routes) => {
-        entry.routes = routes
-        if (excludedRouteInfos.length > 0) {
-          entry.excludedRouteInfos = excludedRouteInfos
-        }
-        return this
-      },
-    }
-    return proxy
-  }
-
-  applyTo(keqRequest: KeqRequest, moduleRef: ModuleRef): void {
-    for (const entry of this.entries) {
-      let resolved = entry.middlewares.map((m) => this.resolveMiddleware(m, moduleRef))
-
-      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
-
-          if (this.isKeqModuleClass(routeTarget)) {
-            const targetRequest = moduleRef.get<KeqRequest>(routeTarget.KEQ_REQUEST, { strict: false })
-            if (targetRequest) {
-              for (const mw of resolved) targetRequest.use(mw)
-            }
-          } else {
-            const route = this.buildRoute(routeTarget as KeqRouteInfo)
-            keqRequest.useRouter().route(route, resolved)
-          }
-        }
-      }
-    }
-  }
-
-  private isKeqModuleClass(route: unknown): route is KeqModuleClass {
-    return (
-      typeof route === 'function'
-      && 'KEQ_REQUEST' in route
-      && typeof (route as Record<string, unknown>).KEQ_REQUEST === 'symbol'
-    )
-  }
-
-  private isNestMiddlewareClass(m: Type<KeqNestMiddleware> | KeqMiddleware): m is Type<KeqNestMiddleware> {
-    return typeof m === 'function' && m.prototype !== undefined && 'use' in m.prototype
-  }
-
-  private resolveMiddleware(m: Type<KeqNestMiddleware> | KeqMiddleware, moduleRef: ModuleRef): KeqMiddleware {
-    if (this.isNestMiddlewareClass(m)) {
-      const instance = moduleRef.get<KeqNestMiddleware>(m, { strict: false })
-      return async (ctx, next) => {
-        await instance.use(ctx, next)
-      }
-    }
-    return 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
+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)
   }
 }

package/src/keq.module.ts

@@ -1,30 +1,14 @@
-import { Global, Module, OnModuleInit } from '@nestjs/common'
-import { ModulesContainer, ModuleRef } from '@nestjs/core'
+import { Global, Module } from '@nestjs/common'
 import { KeqRequest } from 'keq'
-import { KeqMiddlewareConsumerImpl } from './keq-middleware-consumer.js'
-import { hasConfigureKeqMiddleware } from './utils/has-configure-keq-middleware.js'
+import { KeqMiddlewareConsumer } from './keq-middleware-consumer.js'
 
 
 @Global()
 @Module({
-  providers: [{ provide: KeqRequest, useFactory: () => new KeqRequest() }],
-  exports: [KeqRequest],
+  providers: [
+    { provide: KeqRequest, useFactory: () => new KeqRequest() },
+    KeqMiddlewareConsumer,
+  ],
+  exports: [KeqRequest, KeqMiddlewareConsumer],
 })
-export class KeqModule implements OnModuleInit {
-  constructor(
-    private readonly modulesContainer: ModulesContainer,
-    private readonly moduleRef: ModuleRef,
-    private readonly keqRequest: KeqRequest,
-  ) {}
-
-  onModuleInit(): void {
-    for (const [, moduleWrapper] of this.modulesContainer) {
-      const instance = moduleWrapper.instance
-      if (hasConfigureKeqMiddleware(instance)) {
-        const consumer = new KeqMiddlewareConsumerImpl()
-        instance.configureKeqMiddleware(consumer)
-        consumer.applyTo(this.keqRequest, this.moduleRef)
-      }
-    }
-  }
-}
+export class KeqModule {}

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

@@ -1,6 +0,0 @@
-import type { KeqMiddlewareConsumer } from './keq-middleware-consumer.interface.js'
-
-
-export interface KeqMiddlewareModule {
-  configureKeqMiddleware(consumer: KeqMiddlewareConsumer): void
-}

package/src/utils/has-configure-keq-middleware.ts

@@ -1,10 +0,0 @@
-import type { KeqMiddlewareModule } from '../interfaces/keq-middleware-module.interface.js'
-
-
-export function hasConfigureKeqMiddleware(instance: unknown): instance is KeqMiddlewareModule {
-  return (
-    instance !== null
-    && instance !== undefined
-    && typeof (instance as Record<string, unknown>).configureKeqMiddleware === 'function'
-  )
-}