@gateweb/react-utils 1.7.1 → 1.9.0

package/dist/cjs/index.js

@@ -1,9 +1,9 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var dayjs = require('dayjs');
+var queryStoreClient = require('./queryStore-client-q_SLGgYH.js');
 var useCountdownClient = require('./useCountdown-client-uiqhgllY.js');
 var React = require('react');
-var queryStoreClient = require('./queryStore-client-q_SLGgYH.js');
 var downloadClient = require('./download-client-DKxkL92w.js');
 var webStorageClient = require('./webStorage-client-BGQKUfrO.js');
 
@@ -11,302 +11,149 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var dayjs__default = /*#__PURE__*/_interopDefault(dayjs);
 
+const FILE_SIZE_UNITS$1 = [
+    'Bytes',
+    'KB',
+    'MB',
+    'GB',
+    'TB',
+    'PB',
+    'EB',
+    'ZB',
+    'YB'
+];
 /**
- * convert CamelCase string to PascalCase string
- * @param str the string to convert
- * @example
- * camelString2PascalString('camelCase') // 'CamelCase'
- * camelString2PascalString('camelCaseTest') // 'CamelCaseTest'
- */ const camelString2PascalString = (str)=>`${str[0].toUpperCase()}${str.slice(1)}`;
-/**
- * convert CamelCase string to SnakeCase string
- * @param str the string to convert
- * @example
- * camelString2SnakeString('camelCase') // 'camel_case'
- * camelString2SnakeString('camelCaseTest') // 'camel_case_test'
- */ const camelString2SnakeString = (str)=>str.replace(/[A-Z]/g, (letter)=>`_${letter.toLowerCase()}`);
-/**
- * convert PascalCase string to CamelCase string
- * @param str the string to convert
- * @example
- * pascalString2CamelString('PascalCase') // 'pascalCase'
- * pascalString2CamelString('PascalCaseTest') // 'pascalCaseTest'
- */ const pascalString2CamelString = (str)=>`${str[0].toLowerCase()}${str.slice(1)}`;
-/**
- * convert PascalCase string to SnakeCase string
- * @param str the string to convert
- * @example
- * pascalString2SnakeString('PascalCase') // 'pascal_case'
- * pascalString2SnakeString('PascalCaseTest') // 'pascal_case_test'
- */ const pascalString2SnakeString = (str)=>camelString2SnakeString(pascalString2CamelString(str));
-/**
- * convert SnakeCase string to CamelCase string
- * @param str the string to convert
- * @example
- * snakeString2CamelString('snake_case') // 'snakeCase'
- * snakeString2CamelString('snake_case_test') // 'snakeCaseTest'
- */ const snakeString2CamelString = (str)=>str.replace(/(_[a-z])/g, (group)=>group.toUpperCase().replace('_', ''));
-/**
- * convert SnakeCase string to PascalCase string
- * @param str the string to convert
- * @example
- * snakeString2PascalString('snake_case') // 'SnakeCase'
- * snakeString2PascalString('snake_case_test') // 'SnakeCaseTest'
- */ const snakeString2PascalString = (str)=>camelString2PascalString(snakeString2CamelString(str));
-const transformFun = {
-    CamelToPascal: camelString2PascalString,
-    CamelToSnake: camelString2SnakeString,
-    PascalToCamel: pascalString2CamelString,
-    PascalToSnake: pascalString2SnakeString,
-    SnakeToCamel: snakeString2CamelString,
-    SnakeToPascal: snakeString2PascalString
-};
-const transformObjectKey = (obj, transformFunName)=>{
-    if (!obj || typeof obj !== 'object') return obj;
-    if (Array.isArray(obj)) return obj.map((item)=>transformObjectKey(item, transformFunName));
-    return Object.keys(obj).reduce((acc, key)=>({
-            ...acc,
-            [transformFun[transformFunName](key)]: transformObjectKey(obj[key], transformFunName)
-        }), {});
-};
-/**
- * convert object key from CamelCase to PascalCase
- * @param obj the object to convert
- * @example
- * const obj = {
- *  fooBar: 'fooBar',
- *  fooBar2: 'fooBar2',
- *  fooBar3: {
- *    fooBar4: 'fooBar4',
- *    fooBar5: 'fooBar5',
- *  },
- * };
- * const result = camelCase2PascalCase(obj);
- * console.log(result); // { FooBar: 'fooBar', FooBar2: 'fooBar2', FooBar3: { FooBar4: 'fooBar4', FooBar5: 'fooBar5' } }
- */ const camelCase2PascalCase = (obj)=>transformObjectKey(obj, 'CamelToPascal');
-/**
- * convert object key from CamelCase to SnakeCase
- * @param obj the object to convert
- * @example
- * const obj = {
- *  fooBar: 'fooBar',
- *  fooBar2: 'fooBar2',
- *  fooBar3: {
- *    fooBar4: 'fooBar4',
- *    fooBar5: 'fooBar5',
- *  },
- * };
- * const result = camelCase2SnakeCase(obj);
- * console.log(result); // { foo_bar: 'fooBar', foo_bar2: 'fooBar2', foo_bar3: { foo_bar4: 'fooBar4', foo_bar5: 'fooBar5' } }
- */ const camelCase2SnakeCase = (obj)=>transformObjectKey(obj, 'CamelToSnake');
-/**
- * convert object key from PascalCase to CamelCase
- * @param obj the object to convert
- * @example
- * const obj = {
- *  FooBar: 'fooBar',
- *  FooBar2: 'fooBar2',
- *  FooBar3: {
- *    FooBar4: 'fooBar4',
- *    FooBar5: 'fooBar5',
- *  },
- * };
- * const result = pascalCase2CamelCase(obj);
- * console.log(result); // { fooBar: 'fooBar', fooBar2: 'fooBar2', fooBar3: { fooBar4: 'fooBar4', fooBar5: 'fooBar5' } }
- */ const pascalCase2CamelCase = (obj)=>transformObjectKey(obj, 'PascalToCamel');
-/**
- * convert object key from PascalCase to SnakeCase
- * @param obj the object to convert
- * @example
- * const obj = {
- *  FooBar: 'fooBar',
- *  FooBar2: 'fooBar2',
- *  FooBar3: {
- *    FooBar4: 'fooBar4',
- *    FooBar5: 'fooBar5',
- *  },
- * };
- * const result = pascalCase2SnakeCase(obj);
- * console.log(result); // { foo_bar: 'fooBar', foo_bar2: 'fooBar2', foo_bar3: { foo_bar4: 'fooBar4', foo_bar5: 'fooBar5' } }
- */ const pascalCase2SnakeCase = (obj)=>transformObjectKey(obj, 'PascalToSnake');
-/**
- * convert object key from SnakeCase to CamelCase
- * @param obj the object to convert
- * @example
- * const obj = {
- *  foo_bar: 'fooBar',
- *  foo_bar2: 'fooBar2',
- *  foo_bar3: {
- *    foo_bar4: 'fooBar4',
- *    foo_bar5: 'fooBar5',
- *  },
- * };
- * const result = snakeCase2CamelCase(obj);
- * console.log(result); // { fooBar: 'fooBar', fooBar2: 'fooBar2', fooBar3: { fooBar4: 'fooBar4', fooBar5: 'fooBar5' } }
- */ const snakeCase2CamelCase = (obj)=>transformObjectKey(obj, 'SnakeToCamel');
-/**
- * convert object key from SnakeCase to PascalCase
- * @param obj the object to convert
- * @example
- * const obj = {
- *  foo_bar: 'fooBar',
- *  foo_bar2: 'fooBar2',
- *  foo_bar3: {
- *    foo_bar4: 'fooBar4',
- *    foo_bar5: 'fooBar5',
- *  },
- * };
- * const result = snakeCase2PascalCase(obj);
- * console.log(result); // { FooBar: 'fooBar', FooBar2: 'fooBar2', FooBar3: { FooBar4: 'fooBar4', FooBar5: 'fooBar5' } }
- */ const snakeCase2PascalCase = (obj)=>transformObjectKey(obj, 'SnakeToPascal');
-
-/**
- * 檢查稅務編號是否符合正確的編號規則。
- *
- * @param {string} taxId - 要檢查的8位數稅務編號。
- * @returns {boolean} - 如果符合規則則返回 true，否則返回 false。
- *
- * ### 編號檢查規則：
- * 1. **基本格式檢查**：
- *    - 編號必須為 8 位數字。
- *    - 不得為「00000000」或「11111111」，這些編號被視為無效。
- *
- * 2. **驗證邏輯**：
- *    - 使用一組驗證運算子：`[1, 2, 1, 2, 1, 2, 4, 1]`。
- *    - 將稅務編號的每一位數字與對應的運算子相乘後，使用 `calculate` 函數計算各位數的和。
- *      - 計算公式為：`(product % 10) + (product - (product % 10)) / 10`
- *    - 將所有位數經計算後的結果加總為 `sum`。
- *
- * 3. **檢查規則**：
- *    - 如果總和 `sum` 可以被 5 整除，則編號有效。
- *    - 或者，若第七位數為 7，且 `(sum + 1) % 5 === 0`，則編號有效。
- *
- * @example
- *
- * validTaxId('22099131') // true
- * validTaxId('84149961') // true
- * validTaxId('00000000') // false
- * validTaxId('11111111') // false
- * validTaxId('22099132') // false
- */ const validTaxId = (taxId)=>{
-    const invalidList = '00000000,11111111';
-    if (/^\d{8}$/.test(taxId) === false || invalidList.indexOf(taxId) >= 0) {
-        return false;
+ * 代表字節大小的類，提供各種格式化和轉換方法
+ */ class ByteSize {
+    /**
+   * 建立一個新的 ByteSize 實例
+   * @param bytes 位元組數值
+   */ constructor(bytes){
+        this.bytes = bytes;
     }
-    const validateOperator = [
-        1,
-        2,
-        1,
-        2,
-        1,
-        2,
-        4,
-        1
-    ];
-    const calculate = (product)=>product % 10 + (product - product % 10) / 10;
-    const sum = validateOperator.reduce((pre, cur, index)=>pre + calculate(Number(taxId[index]) * cur), 0);
-    return sum % 5 === 0 || taxId[6] === '7' && (sum + 1) % 5 === 0;
-};
+    /**
+   * 取得原始位元組數值
+   */ 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();
+    }
+}
 /**
- * 驗證日期格式是否正確
- *
- * @param dateString 日期字串
- * @param format 日期格式
- * @example
+ * 將位元組轉換為可讀字符串 (保留舊的 API 以確保向後兼容)
  *
- * validateDateString('20210201', 'YYYYMMDD') // true
- * validateDateString('2021-02-01', 'YYYY-MM-DD') // true
- * validateDateString('20210201', 'YYYY-MM-DD') // false
- * validateDateString('20210201', 'YYYYMM') // false
- */ const validateDateString = (dateString, format)=>{
-    if (!dateString) return false;
-    // 根據 format 生成正則表達式
-    const regexPattern = format.replace(/YYYY/, '\\d{4}').replace(/MM/, '\\d{2}').replace(/DD/, '\\d{2}').replace(/HH/, '\\d{2}').replace(/mm/, '\\d{2}').replace(/ss/, '\\d{2}');
-    const regex = new RegExp(`^${regexPattern}$`);
-    // 先用正則驗證格式
-    if (!regex.test(dateString)) return false;
-    // 再用 dayjs 驗證是否為有效日期
-    return dayjs__default.default(dateString, format, true).isValid();
-};
-
-/**
- * 取得去年今年以及明年期別陣列
+ * @param bytes 位元組數值
+ * @param unit 目標單位 (例如 'KB', 'MB', 'GB')，不指定則自動選擇最適合的單位
+ * @param decimals 小數點位數 (預設為 2)
+ * @returns 格式化後的字符串
  *
  * @example
- * // 假設 今年為 112 年
- * generatePeriodArray() // 11102 ~ 11312
- */ const generatePeriodArray = ()=>{
-    const currentYear = new Date().getFullYear() - 1911;
-    const months = [
-        '02',
-        '04',
-        '06',
-        '08',
-        '10',
-        '12'
-    ];
-    const years = [
-        currentYear - 1,
-        currentYear,
-        currentYear + 1
-    ];
-    return years.flatMap((year)=>months.map((month)=>`${year}${month}`));
-};
+ * ```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);
+
 /**
- * 取得當前期別
- *
- * 報稅期限次期開始15日內
+ * 檢查兩個值是否相等（包含陣列等引用型別）
+ * - 支援基本型別的直接比較
+ * - 特別處理空陣列比較
+ * - 支援非空陣列的深度比較
  *
- * 雙數月沒有特殊規則，期別皆為當月開頭
- *
- * 單數月15號以前，期別為上個月否則為下個月開頭
+ * @param value1 - 第一個值
+ * @param value2 - 第二個值
+ * @returns 如果值相等則返回 true
  *
  * @example
- *
- * // 假設今天是 111-02-15
- * getCurrentPeriod() // 11102
- * // 假設今天是 111-02-16
- * getCurrentPeriod() // 11102
- * // 假設今天是 111-03-15
- * getCurrentPeriod() // 11102
- * // 假設今天是 111-03-16
- * getCurrentPeriod() // 11104
- */ const getCurrentPeriod = ()=>{
-    const now = dayjs__default.default();
-    const currentDate = now.format('DD');
-    const currentYear = now.format('YYYY');
-    const currentMonth = now.format('MM');
-    let endMonth;
-    if (Number(currentMonth) % 2 === 1) {
-        endMonth = dayjs__default.default(`${currentYear}${currentMonth}`, 'YYYYMM').add(Number(currentDate) <= 15 ? -1 : 1, 'month').format('YYYYMM');
-    } else {
-        endMonth = `${currentYear}${currentMonth}`;
+ * // 基本型別比較
+ * 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;
     }
-    return dayjs__default.default(endMonth, 'YYYYMM').subtract(1911, 'year').format('YYYYMM').substring(1);
-};
-/**
- * 民國年轉西元年
- * @param dateString 日期字串
- * @param format 日期格式
- * @example
- *
- * rocEraToAd('1100201') // 20210201
- * rocEraToAd('11002', 'YYYYMM') // 202102
- */ const rocEraToAd = (dateString, format = 'YYYYMMDD')=>{
-    if (!validateDateString(`0${dateString}`, format)) return dateString;
-    return dayjs__default.default(`0${dateString}`, format).add(1911, 'year').format(format);
-};
-/**
- * 西元年轉民國年
- * @param dateString 日期字串
- * @param format 日期格式
- * @example
- *
- * adToRocEra('20210201') // 1100201
- * adToRocEra('202102', 'YYYYMM') // 11002
- */ const adToRocEra = (dateString, format = 'YYYYMMDD')=>{
-    if (!validateDateString(dateString, format)) return dateString;
-    return dayjs__default.default(dateString, format).add(-1911, 'year').format(format).substring(1);
+    // 處理空陣列
+    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;
 };
 
 /**
@@ -460,48 +307,18 @@ const transformObjectKey = (obj, transformFunName)=>{
         case 'jpg':
             return 'image/jpeg';
         case 'png':
-            return 'image/png';
-        case 'pdf':
-            return 'application/pdf';
-        case 'zip':
-            return 'application/zip';
-        case 'csv':
-            return 'text/csv';
-        case 'txt':
-            return 'text/plain';
-        default:
-            return 'application/octet-stream';
-    }
-};
-
-/**
- * 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.');
+            return 'image/png';
+        case 'pdf':
+            return 'application/pdf';
+        case 'zip':
+            return 'application/zip';
+        case 'csv':
+            return 'text/csv';
+        case 'txt':
+            return 'text/plain';
+        default:
+            return 'application/octet-stream';
     }
-    const isControlled = value !== undefined;
-    const [internalValue, setInternalValue] = React.useState(defaultValue);
-    const setValue = React.useCallback((newValue)=>{
-        if (!isControlled) {
-            setInternalValue(newValue);
-        }
-    }, [
-        isControlled
-    ]);
-    const currentValue = isControlled ? value : internalValue;
-    return [
-        currentValue,
-        setValue
-    ];
 };
 
 // const isProduction: boolean = process.env.NODE_ENV === 'production';
@@ -559,10 +376,12 @@ message) {
  * @param values 要排除的 value
  *
  * @example
- * const a = { a: undefined, b: null, c: 3, d: 4 };
- * const b = omitByValue(a, undefined, null); // { c: 3, d: 4 }
+ * 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])=>{
-        if (values.includes(value)) {
+        // 使用深度比較檢查值是否應該被排除
+        const shouldOmit = values.some((excludeValue)=>isEqual(value, excludeValue));
+        if (shouldOmit) {
             return acc;
         }
         return {
@@ -592,10 +411,12 @@ message) {
  *
  * @example
  *
- * const a = { a: 1, b: 2, c: 3, d: 4 };
- * const b = pickByValue(a, 1, 2); // { a: 1, b: 2 }
+ * 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])=>{
-        if (values.includes(value)) {
+        // 使用深度比較檢查值是否應該被選擇
+        const shouldPick = values.some((pickValue)=>isEqual(value, pickValue));
+        if (shouldPick) {
             return {
                 ...acc,
                 [key]: value
@@ -663,44 +484,344 @@ const isObject = (value)=>value !== null && typeof value === 'object';
     };
 };
 /**
- * throttle function
+ * 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
+ * @param str the string to convert
+ * @example
+ * camelString2PascalString('camelCase') // 'CamelCase'
+ * camelString2PascalString('camelCaseTest') // 'CamelCaseTest'
+ */ const camelString2PascalString = (str)=>`${str[0].toUpperCase()}${str.slice(1)}`;
+/**
+ * convert CamelCase string to SnakeCase string
+ * @param str the string to convert
+ * @example
+ * camelString2SnakeString('camelCase') // 'camel_case'
+ * camelString2SnakeString('camelCaseTest') // 'camel_case_test'
+ */ const camelString2SnakeString = (str)=>str.replace(/[A-Z]/g, (letter)=>`_${letter.toLowerCase()}`);
+/**
+ * convert PascalCase string to CamelCase string
+ * @param str the string to convert
+ * @example
+ * pascalString2CamelString('PascalCase') // 'pascalCase'
+ * pascalString2CamelString('PascalCaseTest') // 'pascalCaseTest'
+ */ const pascalString2CamelString = (str)=>`${str[0].toLowerCase()}${str.slice(1)}`;
+/**
+ * convert PascalCase string to SnakeCase string
+ * @param str the string to convert
+ * @example
+ * pascalString2SnakeString('PascalCase') // 'pascal_case'
+ * pascalString2SnakeString('PascalCaseTest') // 'pascal_case_test'
+ */ const pascalString2SnakeString = (str)=>camelString2SnakeString(pascalString2CamelString(str));
+/**
+ * convert SnakeCase string to CamelCase string
+ * @param str the string to convert
+ * @example
+ * snakeString2CamelString('snake_case') // 'snakeCase'
+ * snakeString2CamelString('snake_case_test') // 'snakeCaseTest'
+ */ const snakeString2CamelString = (str)=>str.replace(/(_[a-z])/g, (group)=>group.toUpperCase().replace('_', ''));
+/**
+ * convert SnakeCase string to PascalCase string
+ * @param str the string to convert
+ * @example
+ * snakeString2PascalString('snake_case') // 'SnakeCase'
+ * snakeString2PascalString('snake_case_test') // 'SnakeCaseTest'
+ */ const snakeString2PascalString = (str)=>camelString2PascalString(snakeString2CamelString(str));
+const transformFun = {
+    CamelToPascal: camelString2PascalString,
+    CamelToSnake: camelString2SnakeString,
+    PascalToCamel: pascalString2CamelString,
+    PascalToSnake: pascalString2SnakeString,
+    SnakeToCamel: snakeString2CamelString,
+    SnakeToPascal: snakeString2PascalString
+};
+const transformObjectKey = (obj, transformFunName)=>{
+    if (!obj || typeof obj !== 'object') return obj;
+    if (Array.isArray(obj)) return obj.map((item)=>transformObjectKey(item, transformFunName));
+    return Object.keys(obj).reduce((acc, key)=>({
+            ...acc,
+            [transformFun[transformFunName](key)]: transformObjectKey(obj[key], transformFunName)
+        }), {});
+};
+/**
+ * convert object key from CamelCase to PascalCase
+ * @param obj the object to convert
+ * @example
+ * const obj = {
+ *  fooBar: 'fooBar',
+ *  fooBar2: 'fooBar2',
+ *  fooBar3: {
+ *    fooBar4: 'fooBar4',
+ *    fooBar5: 'fooBar5',
+ *  },
+ * };
+ * const result = camelCase2PascalCase(obj);
+ * console.log(result); // { FooBar: 'fooBar', FooBar2: 'fooBar2', FooBar3: { FooBar4: 'fooBar4', FooBar5: 'fooBar5' } }
+ */ const camelCase2PascalCase = (obj)=>transformObjectKey(obj, 'CamelToPascal');
+/**
+ * convert object key from CamelCase to SnakeCase
+ * @param obj the object to convert
+ * @example
+ * const obj = {
+ *  fooBar: 'fooBar',
+ *  fooBar2: 'fooBar2',
+ *  fooBar3: {
+ *    fooBar4: 'fooBar4',
+ *    fooBar5: 'fooBar5',
+ *  },
+ * };
+ * const result = camelCase2SnakeCase(obj);
+ * console.log(result); // { foo_bar: 'fooBar', foo_bar2: 'fooBar2', foo_bar3: { foo_bar4: 'fooBar4', foo_bar5: 'fooBar5' } }
+ */ const camelCase2SnakeCase = (obj)=>transformObjectKey(obj, 'CamelToSnake');
+/**
+ * convert object key from PascalCase to CamelCase
+ * @param obj the object to convert
+ * @example
+ * const obj = {
+ *  FooBar: 'fooBar',
+ *  FooBar2: 'fooBar2',
+ *  FooBar3: {
+ *    FooBar4: 'fooBar4',
+ *    FooBar5: 'fooBar5',
+ *  },
+ * };
+ * const result = pascalCase2CamelCase(obj);
+ * console.log(result); // { fooBar: 'fooBar', fooBar2: 'fooBar2', fooBar3: { fooBar4: 'fooBar4', fooBar5: 'fooBar5' } }
+ */ const pascalCase2CamelCase = (obj)=>transformObjectKey(obj, 'PascalToCamel');
+/**
+ * convert object key from PascalCase to SnakeCase
+ * @param obj the object to convert
+ * @example
+ * const obj = {
+ *  FooBar: 'fooBar',
+ *  FooBar2: 'fooBar2',
+ *  FooBar3: {
+ *    FooBar4: 'fooBar4',
+ *    FooBar5: 'fooBar5',
+ *  },
+ * };
+ * const result = pascalCase2SnakeCase(obj);
+ * console.log(result); // { foo_bar: 'fooBar', foo_bar2: 'fooBar2', foo_bar3: { foo_bar4: 'fooBar4', foo_bar5: 'fooBar5' } }
+ */ const pascalCase2SnakeCase = (obj)=>transformObjectKey(obj, 'PascalToSnake');
+/**
+ * convert object key from SnakeCase to CamelCase
+ * @param obj the object to convert
+ * @example
+ * const obj = {
+ *  foo_bar: 'fooBar',
+ *  foo_bar2: 'fooBar2',
+ *  foo_bar3: {
+ *    foo_bar4: 'fooBar4',
+ *    foo_bar5: 'fooBar5',
+ *  },
+ * };
+ * const result = snakeCase2CamelCase(obj);
+ * console.log(result); // { fooBar: 'fooBar', fooBar2: 'fooBar2', fooBar3: { fooBar4: 'fooBar4', fooBar5: 'fooBar5' } }
+ */ const snakeCase2CamelCase = (obj)=>transformObjectKey(obj, 'SnakeToCamel');
+/**
+ * convert object key from SnakeCase to PascalCase
+ * @param obj the object to convert
+ * @example
+ * const obj = {
+ *  foo_bar: 'fooBar',
+ *  foo_bar2: 'fooBar2',
+ *  foo_bar3: {
+ *    foo_bar4: 'fooBar4',
+ *    foo_bar5: 'fooBar5',
+ *  },
+ * };
+ * const result = snakeCase2PascalCase(obj);
+ * console.log(result); // { FooBar: 'fooBar', FooBar2: 'fooBar2', FooBar3: { FooBar4: 'fooBar4', FooBar5: 'fooBar5' } }
+ */ const snakeCase2PascalCase = (obj)=>transformObjectKey(obj, 'SnakeToPascal');
+
+/**
+ * 將數字轉換成金額千分位格式
+ *
+ * @param num - 數字
+ *
+ * @example
+ *
+ * formatAmount(1234567) // '1,234,567'
+ */ const formatAmount = (num)=>{
+    if (typeof num !== 'number') return '';
+    return num.toString().replace(/(\d)(?=(\d{3})+(?!\d))/g, '$1,');
+};
+/**
+ * 將字串的第 n - m 個字轉換成星號
+ *
+ * @param str - 字串
+ * @param n - 起始位置
+ * @param m - 結束位置
+ *
+ * @example
+ *
+ * formatString('123456', 1, 4) // '1****6'
+ *
+ * @deprecated use `maskString` instead
+ */ const formatStarMask = (str, n, m)=>str.slice(0, n) + '*'.repeat(m - n + 1) + str.slice(m + 1);
+/**
+ * 將字串的指定位置的以後的字元轉換成星號
+ *
+ * @param str 字串
+ * @param start 起始位置 (從 0 開始計算)
+ * @param length 可選，從起始位置開始要遮罩的字元數量，默認為剩餘所有字元
+ *
+ * @example
+ *
+ * ```js
+ * maskString('123456789', 2) // '12*******'
+ * maskString('123456789', 2, 5) // '12*****89'
+ * maskString('123456789', 0, 15) // '*********'
+ * maskString('123456789', 10) // '123456789' (start out of bounds)
+ * maskString('123456789', -1) // '123456789' (start out of bounds)
+ * ```
+ */ const maskString = (str, start, length)=>{
+    if (start < 0 || start >= str.length) return str;
+    const maxMaskLength = str.length - start;
+    const safeLength = length !== undefined ? Math.max(0, Math.min(length, maxMaskLength)) : maxMaskLength;
+    return str.slice(0, start) + '*'.repeat(safeLength) + str.slice(start + safeLength);
+};
+const FILE_SIZE_UNITS = [
+    'Bytes',
+    'KB',
+    'MB',
+    'GB',
+    'TB',
+    'PB',
+    'EB',
+    'ZB',
+    'YB'
+];
+/**
+ * format file size to human readable string
  *
- * @param {Function} fn function to be executed
- * @param {number} delay time to wait before executing the function
+ * it will convert bytes to KB, MB, GB, TB, PB, EB, ZB, YB
+ *
+ * @param bytes file size in bytes
+ * @param decimals number of decimal places (default is 2)
  *
  * @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;
-    };
+ *
+ * ```js
+ * formatBytes(0) // 0 Bytes
+ * formatBytes(1024) // 1 KB
+ * formatBytes(1024, 2) // 1.00 KB
+ * formatBytes(1024 * 1024) // 1 MB
+ * ```
+ * @deprecated use `convertBytes` instead
+ */ const formatBytes = (bytes, decimals = 0)=>{
+    if (bytes === 0) return '0 Bytes';
+    const k = 1024;
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${(bytes / k ** i).toFixed(decimals)} ${FILE_SIZE_UNITS[i]}`;
 };
 
