befly 3.74.2 → 3.75.0

package/lib/dbParse.js

@@ -1,41 +1,30 @@
+import { validationError } from "../utils/error.js";
 import { isNonEmptyString, isNullable, isPlainObject, isString } from "../utils/is.js";
 import { snakeCase } from "../utils/util.js";
 import { assertNoExprField, clearDeep, fieldsToSnake, normalizeQualifierField, orderByToSnake, parseFieldAliasParts, parseFlatWhereKey, parseTableRef, processJoinField, processJoinOn, processJoinOrderBy, processJoinWhere, whereKeysToSnake } from "./dbUtil.js";
 
 function assertNonEmptyString(value, label) {
     if (!isNonEmptyString(value)) {
-        throw new Error(`${label} 必须是非空字符串`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label} 必须是非空字符串`);
     }
 }
 
 function assertPlainObjectValue(value, label) {
     if (!isPlainObject(value)) {
-        throw new Error(`${label} 必须是对象`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label} 必须是对象`);
     }
 }
 
 function validateWhereObject(where, label, required = false) {
     if (isNullable(where)) {
         if (required) {
-            throw new Error(`${label} 必须是对象`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`${label} 必须是对象`);
         }
         return;
     }
 
     if (!isPlainObject(where)) {
-        throw new Error(`${label} 必须是对象`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label} 必须是对象`);
     }
 
     for (const [key, value] of Object.entries(where)) {
@@ -45,97 +34,64 @@ function validateWhereObject(where, label, required = false) {
             }
 
             if (!isPlainObject(value)) {
-                throw new Error(`${label}.$exclude 必须是对象`, {
-                    cause: null,
-                    code: "validation"
-                });
+                throw validationError(`${label}.$exclude 必须是对象`);
             }
 
             for (const [excludeKey, excludeValue] of Object.entries(value)) {
                 assertNonEmptyString(excludeKey, `${label}.$exclude 的字段名`);
                 if (!Array.isArray(excludeValue)) {
-                    throw new Error(`${label}.$exclude.${excludeKey} 必须是数组`, {
-                        cause: null,
-                        code: "validation"
-                    });
+                    throw validationError(`${label}.$exclude.${excludeKey} 必须是数组`);
                 }
             }
             continue;
         }
 
         if (key === "$or" || key === "$and") {
-            throw new Error(`${label} 不再支持 ${key} 嵌套，请改用 field$op$or 扁平写法`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`${label} 不再支持 ${key} 嵌套，请改用 field$op$or 扁平写法`);
         }
 
         parseFlatWhereKey(key);
 
         if (isPlainObject(value)) {
-            throw new Error(`${label}.${key} 不再支持嵌套对象操作符，请改用 field$op 扁平写法`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`${label}.${key} 不再支持嵌套对象操作符，请改用 field$op 扁平写法`);
         }
     }
 }
 
 function validateOrderByItems(orderBy, label) {
     if (!Array.isArray(orderBy)) {
-        throw new Error(`${label} 必须是数组`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label} 必须是数组`);
     }
 
     for (const item of orderBy) {
         if (!isString(item) || !item.includes("#")) {
-            throw new Error(`${label} 字段必须是 "字段#方向" 格式的字符串`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`${label} 字段必须是 "字段#方向" 格式的字符串`);
         }
 
         const parts = item.split("#");
         if (parts.length !== 2) {
-            throw new Error(`${label} 字段必须是 "字段#方向" 格式的字符串`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`${label} 字段必须是 "字段#方向" 格式的字符串`);
         }
 
         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"
-            });
+            throw validationError(`${label} 中字段名不能为空`);
         }
         if (direction !== "ASC" && direction !== "DESC") {
-            throw new Error(`${label} 方向必须是 ASC 或 DESC`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`${label} 方向必须是 ASC 或 DESC`);
         }
     }
 }
 
 function assertJoinFieldRef(value, label) {
     if (!isNonEmptyString(value)) {
-        throw new Error(`${label} 不能为空`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label} 不能为空`);
     }
 
     const parts = value.split(".").map((item) => item.trim());
     if (parts.length !== 2 || !isNonEmptyString(parts[0]) || !isNonEmptyString(parts[1])) {
-        throw new Error(`${label} 必须是 alias.field 格式`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label} 必须是 alias.field 格式`);
     }
 }
 
