import type { VextApp } from "../types/app.js";
import type { RouteDefinition, RouteFactory } from "../types/route.js";
/**
 * defineRoutes — 路由定义辅助函数
 *
 * 提供路由收集模式：用户在 factory 回调中调用 app.get/post/... 注册路由，
 * 实际并不直接注册到 adapter，而是收集到 routes 数组中。
 * 后续由 router-loader 调用 routeDef.register() 统一注册到底层适配器。
 *
 * 设计说明：
 *   - factory 接收一个 collector 对象（模拟 VextApp 的 HTTP 方法签名）
 *   - collector 将每条 app.get/post/... 调用推入 routes 数组
 *   - 返回 RouteDefinition { routes, sourceFile, register }
 *   - register() 负责拼接前缀、组装中间件链、注册到 adapter
 *
 * 执行流程：
 *   1. defineRoutes(factory) 被调用
 *   2. 内部创建 collector（实现 HTTP 方法）
 *   3. 调用 factory(collector as VextApp)，用户代码注册路由
 *   4. collector 将每条路由推入 routes 数组
 *   5. 返回 RouteDefinition
 *   6. 稍后 router-loader 调用 routeDef.register(adapter, prefix, ...)
 *
 * @param factory 路由工厂函数，接收 app（实际是 collector）在其上注册路由
 * @returns RouteDefinition 对象
 *
 * @example
 * // src/routes/users.ts
 * import { defineRoutes } from 'vextjs'
 *
 * export default defineRoutes((app) => {
 *   app.get('/list', {
 *     validate: { query: { page: 'number:1-', limit: 'number:1-100' } },
 *   }, async (req, res) => {
 *     const { page, limit } = req.valid('query')
 *     const users = await app.services.user.findAll({ page, limit })
 *     res.json(users)
 *   })
 *
 *   app.post('/', {
 *     validate: { body: { name: 'string:1-50', email: 'email' } },
 *   }, async (req, res) => {
 *     const user = await app.services.user.create(req.valid('body'))
 *     res.json(user, 201)
 *   })
 * })
 */
export declare function defineRoutes(factory: RouteFactory): RouteDefinition;
/**
 * 执行路由收集（由 router-loader 调用）
 *
 * 将真正的 app 属性混入 collector，然后执行 factory 回调。
 * 执行后 routeDefinition.routes 就包含了所有收集到的路由记录。
 *
 * ⚠️ 注意：这里是“按执行时刻把属性值复制到 collector”，不是给 factory 提供一个
 * 与根 app 保持实时同步的代理对象。因此对 `config`、`services`、`logger`、`throw`
 * 这类稳定引用通常没问题；但若某字段会在运行期被 `app.extend()` 替换成新对象引用
 * （例如 `remoteConfig`），闭包 `app` 中捕获的旧引用不会自动刷新。此类场景应在
 * handler 中优先使用 `req.app`，或在 service 中通过 `this.app` 读取真实运行期 app。
 *
 * @param routeDefinition defineRoutes 返回的路由定义对象
 * @param app             真正的 VextApp 实例
 */
export declare function executeRouteFactory(routeDefinition: RouteDefinition, app: VextApp): void;