@gateweb/react-utils 1.17.0 → 2.1.0

package/dist/es/index.mjs

@@ -1,10 +1,899 @@
-export { B as ByteSize, M as MimeTypeMap, O as OtherMimeType, c as convertBytes, g as createEnumLikeObject, z as debounce, d as decodeBase64, b as decodeJson, x as deepClone, w as deepMerge, e as encodeBase64, a as encodeJson, f as extractEnumLikeObject, h as fakeApi, D as getLocalStorage, j as getMimeType, l as invariant, i as isEqual, n as isServer, m as mergeConfig, o as objectToSearchParams, q as omit, r as omitByValue, k as parseFileInfoFromFilename, p as parseFilenameFromDisposition, t as pick, u as pickByValue, y as renameKey, s as searchParamsToObject, E as setLocalStorage, A as throttle, v as validateFileType, C as wait } from './webStorage-12s-gvD4qbeR.mjs';
 import dayjs from 'dayjs';
-export { Q as QueryProvider, u as useQueryContext } from './queryStore-12s-CFQTVwrg.mjs';
-import React, { useMemo, createContext, useContext, useState, useCallback } from 'react';
-export { u as useCountdown } from './useCountdown-12s-t52WIHfq.mjs';
-export { u as useDisclosure } from './useDisclosure-12s-BQAHpAXK.mjs';
-export { d as downloadFile } from './download-12s-CnaJ0p_f.mjs';
+
+/* 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$1 = [
+    '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$1.includes(unit)) {
+            console.warn(`Invalid unit: ${unit}. Valid units are: ${FILE_SIZE_UNITS$1.join(', ')}`);
+            return this.bytes;
+        }
+        const k = 1024;
+        const i = FILE_SIZE_UNITS$1.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$1.includes(unit) ? FILE_SIZE_UNITS$1.indexOf(unit) : Math.floor(Math.log(this.bytes) / Math.log(k));
+        return `${(this.bytes / k ** i).toFixed(decimals)} ${FILE_SIZE_UNITS$1[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';
+
+/**
+ * 深度走訪物件/陣列，將指定鍵名且值為字串的欄位遮罩為固定字串（預設 "******"）。
+ *
+ * - 預設僅遮罩鍵名等於 `password` 的欄位（區分大小寫）
+ * - 可傳入「字串鍵名」或「函式選擇器」來自訂要遮罩的欄位
+ * - 僅在值為字串時遮罩，其他型別維持原樣
+ * - 不變更輸入參考；回傳全新的資料結構
+ * - 函式選擇器會收到 `key`、`value` 與 `path`（到該鍵的路徑，陣列用索引）
+ * - 支援巢狀物件與陣列
+ *
+ * @param input - 來源資料
+ * @param mask - 遮罩字串，預設為 "******"
+ * @param selector - 欄位選擇器，字串或函式，預設 'password'
+ * @returns 回傳遮罩後的新資料
+ *
+ * @example
+ * const input = { password: 'secret', user: { password: 'abc' }, list: [{ password: 'x' }, { ok: 1 }] };
+ * const output = maskPasswords(input);
+ * // { password: '******', user: { password: '******' }, list: [{ password: '******' }, { ok: 1 }] }
+ *
+ * // 指定鍵名
+ * maskPasswords({ secret: 'xxx' }, '***', 'secret'); // { secret: '***' }
+ *
+ * // 使用函式選擇器（鍵名包含 'pass' 都遮）
+ * maskPasswords({ password: 'a', passcode: 'b' }, '***', (k) => k.includes('pass')); // { password: '***', passcode: '***' }
+ */ const maskPasswords = (input, mask = '******', selector = 'password')=>{
+    const isObject = (val)=>val !== null && typeof val === 'object' && !Array.isArray(val) && !(val instanceof Date);
+    const shouldMask = (key, value, path)=>{
+        if (typeof selector === 'string') {
+            return key === selector && typeof value === 'string';
+        }
+        return selector(key, value, path) && typeof value === 'string';
+    };
+    const walk = (val, path)=>{
+        if (val === null || val === undefined) return val;
+        if (Array.isArray(val)) {
+            return val.map((item, idx)=>walk(item, [
+                    ...path,
+                    idx
+                ]));
+        }
+        if (val instanceof Date) {
+            return new Date(val.getTime());
+        }
+        if (isObject(val)) {
+            const result = Object.entries(val).reduce((acc, [key, v])=>{
+                const nextPath = [
+                    ...path,
+                    key
+                ];
+                if (shouldMask(key, v, nextPath)) {
+                    return {
+                        ...acc,
+                        [key]: mask
+                    };
+                }
+                return {
+                    ...acc,
+                    [key]: walk(v, nextPath)
+                };
+            }, {});
+            return result;
+        }
+        return val;
+    };
+    return walk(input, []);
+};
+
+/**
+ * 將物件中的某些 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;
+};
 
 /**
  * convert CamelCase string to PascalCase string
@@ -495,100 +1384,6 @@ const FILE_SIZE_UNITS = [
  * }
  */ const isNil = (value)=>value === null || value === undefined;
 
