wok-server 0.6.0 → 0.7.0

package/src/mysql/manager/ops/insert.ts

@@ -5,6 +5,37 @@ import { promiseQuery } from '../utils'
 import { MysqlConfig } from '../../config'
 import { processColumnValue } from './utils'
 
+/**
+ * 插入值类型，支持在 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 function processInsertValue(value: any): { frag: string; values: any[] } {
+  if (Array.isArray(value)) {
+    if (value[0] === 'now') {
+      return { frag: 'NOW()', values: [] }
+    }
+    if (value[0] === 'set') {
+      return { frag: '?', values: [processColumnValue(value[1])] }
+    }
+    if (value[0] === 'expr') {
+      return { frag: value[1], values: value[2] || [] }
+    }
+  }
+  return { frag: '?', values: [processColumnValue(value)] }
+}
+
 /**
  * 为表插入数据
  * @param connection
@@ -16,9 +47,8 @@ export async function insert<T>(
   config: MysqlConfig,
   connection: PoolConnection,
   table: Table<T>,
-  data: T
+  data: InsertValue<T>
 ): Promise<T> {
-  // 插入后的新数据
   // 列信息，使用 set 防止 columns 中重复配置 id 和更新创建时间列
   let columnsSet: Set<keyof T> = new Set()
   // 判定下 id ，如果有值，才在 insert 语句中出现 id 列，否则不出现
@@ -37,15 +67,16 @@ export async function insert<T>(
     columnsSet.add(table.updatedDate.column)
   }
   const columns = Array.from(columnsSet)
-  // 构建 sql
-  const sql = `insert into ??(${columns.map(() => '??').join(',')}) values(${columns
-    .map(() => '?')
-    .join(',')})`
-  const values: any[] = [
-    table.tableName,
-    ...columns,
-    ...columns.map(col => processColumnValue(data[col]))
-  ]
+  // 构建 sql，逐列处理以支持表达式
+  const fragList: string[] = []
+  const insertValues: any[] = []
+  for (const col of columns) {
+    const { frag, values: vs } = processInsertValue(data[col])
+    fragList.push(frag)
+    insertValues.push(...vs)
+  }
+  const sql = `insert into ??(${columns.map(() => '??').join(',')}) values(${fragList.join(',')})`
+  const values: any[] = [table.tableName, ...columns, ...insertValues]
   const res = await promiseQuery(config, connection, sql, values)
   const packet = res as ResultSetHeader
   if (packet.affectedRows !== 1) {
@@ -57,7 +88,7 @@ export async function insert<T>(
   if (packet.insertId && (data[table.id] === undefined || data[table.id] === null)) {
     data[table.id] = packet.insertId as any
   }
-  return data
+  return data as unknown as T
 }
 /**
  * 一次插入多条记录
@@ -69,7 +100,7 @@ export async function insertMany<T>(
   config: MysqlConfig,
   connection: PoolConnection,
   table: Table<T>,
-  list: T[]
+  list: InsertValue<T>[]
 ): Promise<void> {
   if (!list.length) {
     return
@@ -99,14 +130,21 @@ export async function insertMany<T>(
     if (idx > 0) {
       sql += ','
     }
-    sql += `(${columns.map(() => '?').join(',')})`
+    const fragList: string[] = []
+    const rowValues: any[] = []
     if (table.createdDate) {
       data[table.createdDate.column] = createdData as any
     }
     if (table.updatedDate) {
       data[table.updatedDate.column] = updatedDate as any
     }
-    values.push(...columns.map(col => processColumnValue(data[col])))
+    for (const col of columns) {
+      const { frag, values: vs } = processInsertValue(data[col])
+      fragList.push(frag)
+      rowValues.push(...vs)
+    }
+    sql += `(${fragList.join(',')})`
+    values.push(...rowValues)
   })
 
   const res = await promiseQuery(config, connection, sql, values)

package/src/mysql/manager/ops/order-by.ts

@@ -0,0 +1,58 @@
+/**
+ * 排序规则类型.
+ *
+ * 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 function buildOrderBy<T>(orderBy: OrderBy<T>): { sql: string; values: any[] } {
+  const fragments: string[] = []
+  const values: any[] = []
+
+  orderBy.forEach((item, idx) => {
+    const prefix = idx === 0 ? ' order by ' : ' , '
+
+    if (item.length === 4 && item[0] === 'expr') {
+      const [, exprSql, exprValues, sort] = item as ['expr', string, any[], 'asc' | 'desc']
+      fragments.push(`${prefix}${exprSql} ${sort}`)
+      values.push(...exprValues)
+    } else {
+      const [field, sort] = item as [keyof T, 'asc' | 'desc']
+      fragments.push(`${prefix}?? ${sort}`)
+      values.push(field)
+    }
+  })
+
+  return { sql: fragments.join(''), values }
+}

package/src/mysql/manager/ops/paginate.ts

@@ -2,8 +2,9 @@ import { PoolConnection } from 'mysql2'
 import { Table } from '../../table-info'
 import { count } from './count'
 import { MixCriteria } from './criteria'
-import { find } from './find'
+import { find, findSelect } from './find'
 import { MysqlConfig } from '../../config'
+import { OrderBy } from './order-by'
 
 export interface MysqlPaginateOpts<T> {
   /**
@@ -27,7 +28,7 @@ export interface MysqlPaginateOpts<T> {
   /**
    * 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
    */
