angular-async-local-storage

Async local storage for Angular

Efficient local storage module for Angular :

• simple : based on native localStorage API,
• perfomance : internally stored via the asynchronous IndexedDB API,
• Angular-like : wrapped in RxJS Observables.

Why this module ?

For now, Angular does not provide a local storage module, and almost every app needs some local storage. There is 2 native JavaScript APIs available :

• localStorage
• IndexedDB

The localStorage API is simple to use but synchronous, so if you use it too often, your app will soon begin to freeze.

The 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 localStorage, but internally stored via the asynchronous IndexedDB for performance. But it is written in ES5 and then it's a mess to include into Angular.

This module is based on the same idea as localForage, but in ES6/ES2015 and additionnaly wrapped into RxJS Observables to be homogeneous with other Angular modules.

Getting started

Install via npm :

npm install angular-async-local-storage

Then include the AsyncLocalStorage module in your app root module (just once, do NOT re-import it in your sub modules).

import { AsyncLocalStorageModule } from 'angular-async-local-storage';

@NgModule({
  imports: [
    BrowserModule,
    AsyncLocalStorageModule,
    ...
  ]
  ...
})
export class AppModule {}

Now you just have to inject the service where you need it :

import { AsyncLocalStorage } from 'angular-async-local-storage';

@Injectable()
export class YourService {

  constructor(protected localStorage: AsyncLocalStorage) {}

}

API

The API follows the native localStorage API, except it's asynchronous via RxJS Observables.

Writing data

let user: User = { firstName: 'Henri', lastName: 'Bergson' };

this.localStorage.setItem('user', user).subscribe(() => {});

You can store any value, without worrying about stringifying.

Deleting data

To delete one item :

this.localStorage.removeItem('user').subscribe(() => {});

To delete all items :

this.localStorage.clear().subscribe(() => {});

Reading data

this.localStorage.getItem<User>('user').subscribe((user) => {
  user.firstName; // should be 'Henri'
});

As any data can be stored, you can type your data. But don't forget it's client-side storage : always check the data, as it could have been forged or deleted.

Notes

Not finding an item is not an error, it succeeds but returns null.

this.localStorage.getItem('notexisting').subscribe((data) => {
  data; // null
});

Errors are unlikely to happen, but in an app it's better to catch any potential error.

this.localStorage.setItem('color', 'red').subscribe(() => {
  // Done
}, () => {
  // Error
});

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).

You do NOT need to unsubscribe : the observable autocompletes (like in the HttpClient service).

Angular support

The last version of this library requires Angular 4+ and TypeScript 2.3+.

If you need Angular 2 support, stay on version 1 :

npm install angular-async-local-storage@1

This module supports AoT pre-compiling.

This module supports Universal server-side rendering via a mock storage.

Browser support

All browsers supporting IndexedDB, ie. all current browsers : Firefox, Chrome, Opera, Safari, Edge and IE10+.

Local storage is required only for apps, and given that you won't do an app in older browsers, current browsers support is far enough.

Even so, IE9 is supported but use native localStorage as a fallback, so internal operations are synchronous (the public API remains asynchronous-like).

This module is not impacted by IE/Edge missing IndexedDB features.

Changelog

Changelog available here.

License

MIT

Changelog

4.0.0 (lts) (2018-04-03)

New package name

This library has been renamed from angular-async-local-storage to @ngx-pwa/local-storage. See the migration guide.

Version alignement

This library major version is now aligned to the major version of Angular. Meaning this v4 is for Angular 4. Same as v2.

We follow Angular LTS support, meaning we support Angular 4 until October 2018. So we backported some bug fixes:

• Detect if storages are null or undefined (partially fixes (partially fixes #26)
• Correctly complete observables (fixes #25 & #5)
• Some IndexedDB connection errors were not caught

---

Previous versions were only released under angular-async-local-storage.

---