foo-state

This package consists of simple global states made possible by observing browser events. It works well when you need to use global states in a react or next.js app.

It can be used both with Typescript or Javascript.

Table of contents

1. Installation
2. Examples
   1. Using as a hook
   2. Using outside React
   3. Partial state hook
   4. Persist state
   5. Using deep comparison
   6. With lazy initialization
   7. Using with TypeScript
3. API Reference
4. Contributing
5. License

⚙️ Installation

npm install --save foo-state

🔌 Examples

1 - using as a hook

See code

import{createGlobalState}from"foo-state"constinitialState=0const{ useGlobalState }=createGlobalState(initialState)constCounter=()=>{const[count,setCount]=useGlobalState()constincrement=()=>{setCount(count+1)}constdecrement=()=>{// you can also use callback functionssetCount((state)=>{if(state>0){returnstate-1}returnstate})}return(<div><buttononClick={decrement}>-</button><span>{count}</span><buttononClick={increment}>+</button></div>)}

2 - using outside react

See code

import{createGlobalState}from"foo-state"constinitialState=0const{ useGlobalState, setGlobalState }=createGlobalState(initialState)functionsetInitialState(){setTimeout(()=>{setGlobalState(10_000)},2_000)}constCounter=()=>{const[count,setCount]=useGlobalState()useEffect(()=>{setInitialState()},[])constdecrement=()=>{setCount(count-1)}constincrement=()=>{setCount(count+1)}return(<div><buttononClick={decrement}>-</button><span>{count}</span><buttononClick={increment}>+</button></div>)}

3 - partial state hook

See code

import{createGlobalState}from"foo-state"constinitialState={firstName: "John",lastName: "Doe",age: 43}const{ createPartialState }=createGlobalState(initialState)constuseAge=createPartialState(state=>state.age)constAge=()=>{constage=useAge()return(<div>{age}</div>)}

4 - persist state

See code

import{createGlobalState}from"foo-state"constinitialState={firstName: "John",lastName: "Doe",age: 43}const{ useGlobalState }=createGlobalState(initialState,{persistence: {key: "x-storage-key",// optional, defaults to localStorage// localStorage or sessionStoragetype: "localStorage",}})constPerson=()=>{const[person,setPerson]=useGlobalState()functiononChange(e){const{name, value}=e.targetsetPerson({
...person,[name]: value})}return(<div><label>
First Name
<br/><inputname="firstName"value={person.firstName}onChange={onChange}/></label><label>
Last Name
<br/><inputname="lastName"value={person.lastName}onChange={onChange}/></label><label>
Age
<br/><inputname="age"value={person.age}onChange={onChange}/></label></div>)}

5 - using deep comparison (useful for objects and arrays to prevent unnecessary re-renders)

See code

import{createGlobalState}from"foo-state"constinitialState={firstName: "John",lastName: "Doe",age: 43,}const{ useGlobalState }=createGlobalState(initialState)constProfile=()=>{const[state,setState]=useGlobalState()functioninvertNames(){constnewState={firstName: "Doe",lastName: "John",age: 43,}setState(newState,{deepCompare: true})}return(<div><p>First Name: {state.firstName}</p><p>Last Name: {state.lastName}</p><p>Age: {state.age}</p><buttononClick={invertNames}>Click me!</button></div>)}

6 - With lazy initialization

See code

functionheavyCalculation(){constuser={name: 'John',birthday: newDate('1995-03-15')}// let's pretend we're getting a correct age hereconstage=newDate().getFullYear()-user.birthday.getFullYear()return{name: user.name,
age,}}const{useGlobalState}=createGlobalState(heavyCalculation)constProfile=()=>{const[state]=useGlobalState()return(<div><p>Name: {state.name}</p><p>Age: {state.age}</p></div>)}

7 - With typescript

See code

import{createGlobalState}from"foo-state"typePerson={firstName: stringlastName: stringage: number}const{ useGlobalState }=createGlobalState<Person>({firstName: "John",lastName: "Doe",// string is not assignable to type numberage: "43"})constProfile=()=>{const[state,setState]=useGlobalState()functioninvertNames(){constnewState={firstName: "Doe",lastName: "John",age: 43,}setState(newState,{deepCompare: true})}return(<div><p>First Name: {state.firstName}</p><p>Last Name: {state.lastName}</p><p>Age: {state.age}</p><buttononClick={invertNames}>Click me!</button></div>)}

API Reference

createGlobalState

createGlobalState<S>(initialState: S|()=>S,options: GlobalStateOptions): GlobalState

This is, most probably, the only function you will need to use from this library.

Params

The initial state can be either a value or a function that resolves to a value. This mirrors the useState API.

The library tries to infer the type as much as possible, but you can also specify the type:

typePerson={}conststate=createGlobalState<Person>({})

You can always read more about the options parameter for createGlobalState.

Returned functions

• useGlobalState - This react hook can be used inside any functional component to access or change the state.

• useReadOnlyState - This react hook doesn't give you access to the setState function, instead it only returns the current state.

• createPartialState - This function will return a read only react hook with a custom partial state. See example of createPartialState

• getGlobalState - This function returns the current state and can be used anywhere in you application, not only inside react components.See example of getGlobalState

• setGlobalState - This function allows you to change the state and can be used anywhere in you application, not only inside react components.See example of setGlobalState

👥 Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

🏛 License

MIT

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Abraham Schilling 🎨🧑‍🏫💻

Daniel Bock 🎨💻

Lenilson "Lenny" Nascimento 💻📖🚧

afennert 💻

Juan Enrique Segebre Zaghmout 💻🚧📖

Sean Hayes 📖💻

Sebastian Londono 👀🤔

This project follows the all-contributors specification. Contributions of any kind welcome!