befly 3.10.18 → 3.11.1

package/{lib/dbDialect.ts → dist/lib/dbDialect.js}

@@ -1,45 +1,26 @@
-export type DbDialectName = "mysql" | "postgresql" | "sqlite";
-
-let DIALECT_CACHE: Map<DbDialectName, DbDialect> | null = null;
-
+let DIALECT_CACHE = null;
 /**
  * 获取方言实例（内部缓存，避免到处 new）。
  *
  * 约束：dialect 实例应当是纯逻辑对象（无连接/无 IO/无状态副作用），可全局复用。
  */
-export function getDialectByName(name: DbDialectName): DbDialect {
+export function getDialectByName(name) {
     const unknownDialectError = new Error(`未知数据库方言: ${String(name)}`);
     if (name !== "mysql" && name !== "postgresql" && name !== "sqlite") {
         throw unknownDialectError;
     }
-
     if (!DIALECT_CACHE) {
-        DIALECT_CACHE = new Map<DbDialectName, DbDialect>();
+        DIALECT_CACHE = new Map();
         DIALECT_CACHE.set("mysql", new MySqlDialect());
         DIALECT_CACHE.set("postgresql", new PostgresDialect());
         DIALECT_CACHE.set("sqlite", new SqliteDialect());
     }
-
     const dialect = DIALECT_CACHE.get(name);
     if (!dialect) {
         throw unknownDialectError;
     }
-
     return dialect;
 }
-
-export type SqlTextQuery = {
-    sql: string;
-    params: unknown[];
-};
-
-export type SyncTableColumnsInfoQuery = {
-    columns: SqlTextQuery;
-    comments?: SqlTextQuery;
-};
-
-export type SyncTableIndexesQuery = SqlTextQuery;
-
 /**
  * syncTable 专用：获取“列元信息”查询。
  *
@@ -47,35 +28,30 @@ export type SyncTableIndexesQuery = SqlTextQuery;
  * - 这里仅负责 SQL + 参数构造（方言差异）；
  * - 解析为 ColumnInfo 的逻辑仍放在 syncTable.ts（保持同步算法聚合）。
  */
-export function getSyncTableColumnsInfoQuery(options: { dialect: DbDialectName; table: string; dbName: string; schema?: string }): SyncTableColumnsInfoQuery {
+export function getSyncTableColumnsInfoQuery(options) {
     if (options.dialect === "mysql") {
-        const columns: SqlTextQuery = {
+        const columns = {
             sql: "SELECT COLUMN_NAME, DATA_TYPE, CHARACTER_MAXIMUM_LENGTH, IS_NULLABLE, COLUMN_DEFAULT, COLUMN_COMMENT, COLUMN_TYPE FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? ORDER BY ORDINAL_POSITION",
             params: [options.dbName, options.table]
         };
         return { columns: columns };
     }
-
     if (options.dialect === "postgresql") {
         const schema = options.schema && options.schema.trim() !== "" ? options.schema : "public";
-        const columns: SqlTextQuery = {
+        const columns = {
             sql: "SELECT column_name, data_type, character_maximum_length, is_nullable, column_default FROM information_schema.columns WHERE table_schema = ? AND table_name = ? ORDER BY ordinal_position",
             params: [schema, options.table]
         };
-
-        const comments: SqlTextQuery = {
+        const comments = {
             sql: "SELECT a.attname AS column_name, col_description(c.oid, a.attnum) AS column_comment FROM pg_class c JOIN pg_attribute a ON a.attrelid = c.oid JOIN pg_namespace n ON n.oid = c.relnamespace WHERE c.relkind = 'r' AND n.nspname = ? AND c.relname = ? AND a.attnum > 0",
             params: [schema, options.table]
         };
-
         return { columns: columns, comments: comments };
     }
-
     const sqlite = getDialectByName("sqlite");
     const columns = sqlite.getTableColumnsQuery(options.table);
     return { columns: columns };
 }
-
 /**
  * syncTable 专用：获取“索引元信息”查询（只负责 SQL + 参数构造）。
  *
@@ -83,14 +59,13 @@ export function getSyncTableColumnsInfoQuery(options: { dialect: DbDialectName;
  * - 仅下沉 MySQL / PostgreSQL；SQLite 仍走 PRAGMA（需要多次查询）。
  * - 解析（比如 PG indexdef 解析列名）仍留在 syncTable.ts。
  */
-export function getSyncTableIndexesQuery(options: { dialect: DbDialectName; table: string; dbName: string; schema?: string }): SyncTableIndexesQuery {
+export function getSyncTableIndexesQuery(options) {
     if (options.dialect === "mysql") {
         return {
             sql: "SELECT INDEX_NAME, COLUMN_NAME FROM information_schema.STATISTICS WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? AND INDEX_NAME != 'PRIMARY' ORDER BY INDEX_NAME",
             params: [options.dbName, options.table]
         };
     }
-
     if (options.dialect === "postgresql") {
         const schema = options.schema && options.schema.trim() !== "" ? options.schema : "public";
         return {
@@ -98,76 +73,39 @@ export function getSyncTableIndexesQuery(options: { dialect: DbDialectName; tabl
             params: [schema, options.table]
         };
     }
-
     throw new Error(`getSyncTableIndexesQuery 不支持方言: ${String(options.dialect)}`);
 }
-
-export interface DbDialect {
-    name: DbDialectName;
-
-    /**
-     * 转义/引用 SQL 标识符（表名/字段名）。
-     * 注意：仅用于单个标识符片段，不支持包含空格、点号、函数等复杂表达式。
-     */
-    quoteIdent(identifier: string): string;
-
-    /**
-     * 获取表字段列表的查询。
-     * 约定：返回结果应能通过 getTableColumnsFromResult 提取列名。
-     */
-    getTableColumnsQuery(table: string, schema?: string): SqlTextQuery;
-
-    /** 从 getTableColumnsQuery 的结果中提取列名数组 */
-    getTableColumnsFromResult(result: any): string[];
-
-    /** 检查表是否存在的查询 */
-    tableExistsQuery(table: string, schema?: string): SqlTextQuery;
-
-    /**
-     * 是否支持 schema.table 形式（仅用于校验；具体 quoting 仍由 SqlBuilder 处理）。
-     */
-    supportsSchema: boolean;
-}
-
-export class MySqlDialect implements DbDialect {
-    name: DbDialectName = "mysql";
-    supportsSchema: boolean = true;
-
-    quoteIdent(identifier: string): string {
+export class MySqlDialect {
+    name = "mysql";
+    supportsSchema = true;
+    quoteIdent(identifier) {
         if (typeof identifier !== "string") {
             throw new Error(`quoteIdent 需要字符串类型标识符 (identifier: ${String(identifier)})`);
         }
-
         const trimmed = identifier.trim();
         if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(trimmed)) {
             throw new Error(`无效的 SQL 标识符: ${trimmed}`);
         }
-
         return `\`${trimmed}\``;
     }
-
-    getTableColumnsQuery(table: string, _schema?: string): SqlTextQuery {
+    getTableColumnsQuery(table, _schema) {
         const quotedTable = this.quoteIdent(table);
         return { sql: `SHOW COLUMNS FROM ${quotedTable}`, params: [] };
     }
-
-    getTableColumnsFromResult(result: any): string[] {
+    getTableColumnsFromResult(result) {
         if (!Array.isArray(result)) {
             return [];
         }
-
-        const columnNames: string[] = [];
+        const columnNames = [];
         for (const row of result) {
             const name = row?.Field;
             if (typeof name === "string" && name.length > 0) {
                 columnNames.push(name);
             }
         }
-
         return columnNames;
     }
-
-    tableExistsQuery(table: string, schema?: string): SqlTextQuery {
+    tableExistsQuery(table, schema) {
         if (typeof schema === "string" && schema.trim() !== "") {
             return {
                 sql: "SELECT COUNT(*) as count FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?",
@@ -177,26 +115,21 @@ export class MySqlDialect implements DbDialect {
         return { sql: "SELECT COUNT(*) as count FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?", params: [table] };
     }
 }
-
-export class PostgresDialect implements DbDialect {
-    name: DbDialectName = "postgresql";
-    supportsSchema: boolean = true;
-
-    quoteIdent(identifier: string): string {
+export class PostgresDialect {
+    name = "postgresql";
+    supportsSchema = true;
+    quoteIdent(identifier) {
         if (typeof identifier !== "string") {
             throw new Error(`quoteIdent 需要字符串类型标识符 (identifier: ${String(identifier)})`);
         }
-
         const trimmed = identifier.trim();
         if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(trimmed)) {
             throw new Error(`无效的 SQL 标识符: ${trimmed}`);
         }
-
         // PostgreSQL 使用双引号引用标识符
         return `"${trimmed}"`;
     }
-
-    getTableColumnsQuery(table: string, schema?: string): SqlTextQuery {
+    getTableColumnsQuery(table, schema) {
         if (typeof schema === "string" && schema.trim() !== "") {
             return {
                 sql: "SELECT column_name FROM information_schema.columns WHERE table_schema = ? AND table_name = ? ORDER BY ordinal_position",
@@ -205,24 +138,20 @@ export class PostgresDialect implements DbDialect {
         }
         return { sql: "SELECT column_name FROM information_schema.columns WHERE table_schema = current_schema() AND table_name = ? ORDER BY ordinal_position", params: [table] };
     }
-
-    getTableColumnsFromResult(result: any): string[] {
+    getTableColumnsFromResult(result) {
         if (!Array.isArray(result)) {
             return [];
         }
-
-        const columnNames: string[] = [];
+        const columnNames = [];
         for (const row of result) {
             const name = row?.column_name;
             if (typeof name === "string" && name.length > 0) {
                 columnNames.push(name);
             }
         }
-
         return columnNames;
     }
-
-    tableExistsQuery(table: string, schema?: string): SqlTextQuery {
+    tableExistsQuery(table, schema) {
         if (typeof schema === "string" && schema.trim() !== "") {
             return {
                 sql: "SELECT COUNT(*)::int as count FROM information_schema.tables WHERE table_schema = ? AND table_name = ?",
@@ -232,51 +161,42 @@ export class PostgresDialect implements DbDialect {
         return { sql: "SELECT COUNT(*)::int as count FROM information_schema.tables WHERE table_schema = current_schema() AND table_name = ?", params: [table] };
     }
 }
-
-export class SqliteDialect implements DbDialect {
-    name: DbDialectName = "sqlite";
+export class SqliteDialect {
+    name = "sqlite";
     // SQLite 的“schema”语义与 MySQL/PG 不同：常规使用下没有独立 schema；
     // 虽然存在 main/temp/attached db 的 database_name.table_name 形式，但这里
     // 统一视为不支持传统 schema.table 校验语义。
-    supportsSchema: boolean = false;
-
-    quoteIdent(identifier: string): string {
+    supportsSchema = false;
+    quoteIdent(identifier) {
         if (typeof identifier !== "string") {
             throw new Error(`quoteIdent 需要字符串类型标识符 (identifier: ${String(identifier)})`);
         }
-
         const trimmed = identifier.trim();
         if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(trimmed)) {
             throw new Error(`无效的 SQL 标识符: ${trimmed}`);
         }
-
         // SQLite 也支持双引号引用标识符
         return `"${trimmed}"`;
     }
-
-    getTableColumnsQuery(table: string, _schema?: string): SqlTextQuery {
+    getTableColumnsQuery(table, _schema) {
         // PRAGMA 不支持参数占位符；此处通过 quoteIdent 限制输入并安全拼接
         const quotedTable = this.quoteIdent(table);
         return { sql: `PRAGMA table_info(${quotedTable})`, params: [] };
     }
-
-    getTableColumnsFromResult(result: any): string[] {
+    getTableColumnsFromResult(result) {
         if (!Array.isArray(result)) {
             return [];
         }
-
-        const columnNames: string[] = [];
+        const columnNames = [];
         for (const row of result) {
             const name = row?.name;
             if (typeof name === "string" && name.length > 0) {
                 columnNames.push(name);
             }
         }
-
         return columnNames;
     }
-
-    tableExistsQuery(table: string, _schema?: string): SqlTextQuery {
+    tableExistsQuery(table, _schema) {
         return {
             sql: "SELECT COUNT(*) as count FROM sqlite_master WHERE type = 'table' AND name = ?",
             params: [table]

package/dist/lib/dbHelper.d.ts

@@ -0,0 +1,204 @@
+/**
+ * 数据库助手 - TypeScript 版本
+ * 提供数据库 CRUD 操作的封装
+ */
+import type { WhereConditions } from "../types/common";
+import type { QueryOptions, InsertOptions, UpdateOptions, DeleteOptions, ListResult, AllResult, TransactionCallback, DbResult, ListSql } from "../types/database";
+import type { DbDialect } from "./dbDialect";
+type RedisCacheLike = {
+    getObject<T = any>(key: string): Promise<T | null>;
+    setObject<T = any>(key: string, obj: T, ttl?: number | null): Promise<string | null>;
+    genTimeID(): Promise<number>;
+};
+/**
+ * 数据库助手类
+ */
+export declare class DbHelper {
+    private redis;
+    private dialect;
+    private sql;
+    private isTransaction;
+    /**
+     * 构造函数
+     * @param redis - Redis 实例
+     * @param sql - Bun SQL 客户端（可选，用于事务）
+     */
+    constructor(options: {
+        redis: RedisCacheLike;
+        sql?: any | null;
+        dialect?: DbDialect;
+    });
+    private createSqlBuilder;
+    private getTableColumns;
+    private prepareQueryOptions;
+    /**
+     * 为 builder 添加 JOIN
+     */
+    private applyJoins;
+    private executeWithConn;
+    /**
+     * 执行原生 SQL（内部工具/同步脚本专用）
+     *
+     * - 复用当前 DbHelper 持有的连接/事务
+     * - 统一走 executeWithConn，保持参数校验与错误行为一致
+     */
+    unsafe(sqlStr: string, params?: any[]): Promise<DbResult<any>>;
+    /**
+     * 检查表是否存在
+     * @param tableName - 表名（支持小驼峰，会自动转换为下划线）
+     * @returns 表是否存在
+     */
+    tableExists(tableName: string): Promise<DbResult<boolean>>;
+    /**
+     * 查询记录数
+     * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
+     * @param options.where - 查询条件
+     * @param options.joins - 多表联查选项
+     * @example
+     * // 查询总数
+     * const count = await db.getCount({ table: 'user' });
+     * // 查询指定条件的记录数
+     * const activeCount = await db.getCount({ table: 'user', where: { state: 1 } });
+     * // 联查计数
+     * const count = await db.getCount({
+     *     table: 'order o',
+     *     joins: [{ table: 'user u', on: 'o.user_id = u.id' }],
+     *     where: { 'o.state': 1 }
+     * });
+     */
+    getCount(options: Omit<QueryOptions, "fields" | "page" | "limit" | "orderBy">): Promise<DbResult<number>>;
+    /**
+     * 查询单条数据
+     * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换；联查时可带别名如 'order o'）
+     * @param options.fields - 字段列表（联查时需带表别名，如 'o.id', 'u.username'）
+     * @param options.joins - 多表联查选项
+     * @example
+     * // 单表查询
+     * getOne({ table: 'userProfile', fields: ['userId', 'userName'] })
+     * // 联查
+     * getOne({
+     *     table: 'order o',
+     *     joins: [{ table: 'user u', on: 'o.user_id = u.id' }],
+     *     fields: ['o.id', 'o.totalAmount', 'u.username'],
+     *     where: { 'o.id': 1 }
+     * })
+     */
+    getOne<T extends Record<string, any> = Record<string, any>>(options: QueryOptions): Promise<DbResult<T | null>>;
+    /**
+     * 查询列表（带分页）
+     * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换；联查时可带别名）
+     * @param options.fields - 字段列表（联查时需带表别名）
+     * @param options.joins - 多表联查选项
+     * @example
+     * // 单表分页
+     * getList({ table: 'userProfile', fields: ['userId', 'userName', 'createdAt'] })
+     * // 联查分页
+     * getList({
+     *     table: 'order o',
+     *     joins: [
+     *         { table: 'user u', on: 'o.user_id = u.id' },
+     *         { table: 'product p', on: 'o.product_id = p.id' }
+     *     ],
+     *     fields: ['o.id', 'o.totalAmount', 'u.username', 'p.name AS productName'],
+     *     where: { 'o.status': 'paid' },
+     *     orderBy: ['o.createdAt#DESC'],
+     *     page: 1,
+     *     limit: 10
+     * })
+     */
+    getList<T extends Record<string, any> = Record<string, any>>(options: QueryOptions): Promise<DbResult<ListResult<T>, ListSql>>;
+    /**
+     * 查询所有数据（不分页，有上限保护）
+     * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换；联查时可带别名）
+     * @param options.fields - 字段列表（联查时需带表别名）
+     * @param options.joins - 多表联查选项
+     * ⚠️ 警告：此方法会查询大量数据，建议使用 getList 分页查询
+     * @example
+     * // 单表查询
+     * getAll({ table: 'userProfile', fields: ['userId', 'userName'] })
+     * // 联查
+     * getAll({
+     *     table: 'order o',
+     *     joins: [{ table: 'user u', on: 'o.user_id = u.id' }],
+     *     fields: ['o.id', 'u.username'],
+     *     where: { 'o.state': 1 }
+     * })
+     */
+    getAll<T extends Record<string, any> = Record<string, any>>(options: Omit<QueryOptions, "page" | "limit">): Promise<DbResult<AllResult<T>, ListSql>>;
+    /**
+     * 插入数据（自动生成 ID、时间戳、state）
+     * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
+     */
+    insData(options: InsertOptions): Promise<DbResult<number>>;
+    /**
+     * 批量插入数据（真正的批量操作）
+     * 使用 INSERT INTO ... VALUES (...), (...), (...) 语法
+     * 自动生成系统字段并包装在事务中
+     * @param table - 表名（支持小驼峰或下划线格式，会自动转换）
+     */
+    insBatch(table: string, dataList: Record<string, any>[]): Promise<DbResult<number[]>>;
+    delForceBatch(table: string, ids: number[]): Promise<DbResult<number>>;
+    updBatch(table: string, dataList: Array<{
+        id: number;
+        data: Record<string, any>;
+    }>): Promise<DbResult<number>>;
+    /**
+     * 更新数据（强制更新时间戳，系统字段不可修改）
+     * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
+     */
+    updData(options: UpdateOptions): Promise<DbResult<number>>;
+    /**
+     * 软删除数据（deleted_at 设置为当前时间，state 设置为 0）
+     * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
+     */
+    delData(options: DeleteOptions): Promise<DbResult<number>>;
+    /**
+     * 硬删除数据（物理删除，不可恢复）
+     * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
+     */
+    delForce(options: Omit<DeleteOptions, "hard">): Promise<DbResult<number>>;
+    /**
+     * 禁用数据（设置 state=2）
+     * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
+     */
+    disableData(options: Omit<DeleteOptions, "hard">): Promise<DbResult<number>>;
+    /**
+     * 启用数据（设置 state=1）
+     * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
+     */
+    enableData(options: Omit<DeleteOptions, "hard">): Promise<DbResult<number>>;
+    /**
+     * 执行事务
+     * 使用 Bun SQL 的 begin 方法开启事务
+     */
+    trans<T = any>(callback: TransactionCallback<T>): Promise<T>;
+    /**
+     * 执行原始 SQL
+     */
+    query(sql: string, params?: any[]): Promise<DbResult<any>>;
+    /**
+     * 检查数据是否存在（优化性能）
+     * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
+     */
+    exists(options: Omit<QueryOptions, "fields" | "orderBy" | "page" | "limit">): Promise<DbResult<boolean>>;
+    /**
+     * 查询单个字段值（带字段名验证）
+     * @param field - 字段名（支持小驼峰或下划线格式）
+     */
+    getFieldValue<T = any>(options: Omit<QueryOptions, "fields"> & {
+        field: string;
+    }): Promise<DbResult<T | null>>;
+    /**
+     * 自增字段（安全实现，防止 SQL 注入）
+     * @param table - 表名（支持小驼峰或下划线格式，会自动转换）
+     * @param field - 字段名（支持小驼峰或下划线格式，会自动转换）
+     */
+    increment(table: string, field: string, where: WhereConditions, value?: number): Promise<DbResult<number>>;
+    /**
+     * 自减字段
+     * @param table - 表名（支持小驼峰或下划线格式，会自动转换）
+     * @param field - 字段名（支持小驼峰或下划线格式，会自动转换）
+     */
+    decrement(table: string, field: string, where: WhereConditions, value?: number): Promise<DbResult<number>>;
+}
+export {};