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 接收真实 VextApp，保证 handler 闭包中的 app 与 req.app 身份一致
 *   - 执行 factory 时临时把 app.get/post/... 指向 collector，将调用推入 routes 数组
 *   - 返回 RouteDefinition { routes, sourceFile, register }
 *   - register() 负责拼接前缀、组装中间件链、注册到 adapter
 *
 * 执行流程：
 *   1. defineRoutes(factory) 被调用
 *   2. 内部创建 collector（实现 HTTP 方法）
 *   3. router-loader 传入真实 app 执行 factory(app)
 *   4. 临时 HTTP 方法 collector 将每条路由推入 routes 数组
 *   5. 返回 RouteDefinition
 *   6. 稍后 router-loader 调用 routeDef.register(adapter, prefix, ...)
 *
 * @param factory 路由工厂函数，接收真实 app 并在其上注册路由
 * @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 上临时挂载 HTTP 方法 collector，然后执行 factory 回调。
 * 执行后 routeDefinition.routes 就包含了所有收集到的路由记录。
 *
 * factory 接收到的 app 与请求期 req.app 是同一对象；收集完成后会恢复 app 原有
 * HTTP 方法，避免污染运行期 app 形状。
 *
 * @param routeDefinition defineRoutes 返回的路由定义对象
 * @param app             真正的 VextApp 实例
 */
export declare function executeRouteFactory(routeDefinition: RouteDefinition, app: VextApp): void;