recoil-tools v2.0.3
Recoil Tools
Custom Recoil atoms and hooks for basic application needs. All atoms are wrappers around native Recoil's atom
function,
so they enforce particular data structure depending on the atom type.
This library only includes static atoms for data storage, no asynchronous logic is involved.
Installation
npm i recoil-tools --save
or
yarn add recoil-tools
List
Useful for organizing and managing data in a list format.
Creation and Usage
Created using listAtom
.
// atoms/listState.ts
import { listAtom } from 'recoil-tools';
export default listAtom<
{ id: string; email: string },
{ activeItemId: string | null }
>({
key: 'listState',
default: {
data: [],
meta: { activeItemId: null },
},
});
Access to the list state and setters is provided through useRecoilList
hook.
import { useRecoilList } from 'recoil-tools';
import listState from './atoms/listState';
function App() {
const [state, setters] = useRecoilList(listState);
}
You can also use only state's data
property:
import { useRecoilListData } from 'recoil-tools';
import listState from './atoms/listState';
function App() {
const users = useRecoilListData(listState);
}
Or only meta
property:
import { useRecoilListMeta } from 'recoil-tools';
import listState from './atoms/listState';
function App() {
const { activeUserId } = useRecoilListMeta(listState);
}
Or only state setters:
import { useRecoilListSetters } from 'recoil-tools';
import listState from './atoms/listState';
function App() {
const { push, reverse } = useRecoilListSetters(listState);
}
API Reference
State
type RecoilListState<T, U> = Readonly<{
/**
* Data items.
*/
data: T[];
/**
* Any metadata related to the list.
*/
meta: U;
}>;
Setters
type RecoilListSetters<T, U> = Readonly<{
/**
* `data` property setter.
*/
setData: SetterOrUpdater<T[]>;
/**
* Alias for `setData([])`.
*/
clearData: () => void;
/**
* `meta` property setter.
*/
setMeta: SetterOrUpdater<U>;
/**
* Inserts an arbitrary number of items at the start of the list.
*/
unshift: (...items: T[]) => void;
/**
* Inserts an arbitrary number of items at the end of the list.
*/
push: (...items: T[]) => void;
/**
* Clears list and inserts an arbitrary number of items.
* Basically a combination of `clearData` and `push`.
*/
clearPush: (...items: T[]) => void;
/**
* Inserts a new item if predicate doesn't return `true`.
*/
upsert: (predicate: (item: T, index: number) => boolean, newItem: T) => void;
/**
* Updates an item at a particular index.
*/
updateAt: (index: number, item: T) => void;
/**
* Updates first item satisfying predicate.
*/
update: (predicate: (item: T, index: number) => boolean, newItem: T) => void;
/**
* Updates all items satisfying predicate.
*/
updateAll: (
predicate: (item: T, index: number) => boolean,
newItem: T
) => void;
/**
* Removes an item at a particular index.
*/
removeAt: (index: number) => void;
/**
* Removes first item satisfying predicate.
*/
remove: (predicate: (item: T, index: number) => boolean) => void;
/**
* Removes all items satisfying predicate.
*/
removeAll: (predicate: (item: T, index: number) => boolean) => void;
/**
* Works like native `Array.filter`.
*/
filter: (
predicate: (value: T, index: number, array: T[]) => boolean,
thisArg?: any
) => void;
/**
* Works like native `Array.sort`.
*/
sort: (compareFn?: (a: T, b: T) => number) => void;
/**
* Works like native `Array.reverse`.
*/
reverse: () => void;
/**
* Resets list state to initial. Done through `useResetRecoilState`.
*/
reset: () => void;
}>;
Dialog
Useful for managing state of global dialog windows like app theme, language, settings or confirmation dialog.
Creation and Usage
Created using dialogAtom
.
// atoms/dialogState.ts
import { dialogAtom } from 'recoil-tools';
export default dialogAtom<{ isDarkMode: boolean }>({
key: 'dialogState',
default: {
isOpen: false,
meta: { isDarkMode: false },
},
});
Access to the dialog state and setters is provided through useRecoilDialog
hook.
import { useRecoilDialog } from 'recoil-tools';
import dialogState from './atoms/dialogState';
function App() {
const [state, setters] = useRecoilDialog(dialogState);
}
You can also use only state's isOpen
property:
import { useRecoilDialogIsOpen } from 'recoil-tools';
import dialogState from './atoms/dialogState';
function App() {
const isOpen = useRecoilDialogIsOpen(dialogState);
}
Or only meta
property:
import { useRecoilDialogMeta } from 'recoil-tools';
import dialogState from './atoms/dialogState';
function App(): JSX.Element {
const { isDarkMode } = useRecoilDialogMeta(dialogState);
}
Or only state setters:
import { useRecoilDialogSetters } from 'recoil-tools';
import dialogState from './atoms/dialogState';
function App() {
const { open } = useRecoilDialogSetters(userListState);
}
API Reference
State
type RecoilDialogState<T> = Readonly<{
/**
* Dialog open state.
*/
isOpen: boolean;
/**
* Any metadata related to the dialog.
*/
meta: T;
}>;
Setters
type RecoilDialogSetters<T> = Readonly<{
/**
* `isOpen` property setter.
*/
setOpen: SetterOrUpdater<boolean>;
/**
* Sets `isOpen` state to `true`. Also supports setting `meta` property.
*/
open: (meta?: T) => void;
/**
* Sets `isOpen` state to `false`.
*/
close: () => void;
/**
* `meta` property setter.
*/
setMeta: SetterOrUpdater<T>;
/**
* Resets dialog state to initial. Done through `useResetRecoilState`.
*/
reset: () => void;
}>;
Filters
Useful for storing and applying values used for filtering data.
Creation and Usage
Created using filtersAtom
.
// atoms/filtersState.ts
import { filtersAtom } from 'recoil-tools';
export default filtersAtom<{ isActive: boolean; categoryId: string }>({
key: 'filtersState',
default: {
isOpen: false,
isApplied: false,
values: { isActive: false, categoryId: '' },
},
});
Access to the filters state and setters is provided through useRecoilFilters
hook.
import { useRecoilFilters } from 'recoil-tools';
import filtersState from './atoms/filtersState';
function App() {
const [state, setters] = useRecoilFilters(filtersState);
}
You can also use only state's isOpen
property:
import { useRecoilFiltersIsOpen } from 'recoil-tools';
import filtersState from './atoms/filtersState';
function App() {
const isOpen = useRecoilFiltersIsOpen(filtersState);
}
Or only isApplied
property:
import { useRecoilFiltersIsApplied } from 'recoil-tools';
import filtersState from './atoms/filtersState';
function App() {
const isApplied = useRecoilFiltersIsApplied(filtersState);
}
Or only values
property:
import { useRecoilFiltersValues } from 'recoil-tools';
import filtersState from './atoms/filtersState';
function App() {
const values = useRecoilFiltersValues(filtersState);
}
Or only state setters:
import { useRecoilFiltersSetters } from 'recoil-tools';
import filtersState from './atoms/filtersState';
function App() {
const { apply } = useRecoilFiltersSetters(filtersState);
}
API Reference
State
type RecoilFiltersState<T extends Record<string, any>> = Readonly<{
/**
* Filters open state.
*/
isOpen: boolean;
/**
* Whether filters have been applied.
*/
isApplied: boolean;
/**
* Filter values object.
*/
values: T;
}>;
Setters
type RecoilFiltersSetters<T extends Record<string, any>> = Readonly<{
/**
* `isOpen` property setter.
*/
setOpen: SetterOrUpdater<boolean>;
/**
* `isApplied` property setter.
*/
setApplied: SetterOrUpdater<boolean>;
/**
* Sets `isOpen` property to `true`.
*/
open: () => void;
/**
* Sets `isOpen` property to `false`.
*/
close: () => void;
/**
* Applies values by setting `values` property
* and `isApplied` property to `true`.
*/
apply: SetterOrUpdater<T>;
/**
* Resets filters state to initial. Done through `useResetRecoilState`.
*/
reset: () => void;
}>;
Pagination
Static storage of pagination state.
Creation and Usage
Created using paginationAtom
.
// atoms/paginationState.ts
import { paginationAtom } from 'recoil-tools';
export default paginationAtom({
key: 'paginationState',
default: {
total: 0,
page: 1,
limit: 10,
offset: 0,
meta: undefined,
},
});
Access to the pagination state and setters is provided through useRecoilPagination
hook.
import { useRecoilPagination } from 'recoil-tools';
import paginationState from './atoms/paginationState';
function App() {
const [state, setters] = useRecoilPagination(paginationState);
}
You can also use only state setters:
import { useRecoilPaginationSetters } from 'recoil-tools';
import paginationState from './atoms/paginationState';
function App() {
const { setPage, setLimit } = useRecoilPaginationSetters(paginationState);
}
API Reference
State
type RecoilPaginationState<T> = Readonly<{
/**
* Total number of records.
*/
total: number;
/**
* Current page number.
*/
page: number;
/**
* Number of records per page.
*/
limit: number;
/**
* Automatically calculated property based on `page` and `limit`
* that shows current offset in records.
*/
offset: number;
/**
* Any metadata related to the pagination.
*/
meta: T;
}>;
Setters
type RecoilPaginationSetters<T> = Readonly<{
/**
* `total` property setter.
*/
setTotal: SetterOrUpdater<number>;
/**
* `page` property setter.
*/
setPage: SetterOrUpdater<number>;
/**
* `limit` property setter.
*/
setLimit: SetterOrUpdater<number>;
/**
* `meta` property setter.
*/
setMeta: SetterOrUpdater<T>;
/**
* Resets pagination state to initial. Done through `useResetRecoilState`.
*/
reset: () => void;
}>;