-  orderBy?: Array<[keyof T, 'asc' | 'desc']>
+  orderBy?: OrderBy<T>
 }
 /**
  * mysql 分页查询结果
@@ -58,3 +59,42 @@ export async function paginate<T>(
     list
   }
 }
+
+/**
+ * 指定字段分页查询选项
+ */
+export interface MysqlPaginateSelectOpts<T, K extends keyof T> extends MysqlPaginateOpts<T> {
+  /**
+   * 要查询的字段
+   */
+  select: K[]
+}
+
+/**
+ * 指定字段分页查询
+ * @param config
+ * @param conn
+ * @param opts
+ */
+export async function paginateSelect<T, K extends keyof T>(
+  config: MysqlConfig,
+  conn: PoolConnection,
+  opts: MysqlPaginateSelectOpts<T, K>
+): Promise<MysqlPage<Pick<T, K>>> {
+  const pn = opts.pn && opts.pn >= 1 ? opts.pn : 1
+  const limit = opts.pz && opts.pz >= 1 && opts.pz <= 1000 ? opts.pz : 20
+  const offset = (pn - 1) * limit
+  const list = await findSelect(config, conn, {
+    table: opts.table,
+    criteria: opts.criteria,
+    offset,
+    limit,
+    orderBy: opts.orderBy,
+    select: opts.select
+  })
+  const total = await count(config, conn, opts.table, opts.criteria)
+  return {
+    total,
+    list
+  }
+}

package/src/mysql/manager/ops/update.ts

@@ -5,6 +5,7 @@ import { MixCriteria, buildQuery } from './criteria'
 import { promiseQuery } from '../utils'
 import { MysqlConfig } from '../../config'
 import { processColumnValue } from './utils'
