angular-async-local-storage

by cyrilletuzi

Efficient local storage module for Angular apps and PWA: simple API + performance + Observables + va...

482 Stars 51 Forks Last release: 3 months ago (v10.0.1) MIT License 983 Commits 65 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Async local storage for Angular

Efficient client-side storage module for Angular: - simplicity: based on native

localStorage
API, - perfomance: internally stored via the asynchronous
indexedDB
API, - Angular-like: wrapped in RxJS
Observable
s, - security: validate data with a JSON Schema, - compatibility: works around some browsers issues and heavily tested via GitHub Actions, - documentation: API fully explained, and a changelog!

Sponsorship

What started as a personal project is now one of the most used Angular library for client-side storage, with more than 10 000 downloads on npm each week.

It's a lot of free work. So if your company earns money with projects using this lib, it would be nice to consider becoming a sponsor.

By the same author

Why this module?

For now, Angular does not provide a client-side storage module, and almost every app needs some client-side storage. There are 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
Promise
s 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'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 built in ES6+ and additionally wrapped into RxJS
Observable
s
to be homogeneous with other Angular modules.

Getting started

Install the package, according to your Angular version:

# For Angular LTS (Angular >= 8):
ng add @ngx-pwa/local-storage

Done!

You should stick to these commands. If for any reason

ng add
does not work, be sure to follow the manual installation guide, as there are additionnal steps to do in addition to the package installation for some versions.

If you have multiple applications in the same project, as usual, you need to choose the project:

bash
ng add @ngx-pwa/local-storage --project yourprojectname

Upgrading

If you still use the old

angular-async-local-storage
package, or to update to new versions, see the migration guides.

API

2 services are available for client-side storage, you just have to inject one of them where you need it.

StorageMap
: recommended

New since version 8 of this lib, this is the recommended service:

import { StorageMap } from '@ngx-pwa/local-storage';

@Injectable() export class YourService { constructor(private storage: StorageMap) {} }

This service API follows the new standard

kv-storage
API, which is similar to the standard
Map
API
, except it's based on RxJS
Observable
s
instead of

Promise
s:
class StorageMap {
  // Write
  set(index: string, value: any): Observable {}
  delete(index: string): Observable {}
  clear(): Observable {}

// Read (one-time) get(index: string): Observable {} get(index: string, schema: JSONSchema): Observable {}

// Observe (version >= 9) watch(index: string): Observable {} watch(index: string, schema: JSONSchema): Observable {}

// Advanced size: Observable; has(index: string): Observable {} keys(): Observable {} }

It does the same thing as the

localStorage
API, but also allows more advanced operations.

LocalStorage
: legacy

You can keep this legacy service in existing apps, but it's not recommended anymore for new applications.

import { LocalStorage } from '@ngx-pwa/local-storage';

@Injectable() export class YourService { constructor(private localStorage: LocalStorage) {} }

This service API follows the standard

localStorage
API, except it's asynchronous via RxJS
Observable
s
:

class LocalStorage {
  // Write
  setItem(index: string, value: any): Observable {}
  removeItem(index: string): Observable {}
  clear(): Observable {}

// Read (one-time) getItem(index: string): Observable {} getItem(index: string, schema: JSONSchema): Observable {}

// Advanced length: Observable; }

How to

The following examples will use the recommended

StorageMap
service. But for older versions, you can always do the same with the
LocalStorage
service.

Writing data

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

this.storage.set('user', user).subscribe(() => {});

You can store any value, without worrying about serializing. But note that: - storing

null
or
undefined
makes no sense and can cause issues in some browsers, so the item will be removed instead, - you should stick to JSON data, ie. primitive types, arrays and literal objects.
Date
,
Map
,
Set
,
Blob
and other special structures can cause issues in some scenarios. See the serialization guide for more details.

Deleting data

To delete one item:

typescript
this.storage.delete('user').subscribe(() => {});

To delete all items:

typescript
this.storage.clear().subscribe(() => {});

Reading data

To get the current value:

typescript
this.storage.get('user').subscribe((user) => {
  console.log(user);
});

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

undefined
(or
null
with
LocalStorage
legacy service):
typescript
this.storage.get('notexisting').subscribe((data) => {
  data; // undefined
});

Note you will only get one value: the

Observable
is here for asynchrony but is not meant to emit again when the stored data is changed. If you need to watch the value, version 9 introduced a
watch()
method, see the watching guide.

Checking data

Don't forget it's client-side storage: always check the data, as it could have been forged.

You can use a JSON Schema to validate the data.

this.storage.get('test', { type: 'string' }).subscribe({
  next: (user) => { /* Called if data is valid or `undefined` */ },
  error: (error) => { /* Called if data is invalid */ },
});

See the full validation guide to see how to validate all common scenarios.

Subscription

You DO NOT need to unsubscribe: the

Observable
autocompletes (like in the Angular
HttpClient
service).

But you DO need to subscribe, even if you don't have something specific to do after writing in storage (because it's how RxJS

Observable
s work).

Errors

As usual, it's better to catch any potential error:

typescript
this.storage.set('color', 'red').subscribe({
  next: () => {},
  error: (error) => {},
});

For read operations, you can also manage errors by providing a default value: ```typescript import { of } from 'rxjs'; import { catchError } from 'rxjs/operators';

this.storage.get('color').pipe( catchError(() => of('red')), ).subscribe((result) => {}); ```

See the errors guide for some details about what errors can happen.

Expiration

This lib, as native

localStorage
and
indexedDb
, is about persistent storage.

Wanting temporary storage (like

sessionStorage
) is a very common misconception: an application doesn't need that. More details here.

Map
-like operations

Starting with version >= 8 of this lib, in addition to the classic

localStorage
-like API, this lib also provides a
Map
-like API for advanced operations: -
.keys()
-
.has(key)
-
.size

See the documentation for more info and some recipes. For example, it allows to implement a multiple databases scenario.

Support

Angular support

We follow Angular LTS support.

This module supports AoT pre-compiling and Ivy.

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

See the browsers support guide for more details and special cases (like private browsing).

Collision

If you have multiple apps on the same subdomain and you don't want to share data between them, see the prefix guide.

Interoperability

For interoperability when mixing this lib with direct usage of native APIs or other libs like

localForage
(which doesn't make sense in most cases), see the interoperability documentation.

Changelog

Changelog available here, and migration guides here.

License

MIT

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.