befly 3.17.0 → 3.17.2

package/utils/importDefault.js

@@ -0,0 +1,51 @@
+/**
+ * 动态导入模块并优先返回其 default 导出。
+ *
+ * - import() 报错：返回 defaultValue
+ * - default 导出为 null/undefined：返回 defaultValue
+ */
+import { isAbsolute } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { Logger } from "../lib/logger.js";
+import { isNullable } from "./is.js";
+import { getTypeTag } from "./util.js";
+
+function isWindowsAbsPath(file) {
+    // e.g. C:\a\b 或 C:/a/b
+    return /^[a-zA-Z]:[\\/]/.test(file);
+}
+
+function toFileImportUrl(file) {
+    if (isAbsolute(file) || isWindowsAbsPath(file)) {
+        return pathToFileURL(file).href;
+    }
+    return file;
+}
+
+export async function importDefault(file, defaultValue) {
+    try {
+        const isJson = file.endsWith(".json");
+
+        // 注意：Node ESM / Bun 对 JSON import 的行为不同。
+        // 为保证一致性：json 一律走 import assertion。
+        const mod = isJson ? await import(toFileImportUrl(file), { with: { type: "json" } }) : await import(file);
+        const value = mod?.default;
+        if (isNullable(value)) {
+            return defaultValue;
+        }
+
+        // 额外保护：如果导入值的运行时类型与 defaultValue 不一致，则回退 defaultValue。
+        // 这样调用方可以通过 defaultValue 的类型约束导入结果（例如 defaultValue 为 {} 时，数组/字符串等会被拒绝）。
+        const expectedType = getTypeTag(defaultValue);
+        const actualType = getTypeTag(value);
+        if (expectedType !== actualType) {
+            Logger.warn("importDefault 导入类型与默认值不一致，已回退到默认值", { file: file, expectedType: expectedType, actualType: actualType });
+            return defaultValue;
+        }
+        return value;
+    } catch (err) {
+        Logger.warn("importDefault 导入失败，已回退到默认值", { err: err, file: file });
+        return defaultValue;
+    }
+}

package/utils/is.js

