@larscom/ngrx-store-storagesync

Highly configurable state sync library between localStorage/sessionStorage and @ngrx/store (Angular)

Features

• ✓ Sync with localStorage and sessionStorage
• ✓ Storage option per feature state, for example:
  • feature1 to sessionStorage
  • feature2 to localStorage
• ✓ Exclude deeply nested properties
• ✓ Sync Reactive Forms (needs additional library)

Dependencies

@larscom/ngrx-store-storagesync depends on @ngrx/store and Angular

Installation

1npm install @larscom/ngrx-store-storagesync

Choose the version corresponding to your Angular version

@angular/core	@larscom/ngrx-store-storagesync
>= 12	>= 13.0.0
< 12	<= 6.3.0

Usage

Include storageSyncReducer in your meta-reducers array in StoreModule.forRoot

1import { NgModule } from '@angular/core'
2import { BrowserModule } from '@angular/platform-browser'
3import { StoreModule } from '@ngrx/store'
4import { routerReducer } from '@ngrx/router-store'
5import { storageSync } from '@larscom/ngrx-store-storagesync'
6import * as fromFeature1 from './feature/reducer'
7
8export const reducers: ActionReducerMap<IRootState> = {
9  router: routerReducer,
10  feature1: fromFeature1.reducer
11}
12
13export function storageSyncReducer(reducer: ActionReducer<IRootState>): ActionReducer<IRootState> {
14  // provide all feature states within the features array
15  // features which are not provided, do not get synced
16  const metaReducer = storageSync<IRootState>({
17    features: [
18      // save only router state to sessionStorage
19      { stateKey: 'router', storageForFeature: window.sessionStorage },
20
21      // exclude key 'success' inside 'auth' and all keys 'loading' inside 'feature1'
22      { stateKey: 'feature1', excludeKeys: ['auth.success', 'loading'] }
23    ],
24    // defaults to localStorage
25    storage: window.localStorage
26  })
27
28  return metaReducer(reducer)
29}
30
31// add storageSyncReducer to metaReducers
32const metaReducers: MetaReducer<any>[] = [storageSyncReducer]
33
34@NgModule({
35  imports: [BrowserModule, StoreModule.forRoot(reducers, { metaReducers })]
36})
37export class AppModule {}

Configuration

1export interface IStorageSyncOptions<T> {
2  /**
3   * By default, states are not synced, provide the feature states you want to sync.
4   */
5  features: IFeatureOptions<T>[]
6  /**
7   * Provide the storage type to sync the state to, it can be any storage which implements the 'Storage' interface.
8   */
9  storage: Storage
10  /**
11   * Give the state a version. Version will be checked before rehydration.
12   *
13   * @examples
14   *  Version from Storage = 1 and Config.version = 2 --> Skip hydration
15   *
16   *  Version from Storage = undefined and Config.version = 1 --> Skip hydration
17   *
18   *  Version from Storage = 1 and Config.version = undefined --> Skip hydration
19   *
20   *  Version from Storage = 1 and Config.version = 1 --> Hydrate
21   */
22  version?: number
23  /**
24   * Under which key the version should be saved into storage
25   */
26  versionKey?: string
27  /**
28   * Function that gets executed on a storage error
29   * @param error the error that occurred
30   */
31  storageError?: (error: any) => void
32  /**
33   * Restore last known state from storage on startup
34   */
35  rehydrate?: boolean
36  /**
37   * Serializer for storage keys
38   * @param key the storage item key
39   */
40  storageKeySerializer?: (key: string) => string
41  /**
42   * Custom state merge function after rehydration (by default it does a deep merge)
43   * @param state the next state
44   * @param rehydratedState the state resolved from a storage location
45   */
46  rehydrateStateMerger?: (state: T, rehydratedState: T) => T
47}

