wok-server 0.1.0

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

@@ -0,0 +1,4 @@
+export * from './text';
+export * from './json';
+export * from './file';
+export * from './html';

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

@@ -0,0 +1,17 @@
+/// <reference types="node" />
+import { ServerResponse } from 'http';
+/**
+ * 渲染 json 格式数据.
+ * @param response 响应信息
+ * @param json json对象
+ * @param status 状态码，默认 200
+ * @returns
+ */
+export declare function renderJson(response: ServerResponse, json: any, status?: number): void;
+/**
+ * 渲染错误信息，json 格式
+ * @param response
+ * @param message
+ * @param status
+ */
+export declare function renderError(response: ServerResponse, message: string, status?: number): void;

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

@@ -0,0 +1,10 @@
+/// <reference types="node" />
+import { ServerResponse } from 'http';
+/**
+ * 渲染 json 格式数据.
+ * @param response 响应信息
+ * @param text 文本
+ * @param status 状态码，默认 200
+ * @returns
+ */
+export declare function renderText(response: ServerResponse, text: string, status?: number): void;

package/types/mvc/router.d.ts

@@ -0,0 +1,11 @@
+import { ServerExchange } from './exchange';
+/**
+ * 路由控制器函数.
+ */
+export interface RouterHandler {
+    (exchange: ServerExchange): Promise<void>;
+}
+/**
+ * 路由列表.
+ */
+export type Routers = Record<string, RouterHandler>;

package/types/mysql/config.d.ts

@@ -0,0 +1,86 @@
+import { ValidationOpts } from '../validation';
+/**
+ * mysql 配置.
+ */
+export interface MysqlConfig {
+    /**
+     * 主机名.
+     */
+    host: string;
+    /**
+     * 端口号
+     */
+    port: number;
+    /**
+     * 用户名
+     */
+    user: string;
+    /**
+     * 密码
+     */
+    password: string;
+    /**
+     * 字符集，默认 utf8mb4
+     */
+    charset: string;
+    /**
+     * 库
+     */
+    database: string;
+    /**
+     * 版本控制开启.
+     */
+    versionControlEnabled: boolean;
+    /**
+     * 版本控制的文件目录，默认 db_migration.
+     */
+    versionControlDir: string;
+    /**
+     * 时区，默认 +08:00
+     */
+    timezone: string;
+    /**
+     * 超时时间，单位毫秒，默认 10秒
+     */
+    connectTimeout: number;
+    /**
+     * 调试模式
+     */
+    debug: boolean;
+    /**
+     * 最大连接数
+     */
+    connectionLimit: number;
+    /**
+     * 最大闲置数
+     */
+    maxIdle: number;
+    /**
+     * 闲置的超时时间，也即多久不用算闲置，单位毫秒
+     */
+    idleTimeout: number;
+    /**
+     * 慢 sql 警告，启用后如果一个查询过慢，就会输出警告日志。
+     */
+    slowSqlWarn: boolean;
+    /**
+     * 慢 sql 毫秒数，执行时间超过设定值的 sql 会被认为是慢 sql ，默认 200
+     */
+    slowSqlMs: number;
+    /**
+     * 事务超时时间，单位毫秒，默认 5000，设置为小于等于 0 的值表示不限制
+     */
+    transactionTimeout: number;
+    /**
+     * 事务严格模式
+     */
+    transactionStrict: boolean;
+}
+/**
+ * 默认配置.
+ */
+export declare const defaultConfig: MysqlConfig;
+/**
+ * 配置校验规则.
+ */
+export declare const configValidation: ValidationOpts<MysqlConfig>;

package/types/mysql/exception.d.ts

@@ -0,0 +1,7 @@
+/**
+ * mysql 异常.
+ */
+export declare class MysqlException extends Error {
+    readonly message: string;
+    constructor(message: string);
+}

package/types/mysql/index.d.ts

@@ -0,0 +1,16 @@
+import { MysqlException } from './exception';
+import { MysqlManager } from './manager';
+import { MysqlCriteria } from './manager/ops/criteria';
+import { Table } from './table-info';
+/**
+ * 启用mysql
+ * @param name 配置名称，同时也是环境变量配置的前缀，英文开头，由英文数字和下划线成.
+ */
+export declare function enableMysql(name?: string): Promise<void>;
+/**
+ * 获取管理器.
+ * @param name  配置名称，如果调用 enableMysql 时填写了，那么这里也要填写并保持一致
+ */
+export declare function getMysqlManager(name?: string): MysqlManager;
+export * from './manager';
+export { MysqlCriteria, MysqlException, Table };

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

