bistate
v1.3.2
Published
A state management library for react inspired by vue 3.0 reactivity api and immer
Downloads
12
Readme
Welcome to bistate 👋
Create the next immutable state tree by simply modifying the current tree
bistate is a tiny package that allows you to work with the immutable state in a more mutable and reactive way, inspired by vue 3.0 reactivity API and immer.
🏠 Homepage
Benefits
bistate is like immer but more reactive
- Immutability with normal JavaScript objects and arrays. No new APIs to learn!
- Strongly typed, no string based paths selectors etc.
- Structural sharing out of the box
- Deep updates are a breeze
- Boilerplate reduction. Less noise, more concise code.
- Provide react-hooks API
- Small size
- Reactive
Environment Requirement
- ES2015 Proxy
- ES2015 Symbol
How it works
Every immutable state is wrapped by a proxy, has a scapegoat state by the side.
immutable state
+ scapegoat state
= bistate
- the immutable target is freezed by proxy
- scapegoat has the same value as the immutable target
- mutate(() => { the_mutable_world }), when calling
mutate(f)
, it will- switch all operations to scapegoat instead of the immutable target when executing
- switch back to the immutable target after executed
- create the next bistate via
scapegoat
andtarget
, sharing the unchanged parts - we get two immutable states now
Install
npm install --save bistate
yarn add bistate
Usage
Counter
import React from 'react'
// import react-hooks api from bistate/react
import { useBistate, useMutate } from 'bistate/react'
export default function Counter() {
// create state via useBistate
let state = useBistate({ count: 0 })
// safely mutate state via useMutate
let incre = useMutate(() => {
state.count += 1
})
let decre = useMutate(() => {
state.count -= 1
})
return (
<div>
<button onClick={incre}>+1</button>
{state.count}
<button onClick={decre}>-1</button>
</div>
)
}
TodoApp
function Todo({ todo }) {
let edit = useBistate({ value: false })
/**
* bistate text is reactive
* we will pass the text down to TodoInput without the need of manually update it in Todo
* */
let text = useBistate({ value: '' })
// create a mutable function via useMutate
let handleEdit = useMutate(() => {
edit.value = !edit.value
text.value = todo.content
})
let handleEdited = useMutate(() => {
edit.value = false
if (text.value === '') {
// remove the todo from todos via remove function
remove(todo)
} else {
// mutate todo even it is not a local bistate
todo.content = text.value
}
})
let handleKeyUp = useMutate(event => {
if (event.key === 'Enter') {
handleEdited()
}
})
let handleRemove = useMutate(() => {
remove(todo)
})
let handleToggle = useMutate(() => {
todo.completed = !todo.completed
})
return (
<li>
<button onClick={handleRemove}>remove</button>
<button onClick={handleToggle}>{todo.completed ? 'completed' : 'active'}</button>
{edit.value && <TodoInput text={text} onBlur={handleEdited} onKeyUp={handleKeyUp} />}
{!edit.value && <span onClick={handleEdit}>{todo.content}</span>}
</li>
)
}
function TodoInput({ text, ...props }) {
let handleChange = useMutate(event => {
/**
* we just simply and safely mutate text at one place
* instead of every parent components need to handle `onChange` event
*/
text.value = event.target.value
})
return <input type="text" {...props} onChange={handleChange} value={text.value} />
}
API
import { createStore, mutate, remove, isBistate, debug, undebug } from 'bistate'
import {
useBistate,
useMutate,
useBireducer,
useComputed,
useBinding,
view,
useAttr,
useAttrs
} from 'bistate/react'
useBistate(array | object, bistate?) -> bistate
receive an array or an object, return bistate.
if the second argument is another bistate which has the same shape with the first argument, return the second argument instead.
let Child = (props: { counter?: { count: number } }) => {
// if props.counter is existed, use props.counter, otherwise use local bistate.
let state = useBistate({ count: 0 }, props.counter)
let handleClick = useMutate(() => {
state.count += 1
})
return <div onClick={handleClick}>{state.count}</div>
}
// use local bistate
<Child />
// use parent bistate
<Child counter={state} />
useMutate((...args) => any_value) -> ((...args) => any_value)
receive a function as argument, return the mutable_function
it's free to mutate any bistates in mutable_function, not matter where they came from(they can belong to the parent component)
useBireducer(reducer, initialState) -> [state, dispatch]
receive a reducer and an initial state, return a pair [state, dispatch]
its' free to mutate any bistates in the reducer funciton
import { useBireducer } from 'bistate/react'
const Test = () => {
let [state, dispatch] = useBireducer(
(state, action) => {
if (action.type === 'incre') {
state.count += 1
}
if (action.type === 'decre') {
state.count -= 1
}
},
{ count: 0 }
)
let handleIncre = () => {
dispatch({ type: 'incre' })
}
let handleIncre = () => {
dispatch({ type: 'decre' })
}
// render view
}
useComputed(obj, deps) -> obj
Create computed state
let state = useBistate({ first: 'a', last: 'b' })
// use getter/setter
let computed = useComputed({
get value() {
return state.first + ' ' + state.last
},
set value(name) {
let [first, last] = name.split(' ')
state.first = first
state.last = last
}
}, [state.first, state.last])
let handleEvent = useMutate(() => {
console.log(computed.value) // 'a b'
// update
computed.value = 'Bill Gates'
console.log(state.first) // Bill
console.log(state.last) // Gates
})
useBinding(bistate) -> obj
Create binding state
A binding state is an object has only one filed { value }
let state = useBistate({ text: 'some text' })
let { text } = useBinding(state)
// don't do this
// access field will trigger a react-hooks
// you should always use ECMAScript 6 (ES2015) destructuring to get binding state
let bindingState = useBinding(state)
if (xxx) xxx = bindingState.xxx
let handleChange = () => {
console.log(text.value) // some text
console.log(state.text) // some text
text.value = 'some new text'
console.log(text.value) // some new text
console.log(state.text) // some new text
}
It's useful when child component needs binding state, but parent component state is not.
function Input({ text, ...props }) {
let handleChange = useMutate(event => {
/**
* we just simply and safely mutate text at one place
* instead of every parent components need to handle `onChange` event
*/
text.value = event.target.value
})
return <input type="text" {...props} onChange={handleChange} value={text.value} />
}
function App() {
let state = useBistate({
fieldA: 'A',
fieldB: 'B',
fieldC: 'C'
})
let { fieldA, fieldB, fieldC } = useBinding(state)
return <>
<Input text={fieldA} />
<Input text={fieldB} />
<Input text={fieldC} />
</>
}
view(FC) -> FC
create a two-way data binding function-component
const Counter = view(props => {
// Counter will not know the count is local or came from the parent
let count = useAttr('count', { value: 0 })
let handleClick = useMutate(() => {
count.value += 1
})
return <button onClick={handleClick}>{count.value}</button>
})
// use local bistate
<Counter />
// create a two-way data binding connection with parent bistate
<Count count={parentBistate.count} />
useAttrs(initValue) -> Record<string, bistate>
create a record of bistate, when the value in props[key] is bistate, connect it.
useAttrs must use in view(fc)
const Test = view(() => {
// Counter will not know the count is local or came from the parent
let attrs = useAttrs({ count: { value: 0 } })
let handleClick = useMutate(() => {
attrs.count.value += 1
})
return <button onClick={handleClick}>{attrs.count.value}</button>
})
// use local bistate
<Counter />
// create a two-way data binding connection with parent bistate
<Count count={parentBistate.count} />
useAttr(key, initValue) -> bistate
a shortcut of useAttrs({ [key]: initValue })[key]
, it's useful when we want to separate attrs
createStore(initialState) -> { subscribe, getState }
create a store with an initial state
store.subscribe(listener) -> unlisten
subscribe to the store, and return an unlisten function
Every time the state has been mutated, a new state will publish to every listener.
store.getState() -> state
get the current state in the store
let store = createStore({ count: 1 })
let state = store.getState()
let unlisten = store.subscribe(nextState => {
expect(state).toEqual({ count: 1 })
expect(nextState).toEqual({ count: 2 })
unlisten()
})
mutate(() => {
state.count += 1
})
mutate(f) -> value_returned_by_f
immediately execute the function and return the value
it's free to mutate the bistate in mutate function
remove(bistate) -> void
remove the bistate from its parent
isBistate(input) -> boolean
check if input is a bistate or not
debug(bistate) -> void
enable debug mode, break point when bistate is mutating
undebug(bistate) -> void
disable debug mode
Caveats
only supports array and object, other data types are not allowed
bistate is unidirectional, any object or array appear only once, no circular references existed
let state = useBistate([{ value: 1 }])
mutate(() => {
state.push(state[0])
// nextState[0] is equal to state[0]
// nextState[1] is not equal to state[0], it's a new one
})
- can not spread object or array as props, it will lose the reactivity connection in it, should pass the reference
// don't do this
<Todo {...todo} />
// do this instead
<Todo todo={todo} />
can not edit state or props via react-devtools, the same problem as above
useMutate or mutate do not support async function
const Test = () => {
let state = useBistate({ count: 0 })
// don't do this
let handleIncre = useMutate(async () => {
let n = await fetchData()
state.count += n
})
// do this instead
let incre = useMutate(n => {
state.count += n
})
let handleIncre = async () => {
let n = await fetchData()
incre(n)
}
return <div onClick={handleIncre}>test</div>
}
Author
👤 Jade Gu
- Twitter: @guyingjie129
- Github: @Lucifier129
🤝 Contributing
Contributions, issues and feature requests are welcome!
Feel free to check issues page.
Show your support
Give a ⭐️ if this project helped you!
📝 License
Copyright © 2019 Jade Gu.
This project is MIT licensed.
This README was generated with ❤️ by readme-md-generator