@gateweb/react-utils

@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.

✨ 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

# With pnpm (recommended)
pnpm add @gateweb/react-utils

# With npm
npm install @gateweb/react-utils

# With yarn
yarn add @gateweb/react-utils

🚀 Usage

Here are some examples of the most common utilities.

React Hooks

useCountdown

A hook to manage a countdown timer.

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

Date Utilities

formatDate

Format a date object or string into a custom format.

import { formatDate } from '@gateweb/react-utils';

const formattedDate = formatDate(new Date(), 'YYYY-MM-DD');
console.log(formattedDate); // e.g., "2023-10-27"

getPeriod

Get a predefined date period, like "last 7 days".

import { getPeriod } from '@gateweb/react-utils';

const last7Days = getPeriod('last_7_days');
console.log(last7Days); // { startDate: Dayjs, endDate: Dayjs }

Core Utilities

toCamelCase

Convert a string from snake_case or kebab-case to camelCase.

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).

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.

import { download } from '@gateweb/react-utils';

function handleDownload() {
  const blob = new Blob(['Hello, world!'], { type: 'text/plain' });
  download(blob, 'hello.txt');
}

🤝 Contributing

Contributions are welcome! To ensure a smooth development process, please follow these steps:

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:

   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.

   # Run all tests
   pnpm test
   
   # Run tests in watch mode
   pnpm test:watch

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.

Publishing (For Maintainers)

Manual Release

1. Update the version in package.json.
2. Install dependencies and build the package:

   pnpm install && pnpm build

3. Log in to npm:

   pnpm login

4. Publish the package:

   pnpm publish --access public --no-git-checks

Automatic Release

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 based on the commit messages (e.g., feat: for minor, fix: for patch).