befly 3.17.0 → 3.17.2

package/lib/dbHelper/index.js

@@ -0,0 +1,27 @@
+import { isNonEmptyString } from "../../utils/is.js";
+import { builderMethods } from "./builders.js";
+import { dataOpsMethods } from "./dataOps.js";
+import { executeMethods } from "./execute.js";
+import { transactionMethods } from "./transaction.js";
+import { convertBigIntFields } from "./context.js";
+
+function DbHelper(options) {
+    this.redis = options.redis;
+
+    if (!isNonEmptyString(options.dbName)) {
+        throw new Error("DbHelper 初始化失败：dbName 必须为非空字符串", {
+            cause: null,
+            code: "validation"
+        });
+    }
+    this.dbName = options.dbName;
+
+    this.sql = options.sql || null;
+    this.isTransaction = Boolean(options.sql);
+    this.idMode = options.idMode === "autoId" ? "autoId" : "timeId";
+}
+
+Object.assign(DbHelper.prototype, builderMethods, executeMethods, dataOpsMethods, transactionMethods);
+DbHelper.convertBigIntFields = convertBigIntFields;
+
+export { DbHelper };

package/lib/dbHelper/transaction.js

@@ -0,0 +1,43 @@
+import { hasBegin, isBeflyResponse, TransAbortError } from "./context.js";
+
+export const transactionMethods = {
+    async trans(callback) {
+        if (this.isTransaction) {
+            const innerResult = await callback(this);
+            if (isBeflyResponse(innerResult) && innerResult.code !== 0) {
+                throw new TransAbortError(innerResult);
+            }
+            return innerResult;
+        }
+
+        const sql = this.sql;
+        if (!sql) {
+            throw new Error("数据库连接未初始化", {
+                cause: null,
+                code: "runtime"
+            });
+        }
+        if (!hasBegin(sql)) {
+            throw new Error("当前 SQL 客户端不支持事务 begin() 方法", {
+                cause: null,
+                code: "runtime"
+            });
+        }
+
+        try {
+            return await sql.begin(async (tx) => {
+                const trans = new this.constructor({ redis: this.redis, dbName: this.dbName, sql: tx, idMode: this.idMode });
+                const result = await callback(trans);
+                if (isBeflyResponse(result) && result.code !== 0) {
+                    throw new TransAbortError(result);
+                }
+                return result;
+            });
+        } catch (error) {
+            if (error instanceof TransAbortError) {
+                return error.payload;
+            }
+            throw error;
+        }
+    }
+};

package/lib/dbHelper/util.js

@@ -0,0 +1,58 @@
+import { isNullable } from "../../utils/is.js";
+import { snakeCase } from "../../utils/util.js";
+import { parseTableRef } from "./validate.js";
+
+export function normalizeTableRef(tableRef) {
+    const parsed = parseTableRef(tableRef);
+    const schemaPart = parsed.schema ? snakeCase(parsed.schema) : null;
+    const tablePart = snakeCase(parsed.table);
+    const aliasPart = parsed.alias ? snakeCase(parsed.alias) : null;
+    let result = schemaPart ? `${schemaPart}.${tablePart}` : tablePart;
+    if (aliasPart) {
+        result = `${result} ${aliasPart}`;
+    }
+    return result;
+}
+
+export function getJoinMainQualifier(tableRef) {
+    const parsed = parseTableRef(tableRef);
+    if (parsed.alias) {
+        return snakeCase(parsed.alias);
+    }
+    return snakeCase(parsed.table);
+}
+
+export function toNumberFromSql(value) {
+    if (isNullable(value)) {
+        return 0;
+    }
+
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            return 0;
+        }
+        return value;
+    }
+
+    if (typeof value === "bigint") {
+        const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+        const minSafe = BigInt(Number.MIN_SAFE_INTEGER);
+        if (value <= maxSafe && value >= minSafe) {
+            return Number(value);
+        }
+        return 0;
+    }
+
+    if (typeof value === "string") {
+        if (!value.trim()) {
+            return 0;
+        }
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed)) {
+            return 0;
+        }
+        return parsed;
+    }
+
+    return 0;
+}

package/lib/dbHelper/validate.js

