@gateweb/react-utils 1.14.4 → 1.15.0

package/dist/cjs/index.d.ts

@@ -764,6 +764,20 @@ type PartialBy<T, K extends keyof T, RemoveUndefined extends boolean = false> =
  *
  */
 declare const deepClone: <T>(obj: T) => T;
+/**
+ * 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 }
+ */
+declare const renameKey: <T extends object, K extends keyof T, NK extends string>(obj: T, oldKey: K, newKey: NK) => Omit<T, K> & Record<NK, T[K]>;
 
 /**
  * debounce function
@@ -1321,5 +1335,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, 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 { 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, renameKey, rocEraToAd, searchParamsToObject, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useQueryContext, useValue, validTaxId, validateDateString, validateFileType, wait };
 export type { MimeTypeExtension, MimeTypeValue, PartialBy, RequiredBy, TCountdownActions };

package/dist/cjs/index.js

@@ -1,11 +1,11 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var dayjs = require('dayjs');
-var queryStoreClient = require('./queryStore-client-q_SLGgYH.js');
+var queryStore12s = require('./queryStore-12s-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-DHr9PcPl.js');
+var useCountdown12s = require('./useCountdown-12s-uiqhgllY.js');
+var download12s = require('./download-12s-DKxkL92w.js');
+var webStorage12s = require('./webStorage-12s-DHr9PcPl.js');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -539,6 +539,27 @@ const isObject = (value)=>value !== null && typeof value === 'object';
     }, {});
     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
+    };
+};
 
 /**
  * 將嵌套物件的所有屬性設為指定的布林值
@@ -1399,12 +1420,12 @@ function mergeRefs(refs) {
     return dayjs__default.default(endMonth, 'YYYYMM').subtract(1911, 'year').format('YYYYMM').substring(1);
 };
 
-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.QueryProvider = queryStore12s.QueryProvider;
+exports.useQueryContext = queryStore12s.useQueryContext;
+exports.useCountdown = useCountdown12s.useCountdown;
+exports.downloadFile = download12s.downloadFile;
+exports.getLocalStorage = webStorage12s.getLocalStorage;
+exports.setLocalStorage = webStorage12s.setLocalStorage;
 exports.ByteSize = ByteSize;
 exports.MimeTypeMap = MimeTypeMap;
 exports.OtherMimeType = OtherMimeType;
@@ -1459,6 +1480,7 @@ exports.pascalString2CamelString = pascalString2CamelString;
 exports.pascalString2SnakeString = pascalString2SnakeString;
 exports.pick = pick;
 exports.pickByValue = pickByValue;
+exports.renameKey = renameKey;
 exports.rocEraToAd = rocEraToAd;
 exports.searchParamsToObject = searchParamsToObject;
 exports.snakeCase2CamelCase = snakeCase2CamelCase;

package/dist/cjs/types.d.ts

@@ -200,5 +200,70 @@ type MapToType<T extends Record<any, any>, A = any> = {
 type OverrideProps<T, R extends {
     [K in keyof R]: any;
 }> = Omit<T, keyof R> & R;
+/**
+ * A utility type that makes a specific property in the generic type `T` required while keeping the rest optional.
+ *
+ * @template T - The object type to modify.
+ * @template K - The key of the property to make required.
+ *
+ * @example
+ * type User = { id?: number; name?: string }
+ * type FormUser = WithRequired<User, 'id'> // { id: number; name?: string }
+ */
+type WithRequired<T, K extends keyof T> = Required<Pick<T, K>> & Omit<T, K>;
+/**
+ * A utility type that makes a specific property in the generic type `T` optional while keeping the rest required.
+ *
+ * @template T - The object type to modify.
+ * @template K - The key of the property to make optional.
+ *
+ * @example
+ * type User = { id: number; name: string }
+ * type FormUser = WithOptional<User, 'id'> // { id?: number; name: string }
+ */
+type WithOptional<T, K extends keyof T> = Partial<Pick<T, K>> & Omit<T, K>;
+/**
+ * 產生從 1 到 N 的「數字字面量聯集」型別。
+ *
+ * @template N - 終止數字（必須是正整數）
+ * @template A - 用於遞迴計數的輔助 tuple，預設為 [any] 代表從 1 開始
+ * @template R - 暫存累積結果的 union，預設為 1
+ *
+ * @returns 1 | 2 | ... | N
+ *
+ * @example
+ * type T1 = Num1ToN<3>;
+ * //   ^? 1 | 2 | 3
+ *
+ * type T2 = Num1ToN<5>;
+ * //   ^? 1 | 2 | 3 | 4 | 5
+ *
+ * @warning
+ * ⚠ **效能注意事項**：
+ * - 遞迴深度等於 `N`，因此 `N` 過大會影響 TypeScript 編譯效能
+ * - 建議 **N ≤ 100**，否則 VS Code IntelliSense 可能變慢
+ */
+type Num1ToN<N extends number, A extends any[] = [], R extends number = never> = A['length'] extends N ? R | N : Num1ToN<N, [...A, any], R | (A['length'] extends 0 ? never : A['length'])>;
+/**
+ * 根據給定的前綴字串與數量，從陣列型別生成一個物件型別。
+ *
+ * @template T - 陣列型別，例如 `string[]`
+ * @template Prefix - 屬性鍵的前綴字串，例如 `'url'`
+ * @template N - 欄位數量，會生成 1..N 的鍵名
+ *
+ * @returns 一個物件型別，鍵為 `${Prefix}${1..N}`，值為 `T[number]`
+ *
+ * @example
+ * type List = string[];
+ *
+ * type Obj = BuildPrefixedObject<List, 'url', 3>;
+ * //   ^? { url1: string; url2: string; url3: string }
+ *
+ * type Obj2 = BuildPrefixedObject<List, 'name', 2>;
+ * //   ^? { name1: string; name2: string }
+ */
+type BuildPrefixedObject<T extends readonly unknown[], Prefix extends string, N extends number> = {
+    [K in Num1ToN<N> as `${Prefix}${K & number}`]: T[number];
+};
 
