@kevisual/router 0.0.82 → 0.0.84

package/dist/ws.d.ts

@@ -57,6 +57,11 @@ type CustomErrorOptions = {
     code?: number;
     message?: string;
 };
+interface throwError {
+    throw(code?: number | string, message?: string): void;
+    throw(code?: number | string, opts?: CustomErrorOptions): void;
+    throw(opts?: CustomErrorOptions): void;
+}
 
 declare class MockProcess {
     emitter?: EventEmitter;
@@ -75,9 +80,20 @@ type RouterContextT = {
     code?: number;
     [key: string]: any;
 };
+type BuildRouteContext<M, U> = M extends {
+    args?: infer A;
+} ? A extends z.ZodObject<any> ? RouteContext<{
+    args?: z.infer<A>;
+}, U> : A extends Record<string, z.ZodTypeAny> ? RouteContext<{
+    args?: {
+        [K in keyof A]: z.infer<A[K]>;
+    };
+}, U> : RouteContext<U> : RouteContext<U>;
 type RouteContext<T = {
     code?: number;
-}, S = any> = {
+}, U extends SimpleObject = {}, S = {
+    [key: string]: any;
+}> = {
     /**
      * 本地自己调用的时候使用，可以标识为当前自调用，那么 auth 就不许重复的校验
      * 或者不需要登录的，直接调用
@@ -100,7 +116,14 @@ type RouteContext<T = {
     code?: number;
     /** return msg */
     message?: string;
+    /**
+     * 传递状态
+     */
     state?: S;
+    /**
+     * 当前routerId
+     */
+    currentId?: string;
     /**
      * 当前路径
      */
@@ -141,14 +164,12 @@ type RouteContext<T = {
         path: string;
         key?: string;
         payload?: any;
-    }, ctx?: RouteContext & {
-        [key: string]: any;
-    }) => Promise<any>;
+    }, ctx?: RouteContext) => Promise<any>;
     index?: number;
-    throw?: (code?: number | string, message?: string, tips?: string) => void;
+    throw?: throwError['throw'];
     /** 是否需要序列化, 使用JSON.stringify和JSON.parse */
     needSerialize?: boolean;