@@ -0,0 +1,158 @@
+import { Pool, PoolConnection } from 'mysql2';
+import { MysqlConfig } from '../config';
+import { Table } from '../table-info';
+import { DeleteManyOpts, FindOpts, MixCriteria, MysqlPage, MysqlPaginateOpts, UpdateOpts, Updater } from './ops';
+/**
+ * mysql 管理器基类，提供基础的操作方法.
+ */
+export declare abstract class BaseMysqlManager {
+    /**
+     * 选项，连接池和连接必须有一个，连接池优先.
+     */
+    private readonly opts;
+    /**
+     * @param mapping 映射
+     */
+    constructor(
+    /**
+     * 选项，连接池和连接必须有一个，连接池优先.
+     */
+    opts: {
+        config: MysqlConfig;
+        pool?: Pool;
+        connection?: PoolConnection;
+    });
+    protected queryWithConnection<T>(queryFn: (conn: PoolConnection) => Promise<T>): Promise<T>;
+    /**
+     * 依据id查找.
+     * @param table 表信息
+     * @param id id
+     * @returns
+     */
+    findById<T>(table: Table<T>, id: string | number): Promise<T | null>;
+    /**
+     * 根据id列表查询
+     * @param table
+     * @param ids
+     * @returns
+     */
+    findByIdIn<T>(table: Table<T>, ids: Array<string | number>): Promise<T[]>;
+    /**
+     * 根据条件判定是否存在记录.
+     * @param table
+     * @param criteria  条件信息，可以为空，为空的情况下判定整个表是否有记录
+     * @returns
+     */
+    existsBy<T>(table: Table<T>, criteria?: MixCriteria<T>): Promise<boolean>;
+    /**
+     * 根据id判定记录是否存在
+     * @param table
+     * @param id
+     * @returns
+     */
+    existsById<T>(table: Table<T>, id: string | number): Promise<boolean>;
+    /**
+     * 按 id 查询
+     * @param table 表信息
+     * @param id
+     */
+    deleteById<T>(table: Table<T>, id: string | number): Promise<boolean>;
+    /**
+     * 按条件删除数据。批量删除是危险操作，建议在使用时尽可能设置 limit 参数来限制数量。
+     * @param opts
+     * @returns
+     */
+    deleteMany<T>(opts: DeleteManyOpts<T>): Promise<number>;
+    /**
+     * 仅删除符合条件的一条记录，必须是相等条件
+     * @param table
+     * @param criteria
+     * @returns
+     */
+    deleteOne<T>(table: Table<T>, criteria: Partial<T>): Promise<boolean>;
+    /**
+     * 查询表中所有数据.
+     * @param table  表信息
+     * @returns
+     */
+    findAll<T>(table: Table<T>): Promise<T[]>;
+    /**
+     * 按条件查询第一条记录.
+     * @param table
+     * @param criteria
+     * @returns
+     */
+    findFirst<T>(table: Table<T>, criteria?: MixCriteria<T>): Promise<T | null>;
+    /**
+     * 插入数据. 不支持自增加长id,id必须提前生成，请使用 uuid.
+     * @param table 表信息
+     * @param data 数据，数据必须是 T 的实例, T 必须是已配置的实体类类型，否则无法完成操作
+     * @returns 插入后的数据
+     */
+    insert<T>(table: Table<T>, data: T): Promise<T>;
+    /**
+     * 批量插入
+     * @param table 表
+     * @param list 要插入的数据列表
+     */
+    insertMany<T>(table: Table<T>, list: T[]): Promise<void>;
+    /**
+     * 更新
+     * @param table 表信息
+     * @param data
+     */
+    update<T>(table: Table<T>, data: T): Promise<T>;
+    /**
+     * 更新所以匹配条件的记录
+     * @param opts
+     * @returns
+     */
+    updateMany<T>(opts: UpdateOpts<T>): Promise<number>;
+    /**
+     * 只更新一条记录。仅支持相等条件，不支持范围条件，可以严格事务中使用。
+     * @param table
+     * @param criteria
+     * @param updater
+     * @returns 更新是否成功
+     */
+    updateOne<T>(table: Table<T>, criteria: Partial<T>, updater: Updater<T>): Promise<boolean>;
+    /**
+     * 部分更新
+     * @param table 表信息
+     * @param data 字段信息，必须要包含id字段，如果包含了更新和创建时间的字段，则忽略掉
+     */
+    partialUpdate<T>(table: Table<T>, data: Updater<T>): Promise<boolean>;
+    /**
+     * 查找实体类 自定义条件
+     * @param opts
+     * @returns
+     */
+    find<T>(opts: FindOpts<T>): Promise<T[]>;
+    /**
+     * 指定条件查询数量
+     * @param table 表信息
+     * @param criteria 查询条件
+     * @returns
+     */
+    count<T>(table: Table<T>, criteria?: MixCriteria<T>): Promise<number>;
+    /**
+     * 分页查询
+     * @param opts
+     * @returns
+     */
+    paginate<T>(opts: MysqlPaginateOpts<T>): Promise<MysqlPage<T>>;
+    /**
+     * 自定义查询，指定 sql 、参数和返回值类型
+     * @param sql 预编译 sql ，参数使用 ”?“（英文问号） 占位，注意查询的字段名称会与返回值类型的字段映射，如果 sql 中的字段名称很特殊（比如纯数字等），需要设置别名，避免产生映射错误
+     * @param values 要传递的值，对应 sql 中的占位符 ”?“（英文问号）
+     * @param T 返回值类型，注意类型映射问题，详细可以参考文档中关于类型映射的说明
+     */
+    query<T>(sql: string, values?: any[]): Promise<T[]>;
+    /**
+     * 自定义 sql 执行，必须是修改类的 sql ，否则会发生错误
+     * @param sql
+     * @param values
+     * @returns 返回影响的行数
+     */
+    modify(sql: string, values?: any[]): Promise<number>;
+}

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

