Restater ·
Tiny hook-based state management tool for React
Table of content
Getting started
Install
With NPM
npm i restater
With yarn
yarn add restater
Usage
Create a store
To create a simple state store, use the createStore
function from restater
.
It will return a tuple with a Provider and a StoreContext.
;;; // Define the initial stateconst initialState = username: 'restater' followers: 42 isPublic: true; // Create the storeconst Provider MyStore = ; ReactDOM; ;
Use the store
In order to use the store, use the useStore
hook from restater
.
The useStore
hook takes a StoreContext and a property-name, and returns a state and a setState tuple, just as useState
.
;;; const App = { const username setUsername = ; return <div>My name is: username</div>;};
Updating the username is easy.
;
Any component that is using the username from the store will now get updated, but without affecting any components "in between".
Create an Async Store
A store can also hold async values, and for that, we create a separate kind of store using createAsyncStore
.
Again, we provide initial values, but the store will treat these values as promises that needs to be resolved before being set.
Creating the store will work the same as before.
;;; // Define the initial stateconst initialState = username: 'restater' followers: 42 isPublic: true; // Create an *async* storeconst Provider MyAsyncStore = ; ReactDOM; ;
Use the async store
When we use an Async Store, the state and setState functions behave a little different.
Instead of username
containing the value directly, it will contain an object with three properties: data
, state
, and error
.
data
contains the value ofusername
.state
represents the current state of the promise, and can be eitherinitial
,loading
,failed
orcompleted
.error
contains the error that is thrown, if the promise fails.
This enables us to render something conditionally, based on the current state of the store data we want to use.
Note that
data
will only exist whenstate
is eitherinitial
orcompleted
, anderror
will only exist ifstate
isfailed
.
;;; const App = { const username setUsername = ; if usernamestate === 'initial' return <div>The initial name is: usernamedata</div>; if usernamestate === 'completed' return <div>My name is: usernamedata</div>; if usernamestate === 'loading' return <div>Loading ...</div>; if usernamestate === 'failed' return <div>Something failed: usernameerrormessage</div>; };
Because the store is async, the setUsername
now expects a promise instead of a raw value.
const getUpdatedUsername = async { const request = await ; const result = await request; // Result is the new username return result;}; ;
This will cause the username.state
to go into loading
in any component that is using the username from the store.
Note that the setUsername
itself returns a promise, so we can await it and do something after the username.state
has gone into either completed
or failed
.
await ;// Do something after the username has been updated
When using an Async Store, the setUsername
function takes an optional options
object as the second argument:
;
Setting skipLoading
to true
will bypass the loading
step.
This will make username.state
go directly from initial
to completed
or failed
.
If ``username.stateis already in
completed, it will stay there, or go to
failed`.
Helper functions
To avoid wrapping too many providers in each other, you can use the helper function combineProviders
which will combine a list of providers into one.
; const Provider1 Context1 = ;const Provider2 Context2 = ; // Combine the providersconst Provider = ; ReactDOM;
License
This project is licensed under the MIT License
Get Help
- Reach out on Twitter
- Reach out on Discord
- Open an issue on GitHub
Contribute
Issues
In the case of a bug report, bugfix or a suggestions, please feel very free to open an issue.
Pull request
Pull requests are always welcome, and I'll do my best to do reviews as fast as I can.