befly 3.16.9 → 3.16.11

package/dist/lib/dbHelper.d.ts

@@ -1,229 +0,0 @@
-/**
- * 数据库助手 - TypeScript 版本
- * 提供数据库 CRUD 操作的封装
- */
-import type { WhereConditions, SqlValue } from "../types/common";
-import type { QueryOptions, InsertOptions, UpdateOptions, DeleteOptions, DbPageResult, DbListResult, TransactionCallback, DbResult, ListSql } from "../types/database";
-type RedisCacheLike = {
-    getObject<T = unknown>(key: string): Promise<T | null>;
-    setObject<T = unknown>(key: string, obj: T, ttl?: number | null): Promise<string | null>;
-    genTimeID(): Promise<number>;
-};
-type SqlClientLike = {
-    unsafe<TResult = unknown>(sqlStr: string, params?: SqlValue[]): Promise<TResult>;
-};
-type DbIdMode = "timeId" | "autoId";
-/**
- * 数据库助手类
- */
-export declare class DbHelper {
-    private redis;
-    private dbName;
-    private sql;
-    private isTransaction;
-    private idMode;
-    static convertBigIntFields<T extends Record<string, unknown> = Record<string, unknown>>(arr: T[], fields?: readonly string[]): T[];
-    static convertBigIntFields<T>(arr: T, fields?: readonly string[]): T;
-    /**
-     * 构造函数
-     * @param redis - Redis 实例
-     * @param sql - Bun SQL 客户端（可选，用于事务）
-     */
-    constructor(options: {
-        redis: RedisCacheLike;
-        dbName: string;
-        sql?: SqlClientLike | null;
-        idMode?: DbIdMode;
-    });
-    private createSqlBuilder;
-    private getTableColumns;
-    private prepareQueryOptions;
-    /**
-     * 为 builder 添加 JOIN
-     */
-    private applyJoins;
-    private executeSelect;
-    private executeRun;
-    private executeWithConn;
-    /**
-     * 执行原生 SQL（内部工具/同步脚本专用）
-     *
-     * - 复用当前 DbHelper 持有的连接/事务
-     * - 统一走 executeWithConn，保持参数校验与错误行为一致
-     */
-    unsafe<TResult = unknown>(sqlStr: string, params?: unknown[]): Promise<DbResult<TResult>>;
-    /**
-     * 检查表是否存在
-     * @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 - 多表联查选项
-     * @returns DbResult<TItem>
-     *
-     * 语义说明（重要）：
-     * - 本方法不再用 `null` 表示“未命中”。
-     * - 当查询未命中（或数据反序列化失败）时，`data` 将返回空对象 `{}`。
-     * - 因此业务侧应通过关键字段判断是否存在（例如 `if (!res.data?.id) { ... }`）。
-     * @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<TItem extends Record<string, unknown> = Record<string, unknown>>(options: QueryOptions): Promise<DbResult<TItem>>;
-    /**
-     * 语义化别名：getDetail（与 getOne 一致）
-     *
-     * 说明：Befly 早期业务侧习惯用 getDetail 表达“查详情”；这里不引入新的查询逻辑，直接复用 getOne。
-     *
-     * 语义说明：与 getOne 完全一致，未命中时 `data` 返回 `{}`。
-     */
-    getDetail<TItem extends Record<string, unknown> = Record<string, unknown>>(options: QueryOptions): Promise<DbResult<TItem>>;
-    /**
-     * 查询列表（带分页）
-     * @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<TItem extends Record<string, unknown> = Record<string, unknown>>(options: QueryOptions): Promise<DbResult<DbPageResult<TItem>, 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<TItem extends Record<string, unknown> = Record<string, unknown>>(options: Omit<QueryOptions, "page" | "limit">): Promise<DbResult<DbListResult<TItem>, ListSql>>;
-    /**
-     * 插入数据（自动生成 ID、时间戳、state）
-     * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
-     */
-    insData<TInsert extends Record<string, SqlValue> = Record<string, SqlValue>>(options: Omit<InsertOptions, "data"> & {
-        data: TInsert;
-    }): Promise<DbResult<number>>;
-    /**
-     * 批量插入数据（真正的批量操作）
-     * 使用 INSERT INTO ... VALUES (...), (...), (...) 语法
-     * 自动生成系统字段并包装在事务中
-     * @param table - 表名（支持小驼峰或下划线格式，会自动转换）
-     */
-    insBatch<TInsert extends Record<string, SqlValue> = Record<string, SqlValue>>(table: string, dataList: TInsert[]): Promise<DbResult<number[]>>;
-    delForceBatch(table: string, ids: number[]): Promise<DbResult<number>>;
-    updBatch(table: string, dataList: Array<{
-        id: number;
-        data: Record<string, unknown>;
-    }>): 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<TResult = unknown>(callback: TransactionCallback<TResult, DbHelper>): Promise<TResult>;
-    /**
-     * 执行原始 SQL
-     */
-    query<TResult = unknown>(sql: string, params?: unknown[]): Promise<DbResult<TResult>>;
-    /**
-     * 检查数据是否存在（优化性能）
-     * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
-     */
-    exists(options: Omit<QueryOptions, "fields" | "orderBy" | "page" | "limit">): Promise<DbResult<boolean>>;
-    /**
-     * 查询单个字段值（带字段名验证）
-     * @param field - 字段名（支持小驼峰或下划线格式）
-     */
-    getFieldValue<TValue = unknown>(options: Omit<QueryOptions, "fields"> & {
-        field: string;
-    }): Promise<DbResult<TValue | 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 {};