wok-server 0.1.0

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

@@ -0,0 +1,70 @@
+import { PoolConnection } from 'mysql2';
+import { Table } from '../../table-info';
+import { MixCriteria } from './criteria';
+import { MysqlConfig } from '../../config';
+/**
+ * 更新
+ * @param config
+ * @param connection
+ * @param mapping
+ * @param data
+ * @returns
+ */
+export declare function update<T>(config: MysqlConfig, connection: PoolConnection, table: Table<T>, data: T): Promise<T>;
+/**
+ * 更新器
+ */
+export type Updater<T> = Partial<{
+    [key in keyof T]: T[key] | undefined | ['setNull'] | ['inc', number];
+}>;
+/**
+ * 部分更新
+ * @param connection
+ * @param mapping
+ * @param type
+ * @param data
+ */
+export declare function partialUpdate<T>(config: MysqlConfig, connection: PoolConnection, table: Table<T>, data: Updater<T>): Promise<boolean>;
+/**
+ * 更新指定的一条记录
+ * @param config
+ * @param connection
+ * @param table
+ * @param query
+ * @param data
+ */
+export declare function updateOne<T>(config: MysqlConfig, connection: PoolConnection, table: Table<T>, query: Partial<T>, updater: Updater<T>): Promise<boolean>;
+/**
+ * 更新选项
+ */
+export interface UpdateOpts<T> {
+    /**
+     * 表
+     */
+    table: Table<T>;
+    /**
+     * 查询条件
+     */
+    query: MixCriteria<T>;
+    /**
+     * 限制数量
+     */
+    limit?: number;
+    /**
+     * 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
+     */
+    orderBy?: Array<[keyof T, 'asc' | 'desc']>;
+    /**
+     * 更新设置
+     */
+    updater: Updater<T>;
+}
+/**
+ * 更新所有匹配条件的记录
+ * @param config
+ * @param connection 连接
+ * @param table 表
+ * @param query 查询条件
+ * @param updater 更新操作，支持置空和递增（需要使用元组）
+ */
+export declare function updateMany<T>(config: MysqlConfig, connection: PoolConnection, opts: UpdateOpts<T>): Promise<number>;

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

@@ -0,0 +1,34 @@
+import { PoolConnection } from 'mysql2';
+import { MysqlConfig } from '../config';
+import { MysqlTxSession } from './tx';
+import { Table } from '../table-info';
+import { DeleteManyOpts, FindOpts, MixCriteria, MysqlPage, MysqlPaginateOpts, UpdateOpts, Updater } from './ops';
+/**
+ * 严格 mysql 事务会话，会禁用一些操作.
+ */
+export declare class MysqlStrictTxSession extends MysqlTxSession {
+    #private;
+    constructor(config: MysqlConfig, conn: PoolConnection);
+    findById<T>(table: Table<T>, id: string | number): Promise<T | null>;
+    findByIdIn<T>(table: Table<T>, ids: (string | number)[]): Promise<T[]>;
+    existsBy<T>(table: Table<T>, criteria?: MixCriteria<T> | undefined): Promise<boolean>;
+    existsById<T>(table: Table<T>, id: string | number): Promise<boolean>;
+    deleteById<T>(table: Table<T>, id: string | number): Promise<boolean>;
+    deleteOne<T>(table: Table<T>, criteria: Partial<T>): Promise<boolean>;
+    deleteMany<T>(opts: DeleteManyOpts<T>): Promise<number>;
+    findAll<T>(table: Table<T>): Promise<T[]>;
+    findFirst<T>(table: Table<T>, criteria?: MixCriteria<T> | undefined): Promise<T | null>;
+    insert<T>(table: Table<T>, data: T): Promise<T>;
+    insertMany<T>(table: Table<T>, list: T[]): Promise<void>;
+    update<T>(table: Table<T>, data: T): Promise<T>;
+    updateMany<T>(opts: UpdateOpts<T>): Promise<number>;
+    updateOne<T>(table: Table<T>, query: Partial<T>, updater: Partial<{
+        [key in keyof T]: ['setNull'] | ['inc', number] | T[key] | undefined;
+    }>): Promise<boolean>;
+    partialUpdate<T>(table: Table<T>, data: Updater<T>): Promise<boolean>;
+    find<T>(opts: FindOpts<T>): Promise<T[]>;
+    count<T>(table: Table<T>, criteria?: MixCriteria<T> | undefined): Promise<number>;
+    paginate<T>(opts: MysqlPaginateOpts<T>): Promise<MysqlPage<T>>;
+    query<T>(sql: string, values?: any[] | undefined): Promise<T[]>;
+    modify(sql: string, values?: any[] | undefined): Promise<number>;
+}

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

