@gateweb/react-utils 1.12.2 → 1.14.0

package/README.md

@@ -1,74 +1,162 @@
-# react-utils
+# @gateweb/react-utils
 
-**_react-utils_** is a collection of utility functions for GateWeb's React projects.
+**`@gateweb/react-utils`** is a comprehensive, TypeScript-first utility library designed to streamline development in React projects at GateWeb. It provides a collection of robust, well-tested, and reusable functions and hooks, covering everything from date manipulation and type conversion to custom hooks and web APIs.
 
-## Installation
+[![npm version](https://img.shields.io/npm/v/@gateweb/react-utils.svg)](https://www.npmjs.com/package/@gateweb/react-utils)
+
+## ✨ Features
+
+- **React Hooks**: A collection of useful hooks like `useCountdown` and `useValue`.
+- **Date Utilities**: Powerful and flexible functions for handling dates and time periods, built on top of `dayjs`.
+- **Core Helpers**: A wide range of utilities for type conversion (`bytes`, `searchParams`), case style formatting, object manipulation, and more.
+- **Web APIs**: Simplified functions for common web tasks like file downloads (`download`) and managing browser storage (`webStorage`).
+- **Validation**: A set of predefined regex patterns and validation functions for common data types.
+- **TypeScript First**: Fully written in TypeScript, providing excellent type safety and autocompletion out of the box.
+- **Lightweight & Tree-Shakable**: Built with `bunchee` to ensure minimal bundle size.
+
+## 📦 Installation
 
 ```bash
+# With pnpm (recommended)
+pnpm add @gateweb/react-utils
+
+# With npm
 npm install @gateweb/react-utils
-# or
+
+# With yarn
 yarn add @gateweb/react-utils
-# or
-pnpm add @gateweb/react-utils
 ```
 
-## Usage
+## 🚀 Usage
+
+Here are some examples of the most common utilities.
+
+### React Hooks
+
+#### `useCountdown`
+
+A hook to manage a countdown timer.
 
 ```tsx
-import { formatAmount } from '@gateweb/react-utils';
+import { useCountdown } from '@gateweb/react-utils';
+
+function MyComponent() {
+  const { count, start, stop, reset } = useCountdown({ initialValue: 60 });
+
+  return (
+    <div>
+      <p>Countdown: {count}</p>
+      <button onClick={start}>Start</button>
+      <button onClick={stop}>Stop</button>
+      <button onClick={reset}>Reset</button>
+    </div>
+  );
+}
 ```
 
-## How to Release a New Version
+### Date Utilities
+
+#### `formatDate`
+
+Format a date object or string into a custom format.
 
-### Manually Bump the Version
+```ts
+import { formatDate } from '@gateweb/react-utils';
 
-1. Update the version in `package.json`
+const formattedDate = formatDate(new Date(), 'YYYY-MM-DD');
+console.log(formattedDate); // e.g., "2023-10-27"
+```
+
+#### `getPeriod`
 
-   ```diff
-   # e.g. bump the version from 0.1.0 to 0.1.1
-   {
-       "name": "@gateweb/react-utils",
-   -   "version": "0.1.0"
-   +   "version": "0.1.1"
-   }
-   ```
+Get a predefined date period, like "last 7 days".
 
-2. Install the dependencies and build the package
+```ts
+import { getPeriod } from '@gateweb/react-utils';
+
+const last7Days = getPeriod('last_7_days');
+console.log(last7Days); // { startDate: Dayjs, endDate: Dayjs }
+```
 
-   ```sh
-   pnpm install
-   pnpm build
-   ```
+### Core Utilities
+
+#### `toCamelCase`
+
+Convert a string from snake_case or kebab-case to camelCase.
+
+```ts
+import { toCamelCase } from '@gateweb/react-utils';
+
+const camel = toCamelCase('hello_world-example');
+console.log(camel); // "helloWorldExample"
+```
+
+#### `bytesToSize`
+
+Convert bytes to a human-readable format (KB, MB, GB).
+
+```ts
+import { bytesToSize } from '@gateweb/react-utils';
+
+const size = bytesToSize(1024 * 1024 * 5); // 5MB
+console.log(size); // "5 MB"
+```
+
+### Web APIs
+
+#### `download`
+
+A simple utility to trigger a file download in the browser.
+
+```ts
+import { download } from '@gateweb/react-utils';
+
+function handleDownload() {
+  const blob = new Blob(['Hello, world!'], { type: 'text/plain' });
+  download(blob, 'hello.txt');
+}
+```
 
-3. login to npm
+## 🤝 Contributing
 
-   ```sh
-   # make sure you have an npm account
-   pnpm login
-   # npm notice Log in on https://registry.npmjs.org/
-   # Login at:
-   # https://www.npmjs.com/login?next=/login/cli/390e514d-7aa5-4ee7-a13a-b17e6dd64518
-   # Press ENTER to open in the browser...
-   ```
+Contributions are welcome! To ensure a smooth development process, please follow these steps:
 
-4. Publish the package
+1.  **Fork & Clone**: Fork the repository and clone it to your local machine.
+2.  **Set Up**: This project uses `pnpm` as the package manager. Install dependencies with:
+    ```bash
+    pnpm install
+    ```
+3.  **Develop**: Create a new branch for your feature or bug fix.
+4.  **Test**: Write tests for your changes and ensure all existing tests pass.
 
-   ```sh
-   pnpm publish --access public --no-git-checks
-   ```
+    ```bash
+    # Run all tests
+    pnpm test
 
-5. Check the published package on npmjs.com
+    # Run tests in watch mode
+    pnpm test:watch
+    ```
 
-   [@gateweb/react-utils](https://www.npmjs.com/package/@gateweb/react-utils)
+5.  **Submit a Pull Request**: Push your changes to your fork and open a pull request to the `main` branch. Your code will be automatically linted and formatted upon commit.
 
-### Automatically Bump the Version
+## Publishing (For Maintainers)
 
-- When you merge a pull request to the `main` branch, the GitHub Action will automatically bump the version and publish the package to npm.
+### Manual Release
 
-- The version will follow the [Semantic Versioning](https://semver.org/) rules.
+1.  Update the version in `package.json`.
+2.  Install dependencies and build the package:
+    ```sh
+    pnpm install && pnpm build
+    ```
+3.  Log in to npm:
+    ```sh
+    pnpm login
+    ```
+4.  Publish the package:
+    ```sh
+    pnpm publish --access public --no-git-checks
+    ```
 
-## Notes
+### Automatic Release
 
-- You should use `pnpm` to develop this package.
-- This package is written in TypeScript and supports TypeScript out of the box.
-- This package is built with [bunchee](https://github.com/huozhi/bunchee) which is a zero-config build tool for TypeScript packages based on Rollup.
+When a pull request is merged into the `main` branch, the `release` GitHub Action will automatically bump the version, create a changelog, and publish the new version to npm. The version bump follows [Semantic Versioning](https.semver.org/) based on the commit messages (e.g., `feat:` for minor, `fix:` for patch).

package/dist/cjs/index.d.ts

@@ -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 };