k99 0.7.1 → 0.9.0

package/index.d.ts

@@ -1,9 +1,9 @@
 /*!
- * k99 v0.7.1
- * (c) 2019-2025 猛火Fierflame
+ * k99 v0.9.0
+ * (c) 2019-2026 猛火Fierflame
  * @license MIT
  */
-type Method = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'OPTIONS';
+type Method = string | 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'OPTIONS';
 interface CookieOption {
     domain?: string;
     path?: string;
@@ -108,375 +108,393 @@ interface Options {
     error?(error: unknown): void;
     catch?(error: unknown): PromiseLike<Response | null> | Response | null;
     environment?: object;
+    replacer?(this: any, key: string, value: any): any;
 }
-type HandlerResult = void | undefined | string | BufferSource | ArrayBufferView | AsyncIterable<string | BufferSource | ArrayBufferView> | Iterable<string | BufferSource | ArrayBufferView> | object | Response | ReadableStream | Blob | FormData | boolean;
+type HandlerResult = void | undefined | string | BufferSource | ArrayBufferView | AsyncIterable<string | BufferSource | ArrayBufferView> | Iterable<string | BufferSource | ArrayBufferView> | object | Response | ReadableStream | Blob | FormData | number | bigint | boolean;
 /** 处理函数定义 */
 interface Handler {
     (ctx: Context): PromiseLike<HandlerResult> | HandlerResult;
-    /** 所属组 */
-    plugin?: string;
 }
 interface FindHandler {
-    (ctx: Context, setParams: (v: Params) => void): PromiseLike<Handler | null> | Handler | null;
+    (ctx: Context, setParams: (v: Params) => void): PromiseLike<Handler | Handler[] | null> | Handler | Handler[] | null;
 }
 
+type FindItem<T extends Function> = [T | T[] | Router<T>, Record<string | symbol, any>, string[]];
+type Finder<T extends Function> = (this: Router<T>, method: Method, path: string[]) => AsyncIterable<FindItem<T>> | Iterable<FindItem<T>>;
+/** @import { Method, Params } from './main/types' */
 /**
- *
- * @param  {...(Onionskin | Onionskin[])} handlers
- * @returns {Handler}
+ * @template {Function} T
+ * @typedef {[T | T[] | Router<T>, Record<string | symbol, any>, string[]]} FindItem
+ */
+/**
+ * @template {Function} T
+ * @callback Finder
+ * @this {Router<T>}
+ * @param {Method} method
+ * @param {string[]} path
+ * @returns {AsyncIterable<FindItem<T>> | Iterable<FindItem<T>>}
  */
-declare function onionskin(...handlers: (Onionskin | Onionskin[])[]): Handler;
-type Onionskin = (ctx: Context, next: () => Promise<HandlerResult>) => PromiseLike<HandlerResult> | HandlerResult;
-
-type Guard = (ctx: Context) => PromiseLike<boolean | Handler | void> | boolean | Handler | void;
-type FindItem = [Handler | Router, Record<string | symbol, any>, string[]];
-type Finder = (this: Router, method: Method, path: string[], ctx: Context) => AsyncIterable<FindItem> | Iterable<FindItem>;
 /**
  * @abstract
+ * @template {Function} T
  */
-declare class Router {
+declare class Router<T extends Function> {
+    /**
+     *
+     * @template {Function} T
+     * @param {Router<T> | T[] | T} route
+     * @param {Method} method
+     * @param {string[]} path
+     * @param {Params} params
+     * @param {AbortSignal?} [signal]
+     * @param {((v: Params) => void)?} [setParams]
+     * @returns {Promise<T[] | null>}
+     */
+    static "__#2@#find"<T_1 extends Function>(route: Router<T_1> | T_1[] | T_1, method: Method, path: string[], params: Params, signal?: AbortSignal | null, setParams?: ((v: Params) => void) | null): Promise<T_1[] | null>;
     /**
      *
-     * @param {Router[]} routers
-     * @returns {FindHandler}
+     * @template {Function} T
+     * @param {Router<T>[]} routers
+     * @param {Method} method
+     * @param {string[]} path
+     * @param {AbortSignal?} [signal]
+     * @param {((v: Params) => void)?} [setParams]
+     * @returns {Promise<T[] | null>}
      */
-    static make(routers: Router[]): FindHandler;
+    static find<T_1 extends Function>(routers: Router<T_1>[], method: Method, path: string[], signal?: AbortSignal | null, setParams?: ((v: Params) => void) | null): Promise<T_1[] | null>;
     /**
      *
-     * @param {Finder} find
-     * @returns {Router}
+     * @template {Function} T
+     * @param {Finder<T>} find
+     * @returns {Router<T>}
      */
-    static create(find: Finder): Router;
+    static create<T_1 extends Function>(find: Finder<T_1>): Router<T_1>;
     disabled: boolean;
     /**
      * @abstract
      * @param {Method} method
      * @param {string[]} path
-     * @param {Context} ctx
-     * @returns {AsyncIterable<FindItem> | Iterable<FindItem>}
+     * @returns {AsyncIterable<FindItem<T>> | Iterable<FindItem<T>>}
      */
-    find(method: Method, path: string[], ctx: Context): AsyncIterable<FindItem> | Iterable<FindItem>;
-    /** @readonly @type {Set<Guard>} */
-    readonly guards: Set<Guard>;
+    find(method: Method, path: string[]): AsyncIterable<FindItem<T>> | Iterable<FindItem<T>>;
     /**
      *
-     * @param {Handler} h
-     * @returns {Handler}
+     * @param  {...T | T[]} guards
      */
-    __onionskin: (h: Handler) => Handler;
-    /** @param {Onionskin} os */
-    onionskin(os: Onionskin): void;
+    guard(...guards: (T | T[])[]): void;
+    #private;
 }
 
-declare class ApiRouter extends Router {
+/**
+ *
+ * @template {Function} T
+ * @extends {Router<T>}
+ */
+declare class MapRouter<T extends Function> extends Router<T> {
     /**
      * 添加子路由
-     * @template {Router | Finder} [T=ApiRouter]
+     * @template {Router<T> | Finder<T>} [P=MapRouter<T>]
      * @overload
-     * @param {T} [router] 要注册的子路由或子路由的 Finder
-     * @returns {T extends Finder ? Router : T}
+     * @param {P} [router] 要注册的子路由或子路由的 Finder<T>
+     * @returns {P extends Finder<T> ? Router<T> : P}
      */
-    route<T extends Router | Finder = ApiRouter>(router?: T | undefined): T extends Finder ? Router : T;
+    route<P extends Router<T> | Finder<T> = MapRouter<T>>(router?: P | undefined): P extends Finder<T> ? Router<T> : P;
     /**
      * 添加子路由
-     * @template {Router | Finder} [T=ApiRouter]
+     * @template {Router<T> | Finder<T>} [P=MapRouter<T>]
      * @overload
      * @param {string} path   要注册的路径
-     * @param {T} [router] 要注册的子路由或子路由的 Finder
-     * @returns {T extends Finder ? Router : T}
+     * @param {P} [router] 要注册的子路由或子路由的 Finder<T>
+     * @returns {P extends Finder<T> ? Router<T> : P}
      */
-    route<T extends Router | Finder = ApiRouter>(path: string, router?: T | undefined): T extends Finder ? Router : T;
+    route<P extends Router<T> | Finder<T> = MapRouter<T>>(path: string, router?: P | undefined): P extends Finder<T> ? Router<T> : P;
     /**
      * 添加子路由
      * @overload
      * @param {TemplateStringsArray} template 要注册的路径模板
      * @param {...any} substitutions 要注册的路径模板代替内容
-     * @returns {RouteBinder}
+     * @returns {RouteBinder<T>}
      */
-    route(template: TemplateStringsArray, ...substitutions: any[]): RouteBinder;
+    route(template: TemplateStringsArray, ...substitutions: any[]): RouteBinder<T>;
     /**
      *
      * @param {Method} method
      * @param {string[]} path
-     * @param {Context} ctx
-     * @returns {Iterable<FindItem>}
+     * @returns {Iterable<FindItem<T>>}
      */
-    find(method: Method, path: string[], ctx: Context): Iterable<FindItem>;
+    find(method: Method, path: string[]): Iterable<FindItem<T>>;
     /**
      * 注册处理函数
      * @overload
      * @param {Method | Iterable<Method> | ArrayLike<Method>} method  要注册的方法
-     * @param {Handler} handler 要注册的处理函数
+     * @param {T} handler 要注册的处理函数
      * @returns {() => void}
      */
-    verb(method: Method | Iterable<Method> | ArrayLike<Method>, handler: Handler): () => void;
+    verb(method: Method | Iterable<Method> | ArrayLike<Method>, handler: T): () => void;
     /**
      * 注册处理函数
      * @overload
      * @param {Method | Iterable<Method> | ArrayLike<Method>} method  要注册的方法
      * @param {string} path 要注册的路径
-     * @param {Handler} handler 要注册的处理函数
+     * @param {T} handler 要注册的处理函数
      * @returns {() => void}
      */
-    verb(method: Method | Iterable<Method> | ArrayLike<Method>, path: string, handler: Handler): () => void;
+    verb(method: Method | Iterable<Method> | ArrayLike<Method>, path: string, handler: T): () => void;
     /**
      * 注册处理函数
      * @overload
      * @param {Method | Iterable<Method> | ArrayLike<Method>} method  要注册的方法
      * @param {string} path   要注册的路径
-     * @returns {Binder}
+     * @returns {Binder<T>}
+     */
+    verb(method: Method | Iterable<Method> | ArrayLike<Method>, path: string): Binder<T>;
+    /**
+     * @param {Method | Iterable<Method> | ArrayLike<Method>} method  要注册的方法
+     * @returns {Verb<T>}
      */
-    verb(method: Method | Iterable<Method> | ArrayLike<Method>, path: string): Binder;
+    method(method: Method | Iterable<Method> | ArrayLike<Method>): Verb<T>;
     /**
      * 注册 HTTP GET/POST/PUT/DELETE 处理函数
      * @overload
-     * @param {Handler} handler 要注册的处理函数
+     * @param {...T} handlers 要注册的处理函数
      * @returns {() => void}
      */
-    match(handler: Handler): () => void;
+    match(...handlers: T[]): () => void;
     /**
      * 注册处理函数
      * @overload
      * @param {string} path 要注册的路径
-     * @param {Handler} handler 要注册的处理函数
+     * @param {...T} handlers 要注册的处理函数
      * @returns {() => void}
      */
-    match(path: string, handler: Handler): () => void;
+    match(path: string, ...handlers: T[]): () => void;
     /**
      * 注册 HTTP GET/POST/PUT/DELETE 处理函数
      * @overload
      * @param {string} path 要注册的路径
-     * @returns {Binder}
+     * @returns {Binder<T>}
      */
-    match(path: string): Binder;
+    match(path: string): Binder<T>;
     /**
      * 注册 HTTP GET/POST/PUT/DELETE 处理函数
      * @overload
      * @param {TemplateStringsArray} template 要注册的路径模板
      * @param {...any} substitutions 要注册的路径模板代替内容
-     * @returns {Binder}
+     * @returns {Binder<T>}
      */
-    match(template: TemplateStringsArray, ...substitutions: any[]): Binder;
+    match(template: TemplateStringsArray, ...substitutions: any[]): Binder<T>;
     /**
      * 注册 HTTP GET 处理函数
      * @overload
-     * @param {Handler} handler 要注册的处理函数
+     * @param {...Handler} handlers 要注册的处理函数
      * @returns {() => void}
      */
-    get(handler: Handler): () => void;
+    get(...handlers: Handler[]): () => void;
     /**
      * 注册 HTTP GET 处理函数
      * @overload
      * @param {string} path 要注册的路径
-     * @param {Handler} handler 要注册的处理函数
+     * @param {...Handler} handlers 要注册的处理函数
      * @returns {() => void}
      */
-    get(path: string, handler: Handler): () => void;
+    get(path: string, ...handlers: Handler[]): () => void;
     /**
      * 注册 HTTP GET 处理函数
      * @overload
      * @param {string} path 要注册的路径
-     * @returns {Binder}
+     * @returns {Binder<T>}
      */
-    get(path: string): Binder;
+    get(path: string): Binder<T>;
     /**
      * 注册 HTTP GET 处理函数
      * @overload
      * @param {TemplateStringsArray} template 要注册的路径模板
      * @param {...any} substitutions 要注册的路径模板代替内容
-     * @returns {Binder}
+     * @returns {Binder<T>}
      */
-    get(template: TemplateStringsArray, ...substitutions: any[]): Binder;
+    get(template: TemplateStringsArray, ...substitutions: any[]): Binder<T>;
     /**
      * 注册 HTTP POST 处理函数
      * @overload
-     * @param {Handler} handler 要注册的处理函数
+     * @param {...Handler} handlers 要注册的处理函数
      * @returns {() => void}
      */
-    post(handler: Handler): () => void;
+    post(...handlers: Handler[]): () => void;
     /**
      * 注册 HTTP POST 处理函数
      * @overload
      * @param {string} path 要注册的路径
-     * @param {Handler} handler 要注册的处理函数
+     * @param {...Handler} handlers 要注册的处理函数
      * @returns {() => void}
      */
-    post(path: string, handler: Handler): () => void;
+    post(path: string, ...handlers: Handler[]): () => void;
     /**
      * 注册 HTTP POST 处理函数
      * @overload
      * @param {string} path 要注册的路径
-     * @returns {Binder}
+     * @returns {Binder<T>}
      */
-    post(path: string): Binder;
+    post(path: string): Binder<T>;
     /**
      * 注册 HTTP POST 处理函数
      * @overload
      * @param {TemplateStringsArray} template 要注册的路径模板
      * @param {...any} substitutions 要注册的路径模板代替内容
-     * @returns {Binder}
+     * @returns {Binder<T>}
      */
-    post(template: TemplateStringsArray, ...substitutions: any[]): Binder;
+    post(template: TemplateStringsArray, ...substitutions: any[]): Binder<T>;
     /**
      * 注册 HTTP PUT 处理函数
      * @overload
-     * @param {Handler} handler 要注册的处理函数
+     * @param {...Handler} handlers 要注册的处理函数
      * @returns {() => void}
      */
-    put(handler: Handler): () => void;
+    put(...handlers: Handler[]): () => void;
     /**
      * 注册 HTTP PUT 处理函数
      * @overload
      * @param {string} path 要注册的路径
-     * @param {Handler} handler 要注册的处理函数
+     * @param {...Handler} handlers 要注册的处理函数
      * @returns {() => void}
      */
-    put(path: string, handler: Handler): () => void;
+    put(path: string, ...handlers: Handler[]): () => void;
     /**
      * 注册 HTTP PUT 处理函数
      * @overload
      * @param {string} path 要注册的路径
-     * @returns {Binder}
+     * @returns {Binder<T>}
      */
-    put(path: string): Binder;
+    put(path: string): Binder<T>;
     /**
      * 注册 HTTP PUT 处理函数
      * @overload
      * @param {TemplateStringsArray} template 要注册的路径模板
      * @param {...any} substitutions 要注册的路径模板代替内容
-     * @returns {Binder}
+     * @returns {Binder<T>}
      */
-    put(template: TemplateStringsArray, ...substitutions: any[]): Binder;
+    put(template: TemplateStringsArray, ...substitutions: any[]): Binder<T>;
     /**
      * 注册 HTTP DELETE 处理函数
      * @overload
-     * @param {Handler} handler 要注册的处理函数
+     * @param {...Handler} handlers 要注册的处理函数
      * @returns {() => void}
      */
-    delete(handler: Handler): () => void;
+    delete(...handlers: Handler[]): () => void;
     /**
      * 注册 HTTP DELETE 处理函数
      * @overload
      * @param {string} path 要注册的路径
-     * @param {Handler} handler 要注册的处理函数
+     * @param {...Handler} handlers 要注册的处理函数
      * @returns {() => void}
      */
-    delete(path: string, handler: Handler): () => void;
+    delete(path: string, ...handlers: Handler[]): () => void;
     /**
      * 注册 HTTP DELETE 处理函数
      * @overload
      * @param {string} path 要注册的路径
-     * @returns {Binder}
+     * @returns {Binder<T>}
      */
-    delete(path: string): Binder;
+    delete(path: string): Binder<T>;
     /**
      * 注册 HTTP DELETE 处理函数
      * @overload
      * @param {TemplateStringsArray} template 要注册的路径模板
      * @param {...any} substitutions 要注册的路径模板代替内容
-     * @returns {Binder}
+     * @returns {Binder<T>}
      */
-    delete(template: TemplateStringsArray, ...substitutions: any[]): Binder;
+    delete(template: TemplateStringsArray, ...substitutions: any[]): Binder<T>;
     /**
      * 注册 HTTP HEAD 处理函数
      * @overload
-     * @param {Handler} handler 要注册的处理函数
+     * @param {...Handler} handlers 要注册的处理函数
      * @returns {() => void}
      */
-    head(handler: Handler): () => void;
+    head(...handlers: Handler[]): () => void;
     /**
      * 注册 HTTP HEAD 处理函数
      * @overload
      * @param {string} path 要注册的路径
-     * @param {Handler} handler 要注册的处理函数
+     * @param {...Handler} handlers 要注册的处理函数
      * @returns {() => void}
      */
-    head(path: string, handler: Handler): () => void;
+    head(path: string, ...handlers: Handler[]): () => void;
     /**
      * 注册 HTTP HEAD 处理函数
      * @overload
      * @param {string} path 要注册的路径
-     * @returns {Binder}
+     * @returns {Binder<T>}
      */
-    head(path: string): Binder;
+    head(path: string): Binder<T>;
     /**
      * 注册 HTTP HEAD 处理函数
      * @overload
      * @param {TemplateStringsArray} template 要注册的路径模板
      * @param {...any} substitutions 要注册的路径模板代替内容
-     * @returns {Binder}
+     * @returns {Binder<T>}
      */
-    head(template: TemplateStringsArray, ...substitutions: any[]): Binder;
+    head(template: TemplateStringsArray, ...substitutions: any[]): Binder<T>;
     /**
      * 注册 HTTP OPTIONS 处理函数
      * @overload
-     * @param {Handler} handler 要注册的处理函数
+     * @param {...Handler} handlers 要注册的处理函数
      * @returns {() => void}
      */
-    options(handler: Handler): () => void;
+    options(...handlers: Handler[]): () => void;
     /**
      * 注册 HTTP OPTIONS 处理函数
      * @overload
      * @param {string} path 要注册的路径
-     * @param {Handler} handler 要注册的处理函数
+     * @param {...Handler} handlers 要注册的处理函数
      * @returns {() => void}
      */
-    options(path: string, handler: Handler): () => void;
+    options(path: string, ...handlers: Handler[]): () => void;
     /**
      * 注册 HTTP OPTIONS 处理函数
      * @overload
      * @param {string} path 要注册的路径
-     * @returns {Binder}
+     * @returns {Binder<T>}
      */
-    options(path: string): Binder;
+    options(path: string): Binder<T>;
     /**
      * 注册 HTTP OPTIONS 处理函数
      * @overload
      * @param {TemplateStringsArray} template 要注册的路径模板
      * @param {...any} substitutions 要注册的路径模板代替内容
-     * @returns {Binder}
+     * @returns {Binder<T>}
      */
-    options(template: TemplateStringsArray, ...substitutions: any[]): Binder;
+    options(template: TemplateStringsArray, ...substitutions: any[]): Binder<T>;
     #private;
 }
 type Match = (paths: string[]) => [Params, string[]] | undefined;
-type Binder = (handler: Handler, ...handlers: Handler[]) => () => void;
-type Route = {
+type Binder<T extends Function> = (handler: T, ...handlers: T[]) => () => void;
+type Verb1<T extends Function> = (handler: T, ...handlers: T[]) => () => void;
+type Verb2<T extends Function> = (path: string, handler: T, ...handlers: T[]) => () => void;
+type Verb3<T extends Function> = (path: string) => Binder<T>;
+type Verb4<T extends Function> = (template: TemplateStringsArray, ...substitutions: any[]) => Binder<T>;
+type Verb<T extends Function> = Verb1<T> & Verb2<T> & Verb3<T> & Verb4<T>;
+type Route<T extends Function> = {
     /**
      * 路径匹配
      */
     match?: Match | undefined;
     router?: null | undefined;
-    /**
-     * 所属插件
-     */
-    plugin?: string | undefined;
     /**
      * 处理函数
      */
-    handler: Handler;
+    handlers: T[];
     /**
      * 方法列表
      */
     methods: Set<Method>;
 };
-type RouterRoute = {
+type RouterRoute<T extends Function> = {
     /**
      * 路径匹配
      */
     match?: Match | undefined;
-    router: Router;
+    router: Router<T>;
 };
-type RouteBinder<T extends Router | Finder = ApiRouter> = (router?: T | undefined) => T extends Finder ? Router : T;
-
-/**
- *
- * @param {Onionskin} onionskin
- * @param {Packer} [packer]
- * @returns {Packer}
- */
-declare function packer(onionskin: Onionskin, packer?: Packer): Packer;
-type Packer = (handler: Handler) => Handler;
+type RouteBinder<T extends Function, P extends Router<T> | Finder<T> = MapRouter<T>> = (router?: P | undefined) => P extends Finder<T> ? Router<T> : P;
 
 /**
  *
@@ -485,23 +503,24 @@ type Packer = (handler: Handler) => Handler;
  * @param {Options} [options]
  * @returns {Promise<Response | null>}
  */
-declare function main(request: Request, getHandler: FindHandler, { runner, error: echoError, catch: catchError, method: toMethod, environment }?: Options): Promise<Response | null>;
+declare function main(request: Request, getHandler: FindHandler, { runner, error: echoError, catch: catchError, method: toMethod, environment, replacer: JSONReplacer, }?: Options): Promise<Response | null>;
 
-/** @import { FindHandler, Options } from './main/types' */
 /**
  *
- * @param {FindHandler} getHandler
+ * @param {Router<Handler> | Router<Handler>[] | FindHandler} routers
  * @param {Options} options
  * @returns {(request: Request) => Promise<Response | null>}
  */
-declare function make(getHandler: FindHandler, options: Options): (request: Request) => Promise<Response | null>;
+declare function make(routers: Router<Handler> | Router<Handler>[] | FindHandler, options: Options): (request: Request) => Promise<Response | null>;
 
+/** @import { FindHandler, Options } from './main/types' */
 /**
  *
- * @param  {...(Handler | Handler[])} handlers
- * @returns {Handler}
+ * @param {FindHandler} getHandler
+ * @param {Options} options
+ * @returns {(request: Request) => Promise<Response | null>}
  */
-declare function merge(...handlers: (Handler | Handler[])[]): Handler;
+declare function bind(getHandler: FindHandler, options: Options): (request: Request) => Promise<Response | null>;
 
 /**
  *
@@ -616,5 +635,5 @@ declare class Param {
     #private;
 }
 
-export { ApiRouter, Param, Router, Service, createFetch, main, make, merge, onionskin, packer, service, stateService, storeService };
-export type { Binder, Context, Cookie, CookieOption, FindHandler, FindItem, Finder, Guard, Handler, HandlerResult, Match, Method, Onionskin, Options, Packer, Route, RouteBinder, RouterRoute, Runner, StateService, StoreService };
+export { MapRouter, Param, Router, Service, bind, createFetch, main, make, service, stateService, storeService };
+export type { Binder, Context, Cookie, CookieOption, FindHandler, FindItem, Finder, Handler, HandlerResult, Match, Method, Options, Route, RouteBinder, RouterRoute, Runner, StateService, StoreService, Verb, Verb1, Verb2, Verb3, Verb4 };