@gateweb/react-utils 1.6.0 → 1.7.1

package/dist/cjs/index.d.ts

@@ -438,6 +438,40 @@ declare const pickByValue: <T extends object, K extends any[]>(object: T, ...val
  *
  */
 declare const deepMerge: <T extends object, U extends object>(target: T, source: U) => T & U;
+/**
+ * a utility type to make all properties of an object required
+ *
+ * @param T - the object type
+ * @param K - the keys to make required
+ * @param RemoveUndefined - whether to remove undefined from the type
+ *
+ * @example
+ *
+ * type A = { a?: number; b?: string | undefined; c?: boolean };
+ * // Even though b is required, it can be undefined
+ * type B = RequiredBy<A, 'a' | 'b'>; // { a: number; b: string | undefined; c?: boolean
+ * type C = RequiredBy<A, 'a' | 'b', true>; // { a: number; b: string; c?: boolean }
+ */
+type RequiredBy<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 type to make all properties of an object optional
+ *
+ * @param T - the object type
+ * @param K - the keys to make optional
+ * @param RemoveUndefined - whether to remove undefined from the type
+ *
+ * @example
+ *
+ * type A = { a: number; b: string | undefined; c: boolean };
+ * // Even though b is optional, it can be undefined
+ * type B = PartialBy<A, 'a' | 'b'>; // { a?: number; b?: string | undefined; c: boolean }
+ * type C = PartialBy<A, 'a' | 'b', true>; // { a?: number; b?: string; c: boolean }
+ */
+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];
+};
 
 /**
  * debounce function
@@ -703,6 +737,56 @@ declare const isTWMobile: () => RegExp;
  */
 declare const isTWPhone: () => RegExp;
 
