@gateweb/react-utils 1.12.2 → 1.14.0

package/dist/cjs/index.js

@@ -5,7 +5,7 @@ var queryStoreClient = require('./queryStore-client-q_SLGgYH.js');
 var React = require('react');
 var useCountdownClient = require('./useCountdown-client-uiqhgllY.js');
 var downloadClient = require('./download-client-DKxkL92w.js');
-var webStorageClient = require('./webStorage-client-BGQKUfrO.js');
+var webStorageClient = require('./webStorage-client-DHr9PcPl.js');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -238,11 +238,31 @@ function createEnumLikeObject(obj, name, scene) {
         }, 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';
+
 /**
- * 檢查檔案是否為合法的 MIME 類型
+ * 檢查檔案是否為合法的檔案類型
+ *
+ * `accepts` 可同時接受副檔名以及 MIME 類型
  *
  * @param file 檔案
- * @param accepts 允許的 MIME 類型
+ * @param accepts 允許的類型
  *
  * @example
  *
@@ -250,21 +270,24 @@ function createEnumLikeObject(obj, name, scene) {
  * 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('/*')) {
-            const acceptedCategory = accept.split('/')[0];
-            const fileCategory = fileMimeType.split('/')[0];
-            if (acceptedCategory === fileCategory) {
-                return true;
-            }
+            return accept.split('/')[0] === fileMimeType.split('/')[0];
         }
         return false;
     });
@@ -291,32 +314,70 @@ function createEnumLikeObject(obj, name, scene) {
  * 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)=>{
-    switch((fileName.split('.').pop() || '').toLocaleLowerCase()){
-        case 'jpeg':
-        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 'xls':
-            return 'application/vnd.ms-excel';
-        case 'xlsx':
-            return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
-        case 'doc':
-            return 'application/msword';
-        case 'docx':
-            return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
-        case 'txt':
-            return 'text/plain';
-        default:
-            return 'application/octet-stream';
+    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';
@@ -446,6 +507,85 @@ const isObject = (value)=>value !== null && typeof value === 'object';
     }, {
         ...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;
+};
+
+/**
+ * 將嵌套物件的所有屬性設為指定的布林值
+ * @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
@@ -855,8 +995,7 @@ const FILE_SIZE_UNITS = [
  *
  * isEmail().test('123') // false
  * isEmail().test('123@gmail.com') // true
- */ const isEmail = ()=>// eslint-disable-next-line
-    /^(?!\.)(?!.*\.\.)([A-Z0-9_+-\.]*)[A-Z0-9_+-]@([A-Z0-9][A-Z0-9\-]*\.)+[A-Z]{2,}$/i;
+ */ const isEmail = ()=>/^(?!\.)(?!.*\.\.)([A-Z0-9_+-\\.]*)[A-Z0-9_+-]@([A-Z0-9][A-Z0-9\\-]*\.)+[A-Z]{2,}$/i;
 /**
  * 日期字串
  *
@@ -1055,6 +1194,29 @@ const FILE_SIZE_UNITS = [
     // 再用 dayjs 驗證是否為有效日期
     return dayjs__default.default(dateString, format, true).isValid();
 };
+/**
+ * 判斷 `value` 是否為 `null` 或 `undefined`
+ *
+ * @param value 值
+ *
+ * @example
+ * isNil(null); // true
+ * isNil(undefined); // true
+ * isNil(0); // false
+ * isNil(''); // false
+ * isNil(false); // false
+ * isNil({}); // false
+ *
+ * // TypeScript 型別縮窄應用
+ * function example(input?: string | null) {
+ *   if (isNil(input)) {
+ *     // input 型別會自動縮窄成 null | undefined
+ *     return 'No value';
+ *   }
+ *   // input 型別自動為 string
+ *   return input.toUpperCase();
+ * }
+ */ const isNil = (value)=>value === null || value === undefined;
 
 /**
  * Creates a strongly-typed React Context and Provider pair for data sharing.
@@ -1064,7 +1226,7 @@ const FILE_SIZE_UNITS = [
  * and a Provider component for supplying context values.
  *
  * @template T - The value type for the context.
- * @returns {Object} An object containing:
+ * @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.
  *
@@ -1238,6 +1400,8 @@ exports.downloadFile = downloadClient.downloadFile;
 exports.getLocalStorage = webStorageClient.getLocalStorage;
 exports.setLocalStorage = webStorageClient.setLocalStorage;
 exports.ByteSize = ByteSize;
+exports.MimeTypeMap = MimeTypeMap;
+exports.OtherMimeType = OtherMimeType;
 exports.adToRocEra = adToRocEra;
 exports.camelCase2PascalCase = camelCase2PascalCase;
 exports.camelCase2SnakeCase = camelCase2SnakeCase;
@@ -1247,6 +1411,7 @@ exports.convertBytes = convertBytes;
 exports.createDataContext = createDataContext;
 exports.createEnumLikeObject = createEnumLikeObject;
 exports.debounce = debounce;
+exports.deepClone = deepClone;
 exports.deepMerge = deepMerge;
 exports.extractEnumLikeObject = extractEnumLikeObject;
 exports.fakeApi = fakeApi;
@@ -1263,6 +1428,7 @@ exports.isDateTimeString = isDateTimeString;
 exports.isEmail = isEmail;
 exports.isEnglish = isEnglish;
 exports.isEqual = isEqual;
+exports.isNil = isNil;
 exports.isNonZeroStart = isNonZeroStart;
 exports.isNumber = isNumber;
 exports.isNumberAtLeastN = isNumberAtLeastN;
@@ -1274,10 +1440,13 @@ exports.isTWPhone = isTWPhone;
 exports.isTimeString = isTimeString;
 exports.isValidPassword = isValidPassword;
 exports.maskString = maskString;
+exports.mergeConfig = mergeConfig;
 exports.mergeRefs = mergeRefs;
 exports.objectToSearchParams = objectToSearchParams;
 exports.omit = omit;
 exports.omitByValue = omitByValue;
+exports.parseFileInfoFromFilename = parseFileInfoFromFilename;
+exports.parseFilenameFromDisposition = parseFilenameFromDisposition;
 exports.pascalCase2CamelCase = pascalCase2CamelCase;
 exports.pascalCase2SnakeCase = pascalCase2SnakeCase;
 exports.pascalString2CamelString = pascalString2CamelString;

package/dist/cjs/types.d.ts

@@ -187,5 +187,18 @@ type TChangeKeyType<T, K extends keyof T, V> = Omit<T, K> & {
 type MapToType<T extends Record<any, any>, A = any> = {
     [K in keyof T]: A;
 };
+/**
+ * 覆寫 T 指定屬性的型別，保留其他屬性。
+ *
+ * @template T 原始型別
+ * @template R 欲覆寫的 key-value 結構
+ *
+ * @example
+ * type User = { id: number; name: string }
+ * type FormUser = OverrideProps<User, { id: string }> // { id: string; name: string }
+ */
+type OverrideProps<T, R extends {
+    [K in keyof R]: any;
+}> = Omit<T, keyof R> & R;
 
