befly 3.17.0 → 3.17.2

package/utils/util.js

@@ -0,0 +1,374 @@
+/**
+ * 注意：本文件用于集中维护 core 内部通用 utils。
+ * - 按项目规范：避免零散小文件噪音；实现集中在本文件，而不是做 re-export 聚合。
+ * - 仅在 packages/core 内部使用；core 对外不承诺这些路径导出。
+ */
+
+import { isBoolean, isNullable, isNumber, isPlainObject } from "./is.js";
+
+/**
+ * 判断 bigint 是否可安全转换为 number。
+ * - 超出安全整数范围则不可转换
+ * - 转换后若是科学计数法表示则不可转换
+ */
+export function canConvertToNumber(value) {
+    const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+    const minSafe = BigInt(Number.MIN_SAFE_INTEGER);
+
+    if (value > maxSafe || value < minSafe) {
+        return null;
+    }
+
+    const asNumber = Number(value);
+    if (!Number.isSafeInteger(asNumber)) {
+        return null;
+    }
+
+    const text = String(asNumber);
+    if (text.includes("e") || text.includes("E")) {
+        return null;
+    }
+
+    return asNumber;
+}
+
+/**
+ * 安全格式化值用于日志预览（截断长文本，避免抛错）。
+ */
+export function formatValuePreview(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (value === undefined) {
+        return "undefined";
+    }
+
+    if (typeof value === "string") {
+        const s = value.length > 80 ? `${value.slice(0, 80)}...` : value;
+        return JSON.stringify(s);
+    }
+
+    if (isNumber(value) || isBoolean(value) || typeof value === "bigint") {
+        return String(value);
+    }
+
+    if (typeof value === "function") {
+        return "[Function]";
+    }
+
+    try {
+        const s = JSON.stringify(value);
+        if (typeof s === "string") {
+            return s.length > 120 ? `${s.slice(0, 120)}...` : s;
+        }
+    } catch {
+        // ignore
+    }
+
+    const s = String(value);
+    return s.length > 120 ? `${s.slice(0, 120)}...` : s;
+}
+
+/**
+ * 获取值的类型标识（数组/对象等做细分）。
+ */
+export function getTypeTag(value) {
+    if (value === null) return "null";
+    if (value === undefined) return "undefined";
+    if (Array.isArray(value)) return "array";
+
+    const t = typeof value;
+    if (t === "string") return "string";
+    if (t === "number") return "number";
+    if (t === "boolean") return "boolean";
+    if (t === "bigint") return "bigint";
+    if (t === "symbol") return "symbol";
+    if (t === "function") return "function";
+
+    return "object";
+}
+
+// 正则字符转义列表
+const REGEXP_SPECIAL = /[\^$.*+?()[\]{}|]/g;
+
+/**
+ * 转义字符串中的正则特殊字符。
+ */
+export function escapeRegExp(input) {
+    return String(input).replace(REGEXP_SPECIAL, "\\$&");
+}
+
+/**
+ * 归一化正整数：非法值回退，超出范围裁剪。
+ */
+export function normalizePositiveInt(value, fallback, min, max) {
+    if (!Number.isFinite(value)) return fallback;
+    const v = Math.floor(value);
+    if (v < min) return fallback;
+    if (v > max) return max;
+    return v;
+}
+
+/**
+ * 遍历 plain object 的自有字段。
+ */
+export function forOwn(obj, iteratee) {
+    if (typeof iteratee !== "function") {
+        return;
+    }
+
+    if (!isPlainObject(obj)) {
+        return;
+    }
+
+    const record = obj;
+    for (const key of Object.keys(record)) {
+        iteratee(record[key], key);
+    }
+}
+
+// 将字符串拆分为词段（用于 camelCase/snakeCase）
+function toWordParts(input) {
+    const normalized = String(input)
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[^a-zA-Z0-9]+/g, " ")
+        .trim();
+
+    if (normalized.length === 0) {
+        return [];
+    }
+
+    return normalized.split(/\s+/).filter((p) => p.length > 0);
+}
+
+// 首字母大写
+function upperFirst(s) {
+    if (s.length === 0) {
+        return s;
+    }
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/**
+ * 把字符串转为小驼峰。
+ * - 主要用于文件名/目录名（例如 my_plugin / my-plugin / my plugin）。
+ */
+export function camelCase(input) {
+    const parts = toWordParts(input);
+    if (parts.length === 0) {
+        return "";
+    }
+
+    const firstPart = parts[0];
+    if (!firstPart) {
+        return "";
+    }
+
+    const first = firstPart.toLowerCase();
+    const rest = parts.slice(1).map((p) => upperFirst(p.toLowerCase()));
+    return [first].concat(rest).join("");
+}
+
+// 归一化字符串为词序列
+function normalizeToWords(input) {
+    return String(input)
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[^a-zA-Z0-9]+/g, " ")
+        .trim();
+}
+
+/**
+ * 把字符串转为 snake_case。
+ * - 主要用于表名/字段名（例如 userId -> user_id）。
+ */
+export function snakeCase(input) {
+    const normalized = normalizeToWords(input);
+    if (normalized.length === 0) {
+        return "";
+    }
+
+    return normalized
+        .split(/\s+/)
+        .filter((p) => p.length > 0)
+        .map((p) => p.toLowerCase())
+        .join("_");
+}
+
+/**
+ * 对象字段名转小驼峰
+ * @param obj - 源对象
+ * @returns 字段名转为小驼峰格式的新对象
+ */
+export const keysToCamel = (obj) => {
+    if (!obj || !isPlainObject(obj)) return obj;
+
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const camelKey = camelCase(key);
+        result[camelKey] = value;
+    }
+    return result;
+};
+
+/**
+ * 对象字段名转下划线
+ * @param obj - 源对象
+ * @returns 字段名转为下划线格式的新对象
+ */
+export const keysToSnake = (obj) => {
+    if (!obj || !isPlainObject(obj)) return obj;
+
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const snakeKey = snakeCase(key);
+        result[snakeKey] = value;
+    }
+    return result;
+};
+
+/**
+ * 数组对象字段名批量转小驼峰
+ * @param arr - 源数组
+ * @returns 字段名转为小驼峰格式的新数组
+ */
+export const arrayKeysToCamel = (arr) => {
+    if (!arr || !Array.isArray(arr)) return arr;
+    return arr.map((item) => keysToCamel(item));
+};
+
+/**
+ * 根据点路径读取对象字段（不存在则返回 undefined）。
+ */
+export function getByPath(obj, path) {
+    if (!path) {
+        return obj;
+    }
+
+    const parts = path.split(".");
+    let cur = obj;
+
+    for (const part of parts) {
+        if (isNullable(cur)) {
+            return undefined;
+        }
+        if (typeof cur !== "object") {
+            return undefined;
+        }
+        const record = cur;
+        cur = record[part];
+    }
+
+    return cur;
+}
+
+/**
+ * 根据点路径写入对象字段（中间层自动补空对象）。
+ */
+export function setByPath(target, path, value) {
+    const parts = path.split(".");
+    // 避免无效 path（如 a..b）导致部分写入
+    for (const part of parts) {
+        if (!part) {
+            return;
+        }
+    }
+    let cur = target;
+
+    for (let i = 0; i < parts.length; i++) {
+        const key = parts[i];
+        if (!key) {
+            return;
+        }
+
+        const isLast = i === parts.length - 1;
+        if (isLast) {
+            cur[key] = value;
+            return;
+        }
+
+        const nextVal = cur[key];
+        if (!isPlainObject(nextVal)) {
+            cur[key] = {};
+        }
+
+        cur = cur[key];
+    }
+}
+
+/**
+ * 生成移除指定字段后的浅拷贝。
+ */
+export function omit(obj, keys) {
+    if (!isPlainObject(obj)) {
+        return {};
+    }
+
+    const keySet = new Set(Array.isArray(keys) ? keys : []);
+    const out = {};
+
+    for (const [k, v] of Object.entries(obj)) {
+        if (keySet.has(k)) {
+            continue;
+        }
+        out[k] = v;
+    }
+
+    return out;
+}
+
+/**
+ * 从对象中挑选指定字段。
+ */
+export const pickFields = (obj, keys) => {
+    if (!obj || (!isPlainObject(obj) && !Array.isArray(obj))) {
+        return {};
+    }
+
+    const record = obj;
+    const result = {};
+
+    for (const key of keys) {
+        if (key in record) {
+            result[key] = record[key];
+        }
+    }
+
+    return result;
+};
+
+/**
+ * 根据 key 生成对象映射。
+ */
+export function keyBy(items, getKey) {
+    const out = {};
+
+    if (!Array.isArray(items) || typeof getKey !== "function") {
+        return out;
+    }
+
+    for (const item of items) {
+        const key = getKey(item);
+        if (typeof key !== "string" || key === "") {
+            continue;
+        }
+        out[key] = item;
+    }
+
+    return out;
+}
+
+/**
+ * 生成短 ID
+ * 由时间戳（base36）+ 随机字符组成，约 13 位
+ * - 前 8 位：时间戳（可排序）
+ * - 后 5 位：随机字符（防冲突）
+ * @returns 短 ID 字符串
+ */
+export function genShortId() {
+    const timePart = Date.now().toString(36);
+    let rand = "";
+    while (rand.length < 10) {
+        rand = rand + Math.random().toString(36).slice(2);
+    }
+    return timePart + rand.slice(0, 10);
+}