mobx-keystone-persist

Persist and hydrate mobx-keystone stores.

Installation

npm i -S mobx-keystone-persist

Usage

import { model, Model } from "mobx-keystone";
import localForage from "localForage";
import { persist } from "mobx-keystone-persist";

@model("myApp/SomeStore")
class SomeStore extends Model({
  name: "John Doe",
  age: 32,
}) {}

const someStore = new SomeStore({});

persist("some", someStore, {
  storage: localForage, // or AsyncStorage in react-native.
  // default: localStorage
  jsonify: false, // if you use AsyncStorage, this shoud be true
  // default: true
  whitelist: ["name"], // only these keys will be persisted
}).then(() => console.log("someStore has been hydrated"));

API

persist(key, store, options)

• arguments

  • key string The key of your storage engine that you want to persist to.
  • store mobx-keystone store The store to be persisted.
  • options object Additional configuration options.
    • version number Version code for the state (default: -1).
    • storage localForage / AsyncStorage / localStorage Any Storage Engine that has a Promise-style API similar to localForage. The default is localStorage, which has a built-in adaptor to make it support Promises. For React Native, one may configure AsyncStorage instead. Any of redux-persist's Storage Engines should also be compatible with mobx-keystone-persist.
    • jsonify bool Enables serialization as JSON (default: true).
    • whitelist Array<string> Only these keys will be persisted (defaults to all keys).
    • blacklist Array<string> These keys will not be persisted (defaults to all keys).
    • migrate function Migration handler for versioning (default: undefined).
    • throttle number Throttle and delay persisting so it can't happen more than once every Nth ms (default: undefined).

• returns a void Promise

Migrations

Mobx-keystone-persist has migration support very similar to redux-persist v6's migrations. The migration process runs after getting stored state but before actually reconciling with the store.

The library ships with createMigrate which covers most use cases and is simple to use. If you need more control of how versioning is handled and migrations are applied, you can instead write your own migrator. It can be any function which takes state as an argument and returns a promise to return a new state object.

[Additional information]

Node and Server-Side Rendering (SSR) Usage

Node environments are supported so long as you configure a Storage Engine that supports Node, such as redux-persist-node-storage, redux-persist-cookie-storage, etc. This allows you to hydrate your store server-side.

For SSR though, you may not want to hydrate your store server-side, so in that case you can call persist conditionally:

if (typeof window !== 'undefined') { // window is undefined in Node
  persist(...)
}

With this conditional check, your store will only be hydrated client-side.

How it works

Basically just a small wrapper around mobx-keystone's getSnapshot and applySnapshot. The source code is currently shorter than this README, so take a look under the hood! :)

Credits

A fork of mst-persist by Anton Gilgur. modified to use mobx-keystone instead of mobx-state-tree.

Inspiration for parts of the original code and API came from redux-persist, mobx-persist, and this MST persist PoC gist