@@ -157,27 +113,18 @@ function parseLeftJoinEquality(joinItem) {
 
 function validateLeftJoinItems(leftJoin, label) {
     if (!Array.isArray(leftJoin)) {
-        throw new Error(`${label} 必须是数组`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label} 必须是数组`);
     }
 
     for (let i = 0; i < leftJoin.length; i++) {
         const joinItem = leftJoin[i];
         if (!isNonEmptyString(joinItem)) {
-            throw new Error(`${label}[${i}] 必须是非空字符串`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`${label}[${i}] 必须是非空字符串`);
         }
 
         const parsed = parseLeftJoinEquality(joinItem);
         if (!parsed) {
-            throw new Error(`${label}[${i}] 必须是 "left.field right.field" 格式（空格表示等于）`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`${label}[${i}] 必须是 "left.field right.field" 格式（空格表示等于）`);
         }
 
         assertJoinFieldRef(parsed.left, `${label}[${i}] 左侧字段`);
@@ -187,19 +134,13 @@ function validateLeftJoinItems(leftJoin, label) {
 
 function validateQueryOptions(options, label) {
     if (!isPlainObject(options)) {
-        throw new Error(`${label} 必须是对象`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label} 必须是对象`);
     }
 
     const tableList = Array.isArray(options.table) ? options.table : [options.table];
 
     if (Array.isArray(options.table) && tableList.length === 0) {
-        throw new Error(`${label}.table 不能为空数组`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label}.table 不能为空数组`);
     }
 
     for (let i = 0; i < tableList.length; i++) {
@@ -215,22 +156,13 @@ function validateQueryOptions(options, label) {
     if (Array.isArray(options.table)) {
         if (Array.isArray(options.leftJoin) && options.leftJoin.length > 0) {
             if (tableList.length !== options.leftJoin.length + 1) {
-                throw new Error(`${label}.table 与 ${label}.leftJoin 数量不匹配，要求 table.length = leftJoin.length + 1`, {
-                    cause: null,
-                    code: "validation"
-                });
+                throw validationError(`${label}.table 与 ${label}.leftJoin 数量不匹配，要求 table.length = leftJoin.length + 1`);
             }
         } else if (tableList.length > 1) {
-            throw new Error(`${label}.table 为数组时必须配合 leftJoin 使用`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`${label}.table 为数组时必须配合 leftJoin 使用`);
         }
     } else if (Array.isArray(options.leftJoin) && options.leftJoin.length > 0) {
-        throw new Error(`${label}.leftJoin 启用时，${label}.table 必须是数组`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label}.leftJoin 启用时，${label}.table 必须是数组`);
     }
 
     if (!isNullable(options.where)) {
@@ -238,10 +170,7 @@ function validateQueryOptions(options, label) {
     }
 
     if (!isNullable(options.fields) && !Array.isArray(options.fields)) {
-        throw new Error(`${label}.fields 必须是数组`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label}.fields 必须是数组`);
     }
 
     if (!isNullable(options.orderBy)) {
@@ -253,34 +182,22 @@ function validateQueryOptions(options, label) {
     }
 
     if (!isNullable(options.page) && (!Number.isFinite(options.page) || Math.floor(options.page) !== options.page)) {
-        throw new Error(`${label}.page 必须是整数`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label}.page 必须是整数`);
     }
 
     if (!isNullable(options.limit) && (!Number.isFinite(options.limit) || Math.floor(options.limit) !== options.limit)) {
-        throw new Error(`${label}.limit 必须是整数`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label}.limit 必须是整数`);
     }
 }
 
 function assertBatchDataList(dataList, label) {
     if (!Array.isArray(dataList)) {
-        throw new Error(`${label} 必须是数组`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label} 必须是数组`);
     }
 
     for (let i = 0; i < dataList.length; i++) {
         if (!isPlainObject(dataList[i])) {
-            throw new Error(`${label}[${i}] 必须是对象`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`${label}[${i}] 必须是对象`);
         }
     }
 }
