wok-server 0.1.0

package/types/mongodb/index.d.ts

@@ -0,0 +1,29 @@
+import { MongoDBManager } from './manager';
+import { MongoMigrationVersion } from './migration';
+/**
+ * 启用 MongoDB
+ * @param opts 选项
+ */
+export declare function enableMongoDB(opts?: {
+    /**
+     * 配置名称，同时也是环境变量配置的前缀，英文开头，由英文数字和下划线成.
+     */
+    name?: string;
+    /**
+     * 迁移
+     */
+    migration?: {
+        versionList: MongoMigrationVersion[];
+    };
+}): Promise<void>;
+/**
+ * 获取管理器实例
+ * @param name
+ * @returns
+ */
+export declare function getMongoDBManager(name?: string): MongoDBManager;
+export { MongoDBConfig } from './config';
+export * from './exception';
+export { MongoMigrationVersion } from './migration';
+export * from './collection';
+export * from './doc';

package/types/mongodb/manager/base.d.ts

@@ -0,0 +1,188 @@
+import { ClientSession, Db, Document, Filter, UpdateFilter } from 'mongodb';
+import { MongoCollection } from '../collection';
+import { MongoDBConfig } from '../config';
+import { MongoDocId, MongoDocWithId } from '../doc';
+/**
+ * mysql 分页查询结果
+ */
+export interface MongoPage<T> {
+    total: number;
+    list: T[];
+}
+/**
+ * mongodb 管理器基类，提供基本的操作功能.
+ */
+export declare abstract class BaseMongoManager {
+    protected config: MongoDBConfig;
+    protected readonly db: Db;
+    private session?;
+    /**
+     * mongodb 管理器构建
+     * @param db 库
+     * @param session 要绑定的会话，用于事务
+     */
+    constructor(config: MongoDBConfig, db: Db, session?: ClientSession | undefined);
+    getCollection<T extends Document>(collInfo: MongoCollection<T>): import("mongodb").Collection<T>;
+    /**
+     * 查询计时
+     * @param opts
+     */
+    protected timingQuery<T, D extends {
+        op: string;
+        coll: string;
+    }>(opts: {
+        query: () => Promise<T>;
+        desc: () => D;
+    }): Promise<T>;
+    findById<T extends Document>(coll: MongoCollection<T>, id: MongoDocId): Promise<MongoDocWithId<T> | null>;
+    /**
+     * 根据id列表查询
+     * @param coll
+     * @param ids
+     * @returns
+     */
+    findByIdIn<T extends Document>(coll: MongoCollection<T>, ids: MongoDocId[]): Promise<MongoDocWithId<T>[]>;
+    /**
+     * 根据id判定是否存在
+     * @param coll
+     * @param id
+     */
+    existsById<T extends Document>(coll: MongoCollection<T>, id: MongoDocId): Promise<boolean>;
+    /**
+     * 按指定的条件来判定是否存在记录
+     * @param coll
+     * @param filter
+     */
+    existsBy<T extends Document>(coll: MongoCollection<T>, filter: Filter<MongoDocWithId<T>>): Promise<boolean>;
+    /**
+     * 按id进行删除
+     * @param coll
+     * @param id
+     * @returns
+     */
+    deleteById<T extends Document>(coll: MongoCollection<T>, id: MongoDocId): Promise<boolean>;
+    /**
+     * 仅删除一条记录
+     * @param coll
+     * @param filter
+     * @returns
+     */
+    deleteOne<T extends Document>(coll: MongoCollection<T>, filter: Partial<T>): Promise<boolean>;
+    /**
+     * 按条件删除数据，返回删除的记录行数.
+     * 务必谨慎使用，大批量删除容易带来性能问题，造成线上事故.
+     * @param coll
+     * @param filter
+     * @returns 被删除记录的数量
+     */
+    deleteMany<T extends Document>(coll: MongoCollection<T>, filter: Filter<MongoDocWithId<T>>): Promise<number>;
+    /**
+     * 查询集合中所有记录.谨慎使用！
+     * @param coll
+     * @returns
+     */
+    findAll<T extends Document>(coll: MongoCollection<T>): Promise<MongoDocWithId<T>[]>;
+    /**
+     * 根据给定的条件查找第一条符合条件的记录
+     * @param coll
+     * @param filter
+     * @returns
+     */
+    findFirst<T extends Document>(coll: MongoCollection<T>, filter: Filter<MongoDocWithId<T>>): Promise<MongoDocWithId<T> | null>;
+    /**
+     * 插入新记录
+     * @param coll
+     * @param data
+     * @returns
+     */
+    insert<T extends Document>(coll: MongoCollection<T>, data: T & {
+        _id?: MongoDocId;
+    }): Promise<MongoDocWithId<T>>;
+    /**
+     * 插入多条，批量插入.
+     * @param coll
+     * @param list
+     */
+    insertMany<T extends Document>(coll: MongoCollection<T>, list: Array<T & {
+        _id?: MongoDocId;
+    }>): Promise<MongoDocWithId<T>[]>;
+    /**
+     * 更新，更新完整的文档内容。
+     * @param coll 集合信息
+     * @param data 要更新的数据，必须包含 _id 字段，支持 mongo 更新语法 $inc 等
+     * @returns 返回最新的数据
+     * @throws MongoDBException 当无法完成更新时抛出
+     */
+    update<T extends Document>(coll: MongoCollection<T>, data: MongoDocWithId<T>): Promise<MongoDocWithId<T>>;
+    /**
+     * 仅更新一条记录
+     * @param coll
+     * @param filter
+     * @param updater
+     */
+    updateOne<T extends Document>(coll: MongoCollection<T>, filter: Partial<T>, updater: UpdateFilter<T>): Promise<boolean>;
+    /**
+     * 局部更新，仅更新部分字段，可对字段做递增或数组元组的处理。
+     * @param coll 集合信息
+     * @param id id
+     * @param updater 更新内容
+     * @returns 更新是否成功
+     */
+    partialUpdate<T extends Document>(coll: MongoCollection<T>, id: MongoDocId, updater: UpdateFilter<T>): Promise<boolean>;
+    /**
+     * 根据条件更新多条记录，和 partialUpdate 区别是可以根据过滤条件来处理多条记录。
+     * @param coll 集合
+     * @param filter 过滤规则
+     * @param updater 更新内容
+     * @returns 此次更新的记录数
+     */
+    updateMany<T extends Document>(coll: MongoCollection<T>, filter: Filter<MongoDocWithId<T>>, updater: UpdateFilter<T>): Promise<number>;
+    /**
+     * 条件查询
+     * @param coll 集合信息
+     * @param filter 过滤条件
+     * @param opts 额外的选项
+     * @returns
+     */
+    find<T extends Document>(coll: MongoCollection<T>, filter: Filter<MongoDocWithId<T>>, opts?: {
+        /**
+         * 偏移，需要 limit 有值才可以
+         */
+        offset?: number;
+        /**
+         * 限制返回的数量
+         */
+        limit?: number;
+        /**
+         * 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
+         */
+        orderBy?: Array<[keyof MongoDocWithId<T>, 'asc' | 'desc']>;
+    }): Promise<MongoDocWithId<T>[]>;
+    /**
+     * 查询符合条件的文档数量。请谨慎使用，count 是不能从索引直接读取的，只能实时计数，使用不当容易造成性能问题，引发线上事故。
+     * @param coll
+     * @param filter
+     * @returns
+     */
+    count<T extends Document>(coll: MongoCollection<T>, filter: Filter<MongoDocWithId<T>>): Promise<number>;
+    /**
+     * 分页查询。谨慎使用，不建议对规模较大的数据查询直接使用分页。
+     * @param coll 集合信息
+     * @param filter 过滤条件
+     * @param opts 分页参数
+     */
+    paginate<T extends Document>(coll: MongoCollection<T>, filter: Filter<MongoDocWithId<T>>, opts: {
+        /**
+         * 页码，从1开始，第一页是 1
+         */
+        pn: number;
+        /**
+         * 每页的数据量大小
+         */
+        pz: number;
+        /**
+         * 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
+         */
+        orderBy?: Array<[keyof MongoDocWithId<T>, 'asc' | 'desc']>;
+    }): Promise<MongoPage<MongoDocWithId<T>>>;
+}

