@ngx-pwa/local-storage
    TypeScript icon, indicating that this package has built-in type declarations

    13.0.2 • Public • Published

    Async local storage for Angular

    Efficient client-side storage module for Angular:

    • simplicity: simple API like native localStorage,
    • perfomance: internally stored via the asynchronous indexedDB API,
    • Angular-like: wrapped in RxJS Observables,
    • 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

    This library is downloaded more than 15 000 times each week on npm, and my other major open source project, the Angular schematics extension for VS Code, is used by 500 000 users. It represents months of full time unpaid work.

    So please consider to sponsor (or ask your company to do so). In addition to support open source, it will grant you access to the Schematics Pro sponsorware, which helps you build optimized and architectured Angular projects in no time.

    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:

    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'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 Observables to be homogeneous with other Angular modules.

    Getting started

    Install the package, according to your Angular version:

    # For Angular LTS (Angular >= 10):
    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:

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

    Upgrading

    To update to new versions, see the migration guides.

    API

    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, and close to the standard localStorage API, except it's based on RxJS Observables instead of Promises:

    class StorageMap {
      // Write
      set(index: string, value: any): Observable<undefined> {}
      delete(index: string): Observable<undefined> {}
      clear(): Observable<undefined> {}
    
      // Read (one-time)
      get(index: string): Observable<unknown> {}
      get<T>(index: string, schema: JSONSchema): Observable<T> {}
    
      // Observe
      watch(index: string): Observable<unknown> {}
      watch<T>(index: string, schema: JSONSchema): Observable<T> {}
    
      // Advanced
      size: Observable<number>;
      has(index: string): Observable<boolean> {}
      keys(): Observable<string> {}
    }

    Note: there is also a LocalStorage service available, but only for compatibility with old versions of this lib.

    How to

    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:

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

    To delete all items:

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

    Reading data

    To get the current value:

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

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

    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, 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 Observables work).

    Errors

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

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

    For read operations, you can also manage errors by providing a default value:

    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

    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 Universal server-side rendering via a mock storage.

    Browser support

    This lib supports the same browsers as Angular. 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

    Install

    npm i @ngx-pwa/local-storage

    DownloadsWeekly Downloads

    17,659

    Version

    13.0.2

    License

    MIT

    Unpacked Size

    551 kB

    Total Files

    50

    Last publish

    Collaborators

    • cyrilletuzi