# @saphe/react-use
> A collection of tiny, useful, type-safe React hooks.
Latest version **0.2.1** (published 2023-01-16) · MIT license · 0 weekly downloads
## Install
```sh
npm install @saphe/react-use
pnpm add @saphe/react-use
yarn add @saphe/react-use
bun add @saphe/react-use
```
## Health
**Score 30/100 (F)** — status: abandoned.
Positive: has types; esm support; no vulnerabilities; high quality score.
Warnings: low downloads; pre 1.0.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 0.2.1 |
| Published | 2023-01-16 |
| First published | 2022-06-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 16.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | William Ford |
| Maintainers | saphewilliam |
| Keywords | typescript, react, hooks, type-safe, use |
## Links
- npm: https://www.npmjs.com/package/@saphe/react-use
- Repository: https://github.com/saphewilliam/saphe-packages
- Homepage: https://github.com/saphewilliam/saphe-packages/tree/main/packages/react-use#readme
- Issues: https://github.com/saphewilliam/saphe-packages/labels/@saphe%2Freact-use
- npm.io page: https://npm.io/package/@saphe/react-use
## Alternatives
- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads
## Recent versions
- 0.2.1 (latest) — 2023-01-16
- 0.2.0 — 2022-08-10
- 0.1.1 — 2022-07-29
- 0.1.0 — 2022-06-02
## README
# @saphe/react-use
[](https://npmjs.com/@saphe/react-use)
[](https://npmjs.com/@saphe/react-use)
[](https://github.com/saphewilliam/saphe-packages/blob/main/LICENSE)
[](https://bundlephobia.com/package/@saphe/react-use)
[](https://libraries.io/npm/%40saphe%2Freact-use/)
[](https://codecov.io/gh/saphewilliam/saphe-packages)
[](https://github.com/saphewilliam/saphe-packages/blob/main/CONTRIBUTING.md)
A collection of tiny, useful, type-safe React hooks.
## Features
- ⚖️ Incredibly lightweight, only ~150 LOC per hook (including types),
- 🌳 Tree-shakable, only include in the bundle what is necessary,
- 👍 All hooks have a sophisticated type system powering them,
- ✔️ 100% test coverage,
- 0️⃣ 0 dependencies.
## Table of Contents
- [Getting Started](#getting-started)
* [Install](#install)
- [useAsyncReducer](#useasyncreducer)
* [Actions](#actions)
* [Queue](#queue)
* [Error handling](#error-handling)
- [useUrlParams](#useurlparams)
* [Parameter config](#parameter-config)
* [Next.JS integration](#nextjs-integration)
## Getting Started
### Install
```sh
pnpm add @saphe/react-use
# or
yarn add @saphe/react-use
# or
npm install @saphe/react-use
```
## useAsyncReducer
The `useAsyncReducer` hook is a variation of React's core useReducer hook. Not a fork, but heavily inspired by [@bitovi/use-simple-reducer](https://github.com/bitovi/use-simple-reducer).
`useAsyncReducer` takes an initial state object and an object of actions that would modify the state, and returns an object containing the current state, the actions that may be performed on the state, a boolean `isLoading` indicating if an action is processing, and an error object for if one of the actions threw an error. All of this with full type-safety.
### Actions
Actions are sync or async functions that accept a state and additional parameters, and return the next state.
```tsx
import { useAsyncReducer } from '@saphe/react-use';
import { ReactElement } from 'react';
export default function IncrementButtons(): ReactElement {
const { state, actions } = useAsyncReducer(
{ count: 0 },
{
increment: (state) => ({ count: state.count + 1 }),
add: async (state, n: number) => ({ count: state.count + n }),
},
);
return (
<>
);
}
```
Even though `add` was defined as an async function, it is called as a sync function with the predefined parameters (all type-safe). You can add as many parameters as you'd like and they can be of any type.
### Queue
If async functions are called after each other, they are added to a queue and are executed one after another. During this execution, the `isLoading` boolean will be `true`.
### Error handling
Any errors thrown within actions are caught and returned using the `error` object, which is `null` as long as there hasn't been an error.
```ts
const { error } = useAsyncReducer(
{ count: 0 },
{
increment: (state) => ({ count: state.count + 1 }),
error: () => {
throw Error('Something went horribly wrong');
},
},
);
```
If an error has occurred, the `error` object looks like this:
```ts
interface Error {
message: string;
action: Action;
pendingActions: Action[];
runFailedAction: () => void;
runPendingActions: () => void;
runAllActions: () => void;
}
```
## useUrlParams
The `useUrlParams` hook provides a type-safe way to parse your URL parameters. It takes a query object and either a parameter name, a list of parameter names, or a list of parameter configurations, and returns a type-safe object containing parsed values from the supplied query object.
### Parameter config
There are three ways to configure a parameter.
1. Define a single parameter name, returning an object with that parameter of type `string | null`:
```ts
const params = useUrlParams('singleStringParam');
params; // { singleStringParam: string | null; }
```
2. Define a list of parameter names, returning an object with those parameters of type `string | null`:
```ts
const params = useUrlParams(['firstStringParam', 'secondStringParam']);
params; // { firstStringParam: string | null; secondStringParam: string | null; }
```
3. Define a list of parameter configurations, returning an object with those parameters with their related type.
```ts
interface ParamConfig {
name: string;
/** Default: 'string' */
type?: 'string' | 'number' | 'boolean';
/** Default: false */
array?: boolean;
}
```
```ts
const params = useUrlParams([
{ name: 'numberParam', type: 'number' },
{ name: 'numberArr', type: 'number', array: true },
{ name: 'boolParam', type: 'boolean' },
{ name: 'boolArr', type: 'boolean', array: true },
{ name: 'stringParam', type: 'string' },
{ name: 'stringArr', type: 'string', array: true },
]);
params; // { numberParam: number | null; numberArr: number[]; boolParam: boolean | null; ...etc }
```
Options 2 and 3 may be combined in a mixed configuration:
```ts
const params = useUrlParams(['first', { name: 'second', type: 'number' }]);
params; // { first: string | null; second: number | null; }
```
### Next.JS integration
```ts
import { useUrlParams, UseUrlParamsTypes } from '@saphe/react-use';
import { useRouter } from 'next/router';
export default function useNextUrlParams<
S extends string,
C extends UseUrlParamsTypes.Config
>(
config: S | C[],
options?: UseUrlParamsTypes.Options,
): UseUrlParamsTypes.State {
const router = useRouter();
return useUrlParams(config, router.query, options);
}
```
---
_Source: https://npm.io/package/@saphe/react-use · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._