-} & T;
+} & T & U;
 type SimpleObject = Record<string, any>;
 type Run<T extends SimpleObject = {}> = (ctx: Required<RouteContext<T>>) => Promise<typeof ctx | null | void>;
 type RunMessage = {
@@ -159,7 +180,7 @@ type RunMessage = {
 };
 type NextRoute = Pick<Route, 'id' | 'path' | 'key'>;
 type RouteMiddleware = {
-    path: string;
+    path?: string;
     key?: string;
     id?: string;
 } | string;
@@ -186,9 +207,11 @@ type RouteOpts<U = {}, T = SimpleObject> = {
 type DefineRouteOpts = Omit<RouteOpts, 'idUsePath' | 'nextRoute'>;
 declare const pickValue: readonly ["path", "key", "id", "description", "type", "middleware", "metadata"];
 type RouteInfo = Pick<Route, (typeof pickValue)[number]>;
-declare class Route<U = {
-    [key: string]: any;
-}, T extends SimpleObject = SimpleObject> {
+/**
+ * @M 是 route的 metadate的类型，默认是 SimpleObject
+ * @U 是 RouteContext 里 state的类型
+ */
+declare class Route<M extends SimpleObject = SimpleObject, U extends SimpleObject = SimpleObject> implements throwError {
     /**
      * 一级路径
      */
@@ -198,10 +221,10 @@ declare class Route<U = {
      */
     key?: string;
     id?: string;
-    run?: Run;
+    run?: Run<BuildRouteContext<M, U>>;
     nextRoute?: NextRoute;
     description?: string;
-    metadata?: T;
+    metadata?: M;
     middleware?: RouteMiddleware[];
     type?: string;
     /**
@@ -216,19 +239,19 @@ declare class Route<U = {
     } = RouterContextT>(opts: DefineRouteOpts): this;
     define<T extends {
         [key: string]: any;
-    } = RouterContextT>(fn: Run<T & U>): this;
+    } = RouterContextT>(fn: Run<T & BuildRouteContext<M, U>>): this;
     define<T extends {
         [key: string]: any;
-    } = RouterContextT>(key: string, fn: Run<T & U>): this;
+    } = RouterContextT>(key: string, fn: Run<T & BuildRouteContext<M, U>>): this;
     define<T extends {
         [key: string]: any;
-    } = RouterContextT>(path: string, key: string, fn: Run<T & U>): this;
+    } = RouterContextT>(path: string, key: string, fn: Run<T & BuildRouteContext<M, U>>): this;
     update(opts: DefineRouteOpts, onlyUpdateList?: string[]): this;
     addTo(router: QueryRouter | {
         add: (route: Route) => void;
         [key: string]: any;
     }, opts?: AddOpts): void;
-    throw(code?: number | string, message?: string, tips?: string): void;
+    throw(...args: any[]): void;
 }
 /**
  * @parmas overwrite 是否覆盖已存在的route，默认true
@@ -236,11 +259,11 @@ declare class Route<U = {
 type AddOpts = {
     overwrite?: boolean;
 };
-declare class QueryRouter {
+declare class QueryRouter<T extends SimpleObject = SimpleObject> implements throwError {
     appId: string;
     routes: Route[];
     maxNextRoute: number;
-    context?: RouteContext;
+    context?: RouteContext<T>;
     constructor();
     /**
      * add route
@@ -268,7 +291,7 @@ declare class QueryRouter {
      * @param ctx
      * @returns
      */
-    runRoute(path: string, key: string, ctx?: RouteContext): any;
+    runRoute(path: string, key: string, ctx?: RouteContext<T>): Promise<RouteContext<T>>;
     /**
      * 第一次执行
      * @param message
@@ -279,9 +302,11 @@ declare class QueryRouter {
         path: string;
         key?: string;
         payload?: any;
-    }, ctx?: RouteContext & {
+    }, ctx?: RouteContext<T> & {
         [key: string]: any;
-    }): Promise<any>;
+    }): Promise<RouteContext<T, {}, {
+        [key: string]: any;
+    }>>;
     /**
      * 返回的数据包含所有的context的请求返回的内容，可做其他处理
      * @param message
@@ -293,9 +318,15 @@ declare class QueryRouter {
         path?: string;
         key?: string;
         payload?: any;
-    }, ctx?: RouteContext & {
+    }, ctx?: RouteContext<T> & {
         [key: string]: any;
-    }): Promise<any>;
+    }): Promise<RouteContext<T, {}, {
+        [key: string]: any;
+    }> | {
+        code: number;
+        body: any;
+        message: string;
+    }>;
     /**
      * 请求 result 的数据
      * @param message
@@ -311,9 +342,9 @@ declare class QueryRouter {
     }, ctx?: RouteContext & {
         [key: string]: any;
     }): Promise<{
-        code: any;
+        code: number;
         data: any;
-        message: any;
+        message: string;
     }>;
     /**
      * Router Run获取数据
@@ -326,12 +357,12 @@ declare class QueryRouter {
         path?: string;
         key?: string;
         payload?: any;
-    }, ctx?: RouteContext & {
+    }, ctx?: RouteContext<T> & {
         [key: string]: any;
     }): Promise<{
-        code: any;
+        code: number;
         data: any;
-        message: any;
+        message: string;
     }>;
     /**
      * 设置上下文
@@ -343,12 +374,12 @@ declare class QueryRouter {
     /**
      * 获取handle函数, 这里会去执行parse函数
      */
-    getHandle<T = any>(router: QueryRouter, wrapperFn?: HandleFn<T>, ctx?: RouteContext): (msg: {
+    getHandle<T = any>(router: QueryRouter, wrapperFn?: HandleFn, ctx?: RouteContext): (msg: {
         id?: string;
         path?: string;
         key?: string;
         [key: string]: any;
-    }, handleContext?: RouteContext) => Promise<{
+    }, handleContext?: RouteContext<T>) => Promise<{
         [key: string]: any;
         code: string;
         data?: any;
@@ -362,24 +393,16 @@ declare class QueryRouter {
         message: any;
         data?: undefined;
     }>;
-    exportRoutes(): Route<{
-        [key: string]: any;
-    }, SimpleObject>[];
+    exportRoutes(): Route<SimpleObject, SimpleObject>[];
     importRoutes(routes: Route[]): void;
     importRouter(router: QueryRouter): void;
-    throw(code?: number | string, message?: string): void;
-    throw(code?: number | string, opts?: CustomErrorOptions): void;
-    throw(opts?: CustomErrorOptions): void;
-    hasRoute(path: string, key?: string): Route<{
-        [key: string]: any;
-    }, SimpleObject>;
+    throw(...args: any[]): void;
+    hasRoute(path: string, key?: string): Route<SimpleObject, SimpleObject>;
     findRoute(opts?: {
         path?: string;
         key?: string;
         id?: string;
-    }): Route<{
-        [key: string]: any;
-    }, SimpleObject>;
+    }): Route<SimpleObject, SimpleObject>;
     createRouteList(opts?: {
         force?: boolean;
         filter?: (route: Route) => boolean;
@@ -421,6 +444,12 @@ declare class QueryRouter {
         [key: string]: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
     };
 }
+type QueryRouterServerOpts<C extends SimpleObject = SimpleObject> = {
+    handleFn?: HandleFn;
+    context?: RouteContext<C>;
+    appId?: string;
+    initHandle?: boolean;
+};
 interface HandleFn<T = any> {
     (msg: {
         path: string;
@@ -433,6 +462,42 @@ interface HandleFn<T = any> {
     };
     (res: RouteContext<T>): any;
 }
+/**
+ * QueryRouterServer
+ * @description 移除server相关的功能，只保留router相关的功能，和http.createServer不相关，独立
+ * @template C 自定义 RouteContext 类型
+ */
+declare class QueryRouterServer<C extends SimpleObject = SimpleObject> extends QueryRouter<C> {
+    appId: string;
+    handle: any;
+    context: RouteContext<C>;
+    constructor(opts?: QueryRouterServerOpts<C>);
+    setHandle(wrapperFn?: HandleFn, ctx?: RouteContext): void;
+    addRoute(route: Route, opts?: AddOpts): void;
+    Route: typeof Route;
+    route<M extends SimpleObject = SimpleObject>(opts: RouteOpts & {
+        metadata?: M;
+    }): Route<M, Required<RouteContext<C>>>;
+    route<M extends SimpleObject = SimpleObject>(path: string, opts?: RouteOpts & {
+        metadata?: M;
+    }): Route<M, Required<RouteContext<C>>>;
+    route<M extends SimpleObject = SimpleObject>(path: string, key?: string): Route<M, Required<RouteContext<C>>>;
+    route<M extends SimpleObject = SimpleObject>(path: string, key?: string, opts?: RouteOpts & {
+        metadata?: M;
+    }): Route<M, Required<RouteContext<C>>>;
+    prompt(description: string): Route<SimpleObject, SimpleObject>;
+    /**
+     * 调用了handle
+     * @param param0
+     * @returns
+     */
+    run(msg: {
+        id?: string;
+        path?: string;
+        key?: string;
+        payload?: any;
+    }, ctx?: Partial<RouteContext<C>>): Promise<any>;
+}
 
 type Cors = {
     /**
@@ -682,7 +747,7 @@ type RouterHandle = (msg: {
     [key: string]: any;
 };
 type AppOptions<T = {}> = {
-    router?: QueryRouter;
+    router?: QueryRouterServer;
     server?: ServerType;
     /** handle msg 关联 */
     routerHandle?: RouterHandle;
@@ -690,17 +755,18 @@ type AppOptions<T = {}> = {
     serverOptions?: ServerNodeOpts;
     appId?: string;
 };
-type AppRouteContext<T = {}> = HandleCtx & RouteContext<T> & {
+type AppRouteContext<T> = HandleCtx & RouteContext<T> & {
     app: App<T>;
 };
 /**
  *  封装了 Router 和 Server 的 App 模块，处理http的请求和响应，内置了 Cookie 和 Token 和 res 的处理
  *  U - Route Context的扩展类型
  */
-declare class App<U = {}> extends QueryRouter {
+declare class App<U = {}> extends QueryRouterServer<AppRouteContext<U>> {
     appId: string;
-    router: QueryRouter;
+    router: QueryRouterServer;
     server: ServerType;
+    context: AppRouteContext<U>;
     constructor(opts?: AppOptions<U>);
     listen(port: number, hostname?: string, backlog?: number, listeningListener?: () => void): void;
     listen(port: number, hostname?: string, listeningListener?: () => void): void;
@@ -710,34 +776,7 @@ declare class App<U = {}> extends QueryRouter {
     listen(path: string, listeningListener?: () => void): void;
     listen(handle: any, backlog?: number, listeningListener?: () => void): void;
     listen(handle: any, listeningListener?: () => void): void;
-    addRoute(route: Route, opts?: AddOpts): void;
     Route: typeof Route;
-    route(opts: RouteOpts<AppRouteContext<U>>): Route<AppRouteContext<U>>;
-    route(path: string, key?: string): Route<AppRouteContext<U>>;
-    route(path: string, opts?: RouteOpts<AppRouteContext<U>>): Route<AppRouteContext<U>>;
-    route(path: string, key?: string, opts?: RouteOpts<AppRouteContext<U>>): Route<AppRouteContext<U>>;
-    prompt(description: string): Route<AppRouteContext<U>>;
-    prompt(description: Function): Route<AppRouteContext<U>>;
-    call(message: {
-        id?: string;
-        path?: string;
-        key?: string;
-        payload?: any;
-    }, ctx?: AppRouteContext<U> & {
-        [key: string]: any;
-    }): Promise<any>;
-    run(msg: {
-        id?: string;
-        path?: string;
-        key?: string;
-        payload?: any;
-    }, ctx?: Partial<AppRouteContext<U>> & {
-        [key: string]: any;
-    }): Promise<{
-        code: any;
-        data: any;
-        message: any;
-    }>;
     static handleRequest(req: IncomingMessage$1, res: ServerResponse$1): Promise<{
         cookies: Record<string, string>;
         token: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@kevisual/router",
-  "version": "0.0.82",
+  "version": "0.0.84",
   "description": "",
   "type": "module",
   "main": "./dist/router.js",
@@ -37,7 +37,7 @@
     "@types/xml2js": "^0.4.14",
     "eventemitter3": "^5.0.4",
     "fast-glob": "^3.3.3",
-    "hono": "^4.12.0",
+    "hono": "^4.12.2",
     "nanoid": "^5.1.6",
     "path-to-regexp": "^8.3.0",
     "send": "^1.2.1",

package/readme.md

@@ -31,63 +31,58 @@ app
 
 在 route handler 中，你可以通过 `ctx` 访问以下属性：
 
-| 属性 | 类型 | 说明 |
-|------|------|------|
-| `query` | `object` | 请求参数，会自动合并 payload |
-| `body` | `number \| string \| Object` | 响应内容 |
-| `code` | `number` | 响应状态码，默认为 200 |
-| `message` | `string` | 响应消息 |
-| `state` | `any` | 状态数据，可在路由间传递 |
-| `appId` | `string` | 应用标识 |
-| `currentPath` | `string` | 当前路由路径 |
-| `currentKey` | `string` | 当前路由 key |
-| `currentRoute` | `Route` | 当前 Route 实例 |
-| `progress` | `[string, string][]` | 路由执行路径记录 |
-| `nextQuery` | `object` | 传递给下一个路由的参数 |
-| `end` | `boolean` | 是否提前结束路由执行 |
-| `app` | `QueryRouter` | 路由实例引用 |
-| `error` | `any` | 错误信息 |
-| `index` | `number` | 当前路由执行深度 |
-| `needSerialize` | `boolean` | 是否需要序列化响应数据 |
+| 属性            | 类型                         | 说明                         |
+| --------------- | ---------------------------- | ---------------------------- |
+| `query`         | `object`                     | 请求参数，会自动合并 payload |
+| `body`          | `number \| string \| Object` | 响应内容                     |
+| `code`          | `number`                     | 响应状态码，默认为 200       |
+| `message`       | `string`                     | 响应消息                     |
+| `state`         | `any`                        | 状态数据，可在路由间传递     |
+| `appId`         | `string`                     | 应用标识                     |
+| `currentId`     | `string`                     | 当前路由ID                   |
+| `currentPath`   | `string`                     | 当前路由路径                 |
+| `currentKey`    | `string`                     | 当前路由 key                 |
+| `currentRoute`  | `Route`                      | 当前 Route 实例              |
+| `progress`      | `[string, string][]`         | 路由执行路径记录             |
+| `nextQuery`     | `object`                     | 传递给下一个路由的参数       |
+| `end`           | `boolean`                    | 是否提前结束路由执行         |
+| `app`           | `QueryRouter`                | 路由实例引用                 |
+| `error`         | `any`                        | 错误信息                     |
+| `index`         | `number`                     | 当前路由执行深度             |
+| `needSerialize` | `boolean`                    | 是否需要序列化响应数据       |
 
 ### 上下文方法
 
-| 方法 | 参数 | 说明 |
-|------|------|------|
-| `ctx.call(msg, ctx?)` | `{ path, key?, payload?, ... } \| { id }` | 调用其他路由，返回完整 context |
-| `ctx.run(msg, ctx?)` | `{ path, key?, payload? }` | 调用其他路由，返回 `{ code, data, message }` |
-| `ctx.forward(res)` | `{ code, data?, message? }` | 设置响应结果 |
-| `ctx.throw(code?, message?, tips?)` | - | 抛出自定义错误 |
+| 方法                                | 参数                                      | 说明                                         |
+| ----------------------------------- | ----------------------------------------- | -------------------------------------------- |
+| `ctx.call(msg, ctx?)`               | `{ path, key?, payload?, ... } \| { id }` | 调用其他路由，返回完整 context               |
+| `ctx.run(msg, ctx?)`                | `{ path, key?, payload? }`                | 调用其他路由，返回 `{ code, data, message }` |
+| `ctx.forward(res)`                  | `{ code, data?, message? }`               | 设置响应结果                                 |
+| `ctx.throw(code?, message?, tips?)` | -                                         | 抛出自定义错误                               |
 
 ## 完整示例
 
 ```ts
 import { App } from '@kevisual/router';
-
+import z from 'zod';
 const app = new App();
 app.listen(4002);
 
 // 基本路由
 app
-  .route({ path: 'user', key: 'info' })
+  .route({ path: 'user', key: 'info', id: 'user-info' })
   .define(async (ctx) => {
     // ctx.query 包含请求参数
     const { id } = ctx.query;
+    // 使用 state 在路由间传递数据
+    ctx.state.orderId = '12345';
     ctx.body = { id, name: '张三' };
     ctx.code = 200;
   })
   .addTo(app);
 
-// 使用 state 在路由间传递数据
-app
-  .route({ path: 'order', key: 'create' })
-  .define(async (ctx) => {
-    ctx.state = { orderId: '12345' };
-  })
-  .addTo(app);
-
 app
-  .route({ path: 'order', key: 'pay' })
+  .route({ path: 'order', key: 'pay', middleware: ['user-info'] })
   .define(async (ctx) => {
     // 可以获取前一个路由设置的 state
     const { orderId } = ctx.state;
@@ -95,14 +90,6 @@ app
   })
   .addTo(app);
 
-// 链式调用
-app
-  .route({ path: 'product', key: 'list' })
-  .define(async (ctx) => {
-    ctx.body = [{ id: 1, name: '商品A' }];
-  })
-  .addTo(app);
-
 // 调用其他路由
 app
   .route({ path: 'dashboard', key: 'stats' })
@@ -114,7 +101,7 @@ app
 
     ctx.body = {
       user: userRes.data,
-      products: productRes.data
+      products: productRes.data,
     };
   })
   .addTo(app);
@@ -140,17 +127,20 @@ import { App, Route } from '@kevisual/router';
 const app = new App();
 
 // 定义中间件
-app.route({
-  id: 'auth-example',
-  description: '权限校验中间件'
-}).define(async(ctx) => {
-  const token = ctx.query.token;
-  if (!token) {
-    ctx.throw(401, '未登录', '需要 token');
-  }
-  // 验证通过，设置用户信息到 state
-  ctx.state.tokenUser = { id: 1, name: '用户A' };
-}).addTo(app);
+app
+  .route({
+    id: 'auth-example',
+    description: '权限校验中间件',
+  })
+  .define(async (ctx) => {
+    const token = ctx.query.token;
+    if (!token) {
+      ctx.throw(401, '未登录', '需要 token');
+    }
+    // 验证通过，设置用户信息到 state
+    ctx.state.tokenUser = { id: 1, name: '用户A' };
+  })
+  .addTo(app);
 
 // 使用中间件（通过 id 引用）
 app
@@ -163,6 +153,33 @@ app
   .addTo(app);
 ```
 
+## 一个丰富的router示例
+
+```ts
+import { App } from '@kevisual/router';
+const app = new App();
+
+app
+  .router({
+    path: 'dog',
+    key: 'info',
+    description: '获取狗的信息',
+    metedata: {
+      args: {
+        owner: z.string().describe('狗主人姓名'),
+        age: z.number().describe('狗的年龄'),
+      },
+    },
+  })
+  .define(async (ctx) => {
+    const { owner, age } = ctx.query;
+    ctx.body = {
+      content: `这是一只${age}岁的狗，主人是${owner}`,
+    };
+  })
+  .addTo(app);
+```
+
 ## 注意事项
 
 1. **path 和 key 的组合是路由的唯一标识**，同一个 path+key 只能添加一个路由，后添加的会覆盖之前的。
@@ -173,16 +190,14 @@ app
 
 3. **ctx.throw 会自动结束执行**，抛出自定义错误。
 
-4. **state 不会自动继承**，每个路由的 state 是独立的，除非显式传递或使用 nextRoute。
-
-5. **payload 会自动合并到 query**，调用 `ctx.run({ path, key, payload })` 时，payload 会合并到 query。
+4. **payload 会自动合并到 query**，调用 `ctx.run({ path, key, payload })` 时，payload 会合并到 query。
 
-6. **nextQuery 用于传递给 nextRoute**，在当前路由中设置 `ctx.nextQuery`，会在执行 nextRoute 时合并到 query。
+5. **nextQuery 用于传递给 nextRoute**，在当前路由中设置 `ctx.nextQuery`，会在执行 nextRoute 时合并到 query。
 
-7. **避免 nextRoute 循环调用**，默认最大深度为 40 次，超过会返回 500 错误。
+6. **避免 nextRoute 循环调用**，默认最大深度为 40 次，超过会返回 500 错误。
 
-8. **needSerialize 默认为 true**，会自动对 body 进行 JSON 序列化和反序列化。
+7. **needSerialize 默认为 true**，会自动对 body 进行 JSON 序列化和反序列化。
 
-9. **progress 记录执行路径**，可用于调试和追踪路由调用链。
+8. **progress 记录执行路径**，可用于调试和追踪路由调用链。
 
-10. **中间件找不到会返回 404**，错误信息中会包含找不到的中间件列表。
+9. **中间件找不到会返回 404**，错误信息中会包含找不到的中间件列表。