wok-server 0.6.0 → 0.7.1

package/types/mysql/config.d.ts

@@ -56,7 +56,7 @@ export interface MysqlConfig {
      */
     maxIdle: number;
     /**
-     * 闲置的超时时间，也即多久不用算闲置，单位毫秒
+     * 闲置的超时时间，当一个数据库连接不再被业务使用、处于闲置状态的时间超过这个阈值，连接池就会自动回收并关闭这个连接，释放资源。
      */
     idleTimeout: number;
     /**

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

@@ -1,7 +1,7 @@
 import { Pool, PoolConnection } from 'mysql2';
 import { MysqlConfig } from '../config';
 import { Table } from '../table-info';
-import { DeleteManyOpts, FindOpts, MixCriteria, MysqlPage, MysqlPaginateOpts, UpdateOpts, Updater, FindSelectOpts } from './ops';
+import { DeleteManyOpts, FindOpts, MixCriteria, MysqlPage, MysqlPaginateOpts, MysqlPaginateSelectOpts, OrderBy, UpdateOpts, Updater, InsertValue, FindSelectOpts } from './ops';
 /**
  * mysql 管理器基类，提供基础的操作方法.
  */
@@ -83,20 +83,45 @@ export declare abstract class BaseMysqlManager {
      * @param orderBy 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
      * @returns
      */
-    findFirst<T>(table: Table<T>, criteria?: MixCriteria<T>, orderBy?: Array<[keyof T, 'asc' | 'desc']>): Promise<T | null>;
+    findFirst<T>(table: Table<T>, criteria?: MixCriteria<T>, orderBy?: OrderBy<T>): Promise<T | null>;
     /**
      * 插入数据. 不支持自增加长id,id必须提前生成，请使用 uuid.
      * @param table 表信息
      * @param data 数据，数据必须是 T 的实例, T 必须是已配置的实体类类型，否则无法完成操作
      * @returns 插入后的数据
      */
-    insert<T>(table: Table<T>, data: T): Promise<T>;
+    insert<T>(table: Table<T>, data: InsertValue<T>): Promise<T>;
     /**
      * 批量插入
      * @param table 表
      * @param list 要插入的数据列表
      */
-    insertMany<T>(table: Table<T>, list: T[]): Promise<void>;
+    insertMany<T>(table: Table<T>, list: InsertValue<T>[]): Promise<void>;
+    /**
+     * Upsert 单条数据
+     * 如果主键冲突则更新，否则插入
+     * @param table 表信息
+     * @param data 数据
+     * @returns
+     */
+    upsert<T>(table: Table<T>, data: InsertValue<T>): Promise<T>;
+    /**
+     * Upsert 多条数据
+     * 如果主键冲突则更新，否则插入
+     * @param table 表
+     * @param list 要插入的数据列表
+     * @returns 影响的行数
+     */
+    upsertMany<T>(table: Table<T>, list: InsertValue<T>[]): Promise<number>;
+    /**
+     * Upsert 单条数据（支持自定义更新器）
+     * 如果主键冲突则按自定义逻辑更新，否则插入
+     * @param table 表信息
+     * @param data 插入的数据
+     * @param updater 冲突时的更新器
+     * @returns
+     */
+    upsertWithUpdater<T>(table: Table<T>, data: InsertValue<T>, updater: Updater<T>): Promise<T>;
     /**
      * 更新
      * @param table 表信息
@@ -148,6 +173,12 @@ export declare abstract class BaseMysqlManager {
      * @returns
      */
     paginate<T>(opts: MysqlPaginateOpts<T>): Promise<MysqlPage<T>>;
+    /**
+     * 指定字段分页查询
+     * @param opts
+     * @returns
+     */
+    paginateSelect<T, K extends keyof T>(opts: MysqlPaginateSelectOpts<T, K>): Promise<MysqlPage<Pick<T, K>>>;
     /**
      * 自定义查询，指定 sql 、参数和返回值类型
      * @param sql 预编译 sql ，参数使用 ”?“（英文问号） 占位，注意查询的字段名称会与返回值类型的字段映射，如果 sql 中的字段名称很特殊（比如纯数字等），需要设置别名，避免产生映射错误

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

@@ -108,6 +108,16 @@ export declare class MysqlCriteria<T> {
      * @returns
      */
     isNotNull(field: MysqlCriteriaKey<T>): this;
+    /**
+     * 自定义表达式查询
+     * 如 .expr('?? * ? > ?', ['balance', 2, 50])
+     * 如 .expr('MATCH(??, ??) AGAINST(? IN BOOLEAN MODE)', ['title', 'content', keyword])
+     * 如 .expr('VECTOR_DISTANCE(??, STRING_TO_VECTOR(?)) < ?', ['content_vec', embedding, threshold])
+     * @param sql SQL 片段，使用 ?? 引用列名，? 引用参数值
+     * @param values 参数值数组，按 SQL 中占位符顺序传入
+     * @returns
+     */
+    expr(sql: string, values?: any[]): this;
     /**
      * 判定是否空，未设置条件.
      * @returns

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

@@ -2,6 +2,7 @@ import { PoolConnection } from 'mysql2';
 import { Table } from '../../table-info';
 import { MixCriteria } from './criteria';
 import { MysqlConfig } from '../../config';
+import { OrderBy } from './order-by';
 /**
  * 按 id 删除.
  *
@@ -33,7 +34,7 @@ export interface DeleteManyOpts<T> {
     /**
      * 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
      */
-    orderBy?: Array<[keyof T, 'asc' | 'desc']>;
+    orderBy?: OrderBy<T>;
 }
 /**
  * 按条件删除，返回被删除的记录数.

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

@@ -2,6 +2,7 @@ import { PoolConnection } from 'mysql2';
 import { Table } from '../../table-info';
 import { MixCriteria } from './criteria';
 import { MysqlConfig } from '../../config';
+import { OrderBy } from './order-by';
 /**
  * 按 id 查询
  * @param connection
@@ -40,7 +41,7 @@ export interface FindOpts<T> {
     /**
      * 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
      */
-    orderBy?: Array<[keyof T, 'asc' | 'desc']>;
+    orderBy?: OrderBy<T>;
 }
 /**
  * 条件查询
@@ -83,4 +84,4 @@ export declare function findFirst<T>(config: MysqlConfig, conn: PoolConnection,
 /**
  * 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
  */
