@kevisual/router 0.0.14 → 0.0.16

package/dist/router-browser.d.ts

@@ -110,6 +110,11 @@ type RouteContext<T = {
 } & T;
 type Run<T = any> = (ctx: RouteContext<T>) => Promise<typeof ctx | null | void>;
 type NextRoute = Pick<Route, 'id' | 'path' | 'key'>;
+type RouteMiddleware = {
+    path: string;
+    key?: string;
+    id?: string;
+} | string;
 type RouteOpts = {
     path?: string;
     key?: string;
@@ -120,7 +125,7 @@ type RouteOpts = {
     metadata?: {
         [key: string]: any;
     };
-    middleware?: Route[] | string[];
+    middleware?: RouteMiddleware[];
     type?: 'route' | 'middleware';
     /**
      * validator: {
@@ -143,6 +148,10 @@ type RouteOpts = {
      * $#$ will be used to split path and key
      */
     idUsePath?: boolean;
+    /**
+     * id 合并的分隔符，默认为 $#$
+     */
+    delimiter?: string;
     isDebug?: boolean;
 };
 type DefineRouteOpts = Omit<RouteOpts, 'idUsePath' | 'verify' | 'verifyKey' | 'nextRoute'>;
@@ -167,7 +176,7 @@ declare class Route<U = {
     metadata?: {
         [key: string]: any;
     };
-    middleware?: (Route | string)[];
+    middleware?: RouteMiddleware[];
     type?: string;
     private _validator?;
     schema?: {
@@ -403,6 +412,12 @@ declare class CustomError extends Error {
         message: string;
         tips: string;
     };
+    /**
+     * 判断 throw 的错误是否不是当前这个错误
+     * @param err
+     * @returns
+     */
+    static isError(err: any): boolean;
     parse(e?: CustomError): {
         code: number;
         data: any;

package/dist/router-browser.js

@@ -51,11 +51,23 @@ class CustomError extends Error {
             tips: e?.tips,
         };
     }
+    /**
+     * 判断 throw 的错误是否不是当前这个错误
+     * @param err
+     * @returns
+     */
+    static isError(err) {
+        if (err instanceof CustomError || err?.code) {
+            return true;
+        }
+        return false;
+    }
     parse(e) {
         if (e) {
             return CustomError.parseError(e);
         }
         else {
+            const e = this;
             return {
                 code: e?.code,
                 data: e?.data,
@@ -5656,7 +5668,8 @@ class Route {
         if (opts) {
             this.id = opts.id || nanoid();
             if (!opts.id && opts.idUsePath) {
-                this.id = path + '$#$' + key;
+                const delimiter = opts.delimiter ?? '$#$';
+                this.id = path + delimiter + key;
             }
             this.run = opts.run;
             this.nextRoute = opts.nextRoute;
@@ -5898,7 +5911,15 @@ class QueryRouter {
                         route = this.routes.find((r) => r.id === item);
                     }
                     else {
-                        route = this.routes.find((r) => r.path === item.path && r.key === item.key);
+                        route = this.routes.find((r) => {
+                            if (item.id) {
+                                return r.id === item.id;
+                            }
+                            else {
+                                // key 可以是空，所以可以不严格验证
+                                return r.path === item.path && r.key == item.key;
+                            }
+                        });
                     }
                     if (!route) {
                         if (isString) {

package/dist/router-define.d.ts

@@ -0,0 +1,464 @@
+import * as node_modules_zod_lib_types_js from 'node_modules/zod/lib/types.js';
+import { Schema } from 'zod';
+
+type BaseRule = {
+    value?: any;
+    required?: boolean;
+    message?: string;
+};
+type RuleString = {
+    type: 'string';
+    minLength?: number;
+    maxLength?: number;
+    regex?: string;
+} & BaseRule;
+type RuleNumber = {
+    type: 'number';
+    min?: number;
+    max?: number;
+} & BaseRule;
+type RuleBoolean = {
+    type: 'boolean';
+} & BaseRule;
+type RuleArray = {
+    type: 'array';
+    items: Rule;
+    minItems?: number;
+    maxItems?: number;
+} & BaseRule;
+type RuleObject = {
+    type: 'object';
+    properties: {
+        [key: string]: Rule;
+    };
+} & BaseRule;
+type RuleAny = {
+    type: 'any';
+} & BaseRule;
+type Rule = RuleString | RuleNumber | RuleBoolean | RuleArray | RuleObject | RuleAny;
+
+type RouterContextT = {
+    code?: number;
+    [key: string]: any;
+};
+type RouteContext<T = {
+    code?: number;
+}, S = any> = {
+    query?: {
+        [key: string]: any;
+    };
+    /** return body */
+    body?: number | string | Object;
+    /** return code */
+    code?: number;
+    /** return msg */
+    message?: string;
+    state?: S;
+    /**
+     * 当前路径
+     */
+    currentPath?: string;
+    /**
+     * 当前key
+     */
+    currentKey?: string;
+    /**
+     * 当前route
+     */
+    currentRoute?: Route;
+    /**
+     * 进度
+     */
+    progress?: [string, string][];
+    nextQuery?: {
+        [key: string]: any;
+    };
+    end?: boolean;
+    /**
+     * 请求 route的返回结果，包函ctx
+     */
+    queryRouter?: QueryRouter;
+    error?: any;
+    /** 请求 route的返回结果，包函ctx */
+    call?: (message: {
+        path: string;
+        key?: string;
+        payload?: any;
+        [key: string]: any;
+    } | {
+        id: string;
+        apyload?: any;
+        [key: string]: any;
+    }, ctx?: RouteContext & {
+        [key: string]: any;
+    }) => Promise<any>;
+    /** 请求 route的返回结果，不包函ctx */
+    queryRoute?: (message: {
+        path: string;
+        key?: string;
+        payload?: any;
+    }, ctx?: RouteContext & {
+        [key: string]: any;
+    }) => Promise<any>;
+    index?: number;
+    throw?: (code?: number | string, message?: string, tips?: string) => void;
+    /** 是否需要序列化 */
+    needSerialize?: boolean;
+} & T;
+type Run<T = any> = (ctx: RouteContext<T>) => Promise<typeof ctx | null | void>;
+type NextRoute = Pick<Route, 'id' | 'path' | 'key'>;
+type RouteMiddleware = {
+    path: string;
+    key?: string;
+    id?: string;
+} | string;
+type RouteOpts = {
+    path?: string;
+    key?: string;
+    id?: string;
+    run?: Run;
+    nextRoute?: NextRoute;
+    description?: string;
+    metadata?: {
+        [key: string]: any;
+    };
+    middleware?: RouteMiddleware[];
+    type?: 'route' | 'middleware';
+    /**
+     * validator: {
+     *  packageName: {
+     *    type: 'string',
+     *    required: true,
+     *  },
+     * }
+     */
+    validator?: {
+        [key: string]: Rule;
+    };
+    schema?: {
+        [key: string]: Schema<any>;
+    };
+    isVerify?: boolean;
+    verify?: (ctx?: RouteContext, dev?: boolean) => boolean;
+    verifyKey?: (key: string, ctx?: RouteContext, dev?: boolean) => boolean;
+    /**
+     * $#$ will be used to split path and key
+     */
+    idUsePath?: boolean;
+    /**
+     * id 合并的分隔符，默认为 $#$
+     */
+    delimiter?: string;
+    isDebug?: boolean;
+};
+type DefineRouteOpts = Omit<RouteOpts, 'idUsePath' | 'verify' | 'verifyKey' | 'nextRoute'>;
+declare const pickValue: readonly ["path", "key", "id", "description", "type", "validator", "middleware"];
+type RouteInfo = Pick<Route, (typeof pickValue)[number]>;
+declare class Route<U = {
+    [key: string]: any;
+}> {
+    /**
+     * 一级路径
+     */
+    path?: string;
+    /**
+     * 二级路径
+     */
+    key?: string;
+    id?: string;
+    share?: boolean;
+    run?: Run;
+    nextRoute?: NextRoute;
+    description?: string;
+    metadata?: {
+        [key: string]: any;
+    };
+    middleware?: RouteMiddleware[];
+    type?: string;
+    private _validator?;
+    schema?: {
+        [key: string]: Schema<any>;
+    };
+    data?: any;
+    /**
+     * 是否需要验证
+     */
+    isVerify?: boolean;
+    /**
+     * 是否开启debug，开启后会打印错误信息
+     */
+    isDebug?: boolean;
+    constructor(path: string, key?: string, opts?: RouteOpts);
+    private createSchema;
+    /**
+     * set validator and create schema
+     * @param validator
+     */
+    set validator(validator: {
+        [key: string]: Rule;
+    });
+    get validator(): {
+        [key: string]: Rule;
+    };
+    /**
+     * has code, body, message in ctx, return ctx if has error
+     * @param ctx
+     * @param dev
+     * @returns
+     */
+    verify(ctx: RouteContext, dev?: boolean): void;
+    /**
+     * Need to manully call return ctx fn and configure body, code, message
+     * @param key
+     * @param ctx
+     * @param dev
+     * @returns
+     */
+    verifyKey(key: string, ctx: RouteContext, dev?: boolean): {
+        message: string;
+        path: string;
+        key: string;
+        error: any;
+    } | {
+        message: string;
+        path: string;
+        key: string;
+        error?: undefined;
+    };
+    setValidator(validator: {
+        [key: string]: Rule;
+    }): this;
+    define<T extends {
+        [key: string]: any;
+    } = RouterContextT>(opts: DefineRouteOpts): this;
+    define<T extends {
+        [key: string]: any;
+    } = RouterContextT>(fn: Run<T & U>): this;
+    define<T extends {
+        [key: string]: any;
+    } = RouterContextT>(key: string, fn: Run<T & U>): this;
+    define<T extends {
+        [key: string]: any;
+    } = RouterContextT>(path: string, key: string, fn: Run<T & U>): this;
+    addTo(router: QueryRouter | {
+        add: (route: Route) => void;
+        [key: string]: any;
+    }): void;
+    setData(data: any): this;
+    throw(code?: number | string, message?: string, tips?: string): void;
+}
+declare class QueryRouter {
+    routes: Route[];
+    maxNextRoute: number;
+    context?: RouteContext;
+    constructor();
+    add(route: Route): void;
+    /**
+     * remove route by path and key
+     * @param route
+     */
+    remove(route: Route | {
+        path: string;
+        key?: string;
+    }): void;
+    /**
+     * remove route by id
+     * @param uniqueId
+     */
+    removeById(unique: string): void;
+    /**
+     * 执行route
+     * @param path
+     * @param key
+     * @param ctx
+     * @returns
+     */
+    runRoute(path: string, key: string, ctx?: RouteContext): any;
+    /**
+     * 第一次执行
+     * @param message
+     * @param ctx
+     * @returns
+     */
+    parse(message: {
+        path: string;
+        key?: string;
+        payload?: any;
+    }, ctx?: RouteContext & {
+        [key: string]: any;
+    }): Promise<any>;
+    /**
+     * 返回的数据包含所有的context的请求返回的内容，可做其他处理
+     * @param message
+     * @param ctx
+     * @returns
+     */
+    call(message: {
+        id?: string;
+        path?: string;
+        key?: string;
+        payload?: any;
+    }, ctx?: RouteContext & {
+        [key: string]: any;
+    }): Promise<any>;
+    /**
+     * 请求 result 的数据
+     * @param message
+     * @param ctx
+     * @returns
+     */
+    queryRoute(message: {
+        path: string;
+        key?: string;
+        payload?: any;
+    }, ctx?: RouteContext & {
+        [key: string]: any;
+    }): Promise<{
+        code: any;
+        data: any;
+        message: any;
+    }>;
+    setContext(ctx: RouteContext): Promise<void>;
+    getList(): RouteInfo[];
+    /**
+     * 获取handle函数, 这里会去执行parse函数
+     */
+    getHandle<T = any>(router: QueryRouter, wrapperFn?: HandleFn<T>, ctx?: RouteContext): (msg: {
+        path: string;
+        key?: string;
+        [key: string]: any;
+    }, handleContext?: RouteContext) => Promise<{
+        [key: string]: any;
+        code: string;
+        data?: any;
+        message?: string;
+    } | {
+        code: any;
+        data: any;
+        message: any;
+    } | {
+        code: number;
+        message: any;
+        data?: undefined;
+    }>;
+    exportRoutes(): Route<{
+        [key: string]: any;
+    }>[];
+    importRoutes(routes: Route[]): void;
+    importRouter(router: QueryRouter): void;
+    throw(code?: number | string, message?: string, tips?: string): void;
+    hasRoute(path: string, key?: string): Route<{
+        [key: string]: any;
+    }>;
+}
+type QueryRouterServerOpts = {
+    handleFn?: HandleFn;
+    context?: RouteContext;
+};
+interface HandleFn<T = any> {
+    (msg: {
+        path: string;
+        [key: string]: any;
+    }, ctx?: any): {
+        code: string;
+        data?: any;
+        message?: string;
+        [key: string]: any;
+    };
+    (res: RouteContext<T>): any;
+}
+/**
+ * QueryRouterServer
+ * @description 移除server相关的功能，只保留router相关的功能，和http.createServer不相关，独立
+ */
+declare class QueryRouterServer extends QueryRouter {
+    handle: any;
+    constructor(opts?: QueryRouterServerOpts);
+    setHandle(wrapperFn?: HandleFn, ctx?: RouteContext): void;
+    use(path: string, fn: (ctx: any) => any, opts?: RouteOpts): void;
+    addRoute(route: Route): void;
+    Route: typeof Route;
+    route(opts: RouteOpts): Route<Required<RouteContext>>;
+    route(path: string, key?: string): Route<Required<RouteContext>>;
+    route(path: string, opts?: RouteOpts): Route<Required<RouteContext>>;
+    route(path: string, key?: string, opts?: RouteOpts): Route<Required<RouteContext>>;
+    /**
+     * 等于queryRoute，但是调用了handle
+     * @param param0
+     * @returns
+     */
+    run({ path, key, payload }: {
+        path: string;
+        key?: string;
+        payload?: any;
+    }): Promise<any>;
+}
+
+type RouteObject = {
+    [key: string]: RouteOpts;
+};
+declare function define<T extends Record<string, RouteOpts>>(value: T): {
+    [K in keyof T]: T[K] & RouteOpts;
+};
+type RouteArray = RouteOpts[];
+type ChainOptions = {
+    app: QueryRouterServer;
+};
+declare class Chain {
+    object: RouteOpts;
+    app?: QueryRouterServer;
+    constructor(object: RouteOpts, opts?: ChainOptions);
+    get key(): string;
+    get path(): string;
+    setDescription(desc: string): this;
+    setMeta(metadata: {
+        [key: string]: any;
+    }): this;
+    setPath(path: string): this;
+    setMiddleware(middleware: RouteMiddleware[]): this;
+    setKey(key: string): this;
+    setId(key: string): this;
+    setRun(run: Run): this;
+    define(run: Run): this;
+    createRoute(): this;
+}
+declare const util: {
+    getChain: (obj: RouteOpts, opts?: ChainOptions) => Chain;
+};
+declare class QueryUtil<T extends RouteObject = RouteObject> {
+    routeObject: T;
+    app: QueryRouterServer;
+    constructor(object: T, opts?: ChainOptions);
+    static createFormObj<U extends RouteObject>(object: U, opts?: ChainOptions): QueryUtil<U>;
+    static create<U extends Record<string, RouteOpts>>(value: U, opts?: ChainOptions): QueryUtil<U>;
+    get<K extends keyof T>(key: K): RouteOpts;
+    chain<K extends keyof T>(key: K, opts?: ChainOptions): Chain;
+    queryChain<K extends keyof T>(key: K): (queryData?: Record<string, any>) => {
+        path?: string;
+        key?: string;
+        id?: string;
+        run?: Run;
+        nextRoute?: NextRoute;
+        description?: string;
+        metadata?: {
+            [key: string]: any;
+        };
+        middleware?: RouteMiddleware[];
+        type?: "route" | "middleware";
+        validator?: {
+            [key: string]: Rule;
+        };
+        schema?: {
+            [key: string]: node_modules_zod_lib_types_js.ZodType<any>;
+        };
+        isVerify?: boolean;
+        verify?: (ctx?: RouteContext, dev?: boolean) => boolean;
+        verifyKey?: (key: string, ctx?: RouteContext, dev?: boolean) => boolean;
+        idUsePath?: boolean;
+        delimiter?: string;
+        isDebug?: boolean;
+    };
+}
+
+export { QueryUtil, define, util };
+export type { RouteArray, RouteObject, RouteOpts };

package/dist/router-define.js

@@ -0,0 +1,92 @@
+function define(value) {
+    return value;
+}
+class Chain {
+    object;
+    app;
+    constructor(object, opts) {
+        this.object = object;
+        this.app = opts?.app;
+    }
+    get key() {
+        return this.object.key;
+    }
+    get path() {
+        return this.object.path;
+    }
+    setDescription(desc) {
+        this.object.description = desc;
+        return this;
+    }
+    setMeta(metadata) {
+        this.object.metadata = metadata;
+        return this;
+    }
+    setPath(path) {
+        this.object.path = path;
+        return this;
+    }
+    setMiddleware(middleware) {
+        this.object.middleware = middleware;
+        return this;
+    }
+    setKey(key) {
+        this.object.key = key;
+        return this;
+    }
+    setId(key) {
+        this.object.id = key;
+        return this;
+    }
+    setRun(run) {
+        this.object.run = run;
+        return this;
+    }
+    define(run) {
+        this.object.run = run;
+        return this;
+    }
+    createRoute() {
+        this.app.route(this.object).addTo(this.app);
+        return this;
+    }
+}
+const util = {
+    getChain: (obj, opts) => {
+        return new Chain(obj, opts);
+    },
+};
+class QueryUtil {
+    routeObject;
+    app;
+    constructor(object, opts) {
+        this.routeObject = object;
+        this.app = opts?.app;
+    }
+    static createFormObj(object, opts) {
+        return new QueryUtil(object, opts);
+    }
+    static create(value, opts) {
+        const obj = value;
+        return new QueryUtil(obj, opts);
+    }
+    get(key) {
+        return this.routeObject[key];
+    }
+    chain(key, opts) {
+        const obj = this.routeObject[key];
+        let newOpts = { app: this.app, ...opts };
+        return new Chain(obj, newOpts);
+    }
+    queryChain(key) {
+        const value = this.routeObject[key];
+        return (queryData) => {
+            return {
+                ...value,
+                ...queryData,
+            };
+        };
+    }
+}
+
+export { QueryUtil, define, util };

package/dist/router-simple.d.ts

@@ -1,6 +1,6 @@
 import * as querystring from 'querystring';
 import { Key } from 'path-to-regexp';
-import { IncomingMessage, ServerResponse } from 'http';
+import { IncomingMessage, ServerResponse } from 'node:http';
 
 type Req = IncomingMessage & {
     params?: Record<string, string>;

package/dist/router.d.ts

@@ -113,6 +113,11 @@ type RouteContext<T = {
 } & T;
 type Run<T = any> = (ctx: RouteContext<T>) => Promise<typeof ctx | null | void>;
 type NextRoute = Pick<Route, 'id' | 'path' | 'key'>;
+type RouteMiddleware = {
+    path: string;
+    key?: string;
+    id?: string;
+} | string;
 type RouteOpts = {
     path?: string;
     key?: string;
@@ -123,7 +128,7 @@ type RouteOpts = {
     metadata?: {
         [key: string]: any;
     };
-    middleware?: Route[] | string[];
+    middleware?: RouteMiddleware[];
     type?: 'route' | 'middleware';
     /**
      * validator: {
@@ -146,6 +151,10 @@ type RouteOpts = {
      * $#$ will be used to split path and key
      */
     idUsePath?: boolean;
+    /**
+     * id 合并的分隔符，默认为 $#$
+     */
+    delimiter?: string;
     isDebug?: boolean;
 };
 type DefineRouteOpts = Omit<RouteOpts, 'idUsePath' | 'verify' | 'verifyKey' | 'nextRoute'>;
@@ -170,7 +179,7 @@ declare class Route<U = {
     metadata?: {
         [key: string]: any;
     };
-    middleware?: (Route | string)[];
+    middleware?: RouteMiddleware[];
     type?: string;
     private _validator?;
     schema?: {
@@ -524,6 +533,12 @@ declare class CustomError extends Error {
         message: string;
         tips: string;
     };
+    /**
+     * 判断 throw 的错误是否不是当前这个错误
+     * @param err
+     * @returns
+     */
+    static isError(err: any): boolean;
     parse(e?: CustomError): {
         code: number;
         data: any;
@@ -633,4 +648,4 @@ declare class App<T = {}, U = AppReqRes> {
 }
 
 export { App, Connect, CustomError, QueryConnect, QueryRouter, QueryRouterServer, Route, Server, createSchema, handleServer };
-export type { RouteContext, RouteOpts, Rule, Run };
+export type { RouteContext, RouteMiddleware, RouteOpts, Rule, Run };

package/dist/router.js

@@ -73,11 +73,23 @@ class CustomError extends Error {
             tips: e?.tips,
         };
     }
+    /**
+     * 判断 throw 的错误是否不是当前这个错误
+     * @param err
+     * @returns
+     */
+    static isError(err) {
+        if (err instanceof CustomError || err?.code) {
+            return true;
+        }
+        return false;
+    }
     parse(e) {
         if (e) {
             return CustomError.parseError(e);
         }
         else {
+            const e = this;
             return {
                 code: e?.code,
                 data: e?.data,
@@ -5678,7 +5690,8 @@ class Route {
         if (opts) {
             this.id = opts.id || nanoid();
             if (!opts.id && opts.idUsePath) {
-                this.id = path + '$#$' + key;
+                const delimiter = opts.delimiter ?? '$#$';
+                this.id = path + delimiter + key;
             }
             this.run = opts.run;
             this.nextRoute = opts.nextRoute;
@@ -5920,7 +5933,15 @@ class QueryRouter {
                         route = this.routes.find((r) => r.id === item);
                     }
                     else {
-                        route = this.routes.find((r) => r.path === item.path && r.key === item.key);
+                        route = this.routes.find((r) => {
+                            if (item.id) {
+                                return r.id === item.id;
+                            }
+                            else {
+                                // key 可以是空，所以可以不严格验证
+                                return r.path === item.path && r.key == item.key;
+                            }
+                        });
                     }
                     if (!route) {
                         if (isString) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@kevisual/router",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "",
   "type": "module",
   "main": "./dist/router.js",
@@ -74,6 +74,11 @@
       "require": "./dist/router-simple.js",
       "types": "./dist/router-simple.d.ts"
     },
+    "./define": {
+      "import": "./dist/router-define.js",
+      "require": "./dist/router-define.js",
+      "types": "./dist/router-define.d.ts"
+    },
     "./simple-lib": {
       "import": "./dist/router-simple-lib.js",
       "require": "./dist/router-simple-lib.js",

package/src/index.ts

@@ -1,7 +1,7 @@
 export { Route, QueryRouter, QueryRouterServer } from './route.ts';
 export { Connect, QueryConnect } from './connect.ts';
 
-export type { RouteContext, RouteOpts } from './route.ts';
+export type { RouteContext, RouteOpts, RouteMiddleware } from './route.ts';
 
 export type { Run } from './route.ts';
 

package/src/result/error.ts

@@ -35,10 +35,22 @@ export class CustomError extends Error {
       tips: e?.tips,
     };
   }
+  /**
+   * 判断 throw 的错误是否不是当前这个错误
+   * @param err
+   * @returns
+   */
+  static isError(err: any) {
+    if (err instanceof CustomError || err?.code) {
+      return true;
+    }
+    return false;
+  }
   parse(e?: CustomError) {
     if (e) {
       return CustomError.parseError(e);
     } else {
+      const e = this;
       return {
         code: e?.code,
         data: e?.data,

package/src/route.ts

@@ -61,6 +61,13 @@ export type RouteContext<T = { code?: number }, S = any> = {
 export type Run<T = any> = (ctx: RouteContext<T>) => Promise<typeof ctx | null | void>;
 
 export type NextRoute = Pick<Route, 'id' | 'path' | 'key'>;
+export type RouteMiddleware =
+  | {
+      path: string;
+      key?: string;
+      id?: string;
+    }
+  | string;
 export type RouteOpts = {
   path?: string;
   key?: string;
@@ -69,7 +76,7 @@ export type RouteOpts = {
   nextRoute?: NextRoute; // route to run after this route
   description?: string;
   metadata?: { [key: string]: any };
-  middleware?: Route[] | string[]; // middleware
+  middleware?: RouteMiddleware[]; // middleware
   type?: 'route' | 'middleware';
   /**
    * validator: {
@@ -88,6 +95,10 @@ export type RouteOpts = {
    * $#$ will be used to split path and key
    */
   idUsePath?: boolean;
+  /**
+   * id 合并的分隔符，默认为 $#$
+   */
+  delimiter?: string;
   isDebug?: boolean;
 };
 export type DefineRouteOpts = Omit<RouteOpts, 'idUsePath' | 'verify' | 'verifyKey' | 'nextRoute'>;
@@ -108,7 +119,7 @@ export class Route<U = { [key: string]: any }> {
   nextRoute?: NextRoute; // route to run after this route
   description?: string;
   metadata?: { [key: string]: any };
-  middleware?: (Route | string)[]; // middleware
+  middleware?: RouteMiddleware[]; // middleware
   type? = 'route';
   private _validator?: { [key: string]: Rule };
   schema?: { [key: string]: Schema<any> };
@@ -129,7 +140,8 @@ export class Route<U = { [key: string]: any }> {
     if (opts) {
       this.id = opts.id || nanoid();
       if (!opts.id && opts.idUsePath) {
-        this.id = path + '$#$' + key;
+        const delimiter = opts.delimiter ?? '$#$';
+        this.id = path + delimiter + key;
       }
       this.run = opts.run;
       this.nextRoute = opts.nextRoute;
@@ -374,7 +386,14 @@ export class QueryRouter {
           if (isString) {
             route = this.routes.find((r) => r.id === item);
           } else {
-            route = this.routes.find((r) => r.path === item.path && r.key === item.key);
+            route = this.routes.find((r) => {
+              if (item.id) {
+                return r.id === item.id;
+              } else {
+                // key 可以是空，所以可以不严格验证
+                return r.path === item.path && r.key == item.key;
+              }
+            });
           }
           if (!route) {
             if (isString) {

package/src/router-define.ts

@@ -0,0 +1,111 @@
+// import type { QueryRouterServer, Route, RouteOpts, Run } from '@kevisual/router';
+import type { QueryRouterServer, RouteOpts, Run, RouteMiddleware } from './index.ts';
+
+// export type RouteObject<T extends readonly string[]> = {
+//   [K in T[number]]: RouteOpts;
+// };
+export type { RouteOpts };
+export type RouteObject = {
+  [key: string]: RouteOpts;
+};
+
+export function define<T extends Record<string, RouteOpts>>(
+  value: T,
+): {
+  [K in keyof T]: T[K] & RouteOpts;
+} {
+  return value as { [K in keyof T]: T[K] & RouteOpts };
+}
+
+export type RouteArray = RouteOpts[];
+type ChainOptions = {
+  app: QueryRouterServer;
+};
+class Chain {
+  object: RouteOpts;
+  app?: QueryRouterServer;
+  constructor(object: RouteOpts, opts?: ChainOptions) {
+    this.object = object;
+    this.app = opts?.app;
+  }
+  get key() {
+    return this.object.key;
+  }
+  get path() {
+    return this.object.path;
+  }
+  setDescription(desc: string) {
+    this.object.description = desc;
+    return this;
+  }
+  setMeta(metadata: { [key: string]: any }) {
+    this.object.metadata = metadata;
+    return this;
+  }
+  setPath(path: string) {
+    this.object.path = path;
+    return this;
+  }
+  setMiddleware(middleware: RouteMiddleware[]) {
+    this.object.middleware = middleware;
+    return this;
+  }
+  setKey(key: string) {
+    this.object.key = key;
+    return this;
+  }
+  setId(key: string) {
+    this.object.id = key;
+    return this;
+  }
+  setRun(run: Run) {
+    this.object.run = run;
+    return this;
+  }
+  define(run: Run) {
+    this.object.run = run;
+    return this;
+  }
+  createRoute() {
+    this.app.route(this.object).addTo(this.app);
+    return this;
+  }
+}
+export const util = {
+  getChain: (obj: RouteOpts, opts?: ChainOptions) => {
+    return new Chain(obj, opts);
+  },
+};
+
+export class QueryUtil<T extends RouteObject = RouteObject> {
+  routeObject: T;
+  app: QueryRouterServer;
+  constructor(object: T, opts?: ChainOptions) {
+    this.routeObject = object;
+    this.app = opts?.app;
+  }
+  static createFormObj<U extends RouteObject>(object: U, opts?: ChainOptions) {
+    return new QueryUtil<U>(object, opts);
+  }
+  static create<U extends Record<string, RouteOpts>>(value: U, opts?: ChainOptions) {
+    const obj = value as { [K in keyof U]: U[K] & RouteOpts };
+    return new QueryUtil<U>(obj, opts);
+  }
+  get<K extends keyof T>(key: K): RouteOpts {
+    return this.routeObject[key] as RouteOpts;
+  }
+  chain<K extends keyof T>(key: K, opts?: ChainOptions) {
+    const obj = this.routeObject[key];
+    let newOpts = { app: this.app, ...opts };
+    return new Chain(obj, newOpts);
+  }
+  queryChain<K extends keyof T>(key: K) {
+    const value = this.routeObject[key] as RouteOpts;
+    return (queryData?: Record<string, any>) => {
+      return {
+        ...value,
+        ...queryData,
+      };
+    };
+  }
+}

package/src/router-simple.ts

@@ -1,5 +1,5 @@
 import { pathToRegexp, Key } from 'path-to-regexp';
-import type { IncomingMessage, ServerResponse } from 'http';
+import type { IncomingMessage, ServerResponse } from 'node:http';
 import { parseBody, parseSearch } from './server/parse-body.ts';
 
 type Req = IncomingMessage & { params?: Record<string, string> };

package/src/test/define.ts

@@ -0,0 +1,10 @@
+import { App } from '@/app.ts';
+import { QueryUtil } from '@/router-define.ts';
+const v = QueryUtil.create({
+  a: {
+    path: 'a',
+    key: 'b',
+  },
+});
+const app = new App();
+app.route(v.get('a'));