@@ -0,0 +1,36 @@
+import { Pool } from 'mysql2';
+import { MysqlConfig } from '../config';
+import { BaseMysqlManager } from './base';
+import { MysqlTxSession } from './tx';
+/**
+ * mysql 管理器，封装数据库操作，提供方便使用的实体类操作方法.
+ */
+export declare class MysqlManager extends BaseMysqlManager {
+    private readonly config;
+    /**
+     * 连接池.
+     */
+    private readonly pool;
+    /**
+     * @param mapping 映射
+     */
+    constructor(config: MysqlConfig, 
+    /**
+     * 连接池.
+     */
+    pool: Pool);
+    /**
+     * 事务. 所有事务中的操作都必须使用 exec 函数中提供的 session 对象，直接使用 MysqlManager 上的方法
+     * 进行的操作不会在事务中生效.
+     * @param ops 逻辑执行函数，内部的所有逻辑都必须在函数内执行完，
+     * 不得有操作在函数外异步执行（异步操作不 await，或使用定时器单独执行等），否则不会在事务中生效
+     * @param opts 选项，可设置超时时间等
+     */
+    tx<T>(ops: (session: MysqlTxSession) => Promise<T>, opts?: {
+        timeout?: number;
+        isolationLevel?: 'REPEATABLE READ' | 'READ COMMITTED' | 'READ UNCOMMITTED' | 'SERIALIZABLE';
+        accessMode?: 'READ WRITE' | 'READ ONLY';
+    }): Promise<T>;
+}
+export { FindOpts, MixCriteria, MysqlCriteria } from './ops';
+export { BaseMysqlManager, MysqlTxSession };

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

@@ -0,0 +1,13 @@
+import { PoolConnection } from 'mysql2';
+import { Table } from '../../table-info';
+import { MixCriteria } from './criteria';
+import { MysqlConfig } from '../../config';
+/**
+ * 按条件统计数量.
+ * @param config
+ * @param conn
+ * @param table
+ * @param criteria
+ * @returns
+ */
+export declare function count<T>(config: MysqlConfig, conn: PoolConnection, table: Table<T>, criteria?: MixCriteria<T>): Promise<number>;

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