@@ -0,0 +1,15 @@
+import { PoolConnection } from 'mysql2';
+import { BaseMysqlManager } from './base';
+import { MysqlConfig } from '../config';
+/**
+ * mysql 事务会话.
+ */
+export declare class MysqlTxSession extends BaseMysqlManager {
+    #private;
+    constructor(config: MysqlConfig, conn: PoolConnection);
+    protected queryWithConnection<T>(queryFn: (conn: PoolConnection) => Promise<T>): Promise<T>;
+    /**
+     * 中止，被中止后的会话不能再进行任何操作
+     */
+    abort(): void;
+}

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

@@ -0,0 +1,17 @@
+import { Connection, OkPacket, Pool, PoolConnection, ResultSetHeader, RowDataPacket } from 'mysql2';
+import { MysqlConfig } from '../config';
+/**
+ * 查询，适用于各种 sql 的执行
+ * @param config
+ * @param conn
+ * @param sql
+ * @param values
+ * @returns
+ */
+export declare function promiseQuery(config: MysqlConfig, conn: Connection, sql: string, values?: any[]): Promise<OkPacket | ResultSetHeader | RowDataPacket[] | [RowDataPacket[], ResultSetHeader] | ResultSetHeader[] | RowDataPacket[][] | OkPacket[]>;
+/**
+ * 获取连接
+ * @param pool
+ * @returns
+ */
+export declare function promiseGetConnection(pool: Pool): Promise<PoolConnection>;

package/types/mysql/migration.d.ts

@@ -0,0 +1,8 @@
+import { Connection } from 'mysql2';
+import { MysqlConfig } from './config';
+/**
+ * 迁移.
+ * @param config
+ * @param conn
+ */
+export declare function migrate(config: MysqlConfig, conn: Connection): Promise<void>;

package/types/mysql/table-info.d.ts

@@ -0,0 +1,36 @@
+import { ValidationOpts } from '../validation';
+/**
+ * 表信息. 表的字段分为三个部分：主键、普通列、时间列，分别对应的属性是：id、columns
+ * 和 createDate 还有 updatedDate，这三部分配置的字段名称不允许有重叠，否则会产生错误.
+ */
+export interface Table<T> {
+    /**
+     * 表名.
+     */
+    tableName: string;
+    /**
+     * id 字段名称.
+     */
+    id: keyof T;
+    /**
+     * 列字段名称.只有配置了名称的字段才会参与数据库的查询与更新，没有配置的其它字段可作其它用途。
+     * 注意：columns 配置的字段不能和 id 或更新时间和创建时间重叠，否则在更新时产生错误，将数据改错。
+     * 程序本身是不会做检查的，编写的时候必须要注意。
+     */
+    columns: Array<keyof T>;
+    /**
+     * 创建时间字段信息.
+     */
+    createdDate?: {
+        column: keyof T;
+        type: 'number' | 'date';
+    };
+    /**
+     * 更新时间字段信息.
+     */
+    updatedDate?: {
+        column: keyof T;
+        type: 'number' | 'date';
+    };
+}
+export declare const tableValidation: ValidationOpts<Table<any>>;

package/types/task/daily.d.ts

@@ -0,0 +1,15 @@
+import { Task, TaskController } from './task';
+/**
+ * 每日任务.
+ * @param hours 时
+ * @param minutes 分
+ * @param task 要执行的任务
+ * @returns
+ */
+export declare function scheduleDailyTask(hours: number, minutes: number, task: Task): TaskController;
+/**
+ * 计算到下次指定时间点的延迟
+ * @param hours
+ * @param minutes
+ */
+export declare function dailyTaskDelay(hours: number, minutes: number): number;

package/types/task/fixed-delay.d.ts

@@ -0,0 +1,8 @@
+import { Task, TaskController } from './task';
+/**
+ * 固定延迟执行任务
+ * @param initialDelay  第一次执行延迟的时间，单位秒
+ * @param delay 每次的延迟时间，单位秒
+ * @param task 任务
+ */
+export declare function scheduleWithFixedDelay(initialDelay: number, delay: number, task: Task): TaskController;

package/types/task/fixed-rate.d.ts

@@ -0,0 +1,8 @@
+import { Task, TaskController } from './task';
+/**
+ * 固定延迟执行任务
+ * @param initialDelay  第一次执行延迟的时间，单位秒
+ * @param period 每次的延迟时间，单位秒
+ * @param task 任务
+ */
+export declare function scheduleWithFixedRate(initialDelay: number, period: number, task: Task): TaskController;

package/types/task/index.d.ts

@@ -0,0 +1,4 @@
+export { Task, TaskController } from './task';
+export * from './fixed-delay';
+export * from './fixed-rate';
+export * from './daily';

package/types/task/task.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 任务.
+ */
+export interface Task {
+    /**
+     * 任务的名称，用于跟踪任务的执行情况，定位错误.
+     * 当任务执行时间过长或任务失败时，相关的错误提示信息会显示名称，以便于排查.
+     */
+    name: string;
+    /**
+     * 任务运行.
+     * @returns
+     */
+    run: () => Promise<void>;
+}
+/**
+ * 任务控制器
+ */
+export declare class TaskController {
+    #private;
+    isStopped(): boolean;
+    stop(): void;
+}
+/**
+ * 任务执行，封装任务执行过程中的一些通用信息输出和异常控制.
+ * @param task
+ * @returns
+ */
+export declare function execTask(task: Task): Promise<{
+    start: number;
+    cost: number;
+    end: number;
+}>;

