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
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.
// this will throw an error, id is requiredconst preferencesUnit = new DictUnit({persistent: true});// this will workconst preferencesUnit = new DictUnit({id: 'preferences', persistent: true});// update Unit's valuepreferencesUnit.set('side', 'dark');// value in the LocalStorage would become {"side": "dark"}// refresh the browser window// check valueconsole.log(preferencesUnit.value()) // logs {"side": "dark"}
Voila! we're done. No manual saving, no manual retrieving.
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.
const preferencesUnit = new DictUnit({id: 'preferences',persistent: true,initialValue: {earth: 'flat'}});// value in the LocalStorage would become {"earth": "flat"}// set a new preference, which dispatches and saves a new valuepreferencesUnit.set('earth', 'oblate ellipsoid');// now LocalStorage has {"earth": "oblate ellipsoid"}// now, refresh the browser window// check valueconsole.log(preferencesUnit.value()) // logs {"earth": "oblate ellipsoid"}// the initial value gets ignored
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)
// taking the Unit from above example, and starting from where we leftconsole.log(preferencesUnit.value()) // logs {"earth": "oblate ellipsoid"}// clear the persisted valuepreferencesUnit.clearPersistedValue();// or clearPersistentStorage()// or clearPersistentStorage(localStorage)// check valueconsole.log(preferencesUnit.value()) // logs {"earth": "oblate ellipsoid"}// because only the persisted value is removed, the Unit's value stays intact// now, refresh the browser window// check valueconsole.log(preferencesUnit.value()) // logs {"earth": "flat"}// the initial value is used, because we cleared the persisted value
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.
const unit = new DictUnit({id: 'session-token',persistent: true,// this is how we can change the storage for a Unitstorage: window.sessionStorage// it overrides the default/global storage configuration});
You can change the default Storage API used by ActiveJS Units through the global Configuration.
// set it in global configurationConfiguration.set({storage: window.sessionStorage})// now all the persistent Units will use SessionStorage// and the global clearPersistentStorage() will also operate on SessionStorage
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.
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
.