@@ -0,0 +1,120 @@
+export interface MysqlQuery {
+    sql: string;
+    values: any[];
+}
+/**
+ * mysql 查询条件（ query criterion ），默认查询条件都是并且关系（and）， 部分方法会有例外，在使用的时候请注意方法说明。
+ *
+ * @param <T> 表类型
+ */
+export declare class MysqlCriteria<T> {
+    /**
+     * 条件列表.
+     */
+    private criteria;
+    /**
+     * 相等.
+     * @param column
+     * @param value
+     */
+    eq(column: keyof T, value: any): this;
+    /**
+     * 不等于，注意不相等不能走索引，谨慎使用
+     * @param column
+     * @param value
+     */
+    neq(column: keyof T, value: any): this;
+    /**
+     * like
+     * @param column
+     * @param value
+     * @returns
+     */
+    like(column: keyof T, value: string): this;
+    /**
+     * not like
+     * @param column
+     * @param value
+     * @returns
+     */
+    notLike(column: keyof T, value: string): this;
+    /**
+     * BETWEEN x and y
+     */
+    between(column: keyof T, min: number, max: number): this;
+    /**
+     * 大于
+     * @param column
+     * @param value
+     */
+    gt(column: keyof T, value: number | Date | string): this;
+    /**
+     * 大于等于
+     * @param column
+     * @param value
+     */
+    gte(column: keyof T, value: number | Date | string): this;
+    /**
+     * 小于
+     * @param column
+     * @param value
+     */
+    lt(column: keyof T, value: number | Date | string): this;
+    /**
+     * 小于等于
+     * @param column
+     * @param value
+     */
+    lte(column: keyof T, value: number | Date | string): this;
+    /**
+     * in 条件
+     * @param column
+     * @param values
+     */
+    in(column: keyof T, values: Array<string | number>): this;
+    /**
+     * 嵌入其它的查询条件，与现有的查询条件是或者关系.
+     * @param criteria
+     */
+    or(orCriteria: (criteria: MysqlCriteria<T>) => void): this;
+    /**
+     * 嵌入其它的查询条件，与现有的查询条件是并且关系.
+     * @param criteria
+     */
+    and(andCriteria: (criteria: MysqlCriteria<T>) => void): this;
+    /**
+     * 字段为空
+     * @param field
+     * @returns
+     */
+    isNull(field: keyof T): this;
+    /**
+     * 字段非空
+     * @param field
+     * @returns
+     */
+    isNotNull(field: keyof T): this;
+    /**
+     * 判定是否空，未设置条件.
+     * @returns
+     */
+    isEmpty(): boolean;
+    /**
+     * 检查条件信息是否有效，在出错时能给予较详细的提示，以方便排查.
+     */
+    check(): void;
+    /**
+     * 生成查询数据
+     */
+    generateQuery(): MysqlQuery;
+}
+/**
+ * 混合的查询对象.
+ */
+export type MixCriteria<T> = Partial<T> | ((criteria: MysqlCriteria<T>) => void) | MysqlCriteria<T>;
+/**
+ * 将混合的查询条件转换成查询语句，如果最终构建的条件是空的，返回 undefined
+ * @param criteria
+ * @returns
+ */
+export declare function buildQuery<T>(criteria: MixCriteria<T>): MysqlQuery | undefined;

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

@@ -0,0 +1,46 @@
+import { PoolConnection } from 'mysql2';
+import { Table } from '../../table-info';
+import { MixCriteria } from './criteria';
+import { MysqlConfig } from '../../config';
+/**
+ * 按 id 删除.
+ *
+ * @param config
+ * @param connection
+ * @param mapping
+ * @param type
+ * @param id
+ */
+export declare function deleteById<T>(config: MysqlConfig, connection: PoolConnection, table: Table<T>, id: string | number): Promise<boolean>;
+/**
+ * 批量删除的选项
+ */
+export interface DeleteManyOpts<T> {
+    /**
+     * 表.
+     */
+    table: Table<T>;
+    /**
+     * 查询条件
+     * @param criteria
+     * @returns
+     */
+    criteria: MixCriteria<T>;
+    /**
+     * 限制数量
+     */
+    limit?: number;
+    /**
+     * 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
+     */
+    orderBy?: Array<[keyof T, 'asc' | 'desc']>;
+}
+/**
+ * 按条件删除，返回被删除的记录数.
+ * 务必谨慎使用，大批量删除容易带来性能问题，造成线上事故.
+ * @param config
+ * @param connection
+ * @param table
+ * @param criteria
+ */
+export declare function deleteMany<T>(config: MysqlConfig, connection: PoolConnection, opts: DeleteManyOpts<T>): Promise<number>;

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

@@ -0,0 +1,6 @@
+import { PoolConnection } from 'mysql2';
+import { Table } from '../../table-info';
+import { MixCriteria } from './criteria';
+import { MysqlConfig } from '../../config';
+export declare function existsById<T>(config: MysqlConfig, connection: PoolConnection, table: Table<T>, id: string | number): Promise<boolean>;
+export declare function existsBy<T>(config: MysqlConfig, connection: PoolConnection, table: Table<T>, criteria?: MixCriteria<T>): Promise<boolean>;

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

