Overview

The benefits of immutable state are clear, but maintaining that immutable state can sometimes be burdensome and verbose: updating a value more than one or two levels deep in your state tree can require lots of object/array spreading, and it's relatively easy to accidentally mutate something.

react-copy-write lets you use straightforward mutations to update an immutable state tree, thanks to Immer. Since Immer uses the copy-on-write technique to update immutable values, we get the benefits of structural sharing and memoization. This means react-copy-write not only lets you use simple mutations to update state, but it's also very efficient about re-rendering.

Documentation

react-copy-write is currently under-going significant API changes as it's tested in a production environment. Most documentation has been removed until we arrive at a stable API. Below you will find a bare-bones API reference that should get you started.

createState

The default export of the package. Takes in an initial state object and returns a collection of components and methods for reading, rendering, and updating state.

``jsx
import createState from 'react-copy-write'

const {
Provider,
Consumer,
createSelector,
mutate,
} = createState({name: 'Brandon' });
`

Provider

The Provider component provides state to all the consumers. All Consumer instances associated with a given provider must be rendered as children of the Provider.

`jsx
const App = () => (



)
`

If you need to initialize state from props you can use the initialState prop to do so. Note that it only initializes state, updating initialState will have no effect.

`jsx
const App = ({user}) => (



)
`

Consumer

A Consumer lets you _consume_ some set of state. It uses a render prop as a child for accessing and rendering state. This is identical to the React Context Consumer API.

`jsx
const Avatar = () => (

{state => (

)}

)
`

The render callback is always called with a tuple of the observed state, using an array. By default that tuple contains one element: the entire state tree.

$3

If a Consumer observes the entire state tree then it will update anytime _any_ value in state changes. This is usually not what you want. You can use the select prop to select a set of values from state that a Consumer depends on.

`jsx
const Avatar = () => (
state.user.avatar.src]}>
{src => }

)
`

Now the Avatar component will only re-render if state.user.avatar.src changes. If a component depends on multiple state values you can just pass in more selectors.

`jsx
const Avatar = () => (
state => state.user.avatar.src,
state => state.theme.avatar,
]}>
{(src, avatarTheme) => }

)
`

Updating State

createState also returns a mutate function that you can use to make state updates.

`js
const {mutate, Consumer, Provider} = createState({...})
`

Mutate takes a single function as an argument, which will be passed a "draft" of the current state. This draft is a mutable copy that you can edit directly with simple mutations

`js
const addTodo = todo => {
mutate(draft => {
draft.todos.push(todo);
})
}
`

You don't have to worry about creating new objects or arrays if you're only updating a single item or property.

`js
const updateUserName = (id, name) => {
mutate(draft => {
// No object spread required 😍
draft.users[id].name = name;
draft.users[id].lastUpdate = Date.now();
})
}
`

Check out the Immer docs for more information.

Since mutate is returned by createState you can call it anywhere. If you've used Redux you can think of it like dispatch in that sense.

Optimized Selectors

createState also returns a createSelector function which you can use to create an _optimized selector_. This selector should be defined outside of render, and ideally be something you use across multiple components.

`jsx
const selectAvatar = createSelector(state => state.user.avatar.src);
`

You can get some really, really nice speed if you use this and follow a few rules:

$3


🚫
`jsx
const App = () => (
// Don't do this
state.user)]}>
{...}

)
`

👍
`jsx
// Define it outside of render!
const selectUser = createSelector(state => state.user);
const App = () => (

{...}

)
`

$3

🚫
`jsx
const selectUser = createSelector(state => state.user);
const App = () => (
// This isn't terrible but the consumer gets de-optimized so
// try to avoid it
state.theme]}>
{...}

)
`

👍
`jsx
const selectUser = createSelector(state => state.user);
const selectTheme = createSelector(state => state.theme);
const App = () => (

{...}

)
``