package/types/mongodb/manager/index.d.ts

@@ -0,0 +1,38 @@
+import { Db, MongoClient, ReadConcernLike, ReadPreferenceLike, WriteConcern } from 'mongodb';
+import { MongoDBConfig } from '../config';
+import { BaseMongoManager } from './base';
+import { MongoTxSession } from './tx';
+/**
+ * mysql 分页查询结果
+ */
+export interface MongoPage<T> {
+    total: number;
+    list: T[];
+}
+/**
+ * mongodb 管理器，目前尚未实现事务的处理.
+ */
+export declare class MongoDBManager extends BaseMongoManager {
+    private readonly client;
+    /**
+     * mongodb 管理器构建
+     * @param db 库
+     */
+    constructor(config: MongoDBConfig, db: Db, client: MongoClient);
+    /**
+     * 事务操作。mongodb 的版本必须在 4.0 以上，连接的必须是副本集节点或分片集群的mongos节点。
+     * @param ops 操作逻辑，所有事务相关的操作都必须使用函数提供的 session 对象
+     * @param opts mongo 事务选项
+     */
+    tx<T>(ops: (session: MongoTxSession) => Promise<T>, opts?: {
+        /** 超时时间，单位毫秒，设置后会覆盖全局设置，设置为0表示不限制 */
+        timeout?: number;
+        /** A default read concern for commands in this transaction */
+        readConcern?: ReadConcernLike;
+        /** A default writeConcern for commands in this transaction */
+        writeConcern?: WriteConcern;
+        /** A default read preference for commands in this transaction */
+        readPreference?: ReadPreferenceLike;
+    }): Promise<T>;
+}
+export { BaseMongoManager, MongoTxSession };