@@ -289,77 +206,47 @@ function validateNoLeftJoinReadOptions(options, label, joinErrorMessage) {
     assertNonEmptyString(options.table, `${label}.table`);
     validateWhereObject(options.where, `${label}.where`, false);
     if (Array.isArray(options.leftJoin) && options.leftJoin.length > 0) {
-        throw new Error(joinErrorMessage, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(joinErrorMessage);
     }
 
     if (Array.isArray(options.table)) {
-        throw new Error(`${label}.table 不支持数组`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label}.table 不支持数组`);
     }
 
     const table = isString(options.table) ? options.table.trim() : "";
     if (!table) {
-        throw new Error(`${label}.table 不能为空`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label}.table 不能为空`);
     }
     if (table.includes(" ")) {
-        throw new Error(`${label} 不支持别名表写法（table: ${table}）`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label} 不支持别名表写法（table: ${table}）`);
     }
     if (table.includes(".")) {
-        throw new Error(`${label} 不支持 schema.table 写法（table: ${table}）`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label} 不支持 schema.table 写法（table: ${table}）`);
     }
 
     if (!isNullable(options.orderBy)) {
         validateOrderByItems(options.orderBy, `${label}.orderBy`);
     }
     if (!isNullable(options.page) && (!Number.isFinite(options.page) || Math.floor(options.page) !== options.page)) {
-        throw new Error(`${label}.page 必须是整数`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label}.page 必须是整数`);
     }
     if (!isNullable(options.limit) && (!Number.isFinite(options.limit) || Math.floor(options.limit) !== options.limit)) {
-        throw new Error(`${label}.limit 必须是整数`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label}.limit 必须是整数`);
     }
 }
 
 function assertSafeFieldName(field) {
     if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(field)) {
-        throw new Error(`无效的字段名: ${field}，只允许字母、数字和下划线`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`无效的字段名: ${field}，只允许字母、数字和下划线`);
     }
 }
 
 function assertPageLimitRange(page, limit, rawTable) {
     if (page < 1 || page > 10000) {
-        throw new Error(`页码必须在 1 到 10000 之间 (table: ${rawTable}, page: ${page}, limit: ${limit})`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`页码必须在 1 到 10000 之间 (table: ${rawTable}, page: ${page}, limit: ${limit})`);
     }
     if (limit < 1 || limit > 100000) {
-        throw new Error(`每页数量必须在 1 到 100000 之间 (table: ${rawTable}, page: ${page}, limit: ${limit})`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`每页数量必须在 1 到 100000 之间 (table: ${rawTable}, page: ${page}, limit: ${limit})`);
     }
 }
 