1export interface IFeatureOptions<T> {
2  /**
3   * The name of the feature state to sync
4   */
5  stateKey: string
6  /**
7   * Filter out (ignore) properties that exist on the feature state.
8   *
9   * @example
10   * // Filter/ignore key with name 'config' and name 'auth'
11   * ['config', 'auth']
12   *
13   * // Filter/ignore only key 'loading' inside object 'auth'
14   * ['auth.loading']
15   */
16  excludeKeys?: string[]
17  /**
18   * Provide the storage type to sync the feature state to,
19   * it can be any storage which implements the 'Storage' interface.
20   *
21   * It will override the storage property in StorageSyncOptions
22   * @see IStorageSyncOptions
23   */
24  storageForFeature?: Storage
25  /**
26   * Sync to storage will only occur when this function returns true
27   * @param featureState the next feature state
28   * @param state the next state
29   */
30  shouldSync?: (featureState: T[keyof T], state: T) => boolean
31  /**
32   * Serializer for storage keys (feature state),
33   * it will override the storageKeySerializer in StorageSyncOptions
34   * @see IStorageSyncOptions
35   *
36   * @param key the storage item key
37   */
38  storageKeySerializerForFeature?: (key: string) => string
39  /**
40   * Serializer for the feature state (before saving to a storage location)
41   * @param featureState the next feature state
42   */
43  serialize?: (featureState: T[keyof T]) => string
44  /**
45   * Deserializer for the feature state (after getting the state from a storage location)
46   *
47   * ISO Date objects which are stored as a string gets revived as Date object by default.
48   * @param featureState the feature state retrieved from a storage location
49   */
50  deserialize?: (featureState: string) => T[keyof T]
51}

Examples

Sync to different storage locations

You can sync to different storage locations per feature state.

1export function storageSyncReducer(reducer: ActionReducer<IRootState>) {
2  return storageSync<IRootState>({
3    features: [
4      { stateKey: 'feature1', storageForFeature: window.sessionStorage }, // to sessionStorage
5      { stateKey: 'feature2' } // to localStorage because of 'default' which is set below.
6    ],
7    storage: window.localStorage // default
8  })(reducer)
9}

Exclude specific properties on state

Prevent specific properties from being synced to storage.

1const state: IRootState = {
2  feature1: {
3    message: 'hello', // excluded
4    loading: false,
5    auth: {
6      loading: false, // excluded
7      loggedIn: false,
8      message: 'hello' // excluded
9    }
10  }
11}
12
13export function storageSyncReducer(reducer: ActionReducer<IRootState>) {
14  return storageSync<IRootState>({
15    features: [{ stateKey: 'feature1', excludeKeys: ['auth.loading', 'message'] }],
16    storage: window.localStorage
17  })(reducer)
18}

Sync conditionally

Sync state to storage based on a condition.

1const state: IRootState = {
2  checkMe: true, // <---
3  feature1: {
4    rememberMe: false, // <---
5    auth: {
6      loading: false,
7      message: 'hello'
8    }
9  }
10}
11
12export function storageSyncReducer(reducer: ActionReducer<IRootState>) {
13  return storageSync<IRootState>({
14    features: [
15      {
16        stateKey: 'feature1',
17        shouldSync: (feature1, state) => {
18          return feature1.rememberMe || state.checkMe
19        }
20      }
21    ],
22    storage: window.localStorage
23  })(reducer)
24}

Serialize state

Override the default serializer for the feature state.

1export function storageSyncReducer(reducer: ActionReducer<IRootState>) {
2  return storageSync<IRootState>({
3    features: [
4      {
5        stateKey: 'feature1',
6        serialize: (feature1) => JSON.stringify(feature1)
7      }
8    ],
9    storage: window.localStorage
10  })(reducer)
11}

Deserialize state

Override the default deserializer for the feature state.

1export function storageSyncReducer(reducer: ActionReducer<IRootState>) {
2  return storageSync<IRootState>({
3    features: [
4      {
5        stateKey: 'feature1',
6        deserialize: (feature1: string) => JSON.parse(feature1)
7      }
8    ],
9    storage: window.localStorage
10  })(reducer)
11}

Serialize storage key

Override the default storage key serializer.

1export function storageSyncReducer(reducer: ActionReducer<IRootState>) {
2  return storageSync<IRootState>({
3    features: [{ stateKey: 'feature1' }],
4    storageKeySerializer: (key: string) => `abc_${key}`,
5    storage: window.localStorage
6  })(reducer)
7}

Merge rehydrated state

Override the default rehydrated state merger.

1export function storageSyncReducer(reducer: ActionReducer<IRootState>) {
2  return storageSync<IRootState>({
3    features: [{ stateKey: 'feature1' }],
4    rehydrateStateMerger: (state: IRootState, rehydratedState: IRootState) => {
5      return { ...state, ...rehydratedState }
6    },
7    storage: window.localStorage
8  })(reducer)
9}