-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;
-            }
-        });
-    };
-}
-
 /**
  * 中文
  *
@@ -869,79 +990,211 @@ function mergeRefs(refs) {
  */ const isTWPhone = ()=>/^(((0[2-9]-?\d{6,8})(#\d{1,5})?)|((0[2-9][0-9]-?\d{6,7})(#\d{1,5})?))$/;
 
 /**
- * 將數字轉換成金額千分位格式
+ * 檢查稅務編號是否符合正確的編號規則。
  *
- * @param num - 數字
+ * @param {string} taxId - 要檢查的8位數稅務編號。
+ * @returns {boolean} - 如果符合規則則返回 true，否則返回 false。
  *
- * @example
+ * ### 編號檢查規則：
+ * 1. **基本格式檢查**：
+ *    - 編號必須為 8 位數字。
+ *    - 不得為「00000000」或「11111111」，這些編號被視為無效。
  *
- * formatAmount(1234567) // '1,234,567'
- */ const formatAmount = (num)=>{
-    if (typeof num !== 'number') return '';
-    return num.toString().replace(/(\d)(?=(\d{3})+(?!\d))/g, '$1,');
-};
-/**
- * 將字串的第 n - m 個字轉換成星號
+ * 2. **驗證邏輯**：
+ *    - 使用一組驗證運算子：`[1, 2, 1, 2, 1, 2, 4, 1]`。
+ *    - 將稅務編號的每一位數字與對應的運算子相乘後，使用 `calculate` 函數計算各位數的和。
+ *      - 計算公式為：`(product % 10) + (product - (product % 10)) / 10`
+ *    - 將所有位數經計算後的結果加總為 `sum`。
  *
- * @param str - 字串
- * @param n - 起始位置
- * @param m - 結束位置
+ * 3. **檢查規則**：
+ *    - 如果總和 `sum` 可以被 5 整除，則編號有效。
+ *    - 或者，若第七位數為 7，且 `(sum + 1) % 5 === 0`，則編號有效。
  *
  * @example
  *
- * formatString('123456', 1, 4) // '1****6'
- */ const formatStarMask = (str, n, m)=>str.slice(0, n) + '*'.repeat(m - n + 1) + str.slice(m + 1);
+ * validTaxId('22099131') // true
+ * validTaxId('84149961') // true
+ * validTaxId('00000000') // false
+ * validTaxId('11111111') // false
+ * validTaxId('22099132') // false
+ */ const validTaxId = (taxId)=>{
+    const invalidList = '00000000,11111111';
+    if (/^\d{8}$/.test(taxId) === false || invalidList.indexOf(taxId) >= 0) {
+        return false;
+    }
+    const validateOperator = [
+        1,
+        2,
+        1,
+        2,
+        1,
+        2,
+        4,
+        1
+    ];
+    const calculate = (product)=>product % 10 + (product - product % 10) / 10;
+    const sum = validateOperator.reduce((pre, cur, index)=>pre + calculate(Number(taxId[index]) * cur), 0);
+    return sum % 5 === 0 || taxId[6] === '7' && (sum + 1) % 5 === 0;
+};
 /**
- * format file size to human readable string
+ * 驗證日期格式是否正確
  *
- * it will convert bytes to KB, MB, GB, TB, PB, EB, ZB, YB
+ * @param dateString 日期字串
+ * @param format 日期格式
+ * @example
  *
- * @param bytes file size in bytes
- * @param decimals number of decimal places (default is 2)
+ * validateDateString('20210201', 'YYYYMMDD') // true
+ * validateDateString('2021-02-01', 'YYYY-MM-DD') // true
+ * validateDateString('20210201', 'YYYY-MM-DD') // false
+ * validateDateString('20210201', 'YYYYMM') // false
+ */ const validateDateString = (dateString, format)=>{
+    if (!dateString) return false;
+    // 根據 format 生成正則表達式
+    const regexPattern = format.replace(/YYYY/, '\\d{4}').replace(/MM/, '\\d{2}').replace(/DD/, '\\d{2}').replace(/HH/, '\\d{2}').replace(/mm/, '\\d{2}').replace(/ss/, '\\d{2}');
+    const regex = new RegExp(`^${regexPattern}$`);
+    // 先用正則驗證格式
+    if (!regex.test(dateString)) return false;
+    // 再用 dayjs 驗證是否為有效日期
+    return dayjs__default.default(dateString, format, true).isValid();
+};
+
+/**
+ * A hook to manage a value.
  *
  * @example
  *
- * ```js
- * formatBytes(0) // 0 Bytes
- * formatBytes(1024) // 1 KB
- * formatBytes(1024, 2) // 1.00 KB
- * formatBytes(1024 * 1024) // 1 MB
+ * ```tsx
+ * const MyComponent = ({ value }: { value?: number }) => {
+ *    const [currentValue, setCurrentValue] = useValue({ value });
+ * };
  * ```
- */ const formatBytes = (bytes, decimals = 0)=>{
-    if (bytes === 0) return '0 Bytes';
-    const k = 1024;
-    const sizes = [
-        'Bytes',
-        'KB',
-        'MB',
-        'GB',
-        'TB',
-        'PB',
-        'EB',
-        'ZB',
-        'YB'
+ */ 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] = React.useState(defaultValue);
+    const setValue = React.useCallback((newValue)=>{
+        if (!isControlled) {
+            setInternalValue(newValue);
+        }
+    }, [
+        isControlled
+    ]);
+    const currentValue = isControlled ? value : internalValue;
+    return [
+        currentValue,
+        setValue
     ];
-    const i = Math.floor(Math.log(bytes) / Math.log(k));
-    return `${(bytes / k ** i).toFixed(decimals)} ${sizes[i]}`;
 };
 
+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;
+            }
+        });
+    };
+}
+
 /**
- * Wait for a given amount of time
- * @param ms time to wait in milliseconds
- */ const wait = (ms)=>{
+ * 民國年轉西元年
+ * @param dateString 日期字串
+ * @param format 日期格式
+ * @example
+ *
+ * rocEraToAd('1100201') // 20210201
+ * rocEraToAd('11002', 'YYYYMM') // 202102
+ */ const rocEraToAd = (dateString, format = 'YYYYMMDD')=>{
+    if (!validateDateString(`0${dateString}`, format)) return dateString;
+    return dayjs__default.default(`0${dateString}`, format).add(1911, 'year').format(format);
+};
+/**
+ * 西元年轉民國年
+ * @param dateString 日期字串
+ * @param format 日期格式
+ * @example
+ *
+ * adToRocEra('20210201') // 1100201
+ * adToRocEra('202102', 'YYYYMM') // 11002
+ */ const adToRocEra = (dateString, format = 'YYYYMMDD')=>{
+    if (!validateDateString(dateString, format)) return dateString;
+    return dayjs__default.default(dateString, format).add(-1911, 'year').format(format).substring(1);
+};
+
+/**
+ * 取得去年今年以及明年期別陣列
+ *
+ * @example
+ * // 假設 今年為 112 年
+ * generatePeriodArray() // 11102 ~ 11312
+ */ const generatePeriodArray = ()=>{
+    const currentYear = new Date().getFullYear() - 1911;
+    const months = [
+        '02',
+        '04',
+        '06',
+        '08',
+        '10',
+        '12'
+    ];
+    const years = [
+        currentYear - 1,
+        currentYear,
+        currentYear + 1
+    ];
+    return years.flatMap((year)=>months.map((month)=>`${year}${month}`));
+};
+/**
+ * 取得當前期別
+ *
+ * 報稅期限次期開始15日內
+ *
+ * 雙數月沒有特殊規則，期別皆為當月開頭
+ *
+ * 單數月15號以前，期別為上個月否則為下個月開頭
+ *
+ * @example
+ *
+ * // 假設今天是 111-02-15
+ * getCurrentPeriod() // 11102
+ * // 假設今天是 111-02-16
+ * getCurrentPeriod() // 11102
+ * // 假設今天是 111-03-15
+ * getCurrentPeriod() // 11102
+ * // 假設今天是 111-03-16
+ * getCurrentPeriod() // 11104
+ */ const getCurrentPeriod = ()=>{
+    const now = dayjs__default.default();
+    const currentDate = now.format('DD');
+    const currentYear = now.format('YYYY');
+    const currentMonth = now.format('MM');
+    let endMonth;
+    if (Number(currentMonth) % 2 === 1) {
+        endMonth = dayjs__default.default(`${currentYear}${currentMonth}`, 'YYYYMM').add(Number(currentDate) <= 15 ? -1 : 1, 'month').format('YYYYMM');
+    } else {
+        endMonth = `${currentYear}${currentMonth}`;
+    }
+    return dayjs__default.default(endMonth, 'YYYYMM').subtract(1911, 'year').format('YYYYMM').substring(1);
 };
 
-exports.useCountdown = useCountdownClient.useCountdown;
 exports.QueryProvider = queryStoreClient.QueryProvider;
 exports.useQueryContext = queryStoreClient.useQueryContext;
+exports.useCountdown = useCountdownClient.useCountdown;
 exports.downloadFile = downloadClient.downloadFile;
 exports.getLocalStorage = webStorageClient.getLocalStorage;
 exports.setLocalStorage = webStorageClient.setLocalStorage;
+exports.ByteSize = ByteSize;
 exports.adToRocEra = adToRocEra;
 exports.camelCase2PascalCase = camelCase2PascalCase;
 exports.camelCase2SnakeCase = camelCase2SnakeCase;
 exports.camelString2PascalString = camelString2PascalString;
 exports.camelString2SnakeString = camelString2SnakeString;
+exports.convertBytes = convertBytes;
 exports.createEnumLikeObject = createEnumLikeObject;
 exports.debounce = debounce;
 exports.deepMerge = deepMerge;
@@ -959,6 +1212,7 @@ exports.isDateString = isDateString;
 exports.isDateTimeString = isDateTimeString;
 exports.isEmail = isEmail;
 exports.isEnglish = isEnglish;
+exports.isEqual = isEqual;
 exports.isNonZeroStart = isNonZeroStart;
 exports.isNumber = isNumber;
 exports.isNumberAtLeastN = isNumberAtLeastN;
@@ -969,7 +1223,9 @@ exports.isTWMobile = isTWMobile;
 exports.isTWPhone = isTWPhone;
 exports.isTimeString = isTimeString;
 exports.isValidPassword = isValidPassword;
+exports.maskString = maskString;
 exports.mergeRefs = mergeRefs;
+exports.objectToSearchParams = objectToSearchParams;
 exports.omit = omit;
 exports.omitByValue = omitByValue;
 exports.pascalCase2CamelCase = pascalCase2CamelCase;
@@ -979,6 +1235,7 @@ exports.pascalString2SnakeString = pascalString2SnakeString;
 exports.pick = pick;
 exports.pickByValue = pickByValue;
 exports.rocEraToAd = rocEraToAd;
+exports.searchParamsToObject = searchParamsToObject;
 exports.snakeCase2CamelCase = snakeCase2CamelCase;
 exports.snakeCase2PascalCase = snakeCase2PascalCase;
 exports.snakeString2CamelString = snakeString2CamelString;