@saphe/react-use
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
Install
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.
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.
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 (
<>
<button onClick={actions.increment}>increment</button>
<button onClick={() => actions.add(5)}>add 5</button>
</>
);
}
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.
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:
interface Error<State> {
message: string;
action: Action<State>;
pendingActions: Action<State>[];
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.
- Define a single parameter name, returning an object with that parameter of type
string | null
:
const params = useUrlParams('singleStringParam');
params; // { singleStringParam: string | null; }
- Define a list of parameter names, returning an object with those parameters of type
string | null
:
const params = useUrlParams(['firstStringParam', 'secondStringParam']);
params; // { firstStringParam: string | null; secondStringParam: string | null; }
- Define a list of parameter configurations, returning an object with those parameters with their related type.
interface ParamConfig {
name: string;
/** Default: 'string' */
type?: 'string' | 'number' | 'boolean';
/** Default: false */
array?: boolean;
}
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:
const params = useUrlParams(['first', { name: 'second', type: 'number' }]);
params; // { first: string | null; second: number | null; }
Next.JS integration
import { useUrlParams, UseUrlParamsTypes } from '@saphe/react-use';
import { useRouter } from 'next/router';
export default function useNextUrlParams<
S extends string,
C extends UseUrlParamsTypes.Config<S>
>(
config: S | C[],
options?: UseUrlParamsTypes.Options,
): UseUrlParamsTypes.State<S, typeof config> {
const router = useRouter();
return useUrlParams(config, router.query, options);
}