@@ -0,0 +1,549 @@
+import { isFiniteNumber, isNonEmptyString, isNullable, isPlainObject, isString } from "../../utils/is.js";
+import { snakeCase } from "../../utils/util.js";
+
+function assertNonEmptyString(value, label) {
+    if (!isNonEmptyString(value)) {
+        throw new Error(`${label} 必须是非空字符串`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function assertPlainObjectValue(value, label) {
+    if (!isPlainObject(value)) {
+        throw new Error(`${label} 必须是对象`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+export function validateWhereObject(where, label, required = false) {
+    if (isNullable(where)) {
+        if (required) {
+            throw new Error(`${label} 必须是对象`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+        return;
+    }
+
+    if (!isPlainObject(where)) {
+        throw new Error(`${label} 必须是对象`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function validateOrderByItems(orderBy, label) {
+    if (!Array.isArray(orderBy)) {
+        throw new Error(`${label} 必须是数组`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    for (const item of orderBy) {
+        if (!isString(item) || !item.includes("#")) {
+            throw new Error(`${label} 字段必须是 "字段#方向" 格式的字符串`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        const parts = item.split("#");
+        if (parts.length !== 2) {
+            throw new Error(`${label} 字段必须是 "字段#方向" 格式的字符串`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        const field = isString(parts[0]) ? parts[0].trim() : "";
+        const direction = isString(parts[1]) ? parts[1].trim().toUpperCase() : "";
+        if (!field) {
+            throw new Error(`${label} 中字段名不能为空`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+        if (direction !== "ASC" && direction !== "DESC") {
+            throw new Error(`${label} 方向必须是 ASC 或 DESC`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+    }
+}
+
+function validateJoins(joins, label) {
+    if (!Array.isArray(joins)) {
+        throw new Error(`${label} 必须是数组`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    for (let i = 0; i < joins.length; i++) {
+        const join = joins[i];
+        if (!isPlainObject(join)) {
+            throw new Error(`${label}[${i}] 必须是对象`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        assertNonEmptyString(join.table, `${label}[${i}].table`);
+        assertNonEmptyString(join.on, `${label}[${i}].on`);
+
+        if (!isNullable(join.type)) {
+            const type = isString(join.type) ? join.type.trim().toLowerCase() : "";
+            if (type !== "left" && type !== "right" && type !== "inner") {
+                throw new Error(`${label}[${i}].type 只允许 left/right/inner`, {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+        }
+    }
+}
+
+export function validateQueryOptions(options, label) {
+    if (!isPlainObject(options)) {
+        throw new Error(`${label} 必须是对象`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    assertNonEmptyString(options.table, `${label}.table`);
+
+    if (!isNullable(options.where)) {
+        validateWhereObject(options.where, `${label}.where`);
+    }
+
+    if (!isNullable(options.fields) && !Array.isArray(options.fields)) {
+        throw new Error(`${label}.fields 必须是数组`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    if (!isNullable(options.orderBy)) {
+        validateOrderByItems(options.orderBy, `${label}.orderBy`);
+    }
+
+    if (!isNullable(options.joins)) {
+        validateJoins(options.joins, `${label}.joins`);
+    }
+
+    if (!isNullable(options.page) && (!isFiniteNumber(options.page) || Math.floor(options.page) !== options.page)) {
+        throw new Error(`${label}.page 必须是整数`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    if (!isNullable(options.limit) && (!isFiniteNumber(options.limit) || Math.floor(options.limit) !== options.limit)) {
+        throw new Error(`${label}.limit 必须是整数`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+export function validateWriteData(data, label) {
+    assertPlainObjectValue(data, label);
+}
+
+export function validateBatchDataList(dataList, label) {
+    if (!Array.isArray(dataList)) {
+        throw new Error(`${label} 必须是数组`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    for (let i = 0; i < dataList.length; i++) {
+        if (!isPlainObject(dataList[i])) {
+            throw new Error(`${label}[${i}] 必须是对象`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+    }
+}
+
+export function validateTableName(table, label) {
+    assertNonEmptyString(table, label);
+}
+
+export function validateTableWhereOptions(options, label, required = false) {
+    validateTableName(options.table, `${label}.table`);
+    validateWhereObject(options.where, `${label}.where`, required);
+}
+
+export function validateTableDataOptions(options, label) {
+    validateTableName(options.table, `${label}.table`);
+    validateWriteData(options.data, `${label}.data`);
+}
+
+export function validateTableBatchDataOptions(table, dataList, label) {
+    validateTableName(table, `${label}.table`);
+    validateBatchDataList(dataList, `${label}.dataList`);
+}
+
+export function validateNoJoinReadOptions(options, label, joinErrorMessage) {
+    validateTableWhereOptions(options, label, false);
+    validateNoJoins(options.joins, joinErrorMessage);
+    validateSimpleTableName(options.table, label);
+}
+
+export function validateIncrementOptions(table, field, where, value, label) {
+    validateTableWhereOptions({ table: table, where: where }, label, true);
+    validateSafeFieldName(snakeCase(table));
+    validateSafeFieldName(snakeCase(field));
+    validateIncrementValue(table, field, value);
+}
+
+export function validateSimpleTableName(rawTable, label) {
+    const table = isString(rawTable) ? rawTable.trim() : "";
+    if (!table) {
+        throw new Error(`${label}.table 不能为空`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (table.includes(" ")) {
+        throw new Error(`${label} 不支持别名表写法（table: ${table}）`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (table.includes(".")) {
+        throw new Error(`${label} 不支持 schema.table 写法（table: ${table}）`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+export function validateSafeFieldName(field) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(field)) {
+        throw new Error(`无效的字段名: ${field}，只允许字母、数字和下划线`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+export function validatePageLimitRange(prepared, rawTable) {
+    if (prepared.page < 1 || prepared.page > 10000) {
+        throw new Error(`页码必须在 1 到 10000 之间 (table: ${rawTable}, page: ${prepared.page}, limit: ${prepared.limit})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (prepared.limit < 1 || prepared.limit > 1000) {
+        throw new Error(`每页数量必须在 1 到 1000 之间 (table: ${rawTable}, page: ${prepared.page}, limit: ${prepared.limit})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+export function validateNoJoins(joins, message) {
+    if (Array.isArray(joins) && joins.length > 0) {
+        throw new Error(message, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+export function validateIncrementValue(table, field, value) {
+    if (typeof value !== "number" || isNaN(value)) {
+        throw new Error(`自增值必须是有效的数字 (table: ${table}, field: ${field}, value: ${value})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+export function validateExecuteSql(sql) {
+    if (!isString(sql)) {
+        throw new Error(`execute 只接受字符串类型的 SQL，收到类型: ${typeof sql}，值: ${JSON.stringify(sql)}`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+export function validateExcludeFieldsResult(resultFields, table, excludeSnakeFields) {
+    if (resultFields.length === 0) {
+        throw new Error(`排除字段后没有剩余字段可查询。表: ${table}, 排除: ${excludeSnakeFields.join(", ")}`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+export function validateTimeIdValue(id) {
+    if (!Number.isFinite(id) || id <= 0) {
+        throw new Error(`buildInsertRow(timeId) 失败：id 必须为 > 0 的有限 number (id: ${String(id)})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+export function validateInsertBatchSize(count, maxBatchSize) {
+    if (count > maxBatchSize) {
+        throw new Error(`批量插入数量 ${count} 超过最大限制 ${maxBatchSize}`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+export function assertNoExprField(field) {
+    if (!isString(field)) {
+        return;
+    }
+    if (!isNonEmptyString(field)) {
+        return;
+    }
+    const trimmed = field.trim();
+    if (trimmed.includes("(") || trimmed.includes(")")) {
+        throw new Error(`字段包含函数/表达式，请使用 selectRaw/whereRaw (field: ${trimmed})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+export function assertNoUndefinedInRecord(row, label) {
+    for (const [key, value] of Object.entries(row)) {
+        if (value === undefined) {
+            throw new Error(`${label} 存在 undefined 字段值 (field: ${key})`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+    }
+}
+
+export function assertBatchInsertRowsConsistent(rows, options) {
+    if (!Array.isArray(rows)) {
+        throw new Error("批量插入 rows 必须是数组", {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (rows.length === 0) {
+        throw new Error(`插入数据不能为空 (table: ${options.table})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const first = rows[0];
+    if (!first || typeof first !== "object" || Array.isArray(first)) {
+        throw new Error(`批量插入的每一行必须是对象 (table: ${options.table}, rowIndex: 0)`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const fields = Object.keys(first);
+    if (fields.length === 0) {
+        throw new Error(`插入数据必须至少有一个字段 (table: ${options.table})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const fieldSet = new Set(fields);
+    for (let i = 0; i < rows.length; i++) {
+        const row = rows[i];
+        if (!row || typeof row !== "object" || Array.isArray(row)) {
+            throw new Error(`批量插入的每一行必须是对象 (table: ${options.table}, rowIndex: ${i})`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        const rowKeys = Object.keys(row);
+        if (rowKeys.length !== fields.length) {
+            throw new Error(`批量插入每行字段必须一致 (table: ${options.table}, rowIndex: ${i})`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        for (const key of rowKeys) {
+            if (!fieldSet.has(key)) {
+                throw new Error(`批量插入每行字段必须一致 (table: ${options.table}, rowIndex: ${i}, extraField: ${key})`, {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+        }
+
+        for (const field of fields) {
+            if (!(field in row)) {
+                throw new Error(`批量插入缺少字段 (table: ${options.table}, rowIndex: ${i}, field: ${field})`, {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+            if (row[field] === undefined) {
+                throw new Error(`批量插入字段值不能为 undefined (table: ${options.table}, rowIndex: ${i}, field: ${field})`, {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+        }
+    }
+
+    return fields;
+}
+
+export function parseTableRef(tableRef) {
+    if (!isString(tableRef)) {
+        throw new Error(`tableRef 必须是字符串 (tableRef: ${String(tableRef)})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const trimmed = tableRef.trim();
+    if (!isNonEmptyString(tableRef)) {
+        throw new Error("tableRef 不能为空", {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const parts = trimmed.split(/\s+/).filter((p) => p.length > 0);
+    if (parts.length === 0) {
+        throw new Error("tableRef 不能为空", {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (parts.length > 2) {
+        throw new Error(`不支持的表引用格式（包含过多片段）。请使用最简形式：table 或 table alias 或 schema.table 或 schema.table alias (tableRef: ${trimmed})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const namePart = parts[0];
+    if (!isNonEmptyString(namePart)) {
+        throw new Error(`tableRef 解析失败：缺少表名 (tableRef: ${trimmed})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    let aliasPart = null;
+    if (parts.length === 2) {
+        const alias = parts[1];
+        if (!isNonEmptyString(alias)) {
+            throw new Error(`tableRef 解析失败：缺少 alias (tableRef: ${trimmed})`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+        aliasPart = alias;
+    }
+
+    const nameSegments = namePart.split(".");
+    if (nameSegments.length > 2) {
+        throw new Error(`不支持的表引用格式（schema 层级过深） (tableRef: ${trimmed})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    if (nameSegments.length === 2) {
+        const schema = nameSegments[0];
+        const table = nameSegments[1];
+        if (!isNonEmptyString(schema)) {
+            throw new Error(`tableRef 解析失败：schema 为空 (tableRef: ${trimmed})`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+        if (!isNonEmptyString(table)) {
+            throw new Error(`tableRef 解析失败：table 为空 (tableRef: ${trimmed})`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+        return { schema: schema, table: table, alias: aliasPart };
+    }
+
+    const table = nameSegments[0];
+    if (!isNonEmptyString(table)) {
+        throw new Error(`tableRef 解析失败：table 为空 (tableRef: ${trimmed})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    return { schema: null, table: table, alias: aliasPart };
+}
+
+export function validateGeneratedBatchId(id, table, index) {
+    if (typeof id !== "number") {
+        throw new Error(`批量插入生成 ID 失败：ids[${index}] 不是 number (table: ${table})`, {
+            cause: null,
+            code: "runtime"
+        });
+    }
+}
+
+export function validateAndClassifyFields(fields) {
+    if (!fields || fields.length === 0) {
+        return { type: "all", fields: [] };
+    }
+
+    if (fields.some((f) => f === "*")) {
+        throw new Error("fields 不支持 * 星号，请使用空数组 [] 或不传参数表示查询所有字段", {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    if (fields.some((f) => !isNonEmptyString(f))) {
+        throw new Error("fields 不能包含空字符串或无效值", {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    for (const rawField of fields) {
+        const checkField = rawField.startsWith("!") ? rawField.substring(1) : rawField;
+        assertNoExprField(checkField);
+    }
+
+    const includeFields = fields.filter((f) => !f.startsWith("!"));
+    const excludeFields = fields.filter((f) => f.startsWith("!"));
+
+    if (includeFields.length > 0 && excludeFields.length === 0) {
+        return { type: "include", fields: includeFields };
+    }
+    if (excludeFields.length > 0 && includeFields.length === 0) {
+        return { type: "exclude", fields: excludeFields.map((f) => f.substring(1)) };
+    }
+
+    throw new Error('fields 不能同时包含普通字段和排除字段（! 开头）。只能使用以下3种方式之一：\n1. 空数组 [] 或不传（查询所有）\n2. 全部指定字段 ["id", "name"]\n3. 全部排除字段 ["!password", "!token"]', {
+        cause: null,
+        code: "validation"
+    });
+}