devbean/ngforage

localForage bindings for Angular

ngforage

localforage bindings for Angular

---

• Demo
• API documentation

---

Installation

For Angular versions >=9.0.0 and ngforage versions >=6.0.0 you can use Angular CLI:

  ng add ngforage

You can also npm install manually:

 npm install localforage@^1.5.0 ngforage@^6.0.0 # Angular 9
 npm install localforage@^1.5.0 ngforage@^5.0.0 # Angular 8
 npm install localforage@^1.5.0 ngforage@^4.0.0 # Angular 7
 npm install localforage@^1.5.0 ngforage@^3.0.0 # Angular 6
 npm install localforage@^1.5.0 ngforage@^2.0.0 # Angular 5

Alternatively, you can replace the following ngforage versions with a dist tag:

npm install ngforage@ng8
npm install ngforage@ng7
npm install ngforage@ng6
npm install ngforage@ng5

Basic Usage

  import {DEFAULT_CONFIG, NgForageOptions, NgForageConfig, Driver} from 'ngforage';
  
  @NgModule({
    providers: [
      // One way of configuring ngForage
      {
        provide: DEFAULT_CONFIG,
        useValue: {
          name: 'MyApp',
          driver: [ // defaults to indexedDB -> webSQL -> localStorage
            Driver.INDEXED_DB,
            Driver.LOCAL_STORAGE
          ]
        } as NgForageOptions
      }
    ]
  })
  export class AppModule{
    // An alternative way of configuring ngforage
    public constructor(ngfConfig: NgForageConfig) {
      ngfConfig.configure({
        name: 'MyApp',
        driver: [ // defaults to indexedDB -> webSQL -> localStorage
          Driver.INDEXED_DB,
          Driver.LOCAL_STORAGE
        ]
      });
    }
  }

  import {NgForage, Driver, NgForageCache, CachedItem} from 'ngforage';

  @Component({
    /* If you plan on making per-component config adjustments, add the services to the component's providers
     * to receive fresh instances; otherwise, skip the providers section.
     */
    providers: [NgForage, NgForageCache]
  })
  class SomeComponent implements OnInit {
    constructor(private readonly ngf: NgForage, private readonly cache: NgForageCache) {}
    
    public getItem<T = any>(key: string): Promise<T> {
      return this.ngf.getItem<T>(key);
    }
    
    public getCachedItem<T = any>(key: string): Promise<T | null> {
      return this.cache.getCached<T>(key)
        .then((r: CachedItem<T>) => {
          if (!r.hasData || r.expired) {
            return null;
          }
          
          return r.data;
        })
    }
    
    public ngOnInit() {
      this.ngf.name = 'SomeStore';
      this.cache.driver = Driver.LOCAL_STORAGE;
    }
  }

Store instances

It is recommended to declare NgForage and/or NgForageCache in providers if you're not using the default configuration. The running configuration hash is used to create and reuse drivers (e.g. different IndexedDB databases), therefore setting it on a shared instance might have unintended side-effects.

Defining a Driver

1. Define a driver as described in the localForage docs
2. Plug it in, either directly through localForage or through NgForageConfig:

import {NgModule} from "@angular/core";
import {NgForageConfig} from 'ngforage';
import localForage from 'localforage';

// Your driver definition
const myDriver: LocalForageDriver = {/*...*/};

// Define it through localForage
localForage.defineDriver(myDriver)
  .then(() => console.log('Defined!'))
  .catch(console.error);

@NgModule({})
export class AppModule {

  constructor(conf: NgForageConfig) {
    // Or through NgForageConfig
    conf.defineDriver(myDriver)
      .then(() => console.log('Defined!'))
      .catch(console.error);
  }
}