@@ -0,0 +1,462 @@
+import { statSync } from "node:fs";
+
+import { join } from "pathe";
+
+import { DECIMAL_KIND_TYPES, ENUM_KIND_TYPES, FLOAT_KIND_TYPES, INT_KIND_TYPES, JSON_KIND_TYPES, STRING_KIND_TYPES, TEXT_KIND_TYPES } from "../configs/constConfig.js";
+
+/**
+ * 判断值是否为 plain object（原型为 Object.prototype 或 null）。
+ */
+export function isPlainObject(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+
+/**
+ * 判断值是否为 JSON 基础类型（string/number/boolean/null）。
+ */
+export function isJsonPrimitive(value) {
+    if (value === null) {
+        return true;
+    }
+    return typeof value === "string" || isNumber(value) || isBoolean(value);
+}
+
+/**
+ * 判断值是否为 JSON 对象（plain object，且非数组/非 Date）。
+ */
+export function isJsonObject(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    if (value instanceof Date) {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        return false;
+    }
+    return true;
+}
+
+/**
+ * 判断值是否为 JSON 结构（数组或对象）。
+ */
+export function isJsonStructure(value) {
+    return Array.isArray(value) || isJsonObject(value);
+}
+
+/**
+ * 判断值是否为可 JSON 序列化结构（递归）。
+ */
+export function isJsonValue(value) {
+    if (isJsonPrimitive(value)) {
+        return true;
+    }
+
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            if (!isJsonValue(item)) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    if (isJsonObject(value)) {
+        for (const v of Object.values(value)) {
+            if (v === undefined) {
+                continue;
+            }
+            if (!isJsonValue(v)) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * 判断值是否为有限数值。
+ */
+export function isFiniteNumber(value) {
+    return isNumber(value) && Number.isFinite(value);
+}
+
+/**
+ * 判断值是否为字符串。
+ */
+export function isString(value) {
+    return typeof value === "string";
+}
+
+/**
+ * 判断值是否为 number。
+ */
+export function isNumber(value) {
+    return Object.prototype.toString.call(value) === "[object Number]";
+}
+
+/**
+ * 判断值是否为 boolean。
+ */
+export function isBoolean(value) {
+    return Object.prototype.toString.call(value) === "[object Boolean]";
+}
+
+/**
+ * 判断值是否为 function。
+ */
+export function isFunction(value) {
+    return Object.prototype.toString.call(value) === "[object Function]";
+}
+
+/**
+ * 判断值是否为 nullable（默认仅 null/undefined）。
+ * 可通过 extraValues 指定更多“空值”。
+ */
+export function isNullable(value, extraValues = []) {
+    if (value === null || value === undefined) {
+        return true;
+    }
+
+    if (!Array.isArray(extraValues) || extraValues.length === 0) {
+        return false;
+    }
+
+    for (const item of extraValues) {
+        if (Object.is(value, item)) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * 判断字符串长度是否至少为指定值（trim 后）。
+ */
+export function isMinLengthString(value, minLength) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    if (!Number.isFinite(minLength)) {
+        return false;
+    }
+    if (minLength <= 0) {
+        return true;
+    }
+    return value.trim().length >= minLength;
+}
+
+/**
+ * 判断值是否为非空字符串。
+ */
+export function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * 判断字符串是否允许空字符串且不允许首尾空白。
+ */
+export function isNoTrimStringAllowEmpty(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+
+    if (value.length === 0) {
+        return true;
+    }
+
+    const firstCharCode = value.charCodeAt(0);
+    if (isWhitespaceCharCode(firstCharCode)) {
+        return false;
+    }
+
+    const lastCharCode = value.charCodeAt(value.length - 1);
+    if (isWhitespaceCharCode(lastCharCode)) {
+        return false;
+    }
+
+    return true;
+}
+
+function isWhitespaceCharCode(code) {
+    if (code === 9 || code === 10 || code === 11 || code === 12 || code === 13) {
+        return true;
+    }
+    if (code === 32 || code === 133 || code === 160) {
+        return true;
+    }
+    if (code === 5760 || code === 8232 || code === 8233 || code === 8239 || code === 8287 || code === 12288 || code === 65279) {
+        return true;
+    }
+    if (code >= 8192 && code <= 8202) {
+        return true;
+    }
+    return false;
+}
+
+/**
+ * 判断是否为小驼峰命名（可选以下划线开头）。
+ */
+export function isLowerCamelCaseName(value) {
+    if (!isNonEmptyString(value)) {
+        return false;
+    }
+    return /^_?[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*$/.test(value);
+}
+
+/**
+ * 判断值是否为合法端口号（1..65535）。
+ */
+export function isValidPort(value) {
+    return isFiniteNumber(value) && value >= 1 && value <= 65535;
+}
+
+/**
+ * 判断值是否为合法非负整数。
+ */
+export function isValidNonNegativeInt(value) {
+    return Number.isInteger(value) && value >= 0;
+}
+
+/**
+ * 判断值是否为合法正整数。
+ */
+export function isValidPositiveInt(value) {
+    return Number.isInteger(value) && value >= 1;
+}
+
+/**
+ * 判断值是否为有效 IANA 时区字符串。
+ */
+export function isValidTimeZone(value) {
+    if (!isNonEmptyString(value)) return false;
+
+    try {
+        // RangeError: Invalid time zone specified
+        new Intl.DateTimeFormat("en-US", { timeZone: value }).format(0);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * 判断值是否为有限整数。
+ */
+export function isIntegerNumber(value) {
+    return isNumber(value) && Number.isInteger(value) && Number.isFinite(value);
+}
+
+/**
+ * 判断字符串是否为正则字面量（/source/flags）。
+ */
+export function isRegexLiteral(input) {
+    const trimmed = String(input || "").trim();
+    if (!isMinLengthString(trimmed, 2)) {
+        return false;
+    }
+    if (!trimmed.startsWith("/")) {
+        return false;
+    }
+
+    const lastSlash = trimmed.lastIndexOf("/");
+    if (lastSlash <= 0) {
+        return false;
+    }
+
+    const flags = trimmed.slice(lastSlash + 1);
+    if (flags !== "" && !/^[gimsuy]+$/.test(flags)) {
+        return false;
+    }
+
+    return true;
+}
+
+/**
+ * 判断输入是否为正则规则（字面量或 @ 别名）。
+ */
+export function isRegexInput(input) {
+    const trimmed = String(input || "").trim();
+    // 约束：正则 input 仅允许 /source/flags 形式；同时保留 @alias 作为正则别名。
+    // 说明：不再支持直接写 source（如 ^\d+$），避免与普通字符串/枚举产生歧义。
+    return isRegexLiteral(trimmed) || trimmed.startsWith("@");
+}
+
+/**
+ * 判断输入是否为枚举规则（首字符非 / 且包含 |）。
+ */
+export function isEnumInput(input) {
+    const trimmed = String(input || "").trim();
+    if (trimmed.length === 0) {
+        return false;
+    }
+    return !trimmed.startsWith("/") && trimmed.includes("|");
+}
+
+/**
+ * 判断输入是否为规则别名（@ 开头）。
+ */
+export function isAliasInput(input) {
+    return String(input || "")
+        .trim()
+        .startsWith("@");
+}
+
+/**
+ * 激进空值判断（项目约定）。
+ */
+export function isEmpty(value) {
+    if (isNullable(value)) {
+        return true;
+    }
+
+    if (typeof value === "string") {
+        return value.trim().length === 0;
+    }
+
+    if (isNumber(value)) {
+        return value === 0 || Number.isNaN(value);
+    }
+
+    if (isBoolean(value)) {
+        return value === false;
+    }
+
+    if (Array.isArray(value)) {
+        return value.length === 0;
+    }
+
+    if (value instanceof Map || value instanceof Set) {
+        return value.size === 0;
+    }
+
+    if (isPlainObject(value)) {
+        return Object.keys(value).length === 0;
+    }
+
+    return false;
+}
+
+/**
+ * 判断当前进程是否为主进程（针对 PM2 cluster 常见环境变量）。
+ */
+export function isPrimaryProcess(env) {
+    const sourceEnv = env && typeof env === "object" ? env : process.env;
+
+    const bunWorkerId = sourceEnv.BUN_WORKER_ID;
+    if (bunWorkerId !== undefined && bunWorkerId !== null) {
+        const normalizedBunWorkerId = String(bunWorkerId).trim();
+        if (normalizedBunWorkerId === "" || normalizedBunWorkerId === "0") {
+            return true;
+        }
+        const bunWorkerIdNumber = Number(normalizedBunWorkerId);
+        if (Number.isInteger(bunWorkerIdNumber) && bunWorkerIdNumber >= 0) {
+            return bunWorkerIdNumber === 0;
+        }
+        return false;
+    }
+
+    const pm2InstanceIdRaw = sourceEnv.NODE_APP_INSTANCE ?? sourceEnv.PM2_INSTANCE_ID ?? sourceEnv.pm_id;
+    if (pm2InstanceIdRaw !== undefined && pm2InstanceIdRaw !== null) {
+        const normalizedPm2InstanceId = String(pm2InstanceIdRaw).trim();
+        if (normalizedPm2InstanceId === "0") {
+            return true;
+        }
+        const pm2InstanceIdNumber = Number(normalizedPm2InstanceId);
+        if (Number.isInteger(pm2InstanceIdNumber) && pm2InstanceIdNumber >= 0) {
+            return pm2InstanceIdNumber === 0;
+        }
+        return false;
+    }
+
+    const execMode = String(sourceEnv.exec_mode || sourceEnv.NODE_EXEC_MODE || "").toLowerCase();
+    const hasPm2Markers = sourceEnv.PM2_HOME !== undefined || sourceEnv.pm_exec_path !== undefined || sourceEnv.PM2_USAGE !== undefined || execMode.includes("cluster");
+    if (hasPm2Markers) {
+        return false;
+    }
+
+    return true;
+}
+
+export const isDirentDirectory = (parentDir, entry) => {
+    if (entry.isDirectory()) {
+        return true;
+    }
+
+    // 兼容 Windows 下的 junction / workspace link：Dirent.isDirectory() 可能为 false，但它实际指向目录。
+    if (!entry.isSymbolicLink()) {
+        return false;
+    }
+
+    try {
+        const stats = statSync(join(parentDir, entry.name));
+        return stats.isDirectory();
+    } catch {
+        return false;
+    }
+};
+
+/**
+ * 数据库类型判定
+ */
+export function isStringDbType(dbType) {
+    return STRING_KIND_TYPES.includes(dbType);
+}
+
+export function isTextDbType(dbType) {
+    return TEXT_KIND_TYPES.includes(dbType);
+}
+
+export function isIntDbType(dbType) {
+    return INT_KIND_TYPES.includes(dbType);
+}
+
+export function isDecimalDbType(dbType) {
+    return DECIMAL_KIND_TYPES.includes(dbType);
+}
+
+export function isFloatDbType(dbType) {
+    return FLOAT_KIND_TYPES.includes(dbType);
+}
+
+export function isJsonDbType(dbType) {
+    return JSON_KIND_TYPES.includes(dbType);
+}
+
+export function isEnumDbType(dbType) {
+    return ENUM_KIND_TYPES.includes(dbType);
+}
+
+export function isNumericDbType(dbType) {
+    return INT_KIND_TYPES.includes(dbType) || DECIMAL_KIND_TYPES.includes(dbType) || FLOAT_KIND_TYPES.includes(dbType);
+}
+
+/**
+ * SQL Value 判定
+ */
+export function isSqlValue(value) {
+    if (value instanceof Date) return true;
+    return isJsonValue(value);
+}
+
+/**
+ * 日志敏感键判定
+ */
+export function isSensitiveKey(key, matcher) {
+    const lower = String(key).toLowerCase();
+    if (matcher.exactSet.has(lower)) return true;
+
+    for (const part of matcher.contains) {
+        if (lower.includes(part)) return true;
+    }
+
+    return false;
+}

package/utils/loggerUtils.js

@@ -0,0 +1,185 @@
+import { isBoolean, isNullable, isNumber, isPlainObject, isSensitiveKey, isString } from "./is.js";
+
+export function buildSensitiveKeyMatcher(options) {
+    const exactSet = new Set();
+    const contains = [];
+
+    const addPattern = (item) => {
+        const trimmed = String(item).trim().toLowerCase();
+        if (trimmed.length === 0) return;
+
+        if (!trimmed.includes("*")) {
+            exactSet.add(trimmed);
+            return;
+        }
+
+        const core = trimmed.replace(/\*+/g, "").trim();
+        if (!core) return;
+        contains.push(core);
+    };
+
+    for (const item of options.builtinPatterns) {
+        addPattern(item);
+    }
+
+    if (Array.isArray(options.userPatterns)) {
+        for (const item of options.userPatterns) {
+            addPattern(item);
+        }
+    }
+
+    return { exactSet: exactSet, contains: contains };
+}
+
+function truncateString(value, maxLen) {
+    if (value.length <= maxLen) return value;
+    return value.slice(0, maxLen);
+}
+
+function sanitizeErrorValue(err, options) {
+    const out = {
+        name: err.name || "Error",
+        message: truncateString(err.message || "", options.maxStringLen)
+    };
+
+    if (isString(err.stack)) {
+        out["stack"] = truncateString(err.stack, options.maxStringLen);
+    }
+
+    return out;
+}
+
+function safeToStringMasked(value, options, visited) {
+    if (isString(value)) return truncateString(value, options.maxStringLen);
+
+    if (value instanceof Error) {
+        try {
+            return truncateString(JSON.stringify(sanitizeErrorValue(value, options)), options.maxStringLen);
+        } catch {
+            return truncateString(`${value.name || "Error"}: ${value.message || ""}`, options.maxStringLen);
+        }
+    }
+
+    if (value && typeof value === "object") {
+        if (visited.has(value)) {
+            return "[Circular]";
+        }
+    }
+
+    try {
+        const localVisited = visited;
+        const replacer = (k, v) => {
+            if (k && isSensitiveKey(k, options.sensitiveKeyMatcher)) {
+                return "[MASKED]";
+            }
+
+            if (v && typeof v === "object") {
+                if (localVisited.has(v)) {
+                    return "[Circular]";
+                }
+                localVisited.add(v);
+            }
+
+            return v;
+        };
+
+        return truncateString(JSON.stringify(value, replacer), options.maxStringLen);
+    } catch {
+        try {
+            return truncateString(String(value), options.maxStringLen);
+        } catch {
+            return "[Unserializable]";
+        }
+    }
+}
+
+function sanitizeAny(value, options, state, depth, visited) {
+    if (isNullable(value)) return value;
+
+    if (isString(value)) {
+        return truncateString(value, options.maxStringLen);
+    }
+
+    if (isNumber(value) || isBoolean(value) || typeof value === "bigint") {
+        return value;
+    }
+
+    if (value instanceof Error) {
+        return sanitizeErrorValue(value, options);
+    }
+
+    const isArr = Array.isArray(value);
+    const isObj = isPlainObject(value);
+
+    if (!isArr && !isObj) {
+        return safeToStringMasked(value, options, visited);
+    }
+
+    if (visited.has(value)) {
+        return "[Circular]";
+    }
+
+    if (depth >= options.sanitizeDepth) {
+        return safeToStringMasked(value, options, visited);
+    }
+
+    if (state.nodes >= options.sanitizeNodes) {
+        return safeToStringMasked(value, options, visited);
+    }
+
+    visited.add(value);
+    state.nodes = state.nodes + 1;
+
+    if (isArr) {
+        const arr = value;
+        const out = [];
+
+        const limit = arr.length > options.maxArrayItems ? options.maxArrayItems : arr.length;
+        for (let i = 0; i < limit; i++) {
+            out[i] = sanitizeAny(arr[i], options, state, depth + 1, visited);
+        }
+
+        return out;
+    }
+
+    const obj = value;
+    const out = {};
+
+    const entries = Object.entries(obj);
+    const limit = entries.length > options.sanitizeObjectKeys ? options.sanitizeObjectKeys : entries.length;
+
+    for (let i = 0; i < limit; i++) {
+        const entry = entries[i];
+        if (!entry) {
+            continue;
+        }
+        const key = entry[0];
+        const child = entry[1];
+
+        if (isSensitiveKey(key, options.sensitiveKeyMatcher)) {
+            out[key] = "[MASKED]";
+            continue;
+        }
+
+        out[key] = sanitizeAny(child, options, state, depth + 1, visited);
+    }
+
+    return out;
+}
+
+export function sanitizeLogObject(obj, options) {
+    const visited = new WeakSet();
+    const state = { nodes: 0 };
+
+    const out = {};
+    for (const [key, val] of Object.entries(obj)) {
+        if (isSensitiveKey(key, options.sensitiveKeyMatcher)) {
+            out[key] = "[MASKED]";
+            continue;
+        }
+
+        out[key] = sanitizeAny(val, options, state, 0, visited);
+    }
+
+    return out;
+}