@gateweb/react-utils 1.15.0 → 1.17.0

package/dist/es/webStorage-12s-gvD4qbeR.mjs

@@ -0,0 +1,879 @@
+'use client';
+/* eslint-disable no-bitwise */ const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/**
+ * 將位元組陣列編碼為 base64 字串
+ *
+ * @param bytes 要編碼的位元組陣列
+ * @returns base64 編碼的字串
+ *
+ * @example
+ * ```ts
+ * const bytes = new TextEncoder().encode('Hello World');
+ * const encoded = encodeBase64(bytes);
+ * console.log(encoded); // 'SGVsbG8gV29ybGQ='
+ * ```
+ */ const encodeBase64 = (bytes)=>{
+    let out = '';
+    for(let i = 0; i < bytes.length; i += 3){
+        const n = bytes[i] << 16 | (bytes[i + 1] || 0) << 8 | (bytes[i + 2] || 0);
+        out += chars[n >> 18 & 63] + chars[n >> 12 & 63] + (i + 1 < bytes.length ? chars[n >> 6 & 63] : '=') + (i + 2 < bytes.length ? chars[n & 63] : '=');
+    }
+    return out;
+};
+/**
+ * 將 base64 字串解碼為位元組陣列
+ *
+ * @param base64 要解碼的 base64 字串（支援 base64url 格式）
+ * @returns 解碼後的位元組陣列
+ *
+ * @example
+ * ```ts
+ * const decoded = decodeBase64('SGVsbG8gV29ybGQ=');
+ * const text = new TextDecoder().decode(decoded);
+ * console.log(text); // 'Hello World'
+ * ```
+ */ const decodeBase64 = (base64)=>{
+    let out = base64.replace(/-/g, '+').replace(/_/g, '/'); // 支援 base64url
+    while(out.length % 4)out += '='; // 自動補 "="
+    const buffer = [];
+    for(let i = 0; i < out.length; i += 4){
+        const n = chars.indexOf(out[i]) << 18 | chars.indexOf(out[i + 1]) << 12 | (chars.indexOf(out[i + 2]) & 63) << 6 | chars.indexOf(out[i + 3]) & 63;
+        buffer.push(n >> 16 & 255);
+        if (out[i + 2] !== '=') buffer.push(n >> 8 & 255);
+        if (out[i + 3] !== '=') buffer.push(n & 255);
+    }
+    return new Uint8Array(buffer);
+};
+/**
+ * 將 JSON 資料編碼為 base64 字串
+ *
+ * @param data 要編碼的 JSON 可序列化資料
+ * @returns base64 編碼的字串
+ *
+ * @example
+ * ```ts
+ * const data = { name: 'John', age: 30 };
+ * const encoded = encodeJson(data);
+ * console.log(encoded); // 'eyJuYW1lIjoiSm9obiIsImFnZSI6MzB9'
+ *
+ * const array = [1, 2, 3];
+ * const encodedArray = encodeJson(array);
+ * ```
+ */ const encodeJson = (data)=>{
+    const json = JSON.stringify(data);
+    return encodeBase64(new TextEncoder().encode(json));
+};
+/**
+ * 將 base64 字串解碼為 JSON 資料
+ *
+ * @param b64 要解碼的 base64 字串
+ * @returns 解碼後的資料
+ *
+ * @example
+ * ```ts
+ * const encoded = 'eyJuYW1lIjoiSm9obiIsImFnZSI6MzB9';
+ * const decoded = decodeJson<{ name: string; age: number }>(encoded);
+ * console.log(decoded); // { name: 'John', age: 30 }
+ *
+ * const decodedArray = decodeJson<number[]>(encodedArray);
+ * ```
+ */ const decodeJson = (b64)=>{
+    const json = new TextDecoder().decode(decodeBase64(b64));
+    return JSON.parse(json);
+};
+
+const FILE_SIZE_UNITS = [
+    'Bytes',
+    'KB',
+    'MB',
+    'GB',
+    'TB',
+    'PB',
+    'EB',
+    'ZB',
+    'YB'
+];
+/**
+ * 代表字節大小的類，提供各種格式化和轉換方法
+ */ class ByteSize {
+    /**
+   * 建立一個新的 ByteSize 實例
+   * @param bytes 位元組數值
+   */ constructor(bytes){
+        this.bytes = bytes;
+    }
+    /**
+   * 取得原始位元組數值
+   */ get value() {
+        return this.bytes;
+    }
+    /**
+   * 將位元組轉換為指定單位的數值
+   *
+   * @param unit 目標單位 (例如 'KB', 'MB', 'GB')
+   * @returns 轉換後的數值
+   *
+   * @example
+   * ```ts
+   * const size = createByteSize(1024);
+   * size.to('KB'); // 1
+   * size.to('MB'); // 0.0009765625
+   * ```
+   */ to(unit) {
+        if (!FILE_SIZE_UNITS.includes(unit)) {
+            console.warn(`Invalid unit: ${unit}. Valid units are: ${FILE_SIZE_UNITS.join(', ')}`);
+            return this.bytes;
+        }
+        const k = 1024;
+        const i = FILE_SIZE_UNITS.indexOf(unit);
+        return this.bytes / k ** i;
+    }
+    /**
+   * 轉換為適當單位的可讀字符串
+   *
+   * @param unit 指定單位 (例如 'KB', 'MB', 'GB')，不指定則自動選擇最適合的單位
+   * @param decimals 小數點位數 (預設為 2)
+   * @returns 格式化後的字符串
+   *
+   * @example
+   * ```ts
+   * const size = createByteSize(1024);
+   * size.format(); // '1.00 KB'
+   * size.format('KB'); // '1.00 KB'
+   * size.format('MB', 3); // '0.001 MB'
+   * ```
+   */ format(unit, decimals = 2) {
+        if (this.bytes === 0) return `0 ${unit || 'Bytes'}`;
+        const k = 1024;
+        // 如果指定了有效單位，則使用；否則，計算最適合的單位
+        const i = unit && FILE_SIZE_UNITS.includes(unit) ? FILE_SIZE_UNITS.indexOf(unit) : Math.floor(Math.log(this.bytes) / Math.log(k));
+        return `${(this.bytes / k ** i).toFixed(decimals)} ${FILE_SIZE_UNITS[i]}`;
+    }
+    /**
+   * 比較兩個 ByteSize 實例
+   *
+   * @param other 要比較的另一個 ByteSize 實例
+   * @returns 比較結果：-1 表示小於，0 表示等於，1 表示大於
+   */ compareTo(other) {
+        if (this.bytes < other.value) return -1;
+        if (this.bytes > other.value) return 1;
+        return 0;
+    }
+    /**
+   * 轉換為字符串表示
+   * @returns 預設格式化的字符串
+   */ toString() {
+        return this.format();
+    }
+}
+/**
+ * 將位元組轉換為可讀字符串 (保留舊的 API 以確保向後兼容)
+ *
+ * @param bytes 位元組數值
+ * @param unit 目標單位 (例如 'KB', 'MB', 'GB')，不指定則自動選擇最適合的單位
+ * @param decimals 小數點位數 (預設為 2)
+ * @returns 格式化後的字符串
+ *
+ * @example
+ * ```ts
+ * convertBytes(0) // '0 Bytes'
+ * convertBytes(1024, 'KB') // '1 KB'
+ * convertBytes(1024, 'KB', 2) // '1.00 KB'
+ * convertBytes(1024 * 1024, 'MB') // '1 MB'
+ * convertBytes(1024 * 1024, 'KB') // '1024 KB'
+ * ```
+ */ const convertBytes = (bytes, unit, decimals = 2)=>new ByteSize(bytes).format(unit, decimals);
+
+/**
+ * 檢查兩個值是否相等（包含陣列等引用型別）
+ * - 支援基本型別的直接比較
+ * - 特別處理空陣列比較
+ * - 支援非空陣列的深度比較
+ *
+ * @param value1 - 第一個值
+ * @param value2 - 第二個值
+ * @returns 如果值相等則返回 true
+ *
+ * @example
+ * // 基本型別比較
+ * isEqual(1, 1); // true
+ * isEqual('abc', 'abc'); // true
+ * isEqual(null, null); // true
+ *
+ * // 陣列比較
+ * isEqual([], []); // true
+ * isEqual([1, 2], [1, 2]); // true
+ * isEqual([1, 2], [1, 3]); // false
+ */ const isEqual = (value1, value2)=>{
+    // 處理基本型別
+    if (value1 === value2) {
+        return true;
+    }
+    // 處理空陣列
+    if (Array.isArray(value1) && Array.isArray(value2) && value1.length === 0 && value2.length === 0) {
+        return true;
+    }
+    // 兩者都是非 null 的物件（包含陣列）
+    if (value1 !== null && value2 !== null && typeof value1 === 'object' && typeof value2 === 'object') {
+        // 處理非空陣列
+        if (Array.isArray(value1) && Array.isArray(value2)) {
+            if (value1.length !== value2.length) {
+                return false;
+            }
+            return value1.every((item, index)=>isEqual(item, value2[index]));
+        }
+    // 未來可以擴展這裡，增加其他物件型別的深度比較
+    }
+    return false;
+};
+
+/**
+ * 將指定格式的物件轉換成類似 enum 的物件
+ *
+ * @param enumObject enum 物件
+ * @param valueKey value 的 key
+ *
+ * @example
+ * const myObj = {
+ *   A: { value: 'a' },
+ *   B: { value: 'b', other: 'other' },
+ * } as const;
+ * const enumCode = extractEnumLikeObject(myObj, 'value');
+ * // => { A: 'a', B: 'b' }
+ */ const extractEnumLikeObject = (enumObject, valueKey)=>Object.entries(enumObject).reduce((acc, [key, value])=>({
+            ...acc,
+            [key]: value[valueKey]
+        }), {});
+// 實作
+function createEnumLikeObject(obj, options) {
+    const name = options?.name;
+    const scene = options?.scene;
+    const valueKey = options?.valueKey ?? 'value';
+    const Enum = extractEnumLikeObject(obj, valueKey);
+    // List：根據有無 scene 做不同處理
+    let list;
+    if (scene) {
+        // scenes 版本：解構指定 scene 的 label
+        list = Object.entries(obj).map(([key, item])=>({
+                key,
+                value: item?.[valueKey],
+                ...item.scenes?.[scene] ?? {}
+            }));
+    } else {
+        // label only 版本
+        list = Object.entries(obj).map(([key, item])=>({
+                key,
+                value: item?.[valueKey],
+                ...item
+            }));
+    }
+    function getLabel(value) {
+        const targetItem = list.find((item)=>// 如果 list 項目內含有 valueKey 對應欄位，優先以該欄位比對；否則以 value 欄位比對
+            valueKey in item ? item[valueKey] === value : item.value === value);
+        if (!targetItem) return String(value);
+        if ('label' in targetItem) return targetItem.label;
+        return String(value);
+    }
+    if (name) {
+        // 命名版：使用 Enum${name}, ${name}List, get${name}Label 鍵名
+        return {
+            [`Enum${name}`]: Enum,
+            [`${name}List`]: list,
+            [`get${name}Label`]: getLabel
+        };
+    }
+    // 未命名：提供預設鍵名 Enum, List, getLabel
+    return {
+        Enum,
+        List: list,
+        getLabel
+    };
+}
+
+/**
+ * simulate a fake api request
+ *
+ * @param returnValue the value to return
+ * @param result the result of the request
+ * @param time the time to wait before resolving
+ *
+ * @example
+ *
+ * const result = await fakeApi({ foo: 'bar' });
+ * console.log(result); // { result: true, data: { foo: 'bar' } }
+ */ const fakeApi = (returnValue, result = true, time = 1000)=>new Promise((resolve)=>{
+        setTimeout(()=>{
+            if (result) resolve({
+                result,
+                data: returnValue
+            });
+            else resolve({
+                result,
+                message: 'error'
+            });
+        }, time);
+    });
+
+const MimeTypeMap = {
+    jpeg: 'image/jpeg',
+    jpg: 'image/jpeg',
+    gif: 'image/gif',
+    png: 'image/png',
+    pdf: 'application/pdf',
+    zip: 'application/zip',
+    csv: 'text/csv',
+    ppt: 'application/vnd.ms-powerpoint',
+    pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    xls: 'application/vnd.ms-excel',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    doc: 'application/msword',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    txt: 'text/plain'
+};
+const OtherMimeType = 'application/octet-stream';
+
+/**
+ * 檢查檔案是否為合法的檔案類型
+ *
+ * `accepts` 可同時接受副檔名以及 MIME 類型
+ *
+ * @param file 檔案
+ * @param accepts 允許的類型
+ *
+ * @example
+ *
+ * ```js
+ * validateFileType({ type: 'image/png' }, ['image/png', 'image/jpeg']) // true
+ * validateFileType({ type: 'image/png' }, ['image/jpeg']) // false
+ * validateFileType({ type: 'image/png' }, ['image/*']) // true
+ * validateFileType({ name: '圖片.png', type: 'image/png' }, ['.png']) // true
+ * ```
+ */ const validateFileType = (file, accepts)=>{
+    if (accepts.length === 0) return true;
+    // 獲取文件的MIME類型
+    const fileMimeType = file.type;
+    // 提取副檔名（含 .，且轉小寫）
+    const fileExt = file.name.includes('.') ? `.${file.name.split('.').pop().toLowerCase()}` : '';
+    return accepts.some((accept)=>{
+        if (accept.startsWith('.')) {
+            // 以副檔名檢查，忽略大小寫
+            return fileExt === accept.toLowerCase();
+        }
+        if (accept === fileMimeType) {
+            return true;
+        }
+        if (accept.endsWith('/*')) {
+            return accept.split('/')[0] === fileMimeType.split('/')[0];
+        }
+        return false;
+    });
+};
+/**
+ * 根據檔案副檔名取得對應的 MIME Type
+ *
+ * 目前支援的副檔名有：pdf, csv, jpeg, jpg, png, zip, txt
+ * 除此之外的副檔名皆回傳 application/octet-stream
+ *
+ * @param fileExtension 檔案副檔名
+ *
+ * @example
+ *
+ * getMimeType('pdf') // 'application/pdf'
+ * getMimeType('csv') // 'text/csv'
+ * getMimeType('jpeg') // 'image/jpeg'
+ * getMimeType('jpg') // 'image/jpeg'
+ * getMimeType('png') // 'image/png'
+ * getMimeType('txt') // 'text/plain'
+ * getMimeType('zip') // 'application/zip'
+ * getMimeType('mp4') // 'application/octet-stream'
+ * getMimeType('xls') // 'application/vnd.ms-excel'
+ * getMimeType('xlsx') // 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+ * getMimeType('doc') // 'application/msword'
+ * getMimeType('docx') // 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+ *
+ * @deprecated use `parseFileInfoFromFilename` instead
+ */ const getMimeType = (fileName)=>{
+    const ext = (fileName.split('.').pop() || '').toLowerCase();
+    return MimeTypeMap[ext] ?? OtherMimeType;
+};
+/**
+ * 用來解析後端在 response header content-disposition 的內容
+ *
+ * 一般來說格式會有以下兩種
+ *
+ * - Content-Disposition: attachment; filename="file name.jpg"
+ * - Content-Disposition: attachment; filename*=UTF-8''file%20name2.jpg
+ *
+ * 如果格式正確就會取得檔案名稱(包含副檔名)，優先取 filename* 內的內容
+ *
+ * @param disposition Content-Disposition
+ *
+ * @example
+ *
+ * parseFilenameFromDisposition('attachment; filename="file name1.jpg') // file name.jpg
+ * parseFilenameFromDisposition('attachment; filename*=UTF-8''file%20name2.jpg') // file name2.jpg
+ * parseFilenameFromDisposition('attachment; filename="file name.jpg; filename*=UTF-8''file%20name2.jpg') // file name2.jpg
+ */ const parseFilenameFromDisposition = (disposition)=>{
+    // 1. 先找 filename*
+    const filenameStarMatch = disposition.match(/filename\*\s*=\s*(?:UTF-8'')?([^;]+)/i);
+    if (filenameStarMatch && filenameStarMatch[1]) {
+        // 依 RFC 5987 格式（UTF-8''URL-ENCODED），要先 decode
+        try {
+            return decodeURIComponent(filenameStarMatch[1].replace(/(^['"]|['"]$)/g, ''));
+        } catch  {
+            // fallback，如果 decode 失敗，直接傳回原值
+            return filenameStarMatch[1];
+        }
+    }
+    // 2. 沒有 filename*，再找 filename
+    const filenameMatch = disposition.match(/filename\s*=\s*("?)([^";]+)\1/i);
+    if (filenameMatch && filenameMatch[2]) {
+        return filenameMatch[2];
+    }
+    // 3. 都沒有則 undefined
+    return undefined;
+};
+/**
+ * 解析 `filename` 回傳檔名、副檔名、MIME type
+ *
+ * @param filename 檔案名稱
+ *
+ * @example
+ *
+ * parseFileInfoFromFilename('image.jpg') // ['image', 'jpg', 'image/jpeg']
+ * parseFileInfoFromFilename('image') // ['image', '', 'application/octet-stream']
+ */ const parseFileInfoFromFilename = (filename)=>{
+    const lastDot = filename.lastIndexOf('.');
+    if (lastDot === -1) return [
+        filename,
+        '',
+        OtherMimeType
+    ]; // 沒有副檔名
+    return [
+        filename.slice(0, lastDot),
+        filename.slice(lastDot + 1),
+        MimeTypeMap[filename.slice(lastDot + 1)] ?? OtherMimeType
+    ];
+};
+
+// const isProduction: boolean = process.env.NODE_ENV === 'production';
+const prefix = 'Invariant failed';
+// Throw an error if the condition fails
+// Strip out error messages for production
+// > Not providing an inline default argument for message as the result is smaller
+function invariant(condition, // Can provide a string, or a function that returns a string for cases where
+// the message takes a fair amount of effort to compute
+message) {
+    if (condition) {
+        return;
+    }
+    // Condition not passed
+    // In production we strip the message but still throw
+    if (process.env.NODE_ENV === 'production') {
+        throw new Error(prefix);
+    }
+    // When not in production we allow the message to pass through
+    // *This block will be removed in production builds*
+    const provided = typeof message === 'function' ? message() : message;
+    // Options:
+    // 1. message provided: `${prefix}: ${provided}`
+    // 2. message not provided: prefix
+    const value = provided ? `${prefix}: ${provided}` : prefix;
+    throw new Error(value);
+}
+
+/**
+ * 判斷執行環境是否為 Server(node.js) 端
+ */ const isServer = ()=>typeof window === 'undefined';
+
+/**
+ * 將物件中的某些 key 排除
+ *
+ * @param object 原始物件
+ * @param keys 要排除的 key
+ *
+ * @example
+ * const a = { a: 1, b: 2, c: 3, d: 4 };
+ * const b = omit(a, 'a', 'b'); // { c: 3, d: 4 }
+ */ const omit = (object, ...keys)=>Object.keys(object).reduce((acc, cur)=>{
+        if (keys.includes(cur)) {
+            return acc;
+        }
+        return {
+            ...acc,
+            [cur]: object[cur]
+        };
+    }, {});
+/**
+ * 將物件中的某些 value 排除
+ *
+ * @param object 原始物件
+ * @param values 要排除的 value
+ *
+ * @example
+ * const a = { a: undefined, b: null, c: 3, d: 4, e: [] };
+ * const b = omitByValue(a, undefined, null, []); // { c: 3, d: 4 }
+ */ const omitByValue = (object, ...values)=>Object.entries(object).reduce((acc, [key, value])=>{
+        // 使用深度比較檢查值是否應該被排除
+        const shouldOmit = values.some((excludeValue)=>isEqual(value, excludeValue));
+        if (shouldOmit) {
+            return acc;
+        }
+        return {
+            ...acc,
+            [key]: value
+        };
+    }, {});
+/**
+ * extract the object fields by the given keys
+ *
+ * @param object - the object to pick fields from
+ * @param keys - the keys to pick
+ *
+ * @example
+ *
+ * const a = { a: 1, b: 2, c: 3, d: 4 };
+ * const b = pick(a, 'a', 'b'); // { a: 1, b: 2 }
+ */ const pick = (object, ...keys)=>keys.reduce((acc, cur)=>({
+            ...acc,
+            [cur]: object[cur]
+        }), {});
+/**
+ * extract the object fields by the given values
+ *
+ * @param object - the object to pick fields from
+ * @param values - the values to pick
+ *
+ * @example
+ *
+ * const a = { a: 1, b: 2, c: 3, d: 4, e: [] };
+ * const b = pickByValue(a, 1, 2, []); // { a: 1, b: 2, e: [] }
+ */ const pickByValue = (object, ...values)=>Object.entries(object).reduce((acc, [key, value])=>{
+        // 使用深度比較檢查值是否應該被選擇
+        const shouldPick = values.some((pickValue)=>isEqual(value, pickValue));
+        if (shouldPick) {
+            return {
+                ...acc,
+                [key]: value
+            };
+        }
+        return acc;
+    }, {});
+const isObject = (value)=>value !== null && typeof value === 'object';
+/**
+ * merge two objects deeply
+ *
+ * @param target - the target object
+ * @param source - the source object
+ *
+ * @example
+ *
+ * const obja = { a: { a1: { a11: 'value 1', a12: 'value 2' }, a2: 'value 3' }, b: 'value 4' };
+ * const objb = { a: { a1: { a13: 'value 5', a14: 'value 6' }, a3: 'value 7' }};
+ *
+ * const mergeResult = deepMerge(obja, objb); // { a: { a1: { a11: 'value 1', a12: 'value 2', a13: 'value 5', a14: 'value 6' }, a2: 'value 3', a3: 'value 7' }, b: 'value 4' }
+ *
+ */ const deepMerge = (target, source)=>Object.entries(source).reduce((acc, [key, value])=>{
+        if (isObject(value)) {
+            acc[key] = key in target && isObject(target[key]) ? deepMerge(target[key], value) : value;
+        } else {
+            acc[key] = value;
+        }
+        return acc;
+    }, {
+        ...target
+    });
+/**
+ * A utility function to deeply clone an object.
+ * @param obj - The object to clone.
+ *
+ * @example
+ *
+ * const original = { a: 1, b: { c: 2 } };
+ * const cloned = deepClone(original);
+ * console.log(cloned); // { a: 1, b: { c: 2 } }
+ *
+ */ const deepClone = (obj)=>{
+    if (obj === null || typeof obj !== 'object') {
+        return obj;
+    }
+    if (obj instanceof Date) {
+        return new Date(obj.getTime());
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item)=>deepClone(item));
+    }
+    const cloned = Object.keys(obj).reduce((acc, key)=>{
+        acc[key] = deepClone(obj[key]);
+        return acc;
+    }, {});
+    return cloned;
+};
+/**
+ * A utility function to rename a key in an object.
+ *
+ * @param obj - The object to modify.
+ * @param oldKey - The key to rename.
+ * @param newKey - The new key name.
+ *
+ * @example
+ *
+ * const obj = { a: 1, b: 2 };
+ * const newObj = renameKey(obj, 'a', 'c');
+ * console.log(newObj); // { c: 1, b: 2 }
+ */ const renameKey = (obj, oldKey, newKey)=>{
+    // 建立一個淺拷貝，避免修改原始物件
+    const { [oldKey]: oldValue, ...rest } = obj;
+    // 回傳新的物件：用新 key 存舊值，其他 key 保留
+    return {
+        ...rest,
+        [newKey]: oldValue
+    };
+};
+
+/**
+ * 將嵌套物件的所有屬性設為指定的布林值
+ * @param obj - 目標物件
+ * @param boolValue - 布林值
+ *
+ * @example
+ * const obj = { a: { b: 1, c: 2 }, d: 3 };
+ * const result = setBooleanToNestedObject(obj, true);
+ * console.log(result); // { a: { b: true, c: true }, d: true }
+ */ const setBooleanToNestedObject = (obj, boolValue)=>Object.entries(obj).reduce((acc, [key, value])=>{
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            // 如果是嵌套物件，遞歸處理
+            acc[key] = setBooleanToNestedObject(value, boolValue);
+        } else {
+            // 如果是基本類型，設為布林值
+            acc[key] = boolValue;
+        }
+        return acc;
+    }, {});
+/**
+ * 深度合併配置物件的通用工具
+ *
+ * @param defaultConfig - 預設配置
+ * @param customConfig - 自訂配置
+ *
+ * @example
+ * const defaultConfig = { a: true, b: { b1: true, b2: true, b3: false }, c: true, d: false };
+ * mergeConfig(defaultConfig, { b: { b1: false }, d: true }); // { a: true, b: { b1: false, b2: true, b3: false }, c: true, d: true }
+ * mergeConfig(defaultConfig, { b: false }); // { a: true, b: { b1: false, b2: false, b3: false }, c: true, d: false }
+ * mergeConfig(defaultConfig, { b: true }); // { a: true, b: { b1: true, b2: true, b3: true }, c: true, d: false }
+ */ const mergeConfig = (defaultConfig, customConfig = {})=>{
+    // 深拷貝預設配置以避免修改原始物件
+    const result = deepClone(defaultConfig);
+    return Object.entries(customConfig).reduce((acc, [key, sourceValue])=>{
+        const targetValue = acc[key];
+        // 如果來源值為 null 或 undefined，跳過
+        if (sourceValue === null || sourceValue === undefined) {
+            return acc;
+        }
+        // 如果目標物件中對應的值是物件，且來源值是布林值
+        // 這是特殊情況：用布林值覆蓋整個嵌套物件
+        if (typeof targetValue === 'object' && targetValue !== null && !Array.isArray(targetValue) && typeof sourceValue === 'boolean') {
+            // 將嵌套物件的所有屬性設為該布林值
+            acc[key] = setBooleanToNestedObject(targetValue, sourceValue);
+        } else if (typeof targetValue === 'object' && targetValue !== null && !Array.isArray(targetValue) && typeof sourceValue === 'object' && sourceValue !== null && !Array.isArray(sourceValue)) {
+            acc[key] = mergeConfig(targetValue, sourceValue);
+        } else {
+            acc[key] = sourceValue;
+        }
+        return acc;
+    }, result);
+};
+
+/**
+ * debounce function
+ *
+ * @param {Function} fn function to be executed
+ * @param {number} delay time to wait before executing the function
+ *
+ * @example
+ * const debouncedFunction = debounce((a: number, b: number) => console.log(a + b), 1000);
+ * debouncedFunction(1, 2);
+ * debouncedFunction(3, 4);
+ * // after 1 second
+ * // 7
+ */ const debounce = (fn, delay)=>{
+    let timeout;
+    // if (isAsync) {
+    //   return (...args: P[]) =>
+    //     new Promise((resolve) => {
+    //       if (timeout) {
+    //         clearTimeout(timeout);
+    //       }
+    //       timeout = setTimeout(() => {
+    //         resolve(fn(...args));
+    //       }, delay);
+    //     });
+    // }
+    return (...args)=>{
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+        timeout = setTimeout(()=>{
+            fn(...args);
+        }, delay);
+    };
+};
+/**
+ * throttle function
+ *
+ * @param {Function} fn function to be executed
+ * @param {number} delay time to wait before executing the function
+ *
+ * @example
+ * const throttledFunction = throttle((a: number, b: number) => a + b, 1000);
+ * throttledFunction(1, 2); // 3
+ * throttledFunction(3, 4); // undefined
+ * setTimeout(() => {
+ *  throttledFunction(5, 6); // 11
+ * }, 2000);
+ */ const throttle = (fn, delay)=>{
+    let wait = false;
+    return (...args)=>{
+        if (wait) return undefined;
+        const val = fn(...args);
+        wait = true;
+        setTimeout(()=>{
+            wait = false;
+        }, delay);
+        return val;
+    };
+};
+
+/**
+ * Wait for a given amount of time
+ * @param ms time to wait in milliseconds
+ */ const wait = (ms)=>{
+};
+
+/**
+ * 將單層物件轉換為 URLSearchParams 物件
+ * - 會自動排除 null、undefined、空字串和空陣列的值
+ * - 陣列會以逗號連接為字串
+ *
+ * @param obj - 要轉換的物件，只支援單層物件，其中值可以是 string、number、boolean、null、undefined 或字串陣列
+ * @returns URLSearchParams 實例
+ *
+ * @example
+ * const params = { a: '1', b: 123, c: false, d: ['1','2'], e: null, f: undefined, g: '', h: [] };
+ * objectToSearchParams(params).toString(); // 'a=1&b=123&c=false&d=1%2C2'
+ */ const objectToSearchParams = (obj)=>{
+    const searchParams = new URLSearchParams();
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+        return searchParams;
+    }
+    Object.entries(omitByValue(obj, undefined, null, '', [])).forEach(([key, value])=>{
+        // 如果是陣列，則以逗號連接
+        const paramValue = Array.isArray(value) ? value.join(',') : String(value);
+        searchParams.append(key, paramValue);
+    });
+    return searchParams;
+};
+/**
+ * 將字串值轉換為指定的型別
+ *
+ * @param value - 要轉換的字串值
+ * @param targetType - 目標型別
+ * @returns 轉換後的值
+ */ const convertValueByType = (value, targetType)=>{
+    switch(targetType){
+        case 'number':
+            return value ? Number(value) : 0;
+        case 'boolean':
+            return value === 'true' || value === '1';
+        case 'array':
+            return value ? value.split(',') : [];
+        case 'string':
+        default:
+            // 預設為字串，不需要轉換
+            return value;
+    }
+};
+/**
+ * 將 URLSearchParams 或字串轉換為物件
+ *
+ * @param searchParams - 要轉換的搜尋參數字串或 URLSearchParams 實例
+ * @param typeMap - 可選的型別轉換映射表，用於指定每個參數的目標型別
+ * @returns
+ *
+ * @example
+ * const queryString = 'a=1&b=123&c=true&d=1,2,3&e=false';
+ * const result = searchParamsToObject(queryString);
+ * // result: { a: '1', b: '123', c: 'true', d: '1,2,3', e: 'false' }
+ * const result = searchParamsToObject(queryString, {
+ *   a: 'string',
+ *   b: 'number',
+ *   c: 'boolean',
+ *   d: 'array',
+ *   e: 'boolean',
+ * });
+ * // result: { a: '1', b: 123, c: true, d: ['1', '2', '3'], e: false }
+ */ const searchParamsToObject = (searchParams, typeMap = {})=>{
+    const searchParamsInstance = typeof searchParams === 'string' ? new URLSearchParams(searchParams) : searchParams;
+    const result = {};
+    // 從 URLSearchParams 取得所有參數
+    searchParamsInstance.forEach((value, key)=>{
+        if (!key) {
+            return;
+        }
+        const targetType = typeMap[key];
+        result[key] = convertValueByType(value, targetType);
+    });
+    return result;
+};
+
+/**
+ * 從 localStorage 取得資料，支援槽狀取值(Json 物件)
+ *
+ * @param key 鍵值
+ * @param deCode 是否解碼
+ * @returns 取得的資料
+ * @example
+ * const data = getLocalStorage('key');
+ *
+ * const data = getLocalStorage('key.subKey');
+ */ const getLocalStorage = (key, deCode = true)=>{
+    const keys = key.split('.');
+    const storage = localStorage.getItem(keys[0]);
+    if (!storage) return undefined;
+    let currentObject;
+    try {
+        if (deCode) {
+            currentObject = decodeJson(storage);
+        } else {
+            currentObject = JSON.parse(storage);
+        }
+    } catch (_error) {
+        return undefined;
+    }
+    // let currentObject = JSON.parse(storage);
+    if (keys.length === 1) {
+        return currentObject;
+    }
+    keys.shift();
+    while(keys.length > 0){
+        const currentKey = keys.shift();
+        if (!currentKey) break;
+        currentObject = currentObject[currentKey];
+        if (!currentObject) break;
+    }
+    return currentObject;
+};
+/**
+ * 將資料(Json 物件)存入 localStorage
+ * @param key 鍵值
+ * @param value 可序列化的資料
+ * @param enCode 是否編碼
+ */ const setLocalStorage = (key, value, enCode = true)=>{
+    if (enCode) {
+        localStorage.setItem(key, encodeJson(value));
+    } else {
+        localStorage.setItem(key, JSON.stringify(value));
+    }
+};
+
+export { throttle as A, ByteSize as B, wait as C, getLocalStorage as D, setLocalStorage as E, MimeTypeMap as M, OtherMimeType as O, encodeJson as a, decodeJson as b, convertBytes as c, decodeBase64 as d, encodeBase64 as e, extractEnumLikeObject as f, createEnumLikeObject as g, fakeApi as h, isEqual as i, getMimeType as j, parseFileInfoFromFilename as k, invariant as l, mergeConfig as m, isServer as n, objectToSearchParams as o, parseFilenameFromDisposition as p, omit as q, omitByValue as r, searchParamsToObject as s, pick as t, pickByValue as u, validateFileType as v, deepMerge as w, deepClone as x, renameKey as y, debounce as z };