@@ -0,0 +1,66 @@
+import { PoolConnection } from 'mysql2';
+import { Table } from '../../table-info';
+import { MixCriteria } from './criteria';
+import { MysqlConfig } from '../../config';
+/**
+ * 按 id 查询
+ * @param connection
+ * @param mapping
+ * @param type
+ * @param id
+ */
+export declare function findById<T>(config: MysqlConfig, connection: PoolConnection, table: Table<T>, id: string | number): Promise<T | null>;
+/**
+ * 查询表中所有数据。需谨慎操作，全表查询有可能会产生大列表问题。
+ * @param connection
+ * @param mapping
+ * @param type
+ * @returns
+ */
+export declare function findAll<T>(config: MysqlConfig, connection: PoolConnection, table: Table<T>): Promise<T[]>;
+export interface FindOpts<T> {
+    /**
+     * 表
+     */
+    table: Table<T>;
+    /**
+     * 查询条件
+     * @param criteria
+     * @returns
+     */
+    criteria?: MixCriteria<T>;
+    /**
+     * 偏移，需要 limit 有值才可以
+     */
+    offset?: number;
+    /**
+     * 限制返回的数量
+     */
+    limit?: number;
+    /**
+     * 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
+     */
+    orderBy?: Array<[keyof T, 'asc' | 'desc']>;
+}
+/**
+ * 条件查询
+ * @param opts
+ * @returns
+ */
+export declare function find<T>(config: MysqlConfig, conn: PoolConnection, opts: FindOpts<T>): Promise<T[]>;
+/**
+ * 根据 id 列表查询记录
+ * @param connection
+ * @param table
+ * @param ids
+ * @returns
+ */
+export declare function findByIdIn<T>(config: MysqlConfig, connection: PoolConnection, table: Table<T>, ids: Array<string | number>): Promise<T[]>;
+/**
+ * 查找符合条件的第一条记录
+ * @param conn
+ * @param table
+ * @param criteria
+ * @returns
+ */
+export declare function findFirst<T>(config: MysqlConfig, conn: PoolConnection, table: Table<T>, criteria?: MixCriteria<T>): Promise<T | null>;

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

@@ -0,0 +1,10 @@
+export * from './count';
+export * from './criteria';
+export * from './delete';
+export * from './exist';
+export * from './find';
+export * from './insert';
+export * from './modify';
+export * from './paginate';
+export * from './query';
+export * from './update';

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

@@ -0,0 +1,18 @@
+import { PoolConnection } from 'mysql2';
+import { Table } from '../../table-info';
+import { MysqlConfig } from '../../config';
+/**
+ * 为表插入数据
+ * @param connection
+ * @param table
+ * @param data
+ * @returns
+ */
+export declare function insert<T>(config: MysqlConfig, connection: PoolConnection, table: Table<T>, data: T): Promise<T>;
+/**
+ * 一次插入多条记录
+ * @param connection 连接
+ * @param table 表
+ * @param list 要插入的记录列表
+ */
+export declare function insertMany<T>(config: MysqlConfig, connection: PoolConnection, table: Table<T>, list: T[]): Promise<void>;

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

@@ -0,0 +1,3 @@
+import { PoolConnection } from 'mysql2';
+import { MysqlConfig } from '../../config';
+export declare function modify(config: MysqlConfig, connection: PoolConnection, sql: string, values?: any[]): Promise<number>;

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

@@ -0,0 +1,36 @@
+import { PoolConnection } from 'mysql2';
+import { Table } from '../../table-info';
+import { MixCriteria } from './criteria';
+import { MysqlConfig } from '../../config';
+export interface MysqlPaginateOpts<T> {
+    /**
+     * 表
+     */
+    table: Table<T>;
+    /**
+     * 查询条件
+     * @param criteria
+     * @returns
+     */
+    criteria?: MixCriteria<T>;
+    /**
+     * 而码,默认1
+     */
+    pn?: number;
+    /**
+     * 每页的数据量大小,默认 20, 必须在 1-1000 之间
+     */
+    pz?: number;
+    /**
+     * 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
+     */
+    orderBy?: Array<[keyof T, 'asc' | 'desc']>;
+}
+/**
+ * mysql 分页查询结果
+ */
+export interface MysqlPage<T> {
+    total: number;
+    list: T[];
+}
+export declare function paginate<T>(config: MysqlConfig, conn: PoolConnection, opts: MysqlPaginateOpts<T>): Promise<MysqlPage<T>>;

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

@@ -0,0 +1,3 @@
+import { PoolConnection } from 'mysql2';
+import { MysqlConfig } from '../../config';
+export declare function query<T>(config: MysqlConfig, connection: PoolConnection, sql: string, values?: any[]): Promise<T[]>;