Async local storage for Angular
Efficient local storage module for Angular apps and Progressive Wep apps (PWA):
- simplicity: based on native
localStorageAPI and automatic JSON stringify/parse,
- perfomance: internally stored via the asynchronous
- Angular-like: wrapped in RxJS
- security: validate data with a JSON Schema,
- compatibility: works around some browsers issues,
- documentation: API fully explained, and a changelog!
- reference: 1st Angular library for local storage according to ngx.tools
By the same author
- Angular schematics extension for VS Code (GUI for Angular CLI commands)
- Library @ngx-pwa/offline
- Popular Angular posts on Medium
- Follow updates of this lib on Twitter
- Angular onsite trainings (based in Paris, so the website is in French, but my English bio is here and I'm open to travel)
Why this module?
localStorage API is simple to use but synchronous, so if you use it too often,
your app will soon begin to freeze.
IndexedDB API is asynchronous and efficient, but it's a mess to use:
you'll soon be caught by the callback hell, as it does not support Promises yet.
Mozilla has done a very great job with the localForage library:
a simple API based on native
but internally stored via the asynchronous
IndexedDB for performance.
But it's built in ES5 old school way and then it's a mess to include into Angular.
This module is based on the same idea as localForage, but in ES6 and additionally wrapped into RxJS Observables to be homogeneous with other Angular modules.
Install the same version as your Angular one via npm:
# For Angular 6 and Angular 7:npm install @ngx-pwa/local-storage@6# For Angular 5:npm install @ngx-pwa/local-storage@5
Now you just have to inject the service where you need it:
Versions 4 & 5 (only) need an additional setup step explained in the old module guide.
About version 7
v7 of this lib works but is not recommended due to unforeseen issues. For example, v7 doesn't support TypeScript 3.2 due to a TypeScript regression (see #64).
v8 will clean the mess, but until then, as you can see above, stay on v6 as it is compatible with Angular 7 too.
You have to tell the version on
as we can't change the
latest tag (it would break users already on v7).
If you still use the old
angular-async-local-storage package, or to update to version 6,
see the migration guides.
You can store any value, without worrying about stringifying.
To delete one item:
To delete all items:
As any data can be stored, you can type your data.
Not finding an item is not an error, it succeeds but returns
If you tried to store
undefined, you'll get
null too, as some storages don't allow
Don't forget it's client-side storage: always check the data, as it could have been forged or deleted.
Starting with version 5, you can use a JSON Schema to validate the data.
Starting with version 7, validation is now required. A migration guide is available.
See the full validation guide to see how to validate all common scenarios.
You DO NOT need to unsubscribe: the observable autocompletes (like in the
But you DO need to subscribe, even if you don't have something specific to do after writing in local storage (because it's how RxJS Observables work).
Since version 5.2, you can use these methods to auto-subscribe:
Use these methods only if these conditions are fulfilled:
- you don't need to manage the error callback (with these methods, errors will silently fail),
- you don't need to wait the operation to finish before the next one (remember, it's asynchronous).
Starting with version >= 7.4, in addition to the classic
this lib also provides some
Map-like methods for advanced operations:
See the documentation for more info and some recipes.
If you have multiple apps on the same subdomain and you don't want to share data between them, see the prefix guide.
- Errors are unlikely to happen, but in an app, it's better to catch any potential error:
- When reading data, you'll only get one value: the observable is here for asynchronicity but is not meant to emit again when the stored data is changed. And it's normal: if app data change, it's the role of your app to keep track of it, not of this lib. See #16 for more context and #4 for an example.
This lib major version is aligned to the major version of Angular. Meaning for Angular 5 you need version 5, for Angular 6 you need version 6, for Angular 7 you need version 7, and so on.
We follow Angular LTS support, meaning we support Angular 5 minimum, until May 2019.
This module supports AoT pre-compiling.
This module supports Universal server-side rendering via a mock storage.
All browsers supporting IndexedDB, ie. all current browsers : Firefox, Chrome, Opera, Safari, Edge, and IE10+.
See the browsers support guide for more details and special cases (like private browsing).
For interoperability when mixing this lib with direct usage of native APIs or other libs (which doesn't make sense in most of cases), see the interoperability documentation.