-export type { AtLeastOne, DeepPartial, Entries, MapToString, MapToType, OnlyOne, PopArgs, PushArgs, ShiftArgs, TChangeKeyType, TExtractValueType, UnshiftArgs };
+export type { AtLeastOne, DeepPartial, Entries, MapToString, MapToType, OnlyOne, OverrideProps, PopArgs, PushArgs, ShiftArgs, TChangeKeyType, TExtractValueType, UnshiftArgs };

package/dist/cjs/{webStorage-client-BGQKUfrO.js → webStorage-client-DHr9PcPl.js}

@@ -20,7 +20,7 @@
         } else {
             currentObject = JSON.parse(storage);
         }
-    } catch (error) {
+    } catch (_error) {
         return undefined;
     }
     // let currentObject = JSON.parse(storage);

package/dist/es/index.d.mts

@@ -404,7 +404,9 @@ declare const extractEnumLikeObject: <T extends Record<string, { [P in K]: any;
  *
  * @param obj 要處理的物件
  * @param name 生成的 enum 名稱
- * @param scene 要使用的條件 (參考 example)
+ *
+ * @remarks
+ * 若需多場景 label，請傳入第三參數 scene，詳細用法請見範例。
  *
  * @example
  *
@@ -419,7 +421,7 @@ declare const extractEnumLikeObject: <T extends Record<string, { [P in K]: any;
  *
  * // scenes 版本
  *
- * Status = { Enabled: { value: 'enabled', scenes: { webA: { label: '啟用' }, webB: { label: '激活' } } }, Disabled: { value: 'disabled', scenes: { webA: { label: '停用' }, webB: { label: '停止' }}}}
+ * const Status = { Enabled: { value: 'enabled', scenes: { webA: { label: '啟用' }, webB: { label: '激活' } } }, Disabled: { value: 'disabled', scenes: { webA: { label: '停用' }, webB: { label: '停止' }}}}
  * const { EnumStatusA, StatusAList, getStatusALabel } = createEnumLikeObject(Status, 'StatusA', 'webA');
  * console.log(EnumStatusA); // { Enabled: 'enabled', Disabled: 'disabled' }
  * console.log(StatusAList); // [ { key: 'Enabled', value: 'enabled', label: '啟用' }, { key: 'Disabled', value: 'disabled', label: '停用' }]
@@ -431,6 +433,7 @@ declare const extractEnumLikeObject: <T extends Record<string, { [P in K]: any;
  * console.log(getStatusBLabel('enabled')); // '激活'
  *
  * ```
+ *
  */
 declare function createEnumLikeObject<T extends Record<string, {
     value: any;
@@ -474,11 +477,33 @@ declare const fakeApi: <T>(returnValue: T, result?: boolean, time?: number) => P
     message: string;
 }>;
 
+declare const MimeTypeMap: {
+    readonly jpeg: "image/jpeg";
+    readonly jpg: "image/jpeg";
+    readonly gif: "image/gif";
+    readonly png: "image/png";
+    readonly pdf: "application/pdf";
+    readonly zip: "application/zip";
+    readonly csv: "text/csv";
+    readonly ppt: "application/vnd.ms-powerpoint";
+    readonly pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation";
+    readonly xls: "application/vnd.ms-excel";
+    readonly xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+    readonly doc: "application/msword";
+    readonly docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+    readonly txt: "text/plain";
+};
+declare const OtherMimeType = "application/octet-stream";
+type MimeTypeExtension = keyof typeof MimeTypeMap;
+type MimeTypeValue = (typeof MimeTypeMap)[MimeTypeExtension] | typeof OtherMimeType;
+
 /**
- * 檢查檔案是否為合法的 MIME 類型
+ * 檢查檔案是否為合法的檔案類型
+ *
+ * `accepts` 可同時接受副檔名以及 MIME 類型
  *
  * @param file 檔案
- * @param accepts 允許的 MIME 類型
+ * @param accepts 允許的類型
  *
  * @example
  *
@@ -486,6 +511,7 @@ declare const fakeApi: <T>(returnValue: T, result?: boolean, time?: number) => P
  * 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
  * ```
  */
 declare const validateFileType: (file: File, accepts: string[]) => boolean;
@@ -511,8 +537,40 @@ declare const validateFileType: (file: File, accepts: string[]) => boolean;
  * getMimeType('xlsx') // 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
  * getMimeType('doc') // 'application/msword'
  * getMimeType('docx') // 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+ *
+ * @deprecated use `parseFileInfoFromFilename` instead
+ */
+declare const getMimeType: (fileName: string) => "image/jpeg" | "image/gif" | "image/png" | "application/pdf" | "application/zip" | "text/csv" | "application/vnd.ms-powerpoint" | "application/vnd.openxmlformats-officedocument.presentationml.presentation" | "application/vnd.ms-excel" | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" | "application/msword" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "text/plain";
+/**
+ * 用來解析後端在 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
+ */
+declare const parseFilenameFromDisposition: (disposition: string) => string | undefined;
+/**
+ * 解析 `filename` 回傳檔名、副檔名、MIME type
+ *
+ * @param filename 檔案名稱
+ *
+ * @example
+ *
+ * parseFileInfoFromFilename('image.jpg') // ['image', 'jpg', 'image/jpeg']
+ * parseFileInfoFromFilename('image') // ['image', '', 'application/octet-stream']
  */
-declare const getMimeType: (fileName: string) => "image/jpeg" | "image/png" | "application/pdf" | "application/zip" | "text/csv" | "application/vnd.ms-excel" | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" | "application/msword" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "text/plain" | "application/octet-stream";
+declare const parseFileInfoFromFilename: (filename: string) => [string, string, MimeTypeValue];
 
 declare function invariant(condition: any, message?: string | (() => string)): asserts condition;
 
@@ -521,6 +579,23 @@ declare function invariant(condition: any, message?: string | (() => string)): a
  */
 declare const isServer: () => boolean;
 
+type DeepPartialWithBooleanOverride<T> = {
+    [K in keyof T]?: T[K] extends object ? T[K] extends boolean ? T[K] : DeepPartialWithBooleanOverride<T[K]> | boolean : T[K];
+};
+/**
+ * 深度合併配置物件的通用工具
+ *
+ * @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 }
+ */
+declare const mergeConfig: <T extends Record<string, any>>(defaultConfig: T, customConfig?: DeepPartialWithBooleanOverride<T>) => T;
+
 /**
  * 將物件中的某些 key 排除
  *
@@ -616,6 +691,18 @@ type RequiredBy<T, K extends keyof T, RemoveUndefined extends boolean = false> =
 type PartialBy<T, K extends keyof T, RemoveUndefined extends boolean = false> = Omit<T, K> & {
     [P in K]?: RemoveUndefined extends true ? Exclude<T[P], undefined> : T[P];
 };
+/**
+ * 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 } }
+ *
+ */
+declare const deepClone: <T>(obj: T) => T;
 
 /**
  * debounce function
@@ -928,6 +1015,30 @@ declare const validTaxId: (taxId: string) => boolean;
  * validateDateString('20210201', 'YYYYMM') // false
  */
 declare const validateDateString: (dateString: string, format: string) => boolean;
+/**
+ * 判斷 `value` 是否為 `null` 或 `undefined`
+ *
+ * @param value 值
+ *
+ * @example
+ * isNil(null); // true
+ * isNil(undefined); // true
+ * isNil(0); // false
+ * isNil(''); // false
+ * isNil(false); // false
+ * isNil({}); // false
+ *
+ * // TypeScript 型別縮窄應用
+ * function example(input?: string | null) {
+ *   if (isNil(input)) {
+ *     // input 型別會自動縮窄成 null | undefined
+ *     return 'No value';
+ *   }
+ *   // input 型別自動為 string
+ *   return input.toUpperCase();
+ * }
+ */
+declare const isNil: (value: unknown) => value is null | undefined;
 
 type TQueryProps<Q> = {
     /**
@@ -987,7 +1098,7 @@ declare const useQueryContext: <Q>() => <T>(selector: (state: TQueryState<Q>) =>
  * and a Provider component for supplying context values.
  *
  * @template T - The value type for the context.
- * @returns {Object} An object containing:
+ * @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.
  *
@@ -1149,4 +1260,5 @@ declare const getLocalStorage: <T>(key: string, deCode?: boolean) => T | undefin
  */
 declare const setLocalStorage: (key: string, value: Record<string, any>, enCode?: boolean) => void;
 
-export { ByteSize, type PartialBy, QueryProvider, type RequiredBy, type TCountdownActions, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, convertBytes, createDataContext, createEnumLikeObject, debounce, deepMerge, downloadFile, extractEnumLikeObject, fakeApi, formatAmount, formatBytes, formatStarMask, generatePeriodArray, getCurrentPeriod, getLocalStorage, getMimeType, invariant, isChinese, isDateString, isDateTimeString, isEmail, isEnglish, isEqual, isNonZeroStart, isNumber, isNumberAtLeastN, isNumberN, isNumberNM, isServer, isTWMobile, isTWPhone, isTimeString, isValidPassword, maskString, mergeRefs, objectToSearchParams, omit, omitByValue, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, rocEraToAd, searchParamsToObject, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useQueryContext, useValue, validTaxId, validateDateString, validateFileType, wait };
+export { ByteSize, MimeTypeMap, OtherMimeType, QueryProvider, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, convertBytes, createDataContext, createEnumLikeObject, debounce, deepClone, deepMerge, downloadFile, extractEnumLikeObject, fakeApi, formatAmount, formatBytes, formatStarMask, generatePeriodArray, getCurrentPeriod, getLocalStorage, getMimeType, invariant, isChinese, isDateString, isDateTimeString, isEmail, isEnglish, isEqual, isNil, isNonZeroStart, isNumber, isNumberAtLeastN, isNumberN, isNumberNM, isServer, isTWMobile, isTWPhone, isTimeString, isValidPassword, maskString, mergeConfig, mergeRefs, objectToSearchParams, omit, omitByValue, parseFileInfoFromFilename, parseFilenameFromDisposition, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, rocEraToAd, searchParamsToObject, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useQueryContext, useValue, validTaxId, validateDateString, validateFileType, wait };
+export type { MimeTypeExtension, MimeTypeValue, PartialBy, RequiredBy, TCountdownActions };