-orderBy?: Array<[keyof T, 'asc' | 'desc']>): Promise<T | null>;
+orderBy?: OrderBy<T>): Promise<T | null>;

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

@@ -5,6 +5,8 @@ export * from './exist';
 export * from './find';
 export * from './insert';
 export * from './modify';
+export * from './order-by';
+export * from './upsert';
 export * from './paginate';
 export * from './query';
 export * from './update';

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

@@ -1,6 +1,20 @@
 import { PoolConnection } from 'mysql2';
 import { Table } from '../../table-info';
 import { MysqlConfig } from '../../config';
+/**
+ * 插入值类型，支持在 INSERT VALUES 中使用表达式
+ */
+export type InsertValue<T> = {
+    [K in keyof T]?: T[K] | ['now'] | ['set', T[K]] | ['expr', string] | ['expr', string, any[]];
+};
+/**
+ * 处理 insert value，支持表达式
+ * @returns { frag: SQL 片段, values: 参数值数组 }
+ */
+export declare function processInsertValue(value: any): {
+    frag: string;
+    values: any[];
+};
 /**
  * 为表插入数据
  * @param connection
@@ -8,11 +22,11 @@ import { MysqlConfig } from '../../config';
  * @param data
  * @returns
  */
-export declare function insert<T>(config: MysqlConfig, connection: PoolConnection, table: Table<T>, data: T): Promise<T>;
+export declare function insert<T>(config: MysqlConfig, connection: PoolConnection, table: Table<T>, data: InsertValue<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>;
+export declare function insertMany<T>(config: MysqlConfig, connection: PoolConnection, table: Table<T>, list: InsertValue<T>[]): Promise<void>;

package/types/mysql/manager/ops/order-by.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 排序规则类型.
+ *
+ * T 为表类型.
+ *
+ * 普通列排序：
+ *   [keyof T, 'asc' | 'desc']
+ *   例: ['balance', 'asc']  →  ORDER BY `balance` asc
+ *
+ * 自定义表达式排序：
+ *   ['expr', SQL片段, 参数值数组, 'asc' | 'desc']
+ *   例: ['expr', '?? * ?', ['balance', 2], 'desc']
+ *       →  ORDER BY `balance` * 2 desc
+ *
+ *   例: ['expr', 'CHAR_LENGTH(??)', ['name'], 'desc']
+ *       →  ORDER BY CHAR_LENGTH(`name`) desc
+ *
+ *   例: ['expr', 'VECTOR_DISTANCE(??, STRING_TO_VECTOR(?))', ['content_vec', embedding], 'asc']
+ *       →  ORDER BY VECTOR_DISTANCE(`content_vec`, STRING_TO_VECTOR(?)) asc
+ *
+ * 混合使用：
+ *   [
+ *     ['active', 'asc'],
+ *     ['expr', '?? * ?', ['balance', 2], 'desc']
+ *   ]
+ *   →  ORDER BY `active` asc , `balance` * 2 desc
+ */
+export type OrderBy<T> = Array<[keyof T, 'asc' | 'desc'] | ['expr', string, any[], 'asc' | 'desc']>;
+/**
+ * 构建 ORDER BY 子句.
+ *
+ * @param orderBy 排序规则
+ * @returns { sql: SQL 片段, values: 参数值数组 }
+ */
+export declare function buildOrderBy<T>(orderBy: OrderBy<T>): {
+    sql: string;
+    values: any[];
+};

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

@@ -2,6 +2,7 @@ import { PoolConnection } from 'mysql2';
 import { Table } from '../../table-info';
 import { MixCriteria } from './criteria';
 import { MysqlConfig } from '../../config';
+import { OrderBy } from './order-by';
 export interface MysqlPaginateOpts<T> {
     /**
      * 表
@@ -24,7 +25,7 @@ export interface MysqlPaginateOpts<T> {
     /**
      * 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
      */
-    orderBy?: Array<[keyof T, 'asc' | 'desc']>;
+    orderBy?: OrderBy<T>;
 }
 /**
  * mysql 分页查询结果
@@ -34,3 +35,19 @@ export interface MysqlPage<T> {
     list: T[];
 }
 export declare function paginate<T>(config: MysqlConfig, conn: PoolConnection, opts: MysqlPaginateOpts<T>): Promise<MysqlPage<T>>;
+/**
+ * 指定字段分页查询选项
+ */
+export interface MysqlPaginateSelectOpts<T, K extends keyof T> extends MysqlPaginateOpts<T> {
+    /**
+     * 要查询的字段
+     */
+    select: K[];
+}
+/**
+ * 指定字段分页查询
+ * @param config
+ * @param conn
+ * @param opts
+ */
+export declare function paginateSelect<T, K extends keyof T>(config: MysqlConfig, conn: PoolConnection, opts: MysqlPaginateSelectOpts<T, K>): Promise<MysqlPage<Pick<T, K>>>;

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

@@ -2,6 +2,7 @@ import { PoolConnection } from 'mysql2';
 import { Table } from '../../table-info';
 import { MixCriteria } from './criteria';
 import { MysqlConfig } from '../../config';
+import { OrderBy } from './order-by';
 /**
  * 更新
  * @param config
@@ -15,14 +16,36 @@ 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'] | ['inc', number] | ['now']
     /**
      * 设置一个字段的值，和直接赋值是一样的，作用是解决一些特殊的情况的冲突
      * 比如将 json 字段的值设置为 ['setNull'] ,这就会被认为是要置空，
      * 使用 ['set',['setNull']] 就可以解决这个问题
      */
-     | ['set', T[key]];
+     | ['set', T[key]]
+    /**
+     * 字符串追加，如 ['concat', '/suffix'] 生成 col = CONCAT(IFNULL(col, ''), '/suffix')
+     * NULL 安全：字段为 NULL 时视作空字符串
+     */
+     | ['concat', string]
+    /**
+     * 使用自定义表达式
+     * 如 ['expr', '?? * ?', ['score', 2]] 生成 score = score * 2
+     * 无参数时可省略第三个参数，如 ['expr', 'NOW()'] 等同 ['expr', 'NOW()', []]
+     */
+     | ['expr', string, any[]] | ['expr', string];
 }>;
