@gateweb/react-utils 2.0.0 → 2.1.0

package/dist/cjs/index.d.ts

@@ -706,6 +706,35 @@ declare function invariant(condition: any, message?: string | (() => string)): a
  */
 declare const isServer: () => boolean;
 
+type MaskKeySelector = string | ((key: string, value: unknown, path: Array<string | number>) => boolean);
+/**
+ * 深度走訪物件/陣列，將指定鍵名且值為字串的欄位遮罩為固定字串（預設 "******"）。
+ *
+ * - 預設僅遮罩鍵名等於 `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: '***' }
+ */
+declare const maskPasswords: <T>(input: T, mask?: string, selector?: MaskKeySelector) => T;
+
 type DeepPartialWithBooleanOverride<T> = {
     [K in keyof T]?: T[K] extends object ? T[K] extends boolean ? T[K] : DeepPartialWithBooleanOverride<T[K]> | boolean : T[K];
 };
@@ -1232,5 +1261,5 @@ declare const generatePeriodArray: () => string[];
  */
 declare const getCurrentPeriod: () => string;
 
-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, 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 };
-export type { MimeTypeExtension, MimeTypeValue, PartialBy, RequiredBy };
+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 };
+export type { MaskKeySelector, MimeTypeExtension, MimeTypeValue, PartialBy, RequiredBy };

package/dist/cjs/index.js

@@ -493,6 +493,74 @@ message) {
  * 判斷執行環境是否為 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 排除
  *
@@ -1446,6 +1514,7 @@ exports.isTWMobile = isTWMobile;
 exports.isTWPhone = isTWPhone;
 exports.isTimeString = isTimeString;
 exports.isValidPassword = isValidPassword;
+exports.maskPasswords = maskPasswords;
 exports.maskString = maskString;
 exports.mergeConfig = mergeConfig;
 exports.objectToSearchParams = objectToSearchParams;

package/dist/es/index.d.mts

@@ -706,6 +706,35 @@ declare function invariant(condition: any, message?: string | (() => string)): a
  */
 declare const isServer: () => boolean;
 
+type MaskKeySelector = string | ((key: string, value: unknown, path: Array<string | number>) => boolean);
+/**
+ * 深度走訪物件/陣列，將指定鍵名且值為字串的欄位遮罩為固定字串（預設 "******"）。
+ *
+ * - 預設僅遮罩鍵名等於 `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: '***' }
+ */
+declare const maskPasswords: <T>(input: T, mask?: string, selector?: MaskKeySelector) => T;
+
 type DeepPartialWithBooleanOverride<T> = {
     [K in keyof T]?: T[K] extends object ? T[K] extends boolean ? T[K] : DeepPartialWithBooleanOverride<T[K]> | boolean : T[K];
 };
@@ -1232,5 +1261,5 @@ declare const generatePeriodArray: () => string[];
  */
 declare const getCurrentPeriod: () => string;
 
-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, 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 };
-export type { MimeTypeExtension, MimeTypeValue, PartialBy, RequiredBy };
+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 };
+export type { MaskKeySelector, MimeTypeExtension, MimeTypeValue, PartialBy, RequiredBy };

package/dist/es/index.mjs

@@ -487,6 +487,74 @@ message) {
  * 判斷執行環境是否為 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 排除
  *
@@ -1397,4 +1465,4 @@ const FILE_SIZE_UNITS = [
     return dayjs(endMonth, 'YYYYMM').subtract(1911, 'year').format('YYYYMM').substring(1);
 };
 
-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, 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 };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gateweb/react-utils",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "React Utils for GateWeb",
   "homepage": "https://github.com/GatewebSolutions/react-utils",
   "files": [