@kevisual/router 0.1.4 → 0.1.5

package/dist/router-define.d.ts

@@ -0,0 +1,560 @@
+import { EventEmitter } from 'eventemitter3';
+import { z } from 'zod';
+import { Query, DataOpts, Result } from '@kevisual/query/query';
+
+type CustomErrorOptions = {
+    cause?: Error | string;
+    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;
+    process?: NodeJS.Process;
+    constructor(opts?: {
+        emitter?: EventEmitter;
+        isNode?: boolean;
+    });
+    send(data?: any, callback?: (err?: Error) => void): void;
+    exit(flag?: number): void;
+    on(fn: (msg?: any) => any): void;
+    desctroy(): void;
+}
+
+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;
+}, U extends SimpleObject$1 = {}, S = {
+    [key: string]: any;
+}> = {
+    /**
+     * 本地自己调用的时候使用，可以标识为当前自调用，那么 auth 就不许重复的校验
+     * 或者不需要登录的，直接调用
+     */
+    appId?: string;
+    query?: {
+        [key: string]: any;
+    };
+    args?: {
+        [key: string]: any;
+    };
+    /** return body */
+    body?: number | string | Object;
+    forward?: (response: {
+        code: number;
+        data?: any;
+        message?: any;
+    }) => void;
+    /** return code */
+    code?: number;
+    /** return msg */
+    message?: string;
+    /**
+     * 传递状态
+     */
+    state?: S;
+    /**
+     * 当前routerId
+     */
+    currentId?: string;
+    /**
+     * 当前路径
+     */
+    currentPath?: string;
+    /**
+     * 当前key
+     */
+    currentKey?: string;
+    /**
+     * 当前route
+     */
+    currentRoute?: Route;
+    /**
+     * 进度
+     */
+    progress?: [string, string][];
+    nextQuery?: {
+        [key: string]: any;
+    };
+    end?: boolean;
+    app?: QueryRouter;
+    error?: any;
+    /** 请求 route的返回结果，不解析body为data */
+    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的返回结果，解析了body为data，就类同于 query.post获取的数据*/
+    run?: (message: {
+        path: string;
+        key?: string;
+        payload?: any;
+    }, ctx?: RouteContext) => Promise<any>;
+    index?: number;
+    throw?: throwError['throw'];
+    /** 是否需要序列化, 使用JSON.stringify和JSON.parse */
+    needSerialize?: boolean;
+} & T & U;
+type SimpleObject$1 = Record<string, any>;
+type Run<T extends SimpleObject$1 = {}> = (ctx: Required<RouteContext<T>>) => Promise<typeof ctx | null | void>;
+type RunMessage = {
+    path?: string;
+    key?: string;
+    id?: string;
+    payload?: any;
+};
+type NextRoute = Pick<Route, 'id' | 'path' | 'key'>;
+type RouteMiddleware = {
+    path?: string;
+    key?: string;
+    id?: string;
+} | string;
+type RouteOpts<U = {}, T = SimpleObject$1> = {
+    path?: string;
+    key?: string;
+    id?: string;
+    run?: Run<U>;
+    nextRoute?: NextRoute;
+    description?: string;
+    metadata?: T;
+    middleware?: RouteMiddleware[];
+    type?: 'route' | 'middleware' | 'compound';
+    isDebug?: boolean;
+};
+type DefineRouteOpts = Omit<RouteOpts, 'idUsePath' | 'nextRoute'>;
+declare const pickValue: readonly ["path", "key", "id", "description", "type", "middleware", "metadata"];
+type RouteInfo = Pick<Route, (typeof pickValue)[number]>;
+/**
+ * @M 是 route的 metadate的类型，默认是 SimpleObject
+ * @U 是 RouteContext 里 state的类型
+ */
+declare class Route<M extends SimpleObject$1 = SimpleObject$1, U extends SimpleObject$1 = SimpleObject$1> implements throwError {
+    /**
+     * 一级路径
+     */
+    path?: string;
+    /**
+     * 二级路径
+     */
+    key?: string;
+    id?: string;
+    run?: Run<BuildRouteContext<M, U>>;
+    nextRoute?: NextRoute;
+    description?: string;
+    metadata?: M;
+    middleware?: RouteMiddleware[];
+    type?: string;
+    /**
+     * 是否开启debug，开启后会打印错误信息
+     */
+    isDebug?: boolean;
+    constructor(path?: string, key?: string, opts?: RouteOpts);
+    prompt(description: string): this;
+    prompt(description: Function): this;
+    define<T extends {
+        [key: string]: any;
+    } = RouterContextT>(opts: DefineRouteOpts): this;
+    define<T extends {
+        [key: string]: any;
+    } = RouterContextT>(fn: Run<T & BuildRouteContext<M, U>>): this;
+    define<T extends {
+        [key: string]: any;
+    } = RouterContextT>(key: string, fn: Run<T & BuildRouteContext<M, U>>): this;
+    define<T extends {
+        [key: string]: any;
+    } = 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(...args: any[]): void;
+}
+/**
+ * @parmas overwrite 是否覆盖已存在的route，默认true
+ */
+type AddOpts = {
+    overwrite?: boolean;
+};
+declare class QueryRouter<T extends SimpleObject$1 = SimpleObject$1> implements throwError {
+    appId: string;
+    routes: Route[];
+    maxNextRoute: number;
+    context?: RouteContext<T>;
+    constructor();
+    /**
+     * add route
+     * @param route
+     * @param opts
+     */
+    add(route: Route, opts?: AddOpts): void;
+    /**
+     * remove route by path and key
+     * @param route
+     */
+    remove(route: Route | {
+        path: string;
+        key?: string;
+    }): void;
+    /**
+     * remove route by id
+     * @param uniqueId
+     */
+    removeById(uniqueId: string): void;
+    /**
+     * 执行route
+     * @param path
+     * @param key
+     * @param ctx
+     * @returns
+     */
+    runRoute(path: string, key: string, ctx?: RouteContext<T>): Promise<RouteContext<T>>;
+    /**
+     * 第一次执行
+     * @param message
+     * @param ctx
+     * @returns
+     */
+    parse(message: {
+        path: string;
+        key?: string;
+        payload?: any;
+    }, ctx?: RouteContext<T> & {
+        [key: string]: any;
+    }): Promise<RouteContext<T, {}, {
+        [key: string]: any;
+    }>>;
+    /**
+     * 返回的数据包含所有的context的请求返回的内容，可做其他处理
+     * @param message
+     * @param ctx
+     * @returns
+     */
+    call(message: {
+        id?: string;
+        path?: string;
+        key?: string;
+        payload?: any;
+    }, ctx?: RouteContext<T> & {
+        [key: string]: any;
+    }): Promise<RouteContext<T, {}, {
+        [key: string]: any;
+    }> | {
+        code: number;
+        body: any;
+        message: string;
+    }>;
+    /**
+     * 请求 result 的数据
+     * @param message
+     * @param ctx
+     * @deprecated use run or call instead
+     * @returns
+     */
+    queryRoute(message: {
+        id?: string;
+        path: string;
+        key?: string;
+        payload?: any;
+    }, ctx?: RouteContext & {
+        [key: string]: any;
+    }): Promise<{
+        code: number;
+        data: any;
+        message: string;
+    }>;
+    /**
+     * Router Run获取数据
+     * @param message
+     * @param ctx
+     * @returns
+     */
+    run(message: {
+        id?: string;
+        path?: string;
+        key?: string;
+        payload?: any;
+    }, ctx?: RouteContext<T> & {
+        [key: string]: any;
+    }): Promise<{
+        code: number;
+        data: any;
+        message: string;
+    }>;
+    /**
+     * 设置上下文
+     * @description 这里的上下文是为了在handle函数中使用
+     * @param ctx
+     */
+    setContext(ctx: RouteContext): void;
+    getList(filter?: (route: Route) => boolean): RouteInfo[];
+    /**
+     * 获取handle函数, 这里会去执行parse函数
+     */
+    getHandle<T = any>(router: QueryRouter, wrapperFn?: HandleFn, ctx?: RouteContext): (msg: {
+        id?: string;
+        path?: string;
+        key?: string;
+        [key: string]: any;
+    }, handleContext?: RouteContext<T>) => Promise<{
+        [key: string]: any;
+        code: string;
+        data?: any;
+        message?: string;
+    } | {
+        code: any;
+        data: any;
+        message: any;
+    } | {
+        code: number;
+        message: any;
+        data?: undefined;
+    }>;
+    exportRoutes(): Route<SimpleObject$1, SimpleObject$1>[];
+    importRoutes(routes: Route[]): void;
+    importRouter(router: QueryRouter): void;
+    throw(...args: any[]): void;
+    hasRoute(path: string, key?: string): Route<SimpleObject$1, SimpleObject$1>;
+    findRoute(opts?: {
+        path?: string;
+        key?: string;
+        id?: string;
+    }): Route<SimpleObject$1, SimpleObject$1>;
+    createRouteList(opts?: {
+        force?: boolean;
+        filter?: (route: Route) => boolean;
+        middleware?: string[];
+    }): void;
+    /**
+     * 等待程序运行, 获取到message的数据,就执行
+     * params 是预设参数
+     * emitter = process
+     * -- .exit
+     * -- .on
+     * -- .send
+     */
+    wait(params?: {
+        message: RunMessage;
+    }, opts?: {
+        mockProcess?: MockProcess;
+        timeout?: number;
+        getList?: boolean;
+        force?: boolean;
+        filter?: (route: Route) => boolean;
+        routeListMiddleware?: string[];
+    }): Promise<void>;
+    toJSONSchema: (args: any, opts?: {
+        mergeObject?: boolean;
+        override?: (opts: {
+            jsonSchema: any;
+            path: string[];
+            zodSchema: z.ZodTypeAny;
+        }) => void;
+    }) => {
+        [key: string]: any;
+    };
+    fromJSONSchema: <Merge extends boolean = false>(args?: any, opts?: {
+        mergeObject?: boolean;
+    }) => Merge extends true ? z.ZodObject<{
+        [key: string]: any;
+    }, z.core.$strip> : {
+        [key: string]: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    };
+}
+type QueryRouterServerOpts<C extends SimpleObject$1 = SimpleObject$1> = {
+    handleFn?: HandleFn;
+    context?: RouteContext<C>;
+    appId?: string;
+    initHandle?: boolean;
+};
+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不相关，独立
+ * @template C 自定义 RouteContext 类型
+ */
+declare class QueryRouterServer<C extends SimpleObject$1 = SimpleObject$1> 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$1 = SimpleObject$1>(opts: RouteOpts & {
+        metadata?: M;
+    }): Route<M, Required<RouteContext<C>>>;
+    route<M extends SimpleObject$1 = SimpleObject$1>(path: string, opts?: RouteOpts & {
+        metadata?: M;
+    }): Route<M, Required<RouteContext<C>>>;
+    route<M extends SimpleObject$1 = SimpleObject$1>(path: string, key?: string): Route<M, Required<RouteContext<C>>>;
+    route<M extends SimpleObject$1 = SimpleObject$1>(path: string, key?: string, opts?: RouteOpts & {
+        metadata?: M;
+    }): Route<M, Required<RouteContext<C>>>;
+    prompt(description: string): Route<SimpleObject$1, SimpleObject$1>;
+    /**
+     * 调用了handle
+     * @param param0
+     * @returns
+     */
+    run(msg: {
+        id?: string;
+        path?: string;
+        key?: string;
+        payload?: any;
+        token?: string;
+        data?: any;
+    }, ctx?: Partial<RouteContext<C>>): Promise<any>;
+    runAction<T extends {
+        id?: string;
+        path?: string;
+        key?: string;
+        metadata?: {
+            args?: any;
+        };
+    } = {}>(api: T, payload: RunActionPayload<T>, ctx?: RouteContext<C>): Promise<any>;
+}
+/** JSON Schema 基本类型映射到 TypeScript 类型 */
+type JsonSchemaTypeToTS<T> = T extends {
+    type: "string";
+} ? string : T extends {
+    type: "boolean";
+} ? boolean : T extends {
+    type: "number";
+} ? number : T extends {
+    type: "integer";
+} ? number : T extends {
+    type: "object";
+} ? object : T extends {
+    type: "array";
+} ? any[] : any;
+/** 将 args shape（key -> JSON Schema 类型）转换为 payload 类型，支持 optional: true 的字段为可选 */
+type ArgsShapeToPayload<T> = {
+    [K in keyof T as T[K] extends {
+        optional: true;
+    } ? never : K]: JsonSchemaTypeToTS<T[K]>;
+} & {
+    [K in keyof T as T[K] extends {
+        optional: true;
+    } ? K : never]?: JsonSchemaTypeToTS<T[K]>;
+};
+/** 处理两种 args 格式：完整 JSON Schema（含 properties）或简单 key->type 映射 */
+type ArgsToPayload<T> = T extends {
+    type: "object";
+    properties: infer P;
+} ? ArgsShapeToPayload<P> : ArgsShapeToPayload<T>;
+/** 从 API 定义中提取 metadata.args */
+type ExtractArgs<T> = T extends {
+    metadata: {
+        args: infer A;
+    };
+} ? A : {};
+/** runAction 第二个参数的类型，根据第一个参数的 metadata.args 推断 */
+type RunActionPayload<T> = ArgsToPayload<ExtractArgs<T>>;
+
+type RouteObject = {
+    [key: string]: RouteOpts;
+};
+type SimpleObject = Record<string, any>;
+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<U extends SimpleObject = {}>(run: Run<U>): this;
+    define<U extends SimpleObject = {}>(run: Run<U>): this;
+    createRoute(): this;
+}
+type QueryChainOptions = {
+    query?: Query;
+    omitKeys?: string[];
+};
+declare class QueryChain {
+    obj: SimpleObject;
+    query: Query;
+    omitKeys: string[];
+    constructor(value?: SimpleObject, opts?: QueryChainOptions);
+    omit(obj: SimpleObject, key?: string[]): {
+        [x: string]: any;
+    };
+    /**
+     * 生成
+     * @param queryData
+     * @returns
+     */
+    getKey(queryData?: SimpleObject): Pick<RouteOpts, 'path' | 'key' | 'metadata' | 'description'>;
+    post<R = SimpleObject, P = SimpleObject>(data: P, options?: DataOpts): Promise<Result<R>>;
+    get<R = SimpleObject, P = SimpleObject>(data: P, options?: DataOpts): Promise<Result<R>>;
+}
+declare const util: {
+    getChain: (obj: RouteOpts, opts?: ChainOptions) => Chain;
+};
+declare class QueryUtil<T extends RouteObject = RouteObject> {
+    obj: T;
+    app: QueryRouterServer;
+    query: Query;
+    constructor(object: T, opts?: ChainOptions & QueryChainOptions);
+    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, opts?: QueryChainOptions): QueryChain;
+    static Chain: typeof Chain;
+    static QueryChain: typeof QueryChain;
+    get routeObject(): T;
+}
+
+export { QueryUtil, define, util };
+export type { RouteArray, RouteObject, RouteOpts };

