expo-waterfall-persist

Run the demo on Expo.io / Clone the demo

expo-waterfall-persist is persistent storage middleware for react-waterfall, for Expo apps.

Installation

npm install expo-waterfall-persist
npm install git://github.com/benallfree/react-waterfall.git#master

Note: a fork of react-waterfall is required temporarily. See Discussion below.

Usage

import { persist } from 'expo-waterfall-persist'
const { Provider } = createStore(config, [persist])

export default () => <Provider onSaved={() => console.log('saved')} />

The magic is in the middleware. By supplying the persist middleware to createStore, you enable state persistance and status callbacks on the Provider.

Provider accepts several new props when the persist middleware is installed:

Props:

fileUri (default ${FileSystem.documentDirectory}/state.json) The path to the file used to persist state. See Expo FileSystem for details.

debounce (default {wait: 250, maxWait: 1000}) Debounce is used to prevent state from saving too rapidly. By default, it will wait at leaste 250ms before saving, but it will save at least every 1s if things have changed.

onLoaded({ state, fileUri }) Called when state has been restored from persistant storage.

onSaved({state, fileUri}) Called when state is saved to persistent storage.

onSaveError({ error, fileUri }) Critically bad news. Called when state fails to save to persistent storage.

onLoadError({ error, fileUri }) Fairly bad news. Called when state fails to load from persistant storage due to some error other than 'file not found'. Default state used instead.

onVersionMismatch({ oldState, newVersion }) Harmless. Called when persisted state version does not match current version specified in config, and the default state is used instead. State versioning is an optional but useful feature if you issue an app update that makes previously persisted states incompatible.

onPersistedStateNotFound({ fileUri }) Harmless. Called when persistent state is not present. Harmless, uses default state.

More Complete Example

See expo-waterfall-persist-demo for a working example.

import React from 'react'
import { Text, View } from 'react-native'
import createStore from 'react-waterfall'
import { persist } from 'expo-waterfall-persist'

const config = {
  initialState: { version: 1, tick: 0 },
  actionsCreators: {
    tick: ({ tick }) => ({
      tick: tick + 1
    })
  }
}

// Here's the magic! The `persist` middleware
const { Provider, actions, connect } = createStore(config, [persist])

const ShowTick = connect(({ tick }) => ({ tick }))(({ tick }) => (
  <Text>{tick}</Text>
))

export default class App extends React.Component {
  componentWillMount() {
    setInterval(() => {
      actions.tick()
    }, 50)
  }

  handleStateSaved = state => {
    console.log('The state was persisted.', state)
  }

  render() {
    return (
      <View>
        <Provider onSaved={this.handleStateSaved}>
          <ShowTick />
        </Provider>
      </View>
    )
  }
}

Discussion

Making this package work has required a temporary fork of react-waterfall. I needed to update the middleware strategy so that middleware was capable of modifying createStore initializers as well as setting state of the store without forcing the user to create an action or polluting the actionsCreators structure.

Due to the asynchronous nature of loading/saving persistent state in the Expo filesystem, this package will not render the children of Provider until state has resolved either to the persisted state or the default state if persisted state fails to load.