wok-server 0.2.1 → 0.3.0

package/documentation/zh-cn/validate.md

@@ -32,8 +32,6 @@ validate(
 | array       | 数组校验,设置元素对象的校验规则来校验每一个元素      |
 | plainObject | 对象校验,如果属性是对象可进一步校验属性值的属性      |
 
-**注意: array 和 plainObject 在校验层级深的对象时,可能无法拥有准确的类型推断,必须在使用这两个函数时指定泛型,比如 `plainObject<User>({...})`，否则编译会报错。**
-
 下面是对象和数组嵌套的校验示例。
 
 ```ts
@@ -66,19 +64,27 @@ validate<User>(
       })
     ],
     tags: [
-      array({
-        id: [notBlank()],
-        name: [notBlank()],
-        permissinos: [
-          notNull(),
-          // 这里无法自动进行推断类型，必须指定类型，否则编译会有错误
-          // 层级过深就必须指定泛型
-          plainObject<{ edit?: boolean; read?: boolean }>({
-            edit: [notNull()],
-            read: [notNull()]
-          })
-        ]
-      })
+      // 标签不得超过5个
+      maxLength(5),
+      // 标签列表不能为空
+      notNull(),
+      // 校验标签数组的元素
+      array([
+        // 元素不能为空
+        notNull(),
+        // 元素的属性校验
+        plainObject({
+          id: [notBlank()],
+          name: [notBlank()],
+          permissinos: [
+            notNull(),
+            plainObject({
+              edit: [notNull()],
+              read: [notNull()]
+            })
+          ]
+        })
+      ])
     ]
   }
 )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wok-server",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "packageManager": "pnpm@8.9.0",
   "description": "一个基于 NodeJs 和 TypeScript 的后端框架，轻量级、克制、简洁。A lightweight, restrained, and concise backend framework based on Node.js and TypeScript.",
   "scripts": {

package/types/config/index.d.ts

@@ -12,4 +12,14 @@ export declare function getConfig<T>(envPrefix: string): T | undefined;
  * @returns 映射了环境变量后的配置
  */
 export declare function registerConfig<T extends {}>(defaultConfig: T, envPrefix: string, validation?: ValidationOpts<T>): T;
+/**
+ * 根据环境变量来生成配置对象，与 registerConfig 的参数是一致的，和 registerConfig 不同的是
+ * generateConfig 可以多次重复使用，方便在运行时更改环境变量后再生成配置，而调用 registerConfig
+ * 一旦注册后不能再被更改。之所以这样设计是为了方便程序的测试，模拟不同的环境来运行程序，和其它的
+ * 一些特殊需求。
+ * @param defaultConfig
+ * @param envPrefix
+ * @param validation
+ */
+export declare function generateConfig<T extends {}>(defaultConfig: T, envPrefix: string, validation?: ValidationOpts<T>): T;
 export * from './exception';

package/types/mvc/config.d.ts

@@ -26,5 +26,17 @@ export interface WebConfig {
      * 跨域允许的请求方法
      */
     corsAllowMethods: string;
+    /**
+     * 是否激活安全传输层
+     */
+    tlsEnable: boolean;
+    /**
+     * pem 格式证书公钥文件路径
+     */
+    tlsCert: string;
+    /**
+     * pem 格式证书私钥文件路径
+     */
+    tlsKey: string;
 }
-export declare const config: WebConfig;
+export declare function getConfig(): WebConfig;

package/types/mvc/handler/json.d.ts

@@ -16,6 +16,20 @@ export interface JsonHandlerExchange {
  * @returns
  */
 export declare function createJsonHandler<REQ, RES = void>(opts: {
+    /**
+     * 缓存设置，通过框架的 cache 模块来缓存响应信息，只能缓存有效的响应信息，如果没有响应正文则不会进行缓存,
+     * 参数和 handle 是一样的
+     * @param body
+     * @param exchange
+     * @returns 返回缓存的 key 和缓存秒数
+     */
+    cache?: (body: REQ, exchange: JsonHandlerExchange) => Promise<{
+        key: string;
+        expiresInSeconds?: number;
+    }> | {
+        key: string;
+        expiresInSeconds?: number;
+    };
     /**
      * 校验信息，可选，用于检查请求信息.对于一些特殊情况，无法使用校验器的，可以在 handle 中继续处理.
      */

package/types/mvc/index.d.ts

@@ -1,42 +1,9 @@
-/// <reference types="node" />
-import { Server } from 'http';
-import { Interceptor } from './interceptor';
-import { Routers } from './router';
+import { WokServerOpts } from './server';
 /**
  * 启动 web服务
  * @param opts
  */
-export declare function startWebServer(opts: {
-    /**
-     * 路由配置.
-     */
-    routers: Routers;
-    /**
-     * 拦截器，在路由处理前可以做一些额外操作.
-     */
-    interceptors?: Interceptor[];
-    /**
-     * 前置控制器，在服务启动之前，对服务做一些额外的操作。比如可以连接 socket.io 或者一些其它
-     * 支持 nodejs 原生 http 服务的组件.
-     * @param server
-     * @returns
-     */
-    preHandler?: (server: Server<any>) => Promise<void>;
-    /**
-     * 静态文件设置，key 是访问路径，value 是相关设置. 如果希望根目录映射，可以将 key 的值设置为 /。
-     * 访问路径和目录的设置都是不允许重复的。
-     */
-    static?: Record<string, {
-        /**
-         * 目录
-         */
-        dir: string;
-        /**
-         * 缓存时长，单位秒，根据设定生成消息头 Cache-Control: max-age=时长，设置为小于等于0可关闭
-         */
-        cacheAge?: number;
-    }>;
-}): Promise<void>;
+export declare function startWebServer(opts: WokServerOpts): Promise<void>;
 /**
  * 停止 web 服务
  * @returns
@@ -44,6 +11,6 @@ export declare function startWebServer(opts: {
 export declare function stopWebServer(): Promise<void>;
 export * from './exchange';
 export * from './handler';
+export * from './interceptor';
 export * from './render';
 export * from './router';
-export * from './interceptor';

package/types/mvc/server.d.ts

@@ -0,0 +1,85 @@
+/// <reference types="node" />
+import { Server } from 'http';
+import { Interceptor } from './interceptor';
+import { Routers } from './router';
+import { ServerStaticRules } from './static';
+/**
+ * mvc 服务选项
+ */
+export interface WokServerOpts {
+    /**
+     * 路由配置.
+     */
+    routers: Routers;
+    /**
+     * 拦截器，在路由处理前可以做一些额外操作.
+     */
+    interceptors?: Interceptor[];
+    /**
+     * 前置控制器，在服务启动之前，对服务做一些额外的操作。比如可以连接 socket.io 或者一些其它
+     * 支持 nodejs 原生 http 服务的组件.
+     * @param server
+     * @returns
+     */
+    preHandler?: (server: Server<any>) => Promise<void>;
+    /**
+     * 静态资源配置
+     */
+    static?: ServerStaticRules;
+}
+/**
+ * web 服务
+ */
+export declare class WokServer {
+    private readonly opts;
+    private readonly config;
+    private readonly server;
+    private readonly interceptors;
+    private readonly routers;
+    private readonly defaultRouter?;
+    private readonly staticHandler?;
+    constructor(opts: WokServerOpts);
+    /**
+     * 处理请求，完成拦截器和路由的流程.
+     *
+     * @param req
+     * @param res
+     */
+    private handleRequest;
+    /**
+     * 处理拦截器.
+     * @param idx 当前要执行的拦截器下标
+     * @param exchange 传输对象
+     * @param req
+     * @param res
+     */
+    private handleInterceptor;
+    /**
+     * 处理路由.
+     * @param exchange
+     * @param routers
+     * @param staticSettings
+     * @returns
+     */
+    private handleRouter;
+    /**
+     * 404响应
+     *
+     * @param exchange
+     * @param path
+     */
+    private respond404;
+    /**
+     * 启动
+     */
+    start(): Promise<void>;
+    /**
+     * 获取 ipv4 地址列表
+     * @returns
+     */
+    private getIpv4List;
+    /**
+     * 停止
+     */
+    stop(): Promise<void>;
+}

package/types/mvc/static/header.d.ts

@@ -0,0 +1,27 @@
+/// <reference types="node" />
+import { IncomingHttpHeaders } from 'http';
+/**
+ * 静态资源消息头信息
+ */
+export interface StaticHeaders {
+    /**
+     * If-Modified-Since 消息头，测试文件是否在某个时间后修改后
+     */
+    ifModifiedSince?: Date;
+    /**
+     * 文件部分读取
+     */
+    range?: {
+        start: number;
+        end?: number;
+    };
+    /**
+     * 是否接受 gzip 压缩，如果支持则压缩后返回
+     */
+    gzip: boolean;
+}
+/**
+ * 解析消息头，返回静态文件处理需要的信息
+ * @param headers
+ */
+export declare function parseHeaders(headers: IncomingHttpHeaders): StaticHeaders;

package/types/mvc/static/index.d.ts

@@ -0,0 +1,3 @@
+export * from './mime-type';
+export * from './header';
+export * from './static-handler';

package/types/mvc/static/mime-type.d.ts

@@ -0,0 +1,2 @@
+export declare const MIME_TYPES: Record<string, string>;
+export declare function decideContentType(fileName: string): string | undefined;

package/types/mvc/static/server-cache-config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 服务器缓存配置
+ * Server Cache Configuration
+ */
+export interface ServerCacheConfig {
+    /**
+     * Enable or disable caching,default is false (disabled)
+     */
+    enable: boolean;
+    /**
+     *  The maximum age of the cache in seconds
+     */
+    maxAge: number;
+    /**
+     * The maximum size of the cache in bytes
+     * or a string representing a number followed by a unit of measure (e.g. 100k, 10m, 1g)
+     */
+    maxSize: number | string;
+    /**
+     * The maximum size of a file in the cache in bytes
+     * or a string representing a number followed by a unit of measure (e.g. 100k, 10m, 1g)
+     */
+    maxFileSize: number | string;
+}
+export declare function parseSize(size: number | string): number;
+/**
+ * 获取缓存的配置信息
+ * @returns
+ */
+export declare function getConfig(): ServerCacheConfig;

package/types/mvc/static/server-cache.d.ts

@@ -0,0 +1,76 @@
+/// <reference types="node" />
+export interface CacheVal {
+    /**
+     * 文件内容
+     */
+    buffer: Buffer;
+    /**
+     * 媒体类型
+     */
+    mimeType: string;
+    /**
+     * 修改时间
+     */
+    mtime: Date;
+    /**
+     * 客户端缓存时间
+     */
+    cacheAge?: number;
+}
+/**
+ * 文件的服务器缓存
+ */
+export declare class ServerCache {
+    private readonly opts;
+    /**
+     * 当前的缓存内容大小，单位字节
+     */
+    private size;
+    /**
+     * 缓存内容
+     */
+    private readonly cacheMap;
+    /**
+     * promise 表，作用是处理异步并发问题，如果有相同的 key 同时请求，保证异步的 provider 只执行一次
+     */
+    private promiseMap;
+    constructor(opts: {
+        /**
+         * 最大缓存大小，超出后将出触发清除缓存操作
+         */
+        maxSize: number;
+        /**
+         * 缓存时长，单位秒
+         */
+        maxAge: number;
+    });
+    /**
+     * 获取缓存
+     */
+    get(key: string): CacheVal | null;
+    /**
+     * 设置缓存内容，如果缓存内容超过最大缓存大小，则触发清除缓存操作
+     * @param key
+     * @param value
+     * @returns
+     */
+    set(key: string, value: CacheVal): void;
+    /**
+     * 删除缓存
+     */
+    remove(key: string): void;
+    /**
+     * 如果缓存不存在，则计算缓存内容并放入缓存
+     * @param key
+     * @param provider 计算函数，返回值将放入缓存，如果返回 null 则表示未能计算出缓存内容，不进行缓存
+     */
+    computeIfAbsent(key: string, provider: () => Promise<CacheVal | null>): Promise<CacheVal | null>;
+    /**
+     * 清理无用的缓存内容
+     */
+    private clean;
+    /**
+     * 清除缓存内容
+     */
+    clear(): void;
+}

package/types/mvc/static/static-handler.d.ts

@@ -0,0 +1,72 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { IncomingMessage, ServerResponse } from 'http';
+/**
+ * 静态资源的映射规则
+ */
+export type ServerStaticRules = Record<
+/**
+ * 要映射的路径
+ */
+string, {
+    /**
+     * 文件目录
+     */
+    dir: string;
+    /**
+     * 客户端缓存时长，单位秒，根据设定生成消息头 Cache-Control: max-age=时长，设置为小于等于0可关闭
+     */
+    cacheAge?: number;
+}>;
+export declare class StaticHandler {
+    private readonly DEFAULT_CONTENT_TYPE;
+    private readonly maxFileSize;
+    private cache?;
+    private rules;
+    /**
+     * 静态处理器。规则说明：
+     * 请求路径仅支持前缀匹配，不支持通配符，比如 /a/demo.html 可以匹配 /a 路径，响应配置的文件目录下的 demo.html 文件。
+     * 路径配置是有优先级的，如果访问 /a/b/music.mp3 则会匹配到 /a/b 的配置，而不是 /a ，因为 /a/b 的配置更详细，优先级也更高，
+     * 并且如果从 /a/b 配置的目录下没有找到文件，也不会再尝试 /a 的配置。
+     *
+     * 静态文件同时也支持主页自动映射，比如访问 /a/b/c ，会匹配到 /a/b 的配置，然后在配置的文件目录下寻找文件 c ，
+     * 如果找不到则尝试寻找目录 c 下的 index.html 文件。
+     * @param rules 规则设置
+     */
+    constructor(rules: ServerStaticRules);
+    /**
+     * 处理静态文件 get 请求
+     * @param request
+     * @param response
+     * @param path
+     * @returns 是否能够处理，如果因为找不到文件或其它原因无法处理则返回 false ，由后续流程继续处理
+     */
+    handleGet(request: IncomingMessage, response: ServerResponse, path: string): Promise<boolean>;
+    /**
+     *  处理 head 请求，不响应正文内容，如果文件可以被找到，仅仅响应以下的消息头：
+     * Content-Length
+     * Content-Type
+     * Last-Modified
+     * Cache-Control
+     *
+     * @param path 请求路径
+     * @param response
+     * @returns 是否成功处理
+     */
+    handleHead(path: string, response: ServerResponse): Promise<boolean>;
+    endRespWithBuffer(response: ServerResponse, buffer: Buffer): Promise<void>;
+    /**
+     * 构建响应文件
+     *
+     * @param path
+     * @param headers
+     * @returns
+     */
+    private buildRespFile;
+    /**
+     * 根据路径查找文件
+     * @param path 访问路径
+     * @returns 返回被查询到的文件信息，如果找不到则返回 null
+     */
+    private findFile;
+}

package/types/mysql/manager/ops/update.d.ts

@@ -15,7 +15,13 @@ export declare function update<T>(config: MysqlConfig, connection: PoolConnectio
  * 更新器
  */
 export type Updater<T> = Partial<{
-    [key in keyof T]: T[key] | undefined | ['setNull'] | ['inc', number];
+    [key in keyof T]: T[key] | undefined | ['setNull'] | ['inc', number]
+    /**
+     * 设置一个字段的值，和直接赋值是一样的，作用是解决一些特殊的情况的冲突
+     * 比如将 json 字段的值设置为 ['setNull'] ,这就会被认为是要置空，
+     * 使用 ['set',['setNull']] 就可以解决这个问题
+     */
+     | ['set', T[key]];
 }>;
 /**
  * 部分更新

package/types/validation/validator/array.d.ts

@@ -1,5 +1,5 @@
-import { PropValidator, ValidationOpts } from '..';
+import { PropValidator } from '..';
 /**
  * 校验数组的条目.
  */
-export declare function array<J>(opts: ValidationOpts<J>): PropValidator<J[]>;
+export declare function array<T>(opts: PropValidator<T>[]): PropValidator<T[] | undefined>;

package/types/validation/validator/min.d.ts

@@ -1,7 +1,7 @@
 import { PropValidator } from '..';
 /**
- * 最大值校验.
- * @param max 最大值
+ * 最小值校验.
+ * @param min 最小值
  * @param msg 错误消息
  */
 export declare function min<T>(min: number, msg?: string): PropValidator<T>;

package/types/validation/validator/plain-obj.d.ts

@@ -4,4 +4,4 @@ import { PropValidator, ValidationOpts } from '..';
  * @param opts
  * @returns
  */
-export declare function plainObject<T>(opts: ValidationOpts<T>): PropValidator<T>;
+export declare function plainObject<T>(opts: ValidationOpts<Exclude<T, undefined>>): PropValidator<T>;