-export type { AtLeastOne, DeepPartial, Entries, MapToString, MapToType, OnlyOne, OverrideProps, PopArgs, PushArgs, ShiftArgs, TChangeKeyType, TExtractValueType, UnshiftArgs };
+export type { AtLeastOne, BuildPrefixedObject, DeepPartial, Entries, MapToString, MapToType, Num1ToN, OnlyOne, OverrideProps, PopArgs, PushArgs, ShiftArgs, TChangeKeyType, TExtractValueType, UnshiftArgs, WithOptional, WithRequired };

package/dist/es/index.d.mts

@@ -764,6 +764,20 @@ type PartialBy<T, K extends keyof T, RemoveUndefined extends boolean = false> =
  *
  */
 declare const deepClone: <T>(obj: T) => T;
+/**
+ * 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 }
+ */
+declare const renameKey: <T extends object, K extends keyof T, NK extends string>(obj: T, oldKey: K, newKey: NK) => Omit<T, K> & Record<NK, T[K]>;
 
 /**
  * debounce function
@@ -1321,5 +1335,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, 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 { 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, renameKey, rocEraToAd, searchParamsToObject, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useQueryContext, useValue, validTaxId, validateDateString, validateFileType, wait };
 export type { MimeTypeExtension, MimeTypeValue, PartialBy, RequiredBy, TCountdownActions };

package/dist/es/index.mjs

@@ -1,9 +1,9 @@
 import dayjs from 'dayjs';
-export { Q as QueryProvider, u as useQueryContext } from './queryStore-client-CFQTVwrg.mjs';
+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-client-t52WIHfq.mjs';
-export { d as downloadFile } from './download-client-CnaJ0p_f.mjs';
-export { g as getLocalStorage, s as setLocalStorage } from './webStorage-client-W1DItzhS.mjs';
+export { u as useCountdown } from './useCountdown-12s-t52WIHfq.mjs';
+export { d as downloadFile } from './download-12s-CnaJ0p_f.mjs';
+export { g as getLocalStorage, s as setLocalStorage } from './webStorage-12s-W1DItzhS.mjs';
 
 const FILE_SIZE_UNITS$1 = [
     'Bytes',
@@ -532,6 +532,27 @@ const isObject = (value)=>value !== null && typeof value === 'object';
     }, {});
     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
+    };
+};
 
 /**
  * 將嵌套物件的所有屬性設為指定的布林值
@@ -1392,4 +1413,4 @@ function mergeRefs(refs) {
     return dayjs(endMonth, 'YYYYMM').subtract(1911, 'year').format('YYYYMM').substring(1);
 };
 
-export { ByteSize, MimeTypeMap, OtherMimeType, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, convertBytes, createDataContext, createEnumLikeObject, debounce, deepClone, deepMerge, 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, mergeRefs, objectToSearchParams, omit, omitByValue, parseFileInfoFromFilename, parseFilenameFromDisposition, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, rocEraToAd, searchParamsToObject, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useValue, validTaxId, validateDateString, validateFileType, wait };
+export { ByteSize, MimeTypeMap, OtherMimeType, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, convertBytes, createDataContext, createEnumLikeObject, debounce, deepClone, deepMerge, 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, mergeRefs, objectToSearchParams, omit, omitByValue, parseFileInfoFromFilename, parseFilenameFromDisposition, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, renameKey, rocEraToAd, searchParamsToObject, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useValue, validTaxId, validateDateString, validateFileType, wait };

package/dist/es/types.d.mts

@@ -200,5 +200,70 @@ type MapToType<T extends Record<any, any>, A = any> = {
 type OverrideProps<T, R extends {
     [K in keyof R]: any;
 }> = Omit<T, keyof R> & R;
+/**
+ * A utility type that makes a specific property in the generic type `T` required while keeping the rest optional.
+ *
+ * @template T - The object type to modify.
+ * @template K - The key of the property to make required.
+ *
+ * @example
+ * type User = { id?: number; name?: string }
+ * type FormUser = WithRequired<User, 'id'> // { id: number; name?: string }
+ */
+type WithRequired<T, K extends keyof T> = Required<Pick<T, K>> & Omit<T, K>;
+/**
+ * A utility type that makes a specific property in the generic type `T` optional while keeping the rest required.
+ *
+ * @template T - The object type to modify.
+ * @template K - The key of the property to make optional.
+ *
+ * @example
+ * type User = { id: number; name: string }
+ * type FormUser = WithOptional<User, 'id'> // { id?: number; name: string }
+ */
+type WithOptional<T, K extends keyof T> = Partial<Pick<T, K>> & Omit<T, K>;
+/**
+ * 產生從 1 到 N 的「數字字面量聯集」型別。
+ *
+ * @template N - 終止數字（必須是正整數）
+ * @template A - 用於遞迴計數的輔助 tuple，預設為 [any] 代表從 1 開始
+ * @template R - 暫存累積結果的 union，預設為 1
+ *
+ * @returns 1 | 2 | ... | N
+ *
+ * @example
+ * type T1 = Num1ToN<3>;
+ * //   ^? 1 | 2 | 3
+ *
+ * type T2 = Num1ToN<5>;
+ * //   ^? 1 | 2 | 3 | 4 | 5
+ *
+ * @warning
+ * ⚠ **效能注意事項**：
+ * - 遞迴深度等於 `N`，因此 `N` 過大會影響 TypeScript 編譯效能
+ * - 建議 **N ≤ 100**，否則 VS Code IntelliSense 可能變慢
+ */
+type Num1ToN<N extends number, A extends any[] = [], R extends number = never> = A['length'] extends N ? R | N : Num1ToN<N, [...A, any], R | (A['length'] extends 0 ? never : A['length'])>;
+/**
+ * 根據給定的前綴字串與數量，從陣列型別生成一個物件型別。
+ *
+ * @template T - 陣列型別，例如 `string[]`
+ * @template Prefix - 屬性鍵的前綴字串，例如 `'url'`
+ * @template N - 欄位數量，會生成 1..N 的鍵名
+ *
+ * @returns 一個物件型別，鍵為 `${Prefix}${1..N}`，值為 `T[number]`
+ *
+ * @example
+ * type List = string[];
+ *
+ * type Obj = BuildPrefixedObject<List, 'url', 3>;
+ * //   ^? { url1: string; url2: string; url3: string }
+ *
+ * type Obj2 = BuildPrefixedObject<List, 'name', 2>;
+ * //   ^? { name1: string; name2: string }
+ */
+type BuildPrefixedObject<T extends readonly unknown[], Prefix extends string, N extends number> = {
+    [K in Num1ToN<N> as `${Prefix}${K & number}`]: T[number];
+};
 
