befly 3.20.11 → 3.21.1

package/lib/dbUtil.js

@@ -0,0 +1,988 @@
+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;
+    }
+    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((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,
+            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 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) {
+        return false;
+    }
+
+    const first = trimmed[0];
+    const last = trimmed[trimmed.length - 1];
+    return (first === "`" && last === "`") || (first === '"' && last === '"');
+}
+
+function startsWithIdentifierQuote(value) {
+    const trimmed = value.trim();
+    return trimmed.startsWith("`") || trimmed.startsWith('"');
+}
+
+function assertPairedQuotedIdent(value, label) {
+    if (startsWithIdentifierQuote(value) && !isQuotedIdentPaired(value)) {
+        throw new Error(`${label} 引用不完整，请使用成对的 \`...\` 或 "..." (value: ${value})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function escapeIdentifierPart(part, kind, quoteIdent, unpairedErrorFactory) {
+    if (isQuotedIdent(part)) {
+        return part;
+    }
+
+    if (startsWithQuote(part)) {
+        throw new Error(unpairedErrorFactory(part), {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    assertSafeIdentifierPart(part, kind);
+    return quoteIdent(part);
+}
+
+export function resolveQuoteIdent(options) {
+    if (options && options.quoteIdent) {
+        return options.quoteIdent;
+    }
+
+    return (identifier) => {
+        const trimmed = validateQuoteIdentifierInput(identifier);
+
+        const escaped = trimmed.replace(/`/g, "``");
+        return `\`${escaped}\``;
+    };
+}
+
+export function isQuotedIdent(value) {
+    return isQuotedIdentPaired(value);
+}
+
+export function startsWithQuote(value) {
+    return startsWithIdentifierQuote(value);
+}
+
+export function escapeField(field, quoteIdent) {
+    if (!isString(field)) {
+        return field;
+    }
+
+    const trimmed = field.trim();
+
+    assertPairedQuotedIdent(trimmed, "字段标识符");
+
+    if (trimmed === "*" || isQuotedIdent(trimmed)) {
+        return trimmed;
+    }
+
+    try {
+        assertNoExprField(trimmed);
+    } catch {
+        throw new Error(`字段包含函数/表达式，请使用 selectRaw/whereRaw (field: ${trimmed})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    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"
+            });
+        }
+
+        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}`;
+    }
+
+    if (trimmed.includes(".")) {
+        const parts = trimmed.split(".");
+        return parts
+            .map((part) => {
+                const cleanPart = part.trim();
+                if (cleanPart === "*" || isQuotedIdent(cleanPart)) {
+                    return cleanPart;
+                }
+                assertPairedQuotedIdent(cleanPart, "字段标识符");
+                return quoteIdent(cleanPart);
+            })
+            .join(".");
+    }
+
+    return quoteIdent(trimmed);
+}
+
+export function escapeTable(table, quoteIdent) {
+    if (!isString(table)) {
+        return table;
+    }
+
+    const trimmed = table.trim();
+
+    if (isQuotedIdent(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 (parts.length > 2) {
+        throw new Error(`不支持的表引用格式（包含过多片段）。请使用 fromRaw 显式传入复杂表达式 (table: ${trimmed})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    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"
+        });
+    }
+
+    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();
+
+        escapedName = escapeIdentifierPart(tableName, "table", quoteIdent, (part) => `table 标识符引用不完整，请使用成对的 \`...\` 或 "..." (table: ${part})`);
+    }
+
+    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;
+    }
+
+    const candidateValues = excludeValueMap.get(field);
+    if (!candidateValues || candidateValues.length === 0) {
+        return false;
+    }
+
+    for (const candidate of candidateValues) {
+        if (value === candidate) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+function mergeExcludeValueMap(parentMap, excludeConfig) {
+    const result = new Map();
+
+    if (parentMap instanceof Map) {
+        for (const [key, values] of parentMap.entries()) {
+            result.set(key, Array.isArray(values) ? [...values] : []);
+        }
+    }
+
+    if (!excludeConfig || typeof excludeConfig !== "object" || Array.isArray(excludeConfig)) {
+        return result;
+    }
+
+    for (const [key, values] of Object.entries(excludeConfig)) {
+        if (!Array.isArray(values) || values.length === 0) {
+            continue;
+        }
+
+        const current = result.get(key) || [];
+        result.set(key, [...current, ...values]);
+    }
+
+    return result;
+}
+
+export function clearDeep(value, options) {
+    const arrayObjectKeys = Array.isArray(options?.arrayObjectKeys) ? options.arrayObjectKeys : ["$or", "$and"];
+    const arrayObjectKeySet = new Set();
+    for (const key of arrayObjectKeys) {
+        arrayObjectKeySet.add(key);
+    }
+
+    const depthRaw = isFiniteNumber(options?.depth) ? Math.floor(options.depth) : 0;
+    const depth = depthRaw < 0 ? 0 : depthRaw;
+
+    const clearInternal = (input, remainingDepth, inheritedExcludeValueMap) => {
+        if (!input || typeof input !== "object") {
+            return input;
+        }
+
+        if (Array.isArray(input)) {
+            return input;
+        }
+
+        const canRecurse = remainingDepth === 0 || remainingDepth > 1;
+        const childDepth = remainingDepth === 0 ? 0 : remainingDepth - 1;
+        const result = {};
+        const currentExcludeValueMap = mergeExcludeValueMap(inheritedExcludeValueMap, input.$exclude);
+
+        for (const [key, item] of Object.entries(input)) {
+            if (key === "$exclude") {
+                continue;
+            }
+
+            if (isNullable(item)) {
+                continue;
+            }
+
+            if (shouldExcludeFieldValue(key, item, currentExcludeValueMap)) {
+                continue;
+            }
+
+            if (arrayObjectKeySet.has(key)) {
+                if (!Array.isArray(item)) {
+                    continue;
+                }
+
+                const outList = [];
+                for (const child of item) {
+                    if (!child || typeof child !== "object" || Array.isArray(child)) {
+                        continue;
+                    }
+                    const cleaned = clearInternal(child, remainingDepth, currentExcludeValueMap);
+                    if (!cleaned || typeof cleaned !== "object" || Array.isArray(cleaned)) {
+                        continue;
+                    }
+                    if (Object.keys(cleaned).length === 0) {
+                        continue;
+                    }
+                    outList.push(cleaned);
+                }
+
+                if (outList.length > 0) {
+                    result[key] = outList;
+                }
+                continue;
+            }
+
+            if (typeof item === "object" && !Array.isArray(item)) {
+                if (!canRecurse) {
+                    result[key] = item;
+                    continue;
+                }
+
+                const nested = clearInternal(item, childDepth, currentExcludeValueMap);
+                if (!nested || typeof nested !== "object" || Array.isArray(nested)) {
+                    continue;
+                }
+                if (Object.keys(nested).length === 0) {
+                    continue;
+                }
+                result[key] = nested;
+                continue;
+            }
+
+            result[key] = item;
+        }
+
+        return result;
+    };
+
+    return clearInternal(value, depth, new Map());
+}
+
+export async function fieldsToSnake(table, classified, getTableColumns) {
+    if (classified.type === "include") {
+        return classified.fields.map((field) => processJoinField(field));
+    }
+    if (classified.type === "exclude") {
+        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);
+        return resultFields;
+    }
+    return ["*"];
+}
+
+function normalizeQualifierField(field) {
+    const parts = field.split(".");
+    if (parts.length === 1) {
+        return snakeCase(field);
+    }
+
+    const fieldName = parts[parts.length - 1].trim();
+    const qualifier = parts
+        .slice(0, parts.length - 1)
+        .map((item) => snakeCase(item.trim()))
+        .join(".");
+
+    if (fieldName === "*") {
+        return `${qualifier}.*`;
+    }
+
+    return `${qualifier}.${snakeCase(fieldName)}`;
+}
+
+function normalizeOrderBy(orderBy, mapField) {
+    if (!orderBy || !Array.isArray(orderBy)) {
+        return orderBy;
+    }
+
+    return orderBy.map((item) => {
+        if (!isString(item) || !item.includes("#")) {
+            return item;
+        }
+
+        const parts = item.split("#");
+        if (parts.length !== 2) {
+            return item;
+        }
+
+        return `${mapField(parts[0].trim())}#${parts[1].trim()}`;
+    });
+}
+
+function mapWhereKeys(where, mapKey) {
+    if (!where || typeof where !== "object") {
+        return where;
+    }
+    if (Array.isArray(where)) {
+        return where.map((item) => mapWhereKeys(item, mapKey));
+    }
+
+    const result = {};
+    for (const [key, value] of Object.entries(where)) {
+        if (key === "$or" || key === "$and") {
+            result[key] = Array.isArray(value) ? value.map((item) => mapWhereKeys(item, mapKey)) : [];
+            continue;
+        }
+
+        const normalizedKey = mapKey(key);
+        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            result[normalizedKey] = mapWhereKeys(value, mapKey);
+            continue;
+        }
+
+        result[normalizedKey] = value;
+    }
+
+    return result;
+}
+
+export function orderByToSnake(orderBy) {
+    return normalizeOrderBy(orderBy, (field) => snakeCase(field));
+}
+
+export function processJoinField(field) {
+    assertNoExprField(field);
+    if (field === "*" || field.startsWith("`")) {
+        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()}`;
+    }
+
+    return normalizeQualifierField(field);
+}
+
+function processJoinWhereKey(key) {
+    if (key === "$or" || key === "$and") {
+        return key;
+    }
+
+    assertNoExprField(key);
+    if (key.includes("$")) {
+        const lastDollarIndex = key.lastIndexOf("$");
+        const fieldPart = key.substring(0, lastDollarIndex);
+        const operator = key.substring(lastDollarIndex);
+
+        return `${normalizeQualifierField(fieldPart)}${operator}`;
+    }
+
+    return normalizeQualifierField(key);
+}
+
+export function processJoinWhere(where) {
+    return mapWhereKeys(where, processJoinWhereKey);
+}
+
+export function processJoinOrderBy(orderBy) {
+    return normalizeOrderBy(orderBy, processJoinField);
+}
+
+export function processJoinOn(on) {
+    if (!isString(on)) {
+        return String(on);
+    }
+
+    const raw = String(on);
+    if (!isNonEmptyString(raw)) {
+        return raw;
+    }
+
+    const replaceSegment = (segment) => {
+        return segment.replace(/([a-zA-Z_][a-zA-Z0-9_]*)(\s*\.\s*)([a-zA-Z_][a-zA-Z0-9_]*)/g, (_match, left, dot, right) => {
+            return `${snakeCase(left)}${dot}${snakeCase(right)}`;
+        });
+    };
+
+    let result = "";
+    let buffer = "";
+    let quote = null;
+    let prev = "";
+
+    for (const ch of raw) {
+        if (quote) {
+            result += ch;
+            if (ch === quote && prev !== "\\") {
+                quote = null;
+            }
+            prev = ch;
+            continue;
+        }
+
+        if (ch === "'" || ch === '"' || ch === "`") {
+            if (buffer.length > 0) {
+                result += replaceSegment(buffer);
+                buffer = "";
+            }
+            quote = ch;
+            result += ch;
+            prev = ch;
+            continue;
+        }
+
+        buffer += ch;
+        prev = ch;
+    }
+
+    if (buffer.length > 0) {
+        result += replaceSegment(buffer);
+    }
+
+    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);
+        if (key.includes("$")) {
+            const lastDollarIndex = key.lastIndexOf("$");
+            const fieldName = key.substring(0, lastDollarIndex);
+            const operator = key.substring(lastDollarIndex);
+            return `${snakeCase(fieldName)}${operator}`;
+        }
+
+        return snakeCase(key);
+    });
+}
+
+export function serializeArrayFields(data) {
+    const serialized = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (isNullable(value)) {
+            serialized[key] = value;
+            continue;
+        }
+        if (Array.isArray(value)) {
+            serialized[key] = JSON.stringify(value);
+            continue;
+        }
+        serialized[key] = value;
+    }
+    return serialized;
+}
+
+export function deserializeArrayFields(data) {
+    if (!data) {
+        return null;
+    }
+    const deserialized = {};
+    for (const [key, value] of Object.entries(data)) {
+        deserialized[key] = value;
+    }
+
+    for (const [key, value] of Object.entries(deserialized)) {
+        if (!isString(value)) {
+            continue;
+        }
+        if (value.startsWith("[") && value.endsWith("]")) {
+            try {
+                const parsed = JSON.parse(value);
+                if (Array.isArray(parsed)) {
+                    deserialized[key] = parsed;
+                }
+            } catch {
+                continue;
+            }
+        }
+    }
+
+    return deserialized;
+}