@huds0n/shared-state
[]()
[](https://github.com/JontiHudson/modules-huds0n-shared-state/issues)
[](https://github.com/JontiHudson/modules-huds0n-shared-state/pulls)
[](/LICENSE)
---
A simple yet powerful React state management module, fully integrated with hooks and typescript.
Turning
const [state, setState] = useState(initialState);
Into
const [state, setState] = GlobalState.useState();
## 📝 Table of Contents
- [About](#about)
- [Features](#features)
- [Getting Started](#getting_started)
- [Basic Usage](#basic_usage)
- [Creating a Shared State](#basic_creating)
- [Accessing State](#basic_accessing)
- [Updating State](#basic_updating)
- [Functional Component Integration](#basic_functional)
- [Class Component Integration](#basic_class)
- [Advanced Usage](#advanced_usage)
- [Update Keys](#advanced_update_keys)
- [State Listeners](#advanced_state_listeners)
- [Using Typescript](#advanced_typescript)
- [Data Persist](#advanced_data_persist)
- [Delayed Initialization](#advanced_delayed_initialization)
- [Reference](#reference)
- [Properties](#reference_properties)
- [Methods](#reference_methods)
- [Example](#example)
- [Authors](#authors)
- [Acknowledgments](#acknowledgement)
## 🧐 About
Global state management is one of the core aspects of nearly all React Native projects, especially as they grow in size.
**Shared States** solves this problem by declaring your shared state variables outside of your components. Then, using familiar syntax to React, registering components for updates on **shared state** change.
## ✅ List of Features
- **Simple:** _Uses similar structure and syntax to standard React._
- **Fast:** _Optimize components to only update when is necessary._
- **Powerful:** _Seemlessly integrate state change with both UI and logic._
- **Versatile:** _Have a single global state, or split it in multiple shared states._
- **Persistant:** _Combine with a **Shared State Store** to presist data._
- **Type-Safe:** _Fully integrated with typescript out-of-the-box._
## 🏁 Getting Started
### **Prerequisites**
Works with any project implementing React 16.8 onwards
### **Installing**
```
npm i @huds0n/shared-state
```
## 🧑💻 Basic Usage
### **Creating a Shared State**
```js
import { SharedState } from "@huds0n/shared-state";
const ExampleState = new SharedState({
username: null,
password: null
...ect
});
```
### **Accessing State**
```js
const { username, password } = ExampleState.state;
```
### **Updating State**
Like regular state, direct mutation will not cause components to update. Instead the **setState** method is used.
```js
ExampleState.setState({
username: "john.doe",
password: "******",
});
```
**setState** can take either the whole or a partial state, updating only the props that are passed. Like regular state, **Shared State** uses shallow comparison to detect state changes.
### **Function Components Integration**
```js
function exampleFunctionComponent() {
const [state, setState] = ExampleState.useState();
// Or if you want to be more specific
const [username, setUsername] = ExampleState.useProp("username");
}
```
### **Class Components Integration**
```js
componentDidMount() {
ExampleState.register(this);
}
componentWillUnmount() {
ExampleState.unregister(this);
}
```
## 🧑🔬 Advanced Usage
### **Update Keys**
Registration of a component to a shared state causes automatic re-rendering on any state change. To select specific props to cause re-render an **update key** (string) or **keys** (array of strings) can be passed to the **register** and **useState** methods.
```js
ExampleState.register(this, "username");
```
_This class component would only update on username change._
```js
Example.useState(["username", "password"]);
```
_This function component would update on either username or password change._
### **State Listeners**
State changes can be used to trigger logic as well.
```js
const removeListener = ExampleState.addListener(
(newState, prevState) => {
if (prevState.user === null) {
// Runs when user changes from null
}
},
["username"]
);
```
_Then to remove the listener._
```js
removeListener();
```
### **Using Typescript**
**Shared State** has been built from the ground up to use typescript. It will predict state type structure automatically from the initial state. However, in cases where state props can be multiple types you will need to pass in declarative typings when instantiating the state.
```ts
type ExampleStateType = {
username: null | string,
password: null | string,
...ect
}
const ExampleState = new SharedState({
username: null,
password: null,
...ect
});
```
## 📖 Reference
### **Properties**
| Prop | Description | Type |
| ------------------------- | ------------------------------------------------------------------------ | ----------------------------------------- |
| [state](#basic_accessing) | current state | _state **object**_ |
| prevState | previous state_(**undefined** if no state change yet has occurred)_ | _state **object**_or _**undefined**_ |
### **Methods**
| Methods/_Param_ | Description | Return/_Type_ |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | --- | --- |
| **[addListener](#advanced_state_listeners)** | **Adds listener to trigger on state changes Returns remove listener function** | **() => boolean** |
| _callback_ | _Called everytime the trigger changes occur_ | _(current: **State**, prev: **Partial State**) => **void**_ |
| _trigger_ (optional) | _Defines which state changes the listener triggers on_ | **_[Update Key](#advanced_update_keys)_** |
| | | | | |
| **refresh** | **Forces registered components to re-render** | - |
| _refreshKeys_ (optional) | _Limits refresh to components registered with specific keys_ | **_[Update Key](#advanced_update_keys)_** |
| | | |
| **[register](#basic_class)** | **Registers class components to re-render on state changeUse in either constructor or componentDidMount methods** | - |
| _component_ | _To link the class component **this** needs to be passed into the function_ | _**this**_ |
| _updateKey(s) (optional)_ | _If present then the component will only re-render on key trigger_ | **_[Update Key](#advanced_update_keys)_** |
| | | |
| **removeAllListeners** | **Clears all listeners started by the addListener method** | - |
| | | |
| **reset** | **Resets state back to the default stateDeletes or updates stored state depending on reset state** | - |
| _resetState (optional)_ | _If present, becomes the State's new default state_ | _**State**_ |
| | | |
| | |
| **setProp** | **Update a single property of the stateShallow comparison is used to detect/trigger re-renders** | - |
| _propName_ | _Defines which property to update_ | _**key of State**_ |
| _newValue_ | _Property's new value_ | _propType_ |
| | | |
| **[setState](#basic_updating)** | **Updates state by combining the newState with the current stateShallow comparison evaluates updated stateUpdated state triggers re-renders and is returned** | **Partial State** |
| _newState_ | _The new state to _ | _**key of State**_ |
| _newValue_ | _Property's new value_ | _propType_ |
| | | |
| **toString** | Returns the current state in as a JSON string | string |
| | | |
| **[unregister](#basic_class)** | **Un-registers class components from re-rendering on state changeUse in componentWillMount methodsFailure of this will result in memory leaks** | - |
| _component_ | _To un-link the class component **this** needs to be passed into the function_ | _**this**_ |
| | |
| **[useProp](#basic_functional)** | **Hook to register functional component to StateReturns array of prop value and prop setter, similar to useState** | **[prop, setPropFn]** |
| _updateKey(s) (optional)_ | _If present then the component will only re-render on key trigger_ | **_[Update Key](#advanced_update_keys)_** |
| | | |
| **[useState](#basic_functional)** | **Hook to register functional component to StateReturns array of state and state setterAllows additional optimization with the shouldUpdate param** | **[state, setStateFn]** |
| _updateKey(s) (optional)_ | _If present then the component will only re-render on key trigger_ | **_[Update Key](#advanced_update_keys)_** |
| _shouldUpdateFn(optional)_ | _Run when triggered by StateThe component will on then update if function return **true**_ | _(newState: **State**, prevState: **Partial State**) => **boolean**_ |
## 📲 Example
Clone or fork the repo at [https://github.com/JontiHudson/modules-huds0n-shared-state](https://github.com/JontiHudson/modules-huds0n-shared-state)
Go to the **\_\_example\_\_** folder. Run **npm install** to install the expo project, then **expo start** to launch the example.
## ✍️ Authors
- [@JontiHudson](https://github.com/JontiHudson) - Idea & Initial work
- [@MartinHudson](https://github.com/martinhudson) - Support & Development
See also the list of [contributors](https://github.com/JontiHudson/modules-huds0n-shared-state/contributors) who participated in this project.
## 🎉 Acknowledgements
- Special thanks to my fiance, Arma, who has been so patient with all my extra-curricular work.