+type TQueryProps<Q> = {
+    /**
+     * the query object
+     */
+    query: Partial<Q>;
+};
+type TQueryState<Q> = {
+    /**
+     * trigger the change of query
+     *
+     * @param query - the new query
+     */
+    changeQuery: (query: TQueryProps<Q>['query']) => void;
+} & TQueryProps<Q>;
+type TInitialProps<Q> = Partial<TQueryProps<Q> & {
+    /**
+     * handle the change of query when calling `changeQuery`
+     *
+     * @param preQuery - the previous query
+     * @param newQuery - the new query
+     * @returns the custom new query
+     */
+    handleChangeQuery: (preQuery: TQueryProps<Q>['query'], newQuery: TQueryProps<Q>['query']) => TQueryProps<Q>['query'];
+}>;
+/**
+ * Provider to provide the store to the context
+ */
+declare const QueryProvider: <Q>({ children, query, handleChangeQuery, }: React.PropsWithChildren<TInitialProps<Q>>) => React.JSX.Element;
+/**
+ * hook to get the store from the context
+ *
+ * because we want the return type of `selector` to be inferred by ts, we use HOF to implement the hook
+ *
+ * so you should use it like this:
+ *
+ * ```tsx
+ * const useQuery = useQueryContext<MyObject>(); // => will return the store hook
+ * const result = useQuery(q => q.query); // => will return the query object
+ * ```
+ *
+ * @example
+ *
+ * ```tsx
+ * const result1 = useQueryContext<MyObject>()(q => '1234');
+ * const result2 = useQueryContext<MyObject>()(q => q.changeQuery);
+ * const result3 = useQueryContext<MyObject>()(q => q.query);
+ * ```
+ */
+declare const useQueryContext: <Q>() => <T>(selector: (state: TQueryState<Q>) => T, equalityFn?: (left: T, right: T) => boolean) => T;
+
 /**
  * 將數字轉換成金額千分位格式
  *
@@ -827,4 +911,5 @@ 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, 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 };
+export { QueryProvider, 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, useQueryContext, useValue, validTaxId, validateDateString, validateFileType, wait };
+export type { PartialBy, RequiredBy, TCountdownActions };

package/dist/cjs/index.js

@@ -1,8 +1,9 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var dayjs = require('dayjs');
-var useCountdownClient = require('./useCountdown-client-CNjGBIUB.js');
-var react = require('react');
+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');
 
@@ -488,8 +489,8 @@ const transformObjectKey = (obj, transformFunName)=>{
         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)=>{
+    const [internalValue, setInternalValue] = React.useState(defaultValue);
+    const setValue = React.useCallback((newValue)=>{
         if (!isControlled) {
             setInternalValue(newValue);
         }
@@ -931,6 +932,8 @@ function mergeRefs(refs) {
 };
 
 exports.useCountdown = useCountdownClient.useCountdown;
+exports.QueryProvider = queryStoreClient.QueryProvider;
+exports.useQueryContext = queryStoreClient.useQueryContext;
 exports.downloadFile = downloadClient.downloadFile;
 exports.getLocalStorage = webStorageClient.getLocalStorage;
 exports.setLocalStorage = webStorageClient.setLocalStorage;

package/dist/cjs/queryStore-client-q_SLGgYH.js

@@ -0,0 +1,77 @@
+'use client';
+var React = require('react');
+var zustand = require('zustand');
+var traditional = require('zustand/traditional');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var React__default = /*#__PURE__*/_interopDefault(React);
+
+const createQueryStore = ({ query, handleChangeQuery })=>zustand.createStore()((set)=>({
+            query: {
+                ...query
+            },
+            changeQuery: (newQuery)=>{
+                set((pre)=>{
+                    if (handleChangeQuery) {
+                        return {
+                            query: handleChangeQuery(pre.query, newQuery)
+                        };
+                    }
+                    return {
+                        query: {
+                            ...pre.query,
+                            ...newQuery
+                        }
+                    };
+                });
+            }
+        }));
+const QueryContext = /*#__PURE__*/ React.createContext(null);
+/**
+ * Provider to provide the store to the context
+ */ const QueryProvider = ({ children, query, handleChangeQuery })=>{
+    const storeRef = React.useRef(null);
+    if (!storeRef.current) {
+        storeRef.current = createQueryStore({
+            query,
+            handleChangeQuery
+        });
+    }
+    return /*#__PURE__*/ React__default.default.createElement(QueryContext.Provider, {
+        value: storeRef.current
+    }, children);
+};
+/**
+ * hook to get the store from the context
+ *
+ * because we want the return type of `selector` to be inferred by ts, we use HOF to implement the hook
+ *
+ * so you should use it like this:
+ *
+ * ```tsx
+ * const useQuery = useQueryContext<MyObject>(); // => will return the store hook
+ * const result = useQuery(q => q.query); // => will return the query object
+ * ```
+ *
+ * @example
+ *
+ * ```tsx
+ * const result1 = useQueryContext<MyObject>()(q => '1234');
+ * const result2 = useQueryContext<MyObject>()(q => q.changeQuery);
+ * const result3 = useQueryContext<MyObject>()(q => q.query);
+ * ```
+ */ const useQueryContext = ()=>{
+    const store = React.useContext(QueryContext);
+    if (!store) throw new Error('Missing QueryContext.Provider in the tree');
+    /**
+   *  the hook to get the store
+   *
+   * @param selector - the selector to get the state from the store
+   * @param equalityFn - the equality function to compare the previous and next state, if it returns `true`, the component will not re-render
+   */ const useStore = (selector, equalityFn)=>traditional.useStoreWithEqualityFn(store, selector, equalityFn);
+    return useStore;
+};
+
+exports.QueryProvider = QueryProvider;
+exports.useQueryContext = useQueryContext;

package/dist/cjs/types.d.ts