package/dist/router-define.js

@@ -0,0 +1,135 @@
+// src/router-define.ts
+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;
+  }
+}
+
+class QueryChain {
+  obj = {};
+  query;
+  omitKeys = ["metadata", "description", "validator"];
+  constructor(value, opts) {
+    this.obj = value || {};
+    this.query = opts?.query;
+    if (opts?.omitKeys)
+      this.omitKeys = opts.omitKeys;
+  }
+  omit(obj, key = []) {
+    const newObj = { ...obj };
+    key.forEach((k) => {
+      delete newObj[k];
+    });
+    return newObj;
+  }
+  getKey(queryData) {
+    const obj = this.omit(this.obj, this.omitKeys);
+    return {
+      ...obj,
+      ...queryData
+    };
+  }
+  post(data, options) {
+    const _queryData = this.getKey(data);
+    return this.query.post(_queryData, options);
+  }
+  get(data, options) {
+    const _queryData = this.getKey(data);
+    return this.query.get(_queryData, options);
+  }
+}
+var util = {
+  getChain: (obj, opts) => {
+    return new Chain(obj, opts);
+  }
+};
+
+class QueryUtil {
+  obj;
+  app;
+  query;
+  constructor(object, opts) {
+    this.obj = object;
+    this.app = opts?.app;
+    this.query = opts?.query;
+  }
+  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.obj[key];
+  }
+  chain(key, opts) {
+    const obj = this.obj[key];
+    let newOpts = { app: this.app, ...opts };
+    return new QueryUtil.Chain(obj, newOpts);
+  }
+  queryChain(key, opts) {
+    const value = this.obj[key];
+    let newOpts = { query: this.query, ...opts };
+    return new QueryUtil.QueryChain(value, newOpts);
+  }
+  static Chain = Chain;
+  static QueryChain = QueryChain;
+  get routeObject() {
+    return this.obj;
+  }
+}
+export {
+  util,
+  define,
+  QueryUtil
+};