befly 3.21.1 → 3.22.0

package/lib/dbUtil.js

@@ -1,72 +1,6 @@
 import { isFiniteNumber, isNonEmptyString, isNullable, isString } from "../utils/is.js";
 import { snakeCase } from "../utils/util.js";
 
-export const SAFE_IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
-
-export function assertNoUndefinedParam(value, label) {
-    if (value === undefined) {
-        throw new Error(`${label} 不能为 undefined`, {
-            cause: null,
-            code: "validation"
-        });
-    }
-}
-
-export function assertSafeIdentifierPart(part, kind) {
-    if (!SAFE_IDENTIFIER_RE.test(part)) {
-        throw new Error(`无效的 ${kind} 标识符: ${part}`, {
-            cause: null,
-            code: "validation"
-        });
-    }
-}
-
-export function validateQuoteIdentifierInput(identifier) {
-    if (!isString(identifier)) {
-        throw new Error(`quoteIdent 需要字符串类型标识符 (identifier: ${String(identifier)})`, {
-            cause: null,
-            code: "validation"
-        });
-    }
-
-    const trimmed = identifier.trim();
-    if (!trimmed) {
-        throw new Error("SQL 标识符不能为空", {
-            cause: null,
-            code: "validation"
-        });
-    }
-
-    return trimmed;
-}
-
-export function validateLimitValue(count) {
-    if (typeof count !== "number" || count < 0) {
-        throw new Error(`LIMIT 数量必须是非负数 (count: ${String(count)})`, {
-            cause: null,
-            code: "validation"
-        });
-    }
-}
-
-export function validateOffsetValue(offset, label = "OFFSET") {
-    if (typeof offset !== "number" || offset < 0) {
-        throw new Error(`${label} 必须是非负数 (offset: ${String(offset)})`, {
-            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 assertNoExprField(field) {
     if (!isString(field)) {
         return;
@@ -84,93 +18,6 @@ export function assertNoExprField(field) {
     }
 }
 
-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)})`, {
@@ -180,7 +27,7 @@ export function parseTableRef(tableRef) {
     }
 
     const trimmed = tableRef.trim();
-    if (!isNonEmptyString(tableRef)) {
+    if (!trimmed) {
         throw new Error("tableRef 不能为空", {
             cause: null,
             code: "validation"
@@ -188,12 +35,6 @@ export function parseTableRef(tableRef) {
     }
 
     const parts = trimmed.split(/\s+/).filter((part) => part.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,
@@ -258,76 +99,6 @@ export function parseTableRef(tableRef) {
     return { schema: null, table: table, alias: aliasPart };
 }
 
-export function validateAndClassifyFields(fields) {
-    if (!fields || fields.length === 0) {
-        return { type: "all", fields: [] };
-    }
-
-    if (fields.some((field) => field === "*")) {
-        throw new Error("fields 不支持 * 星号，请使用空数组 [] 或不传参数表示查询所有字段", {
-            cause: null,
-            code: "validation"
-        });
-    }
-
-    if (fields.some((field) => !isNonEmptyString(field))) {
-        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((field) => !field.startsWith("!"));
-    const excludeFields = fields.filter((field) => field.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((field) => field.substring(1)) };
-    }
-
-    throw new Error('fields 不能同时包含普通字段和排除字段（! 开头）。只能使用以下3种方式之一：\n1. 空数组 [] 或不传（查询所有）\n2. 全部指定字段 ["id", "name"]\n3. 全部排除字段 ["!password", "!token"]', {
-        cause: null,
-        code: "validation"
-    });
-}
-
-export function validateExplicitReadFields(fields) {
-    const classified = validateAndClassifyFields(fields);
-    if (classified.type === "all") {
-        throw new Error("查询必须显式传 fields，不支持空 fields 或查询全部字段", {
-            cause: null,
-            code: "validation"
-        });
-    }
-
-    return classified;
-}
-
-export function validateExplicitLeftJoinFields(fields) {
-    const classified = validateAndClassifyFields(fields);
-    if (classified.type === "all") {
-        throw new Error("leftJoin 查询必须显式传 fields，不支持空 fields 或查询全部字段", {
-            cause: null,
-            code: "validation"
-        });
-    }
-    if (classified.type === "exclude") {
-        throw new Error("leftJoin 查询不支持排除字段，必须显式指定主表/从表字段", {
-            cause: null,
-            code: "validation"
-        });
-    }
-
-    return classified;
-}
-
 function isQuotedIdentPaired(value) {
     const trimmed = value.trim();
     if (trimmed.length < 2) {
@@ -344,52 +115,53 @@ function startsWithIdentifierQuote(value) {
     return trimmed.startsWith("`") || trimmed.startsWith('"');
 }
 
-function assertPairedQuotedIdent(value, label) {
-    if (startsWithIdentifierQuote(value) && !isQuotedIdentPaired(value)) {
-        throw new Error(`${label} 引用不完整，请使用成对的 \`...\` 或 "..." (value: ${value})`, {
-            cause: null,
-            code: "validation"
-        });
+export function resolveQuoteIdent(options) {
+    if (options && options.quoteIdent) {
+        return options.quoteIdent;
     }
+
+    return (identifier) => {
+        const trimmed = isString(identifier) ? identifier.trim() : String(identifier).trim();
+        const escaped = trimmed.replace(/`/g, "``");
+        return `\`${escaped}\``;
+    };
 }
 
-function escapeIdentifierPart(part, kind, quoteIdent, unpairedErrorFactory) {
-    if (isQuotedIdent(part)) {
-        return part;
+export function parseFieldAliasParts(field) {
+    if (!isString(field)) {
+        return null;
+    }
+
+    const trimmed = field.trim();
+    if (!trimmed) {
+        return null;
     }
 
-    if (startsWithQuote(part)) {
-        throw new Error(unpairedErrorFactory(part), {
+    if (/\s+AS\s+/i.test(trimmed)) {
+        throw new Error(`字段别名不支持 AS，请使用单个空格分隔字段与别名 (field: ${trimmed})`, {
             cause: null,
             code: "validation"
         });
     }
 
-    assertSafeIdentifierPart(part, kind);
-    return quoteIdent(part);
-}
-
-export function resolveQuoteIdent(options) {
-    if (options && options.quoteIdent) {
-        return options.quoteIdent;
+    if (!/\s/.test(trimmed)) {
+        return null;
     }
 
-    return (identifier) => {
-        const trimmed = validateQuoteIdentifierInput(identifier);
+    if (!/^[^\s]+ [^\s]+$/.test(trimmed)) {
+        throw new Error(`字段别名必须使用单个空格分隔字段与别名 (field: ${trimmed})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
 
-        const escaped = trimmed.replace(/`/g, "``");
-        return `\`${escaped}\``;
+    const parts = trimmed.split(" ");
+    return {
+        fieldPart: parts[0],
+        aliasPart: parts[1]
     };
 }
 
-export function isQuotedIdent(value) {
-    return isQuotedIdentPaired(value);
-}
-
-export function startsWithQuote(value) {
-    return startsWithIdentifierQuote(value);
-}
-
 export function escapeField(field, quoteIdent) {
     if (!isString(field)) {
         return field;
@@ -397,43 +169,25 @@ export function escapeField(field, quoteIdent) {
 
     const trimmed = field.trim();
 
-    assertPairedQuotedIdent(trimmed, "字段标识符");
+    if (!trimmed) {
+        return trimmed;
+    }
 
-    if (trimmed === "*" || isQuotedIdent(trimmed)) {
+    if (trimmed === "*" || isQuotedIdentPaired(trimmed)) {
         return trimmed;
     }
 
-    try {
-        assertNoExprField(trimmed);
-    } catch {
-        throw new Error(`字段包含函数/表达式，请使用 selectRaw/whereRaw (field: ${trimmed})`, {
-            cause: null,
-            code: "validation"
-        });
+    if (startsWithIdentifierQuote(trimmed) && !isQuotedIdentPaired(trimmed) && !trimmed.includes(".")) {
+        return trimmed;
     }
 
-    if (trimmed.toUpperCase().includes(" AS ")) {
-        const parts = trimmed.split(/\s+AS\s+/i);
-        if (parts.length !== 2) {
-            throw new Error(`字段格式非法，请使用简单字段名或安全引用，复杂表达式请使用 selectRaw/whereRaw (field: ${trimmed})`, {
-                cause: null,
-                code: "validation"
-            });
-        }
+    if (trimmed.includes("(") || trimmed.includes(")") || /\s+AS\s+/i.test(trimmed)) {
+        return trimmed;
+    }
 
-        const fieldPart = parts[0];
-        const aliasPart = parts[1];
-        const cleanFieldPart = fieldPart.trim();
-        const cleanAliasPart = aliasPart.trim();
-        if (!isQuotedIdent(cleanAliasPart)) {
-            if (!SAFE_IDENTIFIER_RE.test(cleanAliasPart)) {
-                throw new Error(`无效的字段别名: ${cleanAliasPart}`, {
-                    cause: null,
-                    code: "validation"
-                });
-            }
-        }
-        return `${escapeField(cleanFieldPart, quoteIdent)} AS ${cleanAliasPart}`;
+    const aliasMatch = trimmed.match(/^([^\s]+)\s+([^\s]+)$/);
+    if (aliasMatch) {
+        return `${escapeField(aliasMatch[1].trim(), quoteIdent)} ${aliasMatch[2].trim()}`;
     }
 
     if (trimmed.includes(".")) {
@@ -441,10 +195,12 @@ export function escapeField(field, quoteIdent) {
         return parts
             .map((part) => {
                 const cleanPart = part.trim();
-                if (cleanPart === "*" || isQuotedIdent(cleanPart)) {
+                if (!cleanPart) {
+                    return cleanPart;
+                }
+                if (cleanPart === "*" || isQuotedIdentPaired(cleanPart) || startsWithIdentifierQuote(cleanPart)) {
                     return cleanPart;
                 }
-                assertPairedQuotedIdent(cleanPart, "字段标识符");
                 return quoteIdent(cleanPart);
             })
             .join(".");
@@ -460,129 +216,51 @@ export function escapeTable(table, quoteIdent) {
 
     const trimmed = table.trim();
 
-    if (isQuotedIdent(trimmed)) {
+    if (!trimmed) {
         return trimmed;
     }
 
-    const parts = trimmed.split(/\s+/).filter((p) => p.length > 0);
-    if (parts.length === 0) {
-        throw new Error("FROM 表名不能为空", {
-            cause: null,
-            code: "validation"
-        });
+    if (isQuotedIdentPaired(trimmed)) {
+        return trimmed;
     }
 
+    if (startsWithIdentifierQuote(trimmed) && !isQuotedIdentPaired(trimmed) && !trimmed.includes(".")) {
+        return trimmed;
+    }
+
+    const parts = trimmed.split(/\s+/).filter((p) => p.length > 0);
     if (parts.length > 2) {
-        throw new Error(`不支持的表引用格式（包含过多片段）。请使用 fromRaw 显式传入复杂表达式 (table: ${trimmed})`, {
-            cause: null,
-            code: "validation"
-        });
+        return trimmed;
     }
 
     const namePart = parts[0].trim();
 
-    const aliasPart = parts.length === 2 ? parts[1].trim() : null;
-
-    const nameSegments = namePart.split(".");
-    if (nameSegments.length > 2) {
-        throw new Error(`不支持的表引用格式（schema 层级过深）。请使用 fromRaw (table: ${trimmed})`, {
-            cause: null,
-            code: "validation"
-        });
+    if (namePart.split(".").some((part) => startsWithIdentifierQuote(part.trim()) && !isQuotedIdentPaired(part.trim()))) {
+        return trimmed;
     }
 
-    let escapedName = "";
-    if (nameSegments.length === 2) {
-        const schemaRaw = nameSegments[0];
-        const tableNameRaw = nameSegments[1];
-        const schema = schemaRaw.trim();
-        const tableName = tableNameRaw.trim();
-
-        const escapedSchema = escapeIdentifierPart(schema, "schema", quoteIdent, (part) => `schema 标识符引用不完整，请使用成对的 \`...\` 或 "..." (schema: ${part})`);
-        const escapedTableName = escapeIdentifierPart(tableName, "table", quoteIdent, (part) => `table 标识符引用不完整，请使用成对的 \`...\` 或 "..." (table: ${part})`);
-
-        escapedName = `${escapedSchema}.${escapedTableName}`;
-    } else {
-        const tableNameRaw = nameSegments[0];
-        const tableName = tableNameRaw.trim();
+    const aliasPart = parts.length === 2 ? parts[1].trim() : null;
 
-        escapedName = escapeIdentifierPart(tableName, "table", quoteIdent, (part) => `table 标识符引用不完整，请使用成对的 \`...\` 或 "..." (table: ${part})`);
-    }
+    const nameSegments = namePart.split(".");
+    const escapedName = nameSegments
+        .map((part) => {
+            const cleanPart = part.trim();
+            if (!cleanPart) {
+                return cleanPart;
+            }
+            if (isQuotedIdentPaired(cleanPart) || startsWithIdentifierQuote(cleanPart)) {
+                return cleanPart;
+            }
+            return quoteIdent(cleanPart);
+        })
+        .join(".");
 
     if (aliasPart) {
-        assertSafeIdentifierPart(aliasPart, "alias");
         return `${escapedName} ${aliasPart}`;
     }
 
     return escapedName;
 }
-
-export function validateParam(value) {
-    assertNoUndefinedParam(value, "SQL 参数值");
-}
-
-export function normalizeLimitValue(count, offset) {
-    validateLimitValue(count);
-    const limitValue = Math.floor(count);
-
-    let offsetValue = null;
-    if (!isNullable(offset)) {
-        validateOffsetValue(offset);
-        offsetValue = Math.floor(offset);
-    }
-
-    return { limitValue: limitValue, offsetValue: offsetValue };
-}
-
-export function normalizeOffsetValue(count) {
-    validateOffsetValue(count, "OFFSET");
-    return Math.floor(count);
-}
-
-export function toSqlParams(params) {
-    if (isNullable(params)) {
-        return [];
-    }
-
-    if (!Array.isArray(params)) {
-        throw new Error(`SQL 参数必须是数组，当前类型: ${typeof params}`, {
-            cause: null,
-            code: "validation"
-        });
-    }
-
-    const out = [];
-    for (const value of params) {
-        if (value === undefined) {
-            throw new Error("SQL 参数不能为 undefined", {
-                cause: null,
-                code: "validation"
-            });
-        }
-
-        if (typeof value === "bigint") {
-            out.push(value.toString());
-            continue;
-        }
-
-        out.push(value);
-    }
-
-    return out;
-}
-
-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;
-}
-
 function shouldExcludeFieldValue(field, value, excludeValueMap) {
     if (!excludeValueMap || excludeValueMap.size === 0) {
         return false;
@@ -724,13 +402,18 @@ export async function fieldsToSnake(table, classified, getTableColumns) {
         const allColumns = await getTableColumns(table);
         const excludeSnakeFields = classified.fields.map((field) => snakeCase(field));
         const resultFields = allColumns.filter((column) => !excludeSnakeFields.includes(column));
-        validateExcludeFieldsResult(resultFields, table, excludeSnakeFields);
+        if (resultFields.length === 0) {
+            throw new Error(`排除字段后没有剩余字段可查询。表: ${table}, 排除: ${excludeSnakeFields.join(", ")}`, {
+                cause: null,
+                code: "validation"
+            });
+        }
         return resultFields;
     }
     return ["*"];
 }
 
-function normalizeQualifierField(field) {
+export function normalizeQualifierField(field) {
     const parts = field.split(".");
     if (parts.length === 1) {
         return snakeCase(field);
@@ -805,14 +488,9 @@ export function processJoinField(field) {
         return field;
     }
 
-    if (field.toUpperCase().includes(" AS ")) {
-        const parts = field.split(/\s+AS\s+/i);
-        const fieldPart = parts[0];
-        const aliasPart = parts[1];
-        if (!isString(fieldPart) || !isString(aliasPart)) {
-            return field;
-        }
-        return `${processJoinField(fieldPart.trim())} AS ${aliasPart.trim()}`;
+    const aliasParts = parseFieldAliasParts(field);
+    if (aliasParts) {
+        return `${processJoinField(aliasParts.fieldPart.trim())} ${aliasParts.aliasPart.trim()}`;
     }
 
     return normalizeQualifierField(field);
@@ -896,39 +574,6 @@ export function processJoinOn(on) {
     return result;
 }
 
-export function parseLeftJoinItem(joinTable, joinItem) {
-    const parts = joinItem.split(" ");
-    return {
-        type: "left",
-        table: normalizeTableRef(joinTable),
-        on: processJoinOn(`${parts[0]} = ${parts[1]}`)
-    };
-}
-
-export function addDefaultStateFilter(where = {}, table, hasLeftJoin = false, beflyMode = "auto") {
-    if (beflyMode === "manual") {
-        return where;
-    }
-
-    const hasStateCondition = Object.keys(where).some((key) => key.startsWith("state") || key.includes(".state"));
-    if (hasStateCondition) {
-        return where;
-    }
-
-    const result = {};
-    for (const [key, value] of Object.entries(where)) {
-        result[key] = value;
-    }
-
-    if (hasLeftJoin && table) {
-        result[`${table}.state$gt`] = 0;
-        return result;
-    }
-
-    result.state$gt = 0;
-    return result;
-}
-
 export function whereKeysToSnake(where) {
     return mapWhereKeys(where, (key) => {
         assertNoExprField(key);