@gateweb/react-utils 1.4.2 → 1.6.0

package/dist/cjs/index.d.ts

@@ -358,7 +358,15 @@ type TValueOptions<T> = AtLeastOne<{
     defaultValue?: T;
 }>;
 /**
+ * A hook to manage a value.
  *
+ * @example
+ *
+ * ```tsx
+ * const MyComponent = ({ value }: { value?: number }) => {
+ *    const [currentValue, setCurrentValue] = useValue({ value });
+ * };
+ * ```
  */
 declare const useValue: <T>({ value, defaultValue }: TValueOptions<T>) => readonly [T, (newValue: T) => void];
 
@@ -415,6 +423,21 @@ declare const pick: <T extends object, K extends [...(keyof T)[]]>(object: T, ..
  * const b = pickByValue(a, 1, 2); // { a: 1, b: 2 }
  */
 declare const pickByValue: <T extends object, K extends any[]>(object: T, ...values: K) => Pick<T, { [K2 in keyof T]: T[K2] extends K[number] ? K2 : never; }[keyof T]>;
+/**
+ * merge two objects deeply
+ *
+ * @param target - the target object
+ * @param source - the source object
+ *
+ * @example
+ *
+ * const obja = { a: { a1: { a11: 'value 1', a12: 'value 2' }, a2: 'value 3' }, b: 'value 4' };
+ * const objb = { a: { a1: { a13: 'value 5', a14: 'value 6' }, a3: 'value 7' }};
+ *
+ * const mergeResult = deepMerge(obja, objb); // { a: { a1: { a11: 'value 1', a12: 'value 2', a13: 'value 5', a14: 'value 6' }, a2: 'value 3', a3: 'value 7' }, b: 'value 4' }
+ *
+ */
+declare const deepMerge: <T extends object, U extends object>(target: T, source: U) => T & U;
 
 /**
  * debounce function
@@ -804,4 +827,4 @@ declare const getLocalStorage: <T>(key: string, deCode?: boolean) => T | undefin
  */
 declare const setLocalStorage: (key: string, value: Record<string, any>, enCode?: boolean) => void;
 
-export { type TCountdownActions, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, createEnumLikeObject, debounce, downloadFile, extractEnumLikeObject, fakeApi, formatAmount, formatBytes, formatStarMask, generatePeriodArray, getCurrentPeriod, getLocalStorage, getMimeType, invariant, isChinese, isDateString, isDateTimeString, isEmail, isEnglish, isNonZeroStart, isNumber, isNumberAtLeastN, isNumberN, isNumberNM, isServer, isTWMobile, isTWPhone, isTimeString, isValidPassword, mergeRefs, omit, omitByValue, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, rocEraToAd, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useValue, validTaxId, validateDateString, validateFileType, wait };
+export { type TCountdownActions, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, createEnumLikeObject, debounce, deepMerge, downloadFile, extractEnumLikeObject, fakeApi, formatAmount, formatBytes, formatStarMask, generatePeriodArray, getCurrentPeriod, getLocalStorage, getMimeType, invariant, isChinese, isDateString, isDateTimeString, isEmail, isEnglish, isNonZeroStart, isNumber, isNumberAtLeastN, isNumberN, isNumberNM, isServer, isTWMobile, isTWPhone, isTimeString, isValidPassword, mergeRefs, omit, omitByValue, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, rocEraToAd, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useValue, validTaxId, validateDateString, validateFileType, wait };

package/dist/cjs/index.js

@@ -474,7 +474,15 @@ const transformObjectKey = (obj, transformFunName)=>{
 };
 
 /**
+ * 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.');
@@ -594,6 +602,30 @@ message) {
         }
         return acc;
     }, {});
+const isObject = (value)=>value !== null && typeof value === 'object';
+/**
+ * merge two objects deeply
+ *
+ * @param target - the target object
+ * @param source - the source object
+ *
+ * @example
+ *
+ * const obja = { a: { a1: { a11: 'value 1', a12: 'value 2' }, a2: 'value 3' }, b: 'value 4' };
+ * const objb = { a: { a1: { a13: 'value 5', a14: 'value 6' }, a3: 'value 7' }};
+ *
+ * const mergeResult = deepMerge(obja, objb); // { a: { a1: { a11: 'value 1', a12: 'value 2', a13: 'value 5', a14: 'value 6' }, a2: 'value 3', a3: 'value 7' }, b: 'value 4' }
+ *
+ */ const deepMerge = (target, source)=>Object.entries(source).reduce((acc, [key, value])=>{
+        if (isObject(value)) {
+            acc[key] = key in target && isObject(target[key]) ? deepMerge(target[key], value) : value;
+        } else {
+            acc[key] = value;
+        }
+        return acc;
+    }, {
+        ...target
+    });
 
 /**
  * debounce function
@@ -909,6 +941,7 @@ exports.camelString2PascalString = camelString2PascalString;
 exports.camelString2SnakeString = camelString2SnakeString;
 exports.createEnumLikeObject = createEnumLikeObject;
 exports.debounce = debounce;
+exports.deepMerge = deepMerge;
 exports.extractEnumLikeObject = extractEnumLikeObject;
 exports.fakeApi = fakeApi;
 exports.formatAmount = formatAmount;

package/dist/cjs/types.d.ts

@@ -1,3 +1,50 @@
+/**
+ * A utility type that shifts the first argument of a function type `T` and returns the new function type.
+ *
+ * @template T - The function type to shift the first argument.
+ *
+ * @example
+ *
+ * type Example = (arg1: string, arg2: number) => boolean;
+ * type ShiftedExample = ShiftArgs<Example>; // ShiftedExample is (arg2: number) => boolean;
+ */
+type ShiftArgs<T extends (...args: any) => any> = T extends (arg1: any, ...rest: infer P) => infer R ? (...args: P) => R : never;
+/**
+ * A utility type that pops the last argument of a function type `T` and returns the new function type.
+ *
+ * @template T - The function type to pop the last argument.
+ *
+ * @example
+ *
+ * type Example = (arg1: string, arg2: number) => boolean;
+ * type PoppedExample = PopArgs<Example>; // PoppedExample is (arg1: string) => boolean;
+ */
+type PopArgs<T extends (...args: any) => any> = T extends (...args: [...infer P, any]) => infer R ? (...args: P) => R : never;
+/**
+ * A utility type that pushes a new argument of type `A` to the end of a function type `T` and returns the new function type.
+ *
+ * @template T - The function type to push the new argument.
+ * @template A - The new argument type to push.
+ *
+ * @example
+ *
+ * type Example = (arg1: string, arg2: number) => boolean;
+ * type PushedExample = PushArgs<Example, boolean>; // PushedExample is (arg1: string, arg2: number, arg3: boolean) => boolean;
+ */
+type PushArgs<T extends (...args: any) => any, A> = T extends (...args: infer P) => infer R ? (...args: [...P, A]) => R : never;
+/**
+ * A utility type that unshift a new argument of type `A` to the beginning of a function type `T` and returns the new function type.
+ *
+ * @template T - The function type to unshift the new argument.
+ * @template A - The new argument type to unshift.
+ *
+ * @example
+ *
+ * type Example = (arg1: string, arg2: number) => boolean;
+ * type UnshiftExample = UnshiftArgs<Example, boolean>; // UnshiftExample is (arg3: boolean, arg1: string, arg2: number) => boolean;
+ */
+type UnshiftArgs<T extends (...args: any) => any, A> = T extends (...args: infer P) => infer R ? (...args: [A, ...P]) => R : never;
+
 /**
  * 從對象類型中提取特定屬性的值類型。
  *
@@ -88,5 +135,41 @@ type OnlyOne<T> = {
         [P in Exclude<keyof T, K>]?: never;
     };
 }[keyof T];
+/**
+ * A utility type that makes all properties in the generic type `T` optional. Also, it makes all nested properties optional.
+ *
+ * @template T - The object type to make all properties optional.
+ *
+ * @example
+ *
+ * type Example = { a: string; b: number };
+ * type ExamplePartial = DeepPartial<Example>;
+ *
+ * const obj: ExamplePartial = { a: 'hello' }; // OK
+ *
+ * type ExampleDeep = { a: { b: string; c: number } };
+ * type ExampleDeepPartial = DeepPartial<ExampleDeep>;
+ *
+ * const obj2: ExampleDeepPartial = { a: { b: 'world' } }; // OK
+ */
+type DeepPartial<T> = (T extends (infer U)[] ? DeepPartial<U>[] : {
+    [P in keyof T]?: DeepPartial<T[P]>;
+}) | T;
+/**
+ * 將 Obj 指定的 key 轉換成指定的型別
+ *
+ * @example
+ *
+ * ```ts
+ * type Obj = { a: string, b: number, c: boolean}
+ *
+ * type NewObj = TChangeKeyType<Obj, 'b', string> // { a: string, b: string, c: boolean }
+ *
+ * type NewObj2 = TChangeKeyType<Obj, 'b' | 'c', string> // { a: string, b: string, c: string }
+ * ```
+ */
+type TChangeKeyType<T, K extends keyof T, V> = Omit<T, K> & {
+    [P in K]: V;
+};
 
-export type { AtLeastOne, Entries, MapToString, OnlyOne, TExtractValueType };
+export type { AtLeastOne, DeepPartial, Entries, MapToString, OnlyOne, PopArgs, PushArgs, ShiftArgs, TChangeKeyType, TExtractValueType, UnshiftArgs };

package/dist/es/index.d.mts

@@ -358,7 +358,15 @@ type TValueOptions<T> = AtLeastOne<{
     defaultValue?: T;
 }>;
 /**
+ * A hook to manage a value.
  *
+ * @example
+ *
+ * ```tsx
+ * const MyComponent = ({ value }: { value?: number }) => {
+ *    const [currentValue, setCurrentValue] = useValue({ value });
+ * };
+ * ```
  */
 declare const useValue: <T>({ value, defaultValue }: TValueOptions<T>) => readonly [T, (newValue: T) => void];
 
@@ -415,6 +423,21 @@ declare const pick: <T extends object, K extends [...(keyof T)[]]>(object: T, ..
  * const b = pickByValue(a, 1, 2); // { a: 1, b: 2 }
  */
 declare const pickByValue: <T extends object, K extends any[]>(object: T, ...values: K) => Pick<T, { [K2 in keyof T]: T[K2] extends K[number] ? K2 : never; }[keyof T]>;
+/**
+ * merge two objects deeply
+ *
+ * @param target - the target object
+ * @param source - the source object
+ *
+ * @example
+ *
+ * const obja = { a: { a1: { a11: 'value 1', a12: 'value 2' }, a2: 'value 3' }, b: 'value 4' };
+ * const objb = { a: { a1: { a13: 'value 5', a14: 'value 6' }, a3: 'value 7' }};
+ *
+ * const mergeResult = deepMerge(obja, objb); // { a: { a1: { a11: 'value 1', a12: 'value 2', a13: 'value 5', a14: 'value 6' }, a2: 'value 3', a3: 'value 7' }, b: 'value 4' }
+ *
+ */
+declare const deepMerge: <T extends object, U extends object>(target: T, source: U) => T & U;
 
 /**
  * debounce function
@@ -804,4 +827,4 @@ declare const getLocalStorage: <T>(key: string, deCode?: boolean) => T | undefin
  */
 declare const setLocalStorage: (key: string, value: Record<string, any>, enCode?: boolean) => void;
 
-export { type TCountdownActions, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, createEnumLikeObject, debounce, downloadFile, extractEnumLikeObject, fakeApi, formatAmount, formatBytes, formatStarMask, generatePeriodArray, getCurrentPeriod, getLocalStorage, getMimeType, invariant, isChinese, isDateString, isDateTimeString, isEmail, isEnglish, isNonZeroStart, isNumber, isNumberAtLeastN, isNumberN, isNumberNM, isServer, isTWMobile, isTWPhone, isTimeString, isValidPassword, mergeRefs, omit, omitByValue, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, rocEraToAd, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useValue, validTaxId, validateDateString, validateFileType, wait };
+export { type TCountdownActions, adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, createEnumLikeObject, debounce, deepMerge, downloadFile, extractEnumLikeObject, fakeApi, formatAmount, formatBytes, formatStarMask, generatePeriodArray, getCurrentPeriod, getLocalStorage, getMimeType, invariant, isChinese, isDateString, isDateTimeString, isEmail, isEnglish, isNonZeroStart, isNumber, isNumberAtLeastN, isNumberN, isNumberNM, isServer, isTWMobile, isTWPhone, isTimeString, isValidPassword, mergeRefs, omit, omitByValue, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, rocEraToAd, setLocalStorage, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useCountdown, useValue, validTaxId, validateDateString, validateFileType, wait };

package/dist/es/index.mjs

@@ -468,7 +468,15 @@ const transformObjectKey = (obj, transformFunName)=>{
 };
 
 /**
+ * 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.');
@@ -588,6 +596,30 @@ message) {
         }
         return acc;
     }, {});
+const isObject = (value)=>value !== null && typeof value === 'object';
+/**
+ * merge two objects deeply
+ *
+ * @param target - the target object
+ * @param source - the source object
+ *
+ * @example
+ *
+ * const obja = { a: { a1: { a11: 'value 1', a12: 'value 2' }, a2: 'value 3' }, b: 'value 4' };
+ * const objb = { a: { a1: { a13: 'value 5', a14: 'value 6' }, a3: 'value 7' }};
+ *
+ * const mergeResult = deepMerge(obja, objb); // { a: { a1: { a11: 'value 1', a12: 'value 2', a13: 'value 5', a14: 'value 6' }, a2: 'value 3', a3: 'value 7' }, b: 'value 4' }
+ *
+ */ const deepMerge = (target, source)=>Object.entries(source).reduce((acc, [key, value])=>{
+        if (isObject(value)) {
+            acc[key] = key in target && isObject(target[key]) ? deepMerge(target[key], value) : value;
+        } else {
+            acc[key] = value;
+        }
+        return acc;
+    }, {
+        ...target
+    });
 
 /**
  * debounce function
@@ -892,4 +924,4 @@ function mergeRefs(refs) {
  */ const wait = (ms)=>{
 };
 
-export { adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, createEnumLikeObject, debounce, extractEnumLikeObject, fakeApi, formatAmount, formatBytes, formatStarMask, generatePeriodArray, getCurrentPeriod, getMimeType, invariant, isChinese, isDateString, isDateTimeString, isEmail, isEnglish, isNonZeroStart, isNumber, isNumberAtLeastN, isNumberN, isNumberNM, isServer, isTWMobile, isTWPhone, isTimeString, isValidPassword, mergeRefs, omit, omitByValue, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, rocEraToAd, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useValue, validTaxId, validateDateString, validateFileType, wait };
+export { adToRocEra, camelCase2PascalCase, camelCase2SnakeCase, camelString2PascalString, camelString2SnakeString, createEnumLikeObject, debounce, deepMerge, extractEnumLikeObject, fakeApi, formatAmount, formatBytes, formatStarMask, generatePeriodArray, getCurrentPeriod, getMimeType, invariant, isChinese, isDateString, isDateTimeString, isEmail, isEnglish, isNonZeroStart, isNumber, isNumberAtLeastN, isNumberN, isNumberNM, isServer, isTWMobile, isTWPhone, isTimeString, isValidPassword, mergeRefs, omit, omitByValue, pascalCase2CamelCase, pascalCase2SnakeCase, pascalString2CamelString, pascalString2SnakeString, pick, pickByValue, rocEraToAd, snakeCase2CamelCase, snakeCase2PascalCase, snakeString2CamelString, snakeString2PascalString, throttle, useValue, validTaxId, validateDateString, validateFileType, wait };

package/dist/es/types.d.mts

@@ -1,3 +1,50 @@
+/**
+ * A utility type that shifts the first argument of a function type `T` and returns the new function type.
+ *
+ * @template T - The function type to shift the first argument.
+ *
+ * @example
+ *
+ * type Example = (arg1: string, arg2: number) => boolean;
+ * type ShiftedExample = ShiftArgs<Example>; // ShiftedExample is (arg2: number) => boolean;
+ */
+type ShiftArgs<T extends (...args: any) => any> = T extends (arg1: any, ...rest: infer P) => infer R ? (...args: P) => R : never;
+/**
+ * A utility type that pops the last argument of a function type `T` and returns the new function type.
+ *
+ * @template T - The function type to pop the last argument.
+ *
+ * @example
+ *
+ * type Example = (arg1: string, arg2: number) => boolean;
+ * type PoppedExample = PopArgs<Example>; // PoppedExample is (arg1: string) => boolean;
+ */
+type PopArgs<T extends (...args: any) => any> = T extends (...args: [...infer P, any]) => infer R ? (...args: P) => R : never;
+/**
+ * A utility type that pushes a new argument of type `A` to the end of a function type `T` and returns the new function type.
+ *
+ * @template T - The function type to push the new argument.
+ * @template A - The new argument type to push.
+ *
+ * @example
+ *
+ * type Example = (arg1: string, arg2: number) => boolean;
+ * type PushedExample = PushArgs<Example, boolean>; // PushedExample is (arg1: string, arg2: number, arg3: boolean) => boolean;
+ */
+type PushArgs<T extends (...args: any) => any, A> = T extends (...args: infer P) => infer R ? (...args: [...P, A]) => R : never;
+/**
+ * A utility type that unshift a new argument of type `A` to the beginning of a function type `T` and returns the new function type.
+ *
+ * @template T - The function type to unshift the new argument.
+ * @template A - The new argument type to unshift.
+ *
+ * @example
+ *
+ * type Example = (arg1: string, arg2: number) => boolean;
+ * type UnshiftExample = UnshiftArgs<Example, boolean>; // UnshiftExample is (arg3: boolean, arg1: string, arg2: number) => boolean;
+ */
+type UnshiftArgs<T extends (...args: any) => any, A> = T extends (...args: infer P) => infer R ? (...args: [A, ...P]) => R : never;
+
 /**
  * 從對象類型中提取特定屬性的值類型。
  *
@@ -88,5 +135,41 @@ type OnlyOne<T> = {
         [P in Exclude<keyof T, K>]?: never;
     };
 }[keyof T];
+/**
+ * A utility type that makes all properties in the generic type `T` optional. Also, it makes all nested properties optional.
+ *
+ * @template T - The object type to make all properties optional.
+ *
+ * @example
+ *
+ * type Example = { a: string; b: number };
+ * type ExamplePartial = DeepPartial<Example>;
+ *
+ * const obj: ExamplePartial = { a: 'hello' }; // OK
+ *
+ * type ExampleDeep = { a: { b: string; c: number } };
+ * type ExampleDeepPartial = DeepPartial<ExampleDeep>;
+ *
+ * const obj2: ExampleDeepPartial = { a: { b: 'world' } }; // OK
+ */
+type DeepPartial<T> = (T extends (infer U)[] ? DeepPartial<U>[] : {
+    [P in keyof T]?: DeepPartial<T[P]>;
+}) | T;
+/**
+ * 將 Obj 指定的 key 轉換成指定的型別
+ *
+ * @example
+ *
+ * ```ts
+ * type Obj = { a: string, b: number, c: boolean}
+ *
+ * type NewObj = TChangeKeyType<Obj, 'b', string> // { a: string, b: string, c: boolean }
+ *
+ * type NewObj2 = TChangeKeyType<Obj, 'b' | 'c', string> // { a: string, b: string, c: string }
+ * ```
+ */
+type TChangeKeyType<T, K extends keyof T, V> = Omit<T, K> & {
+    [P in K]: V;
+};
 
-export type { AtLeastOne, Entries, MapToString, OnlyOne, TExtractValueType };
+export type { AtLeastOne, DeepPartial, Entries, MapToString, OnlyOne, PopArgs, PushArgs, ShiftArgs, TChangeKeyType, TExtractValueType, UnshiftArgs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gateweb/react-utils",
-  "version": "1.4.2",
+  "version": "1.6.0",
   "description": "React Utils for GateWeb",
   "homepage": "https://github.com/GatewebSolutions/react-utils",
   "files": [
@@ -36,17 +36,17 @@
   },
   "dependencies": {
     "dayjs": "^1.11.13",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
     "@commitlint/cli": "^19.5.0",
     "@commitlint/config-conventional": "^19.5.0",
     "@gateweb/eslint-config-gateweb": "^1.0.6",
-    "@testing-library/react": "^16.0.1",
+    "@testing-library/react": "^16.2.0",
     "@types/jest": "^29.5.13",
     "@types/node": "^22.7.7",
-    "@types/react": "^18.3.11",
+    "@types/react": "^19.0.8",
     "@vitest/coverage-v8": "^2.1.4",
     "@vitest/ui": "2.1.4",
     "bunchee": "^5.6.1",