+/**
+ * 转换更新器
+ * @param table
+ * @param updater
+ * @param autoUpdateTime 是否自动添加更新时间
+ * @returns
+ */
+export declare function updatorToSql<T>(table: Table<T>, updater: Updater<T>): {
+    sql: string;
+    values: any[];
+};
 /**
  * 部分更新
  * @param connection
@@ -59,7 +82,7 @@ export interface UpdateOpts<T> {
     /**
      * 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
      */
-    orderBy?: Array<[keyof T, 'asc' | 'desc']>;
+    orderBy?: OrderBy<T>;
     /**
      * 更新设置
      */

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

@@ -0,0 +1,36 @@
+import { PoolConnection } from 'mysql2';
+import { MysqlConfig } from '../../config';
+import { Table } from '../../table-info';
+import { InsertValue } from './insert';
+import { Updater } from './update';
+/**
+ * Upsert 单条数据
+ * 如果主键冲突则更新，否则插入
+ * @param config
+ * @param connection
+ * @param table
+ * @param data
+ * @returns
+ */
+export declare function upsert<T>(config: MysqlConfig, connection: PoolConnection, table: Table<T>, data: InsertValue<T>): Promise<T>;
+/**
+ * Upsert 多条数据
+ * 如果主键冲突则更新，否则插入
+ * @param config
+ * @param connection
+ * @param table
+ * @param list
+ * @returns 影响的行数
+ */
+export declare function upsertMany<T>(config: MysqlConfig, connection: PoolConnection, table: Table<T>, list: InsertValue<T>[]): Promise<number>;
+/**
+ * Upsert 单条数据（支持自定义更新器）
+ * 如果主键冲突则按自定义逻辑更新，否则插入
+ * @param config
+ * @param connection
+ * @param table
+ * @param data 插入的数据
+ * @param updater 冲突时的更新器
+ * @returns
+ */
+export declare function upsertWithUpdater<T>(config: MysqlConfig, connection: PoolConnection, table: Table<T>, data: InsertValue<T>, updater: Updater<T>): Promise<T>;