@@ -88,6 +88,8 @@ type Entries<T> = {
  *
  * @template T - The object type to transform into keys.
  *
+ * @deprecated Use `MapToType` instead.
+ *
  * @example
  *
  * type Example = { a: number; b: string };
@@ -171,5 +173,19 @@ type DeepPartial<T> = (T extends (infer U)[] ? DeepPartial<U>[] : {
 type TChangeKeyType<T, K extends keyof T, V> = Omit<T, K> & {
     [P in K]: V;
 };
+/**
+ * A utility type that transforms an object type `T` into another object type where each value type is replaced with type `A`.
+ *
+ * @template T - The object type to transform into keys.
+ *
+ * @example
+ *
+ * type Example = { a: number; b: string };
+ * type ExampleToBoolean = MapToType<Example, boolean>;
+ * // Result: ExampleToBoolean is { a: boolean; b: boolean; }
+ */
+type MapToType<T extends Record<any, any>, A = any> = {
+    [K in keyof T]: A;
+};
 
-export type { AtLeastOne, DeepPartial, Entries, MapToString, OnlyOne, PopArgs, PushArgs, ShiftArgs, TChangeKeyType, TExtractValueType, UnshiftArgs };
+export type { AtLeastOne, DeepPartial, Entries, MapToString, MapToType, OnlyOne, PopArgs, PushArgs, ShiftArgs, TChangeKeyType, TExtractValueType, UnshiftArgs };

package/dist/cjs/{useCountdown-client-CNjGBIUB.js → useCountdown-client-uiqhgllY.js}

@@ -1,5 +1,5 @@
 'use client';
-var react = require('react');
+var React = require('react');
 
 /**
  * 倒數計時器
@@ -11,17 +11,17 @@ var react = require('react');
  * @param initialCountdown 倒數計時器初始值
  * @param enableReinitialize 允許重設初始值
  */ const useCountdown = (initialCountdown, enableReinitialize = false)=>{
-    const [countdown, setCountdown] = react.useState(initialCountdown);
-    const [isCounting, setIsCounting] = react.useState(false);
-    const initialValues = react.useRef(initialCountdown);
-    const isMounted = react.useRef(false);
-    react.useEffect(()=>{
+    const [countdown, setCountdown] = React.useState(initialCountdown);
+    const [isCounting, setIsCounting] = React.useState(false);
+    const initialValues = React.useRef(initialCountdown);
+    const isMounted = React.useRef(false);
+    React.useEffect(()=>{
         isMounted.current = true;
         return ()=>{
             isMounted.current = false;
         };
     }, []);
-    react.useEffect(()=>{
+    React.useEffect(()=>{
         if (isMounted.current && initialValues.current !== initialCountdown && enableReinitialize) {
             initialValues.current = initialCountdown;
             setCountdown(initialCountdown);
@@ -30,7 +30,7 @@ var react = require('react');
         initialCountdown,
         enableReinitialize
     ]);
-    react.useEffect(()=>{
+    React.useEffect(()=>{
         let timer;
         if (isCounting && countdown > 0) {
             timer = setTimeout(()=>{

package/dist/es/index.d.mts

@@ -438,6 +438,40 @@ declare const pickByValue: <T extends object, K extends any[]>(object: T, ...val
  *
  */
 declare const deepMerge: <T extends object, U extends object>(target: T, source: U) => T & U;
+/**
+ * a utility type to make all properties of an object required
+ *
+ * @param T - the object type
+ * @param K - the keys to make required
+ * @param RemoveUndefined - whether to remove undefined from the type
+ *
+ * @example
+ *
+ * type A = { a?: number; b?: string | undefined; c?: boolean };
+ * // Even though b is required, it can be undefined
+ * type B = RequiredBy<A, 'a' | 'b'>; // { a: number; b: string | undefined; c?: boolean
+ * type C = RequiredBy<A, 'a' | 'b', true>; // { a: number; b: string; c?: boolean }
+ */
+type RequiredBy<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 type to make all properties of an object optional
+ *
+ * @param T - the object type
+ * @param K - the keys to make optional
+ * @param RemoveUndefined - whether to remove undefined from the type
+ *
+ * @example
+ *
+ * type A = { a: number; b: string | undefined; c: boolean };
+ * // Even though b is optional, it can be undefined
+ * type B = PartialBy<A, 'a' | 'b'>; // { a?: number; b?: string | undefined; c: boolean }
+ * type C = PartialBy<A, 'a' | 'b', true>; // { a?: number; b?: string; c: boolean }
+ */
+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];
+};
 
 /**
  * debounce function
@@ -703,6 +737,56 @@ declare const isTWMobile: () => RegExp;
  */
 declare const isTWPhone: () => RegExp;
 
+type TQueryProps<Q> = {
+    /**
+     * the query object
+     */
+    query: Partial<Q>;
+};
+type TQueryState<Q> = {
+    /**
+     * trigger the change of query
+     *
+     * @param query - the new query
+     */
+    changeQuery: (query: TQueryProps<Q>['query']) => void;
+} & TQueryProps<Q>;
+type TInitialProps<Q> = Partial<TQueryProps<Q> & {
+    /**
+     * handle the change of query when calling `changeQuery`
+     *
+     * @param preQuery - the previous query
+     * @param newQuery - the new query
+     * @returns the custom new query
+     */
+    handleChangeQuery: (preQuery: TQueryProps<Q>['query'], newQuery: TQueryProps<Q>['query']) => TQueryProps<Q>['query'];
+}>;
+/**
+ * Provider to provide the store to the context
+ */
+declare const QueryProvider: <Q>({ children, query, handleChangeQuery, }: React.PropsWithChildren<TInitialProps<Q>>) => React.JSX.Element;
+/**
+ * hook to get the store from the context
+ *
+ * because we want the return type of `selector` to be inferred by ts, we use HOF to implement the hook
+ *
+ * so you should use it like this:
+ *
+ * ```tsx
+ * const useQuery = useQueryContext<MyObject>(); // => will return the store hook
+ * const result = useQuery(q => q.query); // => will return the query object
+ * ```
+ *
+ * @example
+ *
+ * ```tsx
+ * const result1 = useQueryContext<MyObject>()(q => '1234');
+ * const result2 = useQueryContext<MyObject>()(q => q.changeQuery);
+ * const result3 = useQueryContext<MyObject>()(q => q.query);
+ * ```
+ */
+declare const useQueryContext: <Q>() => <T>(selector: (state: TQueryState<Q>) => T, equalityFn?: (left: T, right: T) => boolean) => T;
+
 /**
  * 將數字轉換成金額千分位格式
  *
@@ -827,4 +911,5 @@ 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, 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 };
+export { QueryProvider, 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, useQueryContext, useValue, validTaxId, validateDateString, validateFileType, wait };
+export type { PartialBy, RequiredBy, TCountdownActions };

package/dist/es/index.mjs

@@ -1,6 +1,7 @@
 import dayjs from 'dayjs';
 export { u as useCountdown } from './useCountdown-client-t52WIHfq.mjs';
 import { useState, useCallback } from 'react';
+export { Q as QueryProvider, u as useQueryContext } from './queryStore-client-CFQTVwrg.mjs';
 export { d as downloadFile } from './download-client-CnaJ0p_f.mjs';
 export { g as getLocalStorage, s as setLocalStorage } from './webStorage-client-Pd-loNCg.mjs';
 

package/dist/es/queryStore-client-CFQTVwrg.mjs

@@ -0,0 +1,72 @@
+'use client';
+import React, { useRef, createContext, useContext } from 'react';
+import { createStore } from 'zustand';
+import { useStoreWithEqualityFn } from 'zustand/traditional';
+
+const createQueryStore = ({ query, handleChangeQuery })=>createStore()((set)=>({
+            query: {
+                ...query
+            },
+            changeQuery: (newQuery)=>{
+                set((pre)=>{
+                    if (handleChangeQuery) {
+                        return {
+                            query: handleChangeQuery(pre.query, newQuery)
+                        };
+                    }
+                    return {
+                        query: {
+                            ...pre.query,
+                            ...newQuery
+                        }
+                    };
+                });
+            }
+        }));
+const QueryContext = /*#__PURE__*/ createContext(null);
+/**
+ * Provider to provide the store to the context
+ */ const QueryProvider = ({ children, query, handleChangeQuery })=>{
+    const storeRef = useRef(null);
+    if (!storeRef.current) {
+        storeRef.current = createQueryStore({
+            query,
+            handleChangeQuery
+        });
+    }
+    return /*#__PURE__*/ React.createElement(QueryContext.Provider, {
+        value: storeRef.current
+    }, children);
+};
+/**
+ * hook to get the store from the context
+ *
+ * because we want the return type of `selector` to be inferred by ts, we use HOF to implement the hook
+ *
+ * so you should use it like this:
+ *
+ * ```tsx
+ * const useQuery = useQueryContext<MyObject>(); // => will return the store hook
+ * const result = useQuery(q => q.query); // => will return the query object
+ * ```
+ *
+ * @example
+ *
+ * ```tsx
+ * const result1 = useQueryContext<MyObject>()(q => '1234');
+ * const result2 = useQueryContext<MyObject>()(q => q.changeQuery);
+ * const result3 = useQueryContext<MyObject>()(q => q.query);
+ * ```
+ */ const useQueryContext = ()=>{
+    const store = useContext(QueryContext);
+    if (!store) throw new Error('Missing QueryContext.Provider in the tree');
+    /**
+   *  the hook to get the store
+   *
+   * @param selector - the selector to get the state from the store
+   * @param equalityFn - the equality function to compare the previous and next state, if it returns `true`, the component will not re-render
+   */ const useStore = (selector, equalityFn)=>useStoreWithEqualityFn(store, selector, equalityFn);
+    return useStore;
+};
+
+export { QueryProvider as Q, useQueryContext as u };

package/dist/es/types.d.mts

@@ -88,6 +88,8 @@ type Entries<T> = {
  *
  * @template T - The object type to transform into keys.
  *
+ * @deprecated Use `MapToType` instead.
+ *
  * @example
  *
  * type Example = { a: number; b: string };
@@ -171,5 +173,19 @@ type DeepPartial<T> = (T extends (infer U)[] ? DeepPartial<U>[] : {
 type TChangeKeyType<T, K extends keyof T, V> = Omit<T, K> & {
     [P in K]: V;
 };
+/**
+ * A utility type that transforms an object type `T` into another object type where each value type is replaced with type `A`.
+ *
+ * @template T - The object type to transform into keys.
+ *
+ * @example
+ *
+ * type Example = { a: number; b: string };
+ * type ExampleToBoolean = MapToType<Example, boolean>;
+ * // Result: ExampleToBoolean is { a: boolean; b: boolean; }
+ */
+type MapToType<T extends Record<any, any>, A = any> = {
+    [K in keyof T]: A;
+};
 
-export type { AtLeastOne, DeepPartial, Entries, MapToString, OnlyOne, PopArgs, PushArgs, ShiftArgs, TChangeKeyType, TExtractValueType, UnshiftArgs };
+export type { AtLeastOne, DeepPartial, Entries, MapToString, MapToType, OnlyOne, PopArgs, PushArgs, ShiftArgs, TChangeKeyType, TExtractValueType, UnshiftArgs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gateweb/react-utils",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "React Utils for GateWeb",
   "homepage": "https://github.com/GatewebSolutions/react-utils",
   "files": [
@@ -37,7 +37,9 @@
   "dependencies": {
     "dayjs": "^1.11.13",
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "use-sync-external-store": "^1.5.0",
+    "zustand": "^5.0.3"
   },
   "devDependencies": {
     "@commitlint/cli": "^19.5.0",