package/types/mongodb/manager/tx-strict.d.ts

@@ -0,0 +1,41 @@
+import { ClientSession, Db, Document, Filter, UpdateFilter } from 'mongodb';
+import { MongoCollection } from '../collection';
+import { MongoDBConfig } from '../config';
+import { MongoDocId, MongoDocWithId } from '../doc';
+import { MongoPage } from './base';
+import { MongoTxSession } from './tx';
+/**
+ * 严格事务会话
+ */
+export declare class MongoStrictTxSession extends MongoTxSession {
+    #private;
+    constructor(config: MongoDBConfig, db: Db, session: ClientSession);
+    findById<T extends Document>(coll: MongoCollection<T>, id: MongoDocId): Promise<MongoDocWithId<T> | null>;
+    findByIdIn<T extends Document>(coll: MongoCollection<T>, ids: MongoDocId[]): Promise<MongoDocWithId<T>[]>;
+    existsBy<T extends Document>(coll: MongoCollection<T>, filter: Filter<MongoDocWithId<T>>): Promise<boolean>;
+    deleteById<T extends Document>(coll: MongoCollection<T>, id: MongoDocId): Promise<boolean>;
+    deleteOne<T extends Document>(coll: MongoCollection<T>, filter: Partial<T>): Promise<boolean>;
+    deleteMany<T extends Document>(coll: MongoCollection<T>, filter: Filter<MongoDocWithId<T>>): Promise<number>;
+    findAll<T extends Document>(coll: MongoCollection<T>): Promise<MongoDocWithId<T>[]>;
+    findFirst<T extends Document>(coll: MongoCollection<T>, filter: Filter<MongoDocWithId<T>>): Promise<MongoDocWithId<T> | null>;
+    insert<T extends Document>(coll: MongoCollection<T>, data: T & {
+        _id?: MongoDocId | undefined;
+    }): Promise<MongoDocWithId<T>>;
+    insertMany<T extends Document>(coll: MongoCollection<T>, list: (T & {
+        _id?: MongoDocId | undefined;
+    })[]): Promise<MongoDocWithId<T>[]>;
+    update<T extends Document>(coll: MongoCollection<T>, data: MongoDocWithId<T>): Promise<MongoDocWithId<T>>;
+    partialUpdate<T extends Document>(coll: MongoCollection<T>, id: MongoDocId, updator: UpdateFilter<T>): Promise<boolean>;
+    updateMany<T extends Document>(coll: MongoCollection<T>, filter: Filter<MongoDocWithId<T>>, updator: UpdateFilter<T>): Promise<number>;
+    find<T extends Document>(coll: MongoCollection<T>, filter: Filter<MongoDocWithId<T>>, opts?: {
+        offset?: number | undefined;
+        limit?: number | undefined;
+        orderBy?: ['_id' | keyof T, 'asc' | 'desc'][] | undefined;
+    } | undefined): Promise<MongoDocWithId<T>[]>;
+    count<T extends Document>(coll: MongoCollection<T>, filter: Filter<MongoDocWithId<T>>): Promise<number>;
+    paginate<T extends Document>(coll: MongoCollection<T>, filter: Filter<MongoDocWithId<T>>, opts: {
+        pn: number;
+        pz: number;
+        orderBy?: ['_id' | keyof T, 'asc' | 'desc'][] | undefined;
+    }): Promise<MongoPage<MongoDocWithId<T>>>;
+}

package/types/mongodb/manager/tx.d.ts