-export type { AtLeastOne, DeepPartial, Entries, MapToString, MapToType, OnlyOne, OverrideProps, PopArgs, PushArgs, ShiftArgs, TChangeKeyType, TExtractValueType, UnshiftArgs };
+export type { AtLeastOne, BuildPrefixedObject, DeepPartial, Entries, MapToString, MapToType, Num1ToN, OnlyOne, OverrideProps, PopArgs, PushArgs, ShiftArgs, TChangeKeyType, TExtractValueType, UnshiftArgs, WithOptional, WithRequired };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gateweb/react-utils",
-  "version": "1.14.4",
+  "version": "1.15.0",
   "description": "React Utils for GateWeb",
   "homepage": "https://github.com/GatewebSolutions/react-utils",
   "files": [
@@ -31,6 +31,16 @@
       }
     }
   },
+  "scripts": {
+    "prepare": "husky",
+    "run-code": "ts-node src/period.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:ui": "vitest --ui --coverage.enabled=true",
+    "build": "bunchee",
+    "build:prepare": "bunchee --prepare"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -52,7 +62,7 @@
     "@types/react": "^19.1.8",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "3.2.4",
-    "bunchee": "^5.6.1",
+    "bunchee": "^6.6.0",
     "eslint": "^9.31.0",
     "husky": "^9.1.7",
     "jest": "^30.0.5",
@@ -69,13 +79,5 @@
       "@commitlint/config-conventional"
     ]
   },
-  "scripts": {
-    "run-code": "ts-node src/period.ts",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "test:ui": "vitest --ui --coverage.enabled=true",
-    "build": "bunchee",
-    "build:prepare": "bunchee --prepare"
-  }
+  "packageManager": "pnpm@10.11.0"
 }