package/types/validation/exception.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 校验异常.
+ */
+export declare class ValidationException {
+    /**
+     * 异常信息，如 “不能为空” 之类的.
+     */
+    readonly errMsg: string;
+    /**
+     * 校验器名称，如 length 、notNull 之类的.
+     */
+    readonly validator: string;
+    /**
+     * 校验出错的路径.
+     */
+    readonly propertyPath: string;
+    /**
+     * 值
+     */
+    readonly val: any;
+    constructor(
+    /**
+     * 异常信息，如 “不能为空” 之类的.
+     */
+    errMsg: string, 
+    /**
+     * 校验器名称，如 length 、notNull 之类的.
+     */
+    validator: string, 
+    /**
+     * 校验出错的路径.
+     */
+    propertyPath: string, 
+    /**
+     * 值
+     */
+    val: any);
+    /**
+     * 对错误的完整描述信息，用于日志记录.
+     */
+    desc(): string;
+    get message(): string;
+}

package/types/validation/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 校验结果。message：错误信息，反馈给调用处；validator 校验器名称，用于记录错误信息来自哪个校验器，
+ * 以便于程序在出错时知道信息来自哪里。
+ */
+export type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+    validator: string;
+    /**
+     * 如果校验的是层级深的对象，内部的属性发生了错误，可用于标记属性的路径
+     */
+    propPath?: string[];
+};
+/**
+ * 校验器.
+ */
+export type PropValidator<T> = (val: T) => ValidationResult;
+/**
+ * 对象的校验选项
+ */
+export type ValidationOpts<T> = Partial<{
+    [key in keyof T]: PropValidator<T[key]>[];
+}>;
+/**
+ * 校验对象.
+ * @param obj
+ */
+export declare function validate<T>(obj: T, opts: ValidationOpts<T>): void;
+export * from './exception';
+export * from './validator';

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

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

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

@@ -0,0 +1,8 @@
+import { PropValidator } from '..';
+/**
+ * 枚举，校验值必须是指定列表中的一个.
+ * @param list 支持的值列表，仅支持数字和字符串类型
+ * @param msg
+ * @returns
+ */
+export declare function enumerate<T>(list: (number | string)[], msg?: string): PropValidator<T>;

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

@@ -0,0 +1,11 @@
+export * from './not-null';
+export * from './not-blank';
+export * from './max';
+export * from './min';
+export * from './regexp';
+export * from './length';
+export * from './enum';
+export * from './array';
+export * from './plain-obj';
+export * from './max-length';
+export * from './min-length';

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

@@ -0,0 +1,10 @@
+import { PropValidator } from '..';
+/**
+ * length 校验，可用于字符串或数组.
+ * @returns
+ */
+export declare function length<T>(opts: {
+    min?: number;
+    max?: number;
+    message?: string;
+}): PropValidator<T>;

package/types/validation/validator/max-length.d.ts

@@ -0,0 +1,8 @@
+import { PropValidator } from '..';
+/**
+ * 最大长度校验，可用于字符串或数组.
+ * @param maxLength
+ * @param message
+ * @returns
+ */
+export declare function maxLength<T>(maxLength: number, message?: string): PropValidator<T>;

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

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

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

@@ -0,0 +1,6 @@
+import { PropValidator } from '..';
+/**
+ * 最小长度校验，可用于字符串或数组.
+ * @returns
+ */
+export declare function minLength<T>(minLength: number, message?: string): PropValidator<T>;

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

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

package/types/validation/validator/not-blank.d.ts

@@ -0,0 +1,7 @@
+import { PropValidator } from '..';
+/**
+ * 字符串非空校验，以下的情况不会通过校验：undefined，null，非 string 类型，空白字符串.
+ * @param message
+ * @returns
+ */
+export declare function notBlank<T>(message?: string): PropValidator<T>;

package/types/validation/validator/not-null.d.ts

@@ -0,0 +1,6 @@
+import { PropValidator } from '..';
+/**
+ * 非空校验.
+ * @param message
+ */
+export declare function notNull<T>(message?: string): PropValidator<T>;

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

@@ -0,0 +1,7 @@
+import { PropValidator, ValidationOpts } from '..';
+/**
+ * 普通对象校验.
+ * @param opts
+ * @returns
+ */
+export declare function plainObject<T>(opts: ValidationOpts<T>): PropValidator<T>;

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

@@ -0,0 +1,8 @@
+import { PropValidator } from '..';
+/**
+ * 正则校验
+ * @param pattern 正则表达式
+ * @param msg 错误消息
+ * @returns
+ */
+export declare function regexp<T>(pattern: RegExp, msg?: string): PropValidator<T>;