@@ -0,0 +1,21 @@
+import { ClientSession, Db } from 'mongodb';
+import { MongoDBConfig } from '../config';
+import { BaseMongoManager } from './base';
+/**
+ * 事务会话
+ */
+export declare class MongoTxSession extends BaseMongoManager {
+    #private;
+    constructor(config: MongoDBConfig, db: Db, session: ClientSession);
+    protected timingQuery<T, D extends {
+        op: string;
+        coll: string;
+    }>(opts: {
+        query: () => Promise<T>;
+        desc: () => D;
+    }): Promise<T>;
+    /**
+     * 中止，被中止后的会话不能再进行任何操作
+     */
+    abort(): void;
+}

package/types/mongodb/migration.d.ts

@@ -0,0 +1,12 @@
+import { Db } from 'mongodb';
+/**
+ * 迁移版本，是一个函数，可以在函数的内部通过 mongodb 驱动提升的 api 来完成操作。
+ * 注：驱动里有些 api 是没有的，和 mongodb 的脚本有区分，但是有些是可以通过 db.command() 来替代的。
+ */
+export type MongoMigrationVersion = (db: Db) => Promise<void>;
+/**
+ * 迁移
+ * @param db
+ * @param versionList
+ */
+export declare function migrate(db: Db, versionList: MongoMigrationVersion[]): Promise<void>;

package/types/mvc/access-log.d.ts

@@ -0,0 +1,7 @@
+import { Interceptor } from './interceptor';
+/**
+ * 访问日志拦截器，记录请求信息
+ * @param exchange
+ * @param next
+ */
+export declare const accessLogInterceptor: Interceptor;

package/types/mvc/config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * mvc 模块配置.
+ */
+export interface WebConfig {
+    /**
+     * 端口号
+     */
+    port: number;
+    /**
+     * 超时时间
+     */
+    timeout: number;
+    /**
+     * 是否开启访问日志.
+     */
+    accessLog: boolean;
+    /**
+     * 跨域允许的源域名
+     */
+    corsAllowOrigin: string;
+    /**
+     * 跨域允许的消息头
+     */
+    corsAllowHeaders: string;
+    /**
+     * 跨域允许的请求方法
+     */
+    corsAllowMethods: string;
+}
+export declare const config: WebConfig;

package/types/mvc/exchange.d.ts

@@ -0,0 +1,72 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { IncomingMessage, ServerResponse } from 'http';
+import { QueryString } from './query';
+import { HtmlStuct } from './render';
+/**
+ * 服务的数据交换对象.
+ */
+export declare class ServerExchange {
+    #private;
+    readonly request: IncomingMessage;
+    readonly response: ServerResponse;
+    constructor(request: IncomingMessage, response: ServerResponse);
+    bodyBuffer(): Promise<Buffer>;
+    bodyText(): Promise<string>;
+    bodyJson<T>(): Promise<T>;
+    /**
+     * 响应纯文本
+     * @param text 文本内容
+     * @param status 状态码，可选，默认 200
+     */
+    respondText(text: string, status?: number): void;
+    /**
+     * 响应 json
+     * @param json 任意可被 json 序列化的对象
+     * @param status 状态码，可选，默认 200
+     */
+    respondJson(json: any, status?: number): void;
+    /**
+     * 响应错误信息提示，提供一个统一的格式封装，json 格式
+     * @param message 消息
+     * @param status 状态码，默认 400 ，表示业务错误
+     * @returns
+     */
+    respondErrMsg(message: string, status?: number): void;
+    /**
+     * 响应文件
+     * @param filePath 文件路径，绝对路径
+     * @param download 是否下载模式
+     * @returns
+     */
+    respondFile(filePath: string, download?: boolean): Promise<void>;
+    /**
+     * 响应 html
+     * @param html html 内容，一个特定结构的对象或者是字符串
+     * @param status 状态码，可选，默认 200
+     */
+    respondHtml(html: HtmlStuct | string, status?: number): void;
+    /**
+     * 响应
+     * @param opts
+     */
+    respond(opts: {
+        /**
+         * 状态码.
+         */
+        statusCode: number;
+        /**
+         * 响应正文内容.
+         */
+        body?: string | Buffer | Uint8Array;
+        /**
+         * 自定义消息头
+         */
+        headers?: Record<string, string>;
+    }): void;
+    /**
+     * 解析 queryString
+     * @returns
+     */
+    parseQueryString(): QueryString;
+}

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

