Persistence

ActiveJS Units can be made persistent by setting a configuration flag to true. By default, persistent Units use localStorage for the persistence. You can change it to any storage API that implements Storage interface. e.g.: sessionStorage​
Creating a persistent Unit
All that it takes to make a Unit persistent is a flag, and a unique id. The id is required to identify the Unit and its stored value.
1
// this will throw an error, id is required
2
const preferencesUnit = new DictUnit({persistent: true});
3
​
4
// this will work
5
const preferencesUnit = new DictUnit({id: 'preferences', persistent: true});
6
​
7
​
8
// update Unit's value
9
preferencesUnit.set('side', 'dark');
10
// value in the LocalStorage would become {"side": "dark"}
11
​
12
// refresh the browser window
13
​
14
// check value
15
console.log(preferencesUnit.value()) // logs {"side": "dark"}
Copied!
Voila! we're done. No manual saving, no manual retrieving.
Initial value vs persisted value
When you provide an initial value to a persistent Unit, at first instance it gets saved to the persistent storage immediately, but when you refresh the browser window or open a new one, on the second instance the stored value takes precedence over the provided initial value.
1
const preferencesUnit = new DictUnit({
2
    id: 'preferences', 
3
    persistent: true,
4
    initialValue: {earth: 'flat'}
5
});
6
// value in the LocalStorage would become {"earth": "flat"}
7
​
8
// set a new preference, which dispatches and saves a new value
9
preferencesUnit.set('earth', 'oblate ellipsoid');
10
// now LocalStorage has {"earth": "oblate ellipsoid"}
11
​
12
// now, refresh the browser window
13
​
14
// check value
15
console.log(preferencesUnit.value()) // logs {"earth": "oblate ellipsoid"}
16
// the initial value gets ignored
Copied!
Clearing the persisted value
Persisted value can be cleared in two ways, per Unit, or every Unit in a Storage instance.
To clear the persisted value of a Unit, you can use Unit.clearPersistedValue()
To clear all Units' persisted values from the default storage, you can use the global function clearPersistentStorage().
If you want to clear a particular storage you can pass it to the clearPersistentStorage() function.
e.g. clearPersistentStorage(window.sessionStorage) 
1
// taking the Unit from above example, and starting from where we left
2
console.log(preferencesUnit.value()) // logs {"earth": "oblate ellipsoid"}
3
​
4
// clear the persisted value
5
preferencesUnit.clearPersistedValue();
6
// or clearPersistentStorage()
7
// or clearPersistentStorage(localStorage)
8
​
9
// check value
10
console.log(preferencesUnit.value()) // logs {"earth": "oblate ellipsoid"}
11
// because only the persisted value is removed, the Unit's value stays intact
12
​
13
// now, refresh the browser window
14
​
15
// check value
16
console.log(preferencesUnit.value()) // logs {"earth": "flat"}
17
// the initial value is used, because we cleared the persisted value
Copied!
Changing the persistence storage
All Units use the localStorage for persistence by default, but it can be changed to sessionStorage as well, and you can either change it globally or for a specific Unit.
Changing storage for one Unit
1
const unit = new DictUnit({
2
    id: 'session-token', 
3
    persistent: true, 
4
    
5
    // this is how we can change the storage for a Unit
6
    storage: window.sessionStorage
7
    // it overrides the default/global storage configuration
8
});
Copied!
Changing default storage for every Unit
You can change the default Storage API used by ActiveJS Units through the global Configuration.
1
// set it in global configuration
2
Configuration.set({storage: window.sessionStorage})
3
// now all the persistent Units will use SessionStorage
4
// and the global clearPersistentStorage() will also operate on SessionStorage
Copied!
Be advised that you should only change it once and that too before initializing any persistent Unit.
Otherwise, some persistent Units will save their values in LocalStorage and try to restore it from SessionStorage. Also, the global functionclearPersistentStorage() won't be able to clear persisted values from the other storage, you'll have to manually provide the non-current storage you want to clean up.
Supported data types
It's advised to put only serializable data types in a persistent Unit, otherwise, the information will be lost in serialization done to save it in the LocalStorage. Non-serializable data types like Date, Map, Set, etc. are not supported.
All the data types that support JSON.stringify and JSON.parse can be used as values.
Note: Date object works with JSON.stringify, however it can't be parsed back to a Date object.
When using the persisted value of the Unit, you'll only get a string representation of Date, not a Date object.

Guides - Previous

Caching

Next - Guides

Immutability

Last modified 1yr ago

Copy link

Contents

Creating a persistent Unit

Initial value vs persisted value

Clearing the persisted value

Changing the persistence storage

Changing storage for one Unit

Changing default storage for every Unit

Supported data types