@@ -369,28 +256,19 @@ function validateIncrementOptions(table, field, where, value, label) {
     assertSafeFieldName(snakeCase(table));
     assertSafeFieldName(snakeCase(field));
     if (typeof value !== "number" || Number.isNaN(value)) {
-        throw new Error(`自增值必须是有效的数字 (table: ${table}, field: ${field}, value: ${value})`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`自增值必须是有效的数字 (table: ${table}, field: ${field}, value: ${value})`);
     }
 }
 
 function assertEffectiveWhere(where, label) {
     if (!where || Object.keys(where).length === 0) {
-        throw new Error(`${label} 需要有效的 WHERE 条件`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`${label} 需要有效的 WHERE 条件`);
     }
 }
 
 function assertDefinedParamValue(value) {
     if (value === undefined) {
-        throw new Error("SQL 参数值 不能为 undefined", {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError("SQL 参数值 不能为 undefined");
     }
 }
 
@@ -412,21 +290,15 @@ function parseFieldSelection(fields) {
     }
 
     if (fields.some((field) => field === "*")) {
-        throw new Error("fields 不支持 * 星号，请使用空数组 [] 或不传参数表示查询所有字段", {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError("fields 不支持 * 星号，请使用空数组 [] 或不传参数表示查询所有字段");
     }
 
     if (fields.some((field) => !isNonEmptyString(field))) {
-        throw new Error("fields 不能包含空字符串或无效值", {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError("fields 不能包含空字符串或无效值");
     }
 
     for (const rawField of fields) {
-        const checkField = rawField.startsWith("!") ? rawField.substring(1) : rawField;
+        const checkField = rawField.startsWith("!") ? rawField.slice(1) : rawField;
         assertNoExprField(checkField);
     }
 
@@ -437,13 +309,10 @@ function parseFieldSelection(fields) {
         return { type: "include", fields: includeFields };
     }
     if (excludeFields.length > 0 && includeFields.length === 0) {
-        return { type: "exclude", fields: excludeFields.map((field) => field.substring(1)) };
+        return { type: "exclude", fields: excludeFields.map((field) => field.slice(1)) };
     }
 
-    throw new Error('fields 不能同时包含普通字段和排除字段（! 开头）。只能使用以下3种方式之一：\n1. 空数组 [] 或不传（查询所有）\n2. 全部指定字段 ["id", "name"]\n3. 全部排除字段 ["!password", "!token"]', {
-        cause: null,
-        code: "validation"
-    });
+    throw validationError('fields 不能同时包含普通字段和排除字段（! 开头）。只能使用以下3种方式之一：\n1. 空数组 [] 或不传（查询所有）\n2. 全部指定字段 ["id", "name"]\n3. 全部排除字段 ["!password", "!token"]');
 }
 
 function getTableQualifier(tableRef) {
@@ -457,10 +326,7 @@ function getTableQualifier(tableRef) {
 
 function parseJoinFieldSelection(fields, mainTableRef) {
     if (!fields || fields.length === 0) {
-        throw new Error("leftJoin 查询必须显式传 fields，不支持空 fields 或查询全部字段", {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError("leftJoin 查询必须显式传 fields，不支持空 fields 或查询全部字段");
     }
 
     const mainQualifier = getTableQualifier(mainTableRef);
@@ -471,51 +337,33 @@ function parseJoinFieldSelection(fields, mainTableRef) {
 
     for (const rawField of fields) {
         if (!isNonEmptyString(rawField)) {
-            throw new Error("fields 不能包含空字符串或无效值", {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError("fields 不能包含空字符串或无效值");
         }
 
         const trimmed = rawField.trim();
         if (trimmed === "*") {
-            throw new Error("fields 不支持 * 星号，请使用空数组 [] 或不传参数表示查询所有字段", {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError("fields 不支持 * 星号，请使用空数组 [] 或不传参数表示查询所有字段");
         }
 
         if (trimmed.startsWith("!")) {
-            const fieldPart = trimmed.substring(1).trim();
+            const fieldPart = trimmed.slice(1).trim();
             if (!isNonEmptyString(fieldPart)) {
-                throw new Error("fields 不能包含空字符串或无效值", {
-                    cause: null,
-                    code: "validation"
-                });
+                throw validationError("fields 不能包含空字符串或无效值");
             }
             if (/\s/.test(fieldPart)) {
-                throw new Error("leftJoin 排除字段不支持别名", {
-                    cause: null,
-                    code: "validation"
-                });
+                throw validationError("leftJoin 排除字段不支持别名");
             }
 
             assertNoExprField(fieldPart);
             const normalizedField = normalizeQualifierField(fieldPart);
             if (normalizedField === mainWildcard) {
-                throw new Error("leftJoin 主表排除字段不能使用 *", {
-                    cause: null,
-                    code: "validation"
-                });
+                throw validationError("leftJoin 主表排除字段不能使用 *");
             }
             if (!normalizedField.startsWith(`${mainQualifier}.`)) {
-                throw new Error("leftJoin 排除字段仅支持主表字段，请使用主表限定符", {
-                    cause: null,
-                    code: "validation"
-                });
+                throw validationError("leftJoin 排除字段仅支持主表字段，请使用主表限定符");
             }
 
-            mainExcludeFields.push(normalizedField.substring(mainQualifier.length + 1));
+            mainExcludeFields.push(normalizedField.slice(mainQualifier.length + 1));
             continue;
         }
 
@@ -524,10 +372,7 @@ function parseJoinFieldSelection(fields, mainTableRef) {
         const normalizedField = normalizeQualifierField(aliasParts ? aliasParts.fieldPart.trim() : trimmed);
         if (normalizedField === mainWildcard) {
             if (aliasParts) {
-                throw new Error("leftJoin 主表全字段不支持别名", {
-                    cause: null,
-                    code: "validation"
-                });
+                throw validationError("leftJoin 主表全字段不支持别名");
             }
             mainAllIncluded = true;
             continue;
@@ -537,10 +382,7 @@ function parseJoinFieldSelection(fields, mainTableRef) {
     }
 
     if (mainExcludeFields.length > 0 && !mainAllIncluded) {
-        throw new Error("leftJoin 使用主表排除字段时，必须同时传主表限定符.*", {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError("leftJoin 使用主表排除字段时，必须同时传主表限定符.*");
     }
 
     return {
@@ -572,16 +414,10 @@ function normalizeOrGroupKey(orGroup) {
 
 function buildArrayOperatorNode(fieldName, operator, value, errorFactory, emptyMessage) {
     if (!Array.isArray(value)) {
-        throw new Error(errorFactory(operator), {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(errorFactory(operator));
     }
     if (value.length === 0) {
-        throw new Error(emptyMessage, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(emptyMessage);
     }
 
     return { type: "op", field: fieldName, operator: operator, value: value };
@@ -741,22 +577,6 @@ export class DbParse {
         this.getTableColumns = options.getTableColumns;
     }
 
-    classifyFields(fields) {
-        return parseFieldSelection(fields);
-    }
-
-    classifyJoinFields(fields, mainTableRef) {
-        return parseJoinFieldSelection(fields, mainTableRef);
-    }
-
-    parseLeftJoinItem(joinTable, joinItem) {
-        return parseLeftJoinItem(joinTable, joinItem);
-    }
-
-    applyDefaultStateFilter(where, table, hasLeftJoin = false) {
-        return applyDefaultStateFilter(where, table, hasLeftJoin, this.beflyMode);
-    }
-
     async parseRead(options, mode) {
         const label = mode === "one" ? "getOne.options" : mode === "list" ? "getList.options" : "getAll.options";
         validateQueryOptions(options, label);
@@ -861,10 +681,7 @@ export class DbParse {
     parseDelForceBatch(table, ids) {
         assertNonEmptyString(table, "delForceBatch.table");
         if (!Array.isArray(ids)) {
-            throw new Error("delForceBatch.ids 必须是数组", {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError("delForceBatch.ids 必须是数组");
         }
         return {
             table: table,
@@ -996,12 +813,12 @@ export class DbParse {
         }
 
         if (processedFields.length === 0) {
-            throw new Error(`排除字段后没有剩余字段可查询。表: ${mainTableRef}, 排除: ${classifiedFields.mainExcludeFields.join(", ")}`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`排除字段后没有剩余字段可查询。表: ${mainTableRef}, 排除: ${classifiedFields.mainExcludeFields.join(", ")}`);
         }
 
         return processedFields;
     }
 }
+
+// 供内部/测试直接使用的字段分类工具（类方法套壳已移除）
+export { applyDefaultStateFilter, parseFieldSelection, parseJoinFieldSelection, parseLeftJoinItem };