@@ -0,0 +1,3 @@
+export * from './json';
+export * from './upload';
+export * from './restful';

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

@@ -0,0 +1,23 @@
+import { ValidationOpts } from '../../validation';
+import { ServerExchange } from '../exchange';
+import { RouterHandler } from '../router';
+/**
+ * 创建 json 处理器..
+ * @param <REQ> 表示请求的 json 数据格式类型
+ * @param <RES> 表示响应的类型，可选，如果不需要响应 json 数据，则方法可以不返回任何值
+ * @param opts
+ * @returns
+ */
+export declare function createJsonHandler<REQ, RES = void>(opts: {
+    /**
+     * 校验信息，可选，用于检查请求信息.对于一些特殊情况，无法使用校验器的，可以在 handle 中继续处理.
+     */
+    validation?: ValidationOpts<REQ>;
+    /**
+     * 处理请求.
+     * @param body 正文内容
+     * @param exchange 请求传输对象，用于获取请求的基本信息
+     * @returns
+     */
+    handle: (body: REQ, exchange: ServerExchange) => Promise<RES>;
+}): RouterHandler;

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

@@ -0,0 +1,11 @@
+import { RouterHandler } from '../router';
+/**
+ * 构建 restful 风格路由
+ */
+export declare function restful(opts: {
+    get?: RouterHandler;
+    post?: RouterHandler;
+    put?: RouterHandler;
+    patch?: RouterHandler;
+    delete?: RouterHandler;
+}): RouterHandler;

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

@@ -0,0 +1,40 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { IncomingHttpHeaders } from 'http';
+import { QueryString } from '../query';
+import { RouterHandler } from '../router';
+/**
+ * 上传请求传输对象.
+ */
+export interface UploadRouterExchange {
+    /**
+     * 请求地址
+     */
+    url: string;
+    /**
+     * 请求头
+     */
+    headers: IncomingHttpHeaders;
+    /**
+     * querystring 解析结果
+     */
+    query: QueryString;
+}
+/**
+ * 创建上传处理器. 上传要求一次只能传输一个文件，并且请求正文就是文件二进制内容。
+ * 必须是 post 请求，额外的参数只能通过 queryString 或 header 来传递。
+ * 和 postman 中的 binary 模式是一致的，这样上传文件性能会好一些，但是局限性也很大。
+ *
+ * @param opts
+ * @param <RES> 响应json数据类型
+ * @returns
+ */
+export declare function createUploadHandler<RES = void>(opts: {
+    /**
+     * 处理请求.
+     * @param body 正文内容
+     * @param exchange 请求传输对象，用于获取请求的基本信息
+     * @returns
+     */
+    handle: (body: Buffer, exchange: UploadRouterExchange) => Promise<RES>;
+}): RouterHandler;

package/types/mvc/index.d.ts

@@ -0,0 +1,49 @@
+/// <reference types="node" />
+import { Server } from 'http';
+import { Interceptor } from './interceptor';
+import { Routers } from './router';
+/**
+ * 启动 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>;
+/**
+ * 停止 web 服务
+ * @returns
+ */
+export declare function stopWebServer(): Promise<void>;
+export * from './exchange';
+export * from './handler';
+export * from './render';
+export * from './router';
+export * from './interceptor';

package/types/mvc/interceptor.d.ts

@@ -0,0 +1,11 @@
+import { ServerExchange } from './exchange';
+/**
+ * 拦截器.
+ */
+export interface Interceptor {
+    /**
+     * @param exchange 传输对象，提供获取请求信息和通用的响应数据功能
+     * @param next 执行后面的流程，可能是下一个拦截器，也可能是路由
+     */
+    (exchange: ServerExchange, next: () => Promise<void>): Promise<void>;
+}

package/types/mvc/query.d.ts

@@ -0,0 +1,13 @@
+export declare class QueryString {
+    private qs;
+    constructor(url: string);
+    /**
+     * 获取单个字符串值
+     * @param name
+     */
+    getStr(name: string): string | undefined;
+    /**
+     * 获取参数的所有值
+     */
+    getStrVals(name: string): string[] | undefined;
+}

package/types/mvc/render/file.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="node" />
+import { IncomingMessage, ServerResponse } from 'http';
+/**
+ * 响应一个文件.
+ * @param request  请求信息
+ * @param response 响应信息
+ * @param filePath 文件路径，如果文件不存在，则会响应 404
+ * @param download 是否下载
+ */
+export declare function renderFile(request: IncomingMessage, response: ServerResponse, filePath: string, download?: boolean): Promise<void>;