redux-deep-persist

Redux Deep Persist

Demo Page

About this package

Redux Deep Perist contains transforms and state reconciler for Redux Persist giving you a possibility to define a nested configuration for your redux-persist.

If your redux state is deeply nested you don't have to create multiple, nested persist configs. You can easily create a whitelist or a blacklist for fields at any level of your state, using simple dot notation ['someProp.secondLevel.thirdLevel.anotherLevel']

Redux documentation recommends to keep the state as flat as possible, but it is not always possible. Redux Deep Persist may be very helpful in a situation when deep nesting is hard to avoid.

Installation

npm install redux-deep-persist

Usage

Configuration is similar to the Redux Persist, the only difference is you don't have to define nested persist configs. You can use getPersistConfig which will return the correct configuration you need.

It doesn't matter how deep you want to persist your state.

Example

State:

{
    property1: {
        a1: {
            b1: {
                c1: 'some value'
            }
        },
        a2: {
            b2: {
                c2: 'some value',
                d2: 'some value'
            }
        }
    },
    property2: {
        a1: {
            b1: {
                c1: {
                    d1: 'some value'
                }
            }
        }
        a2: 'some value'
    },
}

Configuration

import { getPersistConfig } from 'redux-deep-persist';

const config = getPersistConfig({
    key: 'root',
    storage: LocalStorage, // whatever storage you use
    whitelist: [
        'property1.a1.b1',  
        'property1.a2.b2.c2',  
        'property2.a2',
    ],
    rootReducer, // your root reducer must be also passed here
    ... // any other props from original redux-persist config omitting the state reconciler
})

Whitelist configuration property contains paths that define pieces of your state to be kept in your storage.

Use cases

• Once you define a whitelist any path which is not listed in that property won't be persisted
• If you don't define a whitelist then your entire store will be persisted. To exclude some pieces of your state from storage you must define a blacklist with specific paths of your choice.
• This package supports arrays. You can define at what index you would like to keep or exclude a value. This would be an extremely rare situation if you would need this but anyway it's possible to handle it.

{
    ...
    whitelist: ['a.b.4.c.8.5'] // the numbers represent indexes of arrays
}

• You can keep arrays with undefined and null values even if your store will be stringified. It's also a very rare case but undefined values of an array won't be replaced with null and after rehydration, you will get all null and undefined values as you would expect.

Errors and their meaning

The package has config validators and if your config is wrong you may see the following errors:

• "You should not define a whitelist and blacklist in parallel."

  • it occurs when you try to use whitelist and blacklist at once, you should choose just one approach

• "Duplicates of paths found in your whitelist/blacklist."

  • you defined duplicated paths in your whitelist or blacklist arrays. Wrong: ["property1", "property2.a2", "property1"].

• "Subsets of some parent keys found in your whitelist/blacklist. You must decide if you want to persist an entire path or its specific subset."

  • i.e. if you want to persist the entire "property1" you can't list its subsets in the config. Wrong: ["property1", "property1.a1"]

Examples repository

• coming soon

Contributors

I want to thank Andrzej Wilde and David de Rosier for all their support and accurate reviews.

License

MIT