-/**
- * Creates a strongly-typed React Context and Provider pair for data sharing.
- *
- * This utility helps you avoid prop drilling by providing a reusable way to define
- * context with strict type inference. It returns a custom hook for consuming the context
- * and a Provider component for supplying context values.
- *
- * @template T - The value type for the context.
- * @returns {object} An object containing:
- *   - useDataContext: A custom hook to access the context value. Throws an error if used outside the provider.
- *   - DataProvider: A Provider component to wrap your component tree and supply the context value.
- *
- * @example
- * // Example usage:
- * const { useDataContext, DataProvider } = createDataContext<{ count: number }>();
- *
- * function Counter() {
- *   const { count } = useDataContext();
- *   return <span>{count}</span>;
- * }
- *
- * function App() {
- *   return (
- *     <DataProvider value={{ count: 42 }}>
- *       <Counter />
- *     </DataProvider>
- *   );
- * }
- */ const createDataContext = ()=>{
-    const Context = /*#__PURE__*/ createContext(undefined);
-    const useDataContext = ()=>{
-        const context = useContext(Context);
-        if (context === undefined) {
-            throw new Error(`useDataContext must be used within a DataProvider`);
-        }
-        return context;
-    };
-    const DataProvider = ({ children, value })=>{
-        const memoized = useMemo(()=>value, [
-            value
-        ]);
-        return /*#__PURE__*/ React.createElement(Context.Provider, {
-            value: memoized
-        }, children);
-    };
-    return {
-        useDataContext,
-        DataProvider
-    };
-};
-
-/**
- * A hook to manage a value.
- *
- * @example
- *
- * ```tsx
- * const MyComponent = ({ value }: { value?: number }) => {
- *    const [currentValue, setCurrentValue] = useValue({ value });
- * };
- * ```
- */ const useValue = ({ value, defaultValue })=>{
-    if (value === undefined && defaultValue === undefined) {
-        throw new Error('Either `value` or `defaultValue` must be provided.');
-    }
-    const isControlled = value !== undefined;
-    const [internalValue, setInternalValue] = useState(defaultValue);
-    const setValue = useCallback((newValue)=>{
-        if (!isControlled) {
-            setInternalValue(newValue);
-        }
-    }, [
-        isControlled
-    ]);
-    const currentValue = isControlled ? value : internalValue;
-    return [
-        currentValue,
-        setValue
-    ];
-};
-
-function mergeRefs(refs) {
-    return (value)=>{
-        refs.forEach((ref)=>{
-            if (typeof ref === 'function') {
-                ref(value);
-            } else if (ref != null) {
-                // eslint-disable-next-line no-param-reassign
-                ref.current = value;
-            }
-        });
-    };
-}
-
 /**
  * 民國年轉西元年
  * @param dateString 日期字串
@@ -670,4 +1465,4 @@ function mergeRefs(refs) {
     return dayjs(endMonth, 'YYYYMM').subtract(1911, 'year').format('YYYYMM').substring(1);
 };
 
-export { adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, createDataContext, formatAmount, formatBytes, formatStarMask, generatePeriodArray, getCurrentPeriod, isChinese, isDateString, isDateTimeString, isEmail, isEnglish, isNil, isNonZeroStart, isNumber, isNumberAtLeastN, isNumberN, isNumberNM, isTWMobile, isTWPhone, isTimeString, isValidPassword, maskString, mergeRefs, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, rocEraToAd, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, useValue, validTaxId, validateDateString };
+export { ByteSize, MimeTypeMap, OtherMimeType, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, convertBytes, createEnumLikeObject, debounce, decodeBase64, decodeJson, deepClone, deepMerge, encodeBase64, encodeJson, extractEnumLikeObject, fakeApi, formatAmount, formatBytes, formatStarMask, generatePeriodArray, getCurrentPeriod, getMimeType, invariant, isChinese, isDateString, isDateTimeString, isEmail, isEnglish, isEqual, isNil, isNonZeroStart, isNumber, isNumberAtLeastN, isNumberN, isNumberNM, isServer, isTWMobile, isTWPhone, isTimeString, isValidPassword, maskPasswords, maskString, mergeConfig, objectToSearchParams, omit, omitByValue, parseFileInfoFromFilename, parseFilenameFromDisposition, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, renameKey, rocEraToAd, searchParamsToObject, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, validTaxId, validateDateString, validateFileType, wait };