+import { OrderBy, buildOrderBy } from './order-by'
 
 /**
  * 更新
@@ -63,57 +64,77 @@ export type Updater<T> = Partial<{
     | undefined
     // 将字段置空，置空是不能使用 null 类型的，必须使用元组 ['setNull']
     | ['setNull']
-    // 将字段自增
+    // 字段自增 +1，等价于 ['inc', 1]
+    | ['inc']
+    // 字段自增指定值
     | ['inc', number]
+    // NOW() 快捷方式，等价于 ['expr', 'NOW()', []]
+    | ['now']
     /**
      * 设置一个字段的值，和直接赋值是一样的，作用是解决一些特殊的情况的冲突
      * 比如将 json 字段的值设置为 ['setNull'] ,这就会被认为是要置空，
      * 使用 ['set',['setNull']] 就可以解决这个问题
      */
     | ['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
  */
-function updatorToSql<T>(table: Table<T>, updater: Updater<T>): { sql: string; values: any[] } {
+export function updatorToSql<T>(table: Table<T>, updater: Updater<T>): { sql: string; values: any[] } {
   const values: any[] = []
-  // 更新操作
   const updateFragList: string[] = []
-  // 更新时间
-  if (table.updatedDate) {
-    const updatedDate = table.updatedDate.type === 'date' ? new Date() : new Date().getTime()
-    updateFragList.push(' ?? = ?')
-    values.push(table.updatedDate.column, updatedDate)
-  }
+
   for (const column in updater) {
-    // 过滤掉id
+    // 过滤掉 id
     if (column === table.id) {
       continue
     }
+    // 过滤掉 createdDate / updatedDate（自动处理）
+    if ((table.createdDate && column === table.createdDate.column)
+      || (table.updatedDate && column === table.updatedDate.column)) {
+      continue
+    }
     const val = updater[column]
-    // undefined 表示不参与更新，作用是方便编写一些特殊的逻辑，比如特定情况下不更新
+    // undefined 表示不参与更新
     if (val === undefined) {
       continue
     }
-    // 兼容将值设置成 null 的情况，和 ['setNull’] 等同
+    // 0.7.0 版本开始，null 和 undefined 一样被忽略更新
+    // 如需设置字段为 NULL，请使用 ['setNull']
     if (val === null) {
-      updateFragList.push(' ?? = NULL ')
-      values.push(column)
       continue
     }
     if (Array.isArray(val)) {
-      // set null
       if (val[0] === 'setNull') {
         updateFragList.push(' ?? = NULL ')
         values.push(column)
         continue
       }
       if (val[0] === 'inc') {
+        const incBy = val.length === 1 ? 1 : val[1]
         updateFragList.push(' ?? = ?? + ? ')
-        values.push(column, column, val[1])
+        values.push(column, column, incBy)
+        continue
+      }
+      if (val[0] === 'now') {
+        updateFragList.push(' ?? = NOW() ')
+        values.push(column)
         continue
       }
       if (val[0] === 'set') {
@@ -121,10 +142,35 @@ function updatorToSql<T>(table: Table<T>, updater: Updater<T>): { sql: string; v
         values.push(column, processColumnValue(val[1]))
         continue
       }
+      if (val[0] === 'concat') {
+        updateFragList.push(' ?? = CONCAT(IFNULL(??, \'\'), ?) ')
+        values.push(column, column, val[1])
+        continue
+      }
+      if (val[0] === 'expr') {
+        updateFragList.push(' ?? = ' + val[1] + ' ')
+        values.push(column, ...(val[2] || []))
+        continue
+      }
     }
     updateFragList.push(' ?? = ? ')
     values.push(column, processColumnValue(val))
   }
+
+  // 如果没有有效更新字段，抛出异常
+  if (updateFragList.length === 0) {
+    throw new MysqlException(
+      `No effective fields to update (null values are ignored since v0.7.0), table: ${table.tableName}, updater: ${JSON.stringify(updater)}`
+    )
+  }
+
+  // 自动添加更新时间
+  if (table.updatedDate) {
+    const updatedDate = table.updatedDate.type === 'date' ? new Date() : new Date().getTime()
+    updateFragList.push(' ?? = ?')
+    values.push(table.updatedDate.column, updatedDate)
+  }
+
   return { sql: updateFragList.join(','), values }
 }
 
@@ -152,13 +198,6 @@ export async function partialUpdate<T>(
   if (typeof id !== 'string' && typeof id !== 'number') {
     throw new MysqlException('Primary key can only be of string or number type')
   }
-  if (Object.keys(data).length < 2) {
-    throw new MysqlException(
-      `Can't do a partial update, data must contain at least one column outside of the primary key，table: ${
-        table.tableName
-      }，column：${JSON.stringify(data)}`
-    )
-  }
   const fieldNames = Object.keys(data)
   for (const name of fieldNames) {
     if (name !== table.id && !table.columns.some(col => col === name)) {
@@ -171,9 +210,6 @@ export async function partialUpdate<T>(
   const values: any[] = [table.tableName]
   // 更新操作
   const convertRes = updatorToSql(table, data)
-  if (!convertRes.sql) {
-    throw new MysqlException('No fields were specified to be updated!')
-  }
   values.push(...convertRes.values)
   sql += ` set ${convertRes.sql} where ?? = ?`
   values.push(table.id, id)
@@ -206,9 +242,6 @@ export async function updateOne<T>(
   values.push(table.tableName)
   // 更新操作
   const convertRes = updatorToSql(table, updater)
-  if (!convertRes.sql) {
-    throw new MysqlException('No fields were specified to be updated!')
-  }
   sql += ` set ${convertRes.sql} `
   values.push(...convertRes.values)
   sql += ` where ${mysqlQuery.sql} limit 1`
@@ -236,7 +269,7 @@ export interface UpdateOpts<T> {
   /**
    * 排序规则，按先后顺序放入，每个规则是一个元组，第一个元素是字段名称，第二个元素是顺序
    */
-  orderBy?: Array<[keyof T, 'asc' | 'desc']>
+  orderBy?: OrderBy<T>
   /**
    * 更新设置
    */
@@ -265,24 +298,15 @@ export async function updateMany<T>(
   values.push(opts.table.tableName)
   // 更新操作
   const convertRes = updatorToSql(opts.table, opts.updater)
-  if (!convertRes.sql) {
-    throw new MysqlException('No fields were specified to be updated!')
-  }
   sql += ` set ${convertRes.sql} `
   values.push(...convertRes.values)
   sql += ` where ${mysqlQuery.sql} `
   values.push(...mysqlQuery.values)
   // 排序
   if (opts.orderBy && opts.orderBy.length) {
-    opts.orderBy.forEach((orderBy, idx) => {
-      const [field, sort] = orderBy
-      if (idx == 0) {
-        sql += ` order by ?? ${sort} `
-      } else {
-        sql += ` , ?? ${sort} `
-      }
-      values.push(field)
-    })
+    const ob = buildOrderBy(opts.orderBy)
+    sql += ob.sql
+    values.push(...ob.values)
   }
   // 数量限制
   if (opts.limit) {

package/src/mysql/manager/ops/upsert.ts

@@ -0,0 +1,224 @@
+import { PoolConnection, ResultSetHeader } from 'mysql2'
+import { MysqlConfig } from '../../config'
+import { Table } from '../../table-info'
+import { promiseQuery } from '../utils'
+import { InsertValue, processInsertValue } from './insert'
+import { Updater, updatorToSql } from './update'
+
+/**
+ * Upsert 单条数据
+ * 如果主键冲突则更新，否则插入
+ * @param config
+ * @param connection
+ * @param table
+ * @param data
+ * @returns
+ */
+export async function upsert<T>(
+  config: MysqlConfig,
+  connection: PoolConnection,
+  table: Table<T>,
+  data: InsertValue<T>
+): Promise<T> {
+  let columnsSet: Set<keyof T> = new Set()
+  if (data[table.id]) {
+    columnsSet.add(table.id)
+  }
+  table.columns.forEach(col => columnsSet.add(col))
+  
+  const now = new Date()
+  const nowTimestamp = now.getTime()
+  
+  if (table.createdDate) {
+    const createdData = table.createdDate.type === 'date' ? now : nowTimestamp
+    data[table.createdDate.column] = createdData as any
+    columnsSet.add(table.createdDate.column)
+  }
+  if (table.updatedDate) {
+    const updatedDate = table.updatedDate.type === 'date' ? now : nowTimestamp
+    data[table.updatedDate.column] = updatedDate as any
+    columnsSet.add(table.updatedDate.column)
+  }
+  
+  const columns = Array.from(columnsSet)
+  
+  // 构建 insert values
+  const fragList: string[] = []
+  const insertValues: any[] = []
+  for (const col of columns) {
+    const { frag, values: vs } = processInsertValue(data[col])
+    fragList.push(frag)
+    insertValues.push(...vs)
+  }
+  const insertSql = `insert into ??(${columns.map(() => '??').join(',')}) values(${fragList.join(',')})`
+  
+  // 构建 on duplicate key update（排除 id）
+  const updateColumns = columns.filter(col => col !== table.id)
+  const updateFragments: string[] = []
+  const updateValues: any[] = []
+  for (const col of updateColumns) {
+    const { frag, values: vs } = processInsertValue(data[col])
+    updateFragments.push(`?? = ${frag}`)
+    updateValues.push(col, ...vs)
+  }
+  const updateSql = ` on duplicate key update ${updateFragments.join(',')}`
+  
+  const sql = insertSql + updateSql
+  
+  const values = [table.tableName, ...columns, ...insertValues, ...updateValues]
+  
+  const res = await promiseQuery(config, connection, sql, values)
+  const packet = res as ResultSetHeader
+  
+  if (packet.insertId && (data[table.id] === undefined || data[table.id] === null)) {
+    data[table.id] = packet.insertId as any
+  }
+  
+  return data as unknown as T
+}
+
+/**
+ * Upsert 多条数据
+ * 如果主键冲突则更新，否则插入
+ * @param config
+ * @param connection
+ * @param table
+ * @param list
+ * @returns 影响的行数
+ */
+export async function upsertMany<T>(
+  config: MysqlConfig,
+  connection: PoolConnection,
+  table: Table<T>,
+  list: InsertValue<T>[]
+): Promise<number> {
+  if (!list.length) {
+    return 0
+  }
+  
+  let columnsSet: Set<keyof T> = new Set()
+  if (list[0][table.id]) {
+    columnsSet.add(table.id)
+  }
+  table.columns.forEach(col => columnsSet.add(col))
+  
+  const now = new Date()
+  const nowTimestamp = now.getTime()
+  
+  let createdData: Date | number | undefined = undefined
+  if (table.createdDate) {
+    createdData = table.createdDate.type === 'date' ? now : nowTimestamp
+    columnsSet.add(table.createdDate.column)
+  }
+  let updatedDate: Date | number | undefined = undefined
+  if (table.updatedDate) {
+    updatedDate = table.updatedDate.type === 'date' ? now : nowTimestamp
+    columnsSet.add(table.updatedDate.column)
+  }
+  
+  const columns = Array.from(columnsSet)
+  
+  let sql = `insert into ??(${columns.map(() => '??').join(',')}) values`
+  const values: any[] = [table.tableName, ...columns]
+  
+  list.forEach((data, idx) => {
+    if (idx > 0) {
+      sql += ','
+    }
+    const fragList: string[] = []
+    const rowValues: any[] = []
+    if (table.createdDate) {
+      data[table.createdDate.column] = createdData as any
+    }
+    if (table.updatedDate) {
+      data[table.updatedDate.column] = updatedDate as any
+    }
+    for (const col of columns) {
+      const { frag, values: vs } = processInsertValue(data[col])
+      fragList.push(frag)
+      rowValues.push(...vs)
+    }
+    sql += `(${fragList.join(',')})`
+    values.push(...rowValues)
+  })
+  
+  const updateColumns = columns.filter(col => col !== table.id)
+  sql += ` on duplicate key update ${updateColumns.map(() => '?? = values(??)').join(',')}`
+  updateColumns.forEach(col => values.push(col, col))
+  
+  const res = await promiseQuery(config, connection, sql, values)
+  const packet = res as ResultSetHeader
+  
+  return packet.affectedRows
+}
+
+/**
+ * Upsert 单条数据（支持自定义更新器）
+ * 如果主键冲突则按自定义逻辑更新，否则插入
+ * @param config
+ * @param connection
+ * @param table
+ * @param data 插入的数据
+ * @param updater 冲突时的更新器
+ * @returns
+ */
+export async function upsertWithUpdater<T>(
+  config: MysqlConfig,
+  connection: PoolConnection,
+  table: Table<T>,
+  data: InsertValue<T>,
+  updater: Updater<T>
+): Promise<T> {
+  let columnsSet: Set<keyof T> = new Set()
+  if (data[table.id]) {
+    columnsSet.add(table.id)
+  }
+  table.columns.forEach(col => {
+    if (data[col] !== undefined) {
+      columnsSet.add(col)
+    }
+  })
+  
+  const now = new Date()
+  const nowTimestamp = now.getTime()
+  
+  if (table.createdDate) {
+    const createdData = table.createdDate.type === 'date' ? now : nowTimestamp
+    data[table.createdDate.column] = createdData as any
+    columnsSet.add(table.createdDate.column)
+  }
+  if (table.updatedDate) {
+    const updatedDate = table.updatedDate.type === 'date' ? now : nowTimestamp
+    data[table.updatedDate.column] = updatedDate as any
+    columnsSet.add(table.updatedDate.column)
+  }
+  
+  const columns = Array.from(columnsSet)
+  
+  // 构建 insert values
+  const fragList: string[] = []
+  const insertValues: any[] = []
+  for (const col of columns) {
+    const { frag, values: vs } = processInsertValue(data[col])
+    fragList.push(frag)
+    insertValues.push(...vs)
+  }
+  const insertSql = `insert into ??(${columns.map(() => '??').join(',')}) values(${fragList.join(',')})`
+  
+  const convertRes = updatorToSql(table, updater)
+  
+  const updateSql = ` on duplicate key update ${convertRes.sql}`
+  
+  const sql = insertSql + updateSql
+  
+  const values = [table.tableName, ...columns, ...insertValues, ...convertRes.values]
+  
+  const res = await promiseQuery(config, connection, sql, values)
+  const packet = res as ResultSetHeader
+  
+  if (packet.insertId && (data[table.id] === undefined || data[table.id] === null)) {
+    data[table.id] = packet.insertId as any
+  }
+  
+  return data as unknown as T
+}

package/src/mysql/manager/ops/utils.ts

@@ -3,6 +3,10 @@
  * @param value
  */
 export function processColumnValue(value: any) {
+  // undefined/null 返回 null，mysql2 会正确处理为 SQL NULL
+  if (value === undefined || value === null) {
+    return null
+  }
   // date 类型 typeof 也是 object ，先排除
   if (value instanceof Date) {
     return value

package/types/mysql/config.d.ts

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