ngforage

localForage bindings for Angular 4 and 5

Table of Contents

• Installation
• Types and polyfills
• Importing the module
• Usage
  • Using the Standard Store
  • Using the Cache Store
• Configuration
  • Global Configuration
  • Instance-Level Configuration
• Store instances
• Defining a Driver

Installation

The metadata version for Angular's AOT compiler differs between Angular 4.x and Angular 5.x, therefore two flavours of this library are released:

| Flavour | Angular 4 | Angular 5 | |-----------|--------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------| | Local | npm install @ngforage/ngforage-ng4 | npm install @ngforage/ngforage-ng5 | | CDN | Package | Package |

The UMD global name is ngForage.

Types and polyfills

Ensure that the following are available globally:

• Promise
• Object.assign

Importing the module

Replace ngforage with @ngforage/ngforage-ng4 or @ngforage/ngforage-ng5 depending on which version of Angular you're using.

import {NgModule} from "@angular/core";
import {NgForageModule} from "ngforage";

@NgModule({
  imports: [
    NgForageModule
  ]
})
export class MyModule {

}

Usage

Using the Standard Store

import {ChangeDetectionStrategy, Component} from "@angular/core";
import {NgForage, NgForageConfig} from "ngforage";

@Component({
  selector: 'my-component',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: 'foo'
})
export class MyComponent {

  constructor(private readonly ngf: NgForage) {

  }

  async getSomething() {
    const clickCount = await this.ngf.getItem<number>('clickCount');

    console.log(`${clickCount === null ? 'No' : clickCount} clicks.`);
  }

  async setSomething() {
    await this.ngf.setItem('foo', {bar: 'qux'});
  }

  async removeSomething() {
    await this.ngf.removeItem('foo');
  }

  async removeEverything() {
    await this.ngf.clear();
  }

  async getNumberOfItems() {
    console.log(`There are ${await this.ngf.length()} items stored!`);
  }

  async printKeysStored() {
    const keys: string[] = await this.ngf.keys();

    console.log('Keys:', keys.sort().join("\n"));
  }

  async checkIfDriverIsSupported() {
    const supports = this.ngf.supports(NgForageConfig.DRIVER_INDEXEDDB);

    console.log(`IndexedDB is ${supports ? '' : 'not '}supported`);
  }
}

Using the Cache Store

The cache store can be used as a replacement for NgForage, but also supports the following operations:

import {ChangeDetectionStrategy, Component} from "@angular/core";
import {CachedItem, NgForageCache} from "ngforage";

@Component({
  selector: 'my-component',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: 'foo'
})
export class MyComponent {

  constructor(private readonly ngfc: NgForageCache) {

  }

  async setSomething() {
    // Use default expiry time
    await this.ngfc.setCached('foo', 'bar');

    // Cache for one minute
    await this.ngfc.setCached('qux', {baz: 1}, 60000);
  }

  async getSomething() {
    const item: CachedItem<string> = await this.ngfc.getCached<string>('foo');

    if (item.hasData) {
      console.log(`The item is ${item.data}`);
    } else {
      console.log('No data found');
    }

    if (item.expired) {
      console.log('Item has expired');
    } else {
      const expiryDate: Date = item.expires;

      console.log(`The item will expire in ${Math.round(item.expiresIn / 1000)} seconds, on ${expiryDate.toLocaleString()}`);
    }
  }

  async removeSomething() {
    await this.ngfc.removeCached('foo');
  }
}

Configuration

Global Configuration

import {NgModule} from "@angular/core";
import {NgForageConfig, NgForageModule, NgForageOptions} from "ngforage";

@NgModule({
  imports: [
    NgForageModule
  ]
})
export class MyModule {

  constructor(conf: NgForageConfig) {
    // Set the database name
    conf.name = 'myDB';

    // Set the store name (e.g. in IndexedDB this is the dataStore)
    conf.storeName = 'my_store';

    // Set default cache time to 5 minutes
    conf.cacheTime = 300000;

    // Set driver to local storage
    conf.driver = NgForageConfig.DRIVER_LOCALSTORAGE;

    // Set the driver to indexed db if available,
    // falling back to websql
    // falling back to local storage
    conf.driver = [
      NgForageConfig.DRIVER_INDEXEDDB,
      NgForageConfig.DRIVER_WEBSQL,
      NgForageConfig.DRIVER_LOCALSTORAGE
    ];

    // Set websql database size
    conf.size = 1024 * 1024 * 4;

    // Set DB version. Currently unused.
    conf.version = 2.0;

    // Configure in bulk
    const bulk: NgForageOptions = {
      version: 3.0,
      name: 'newDB'
    };
    conf.configure(bulk);
  }
}

Instance-Level Configuration

You can configure ngForage on an instance level. If need be, every component can have its own instance:

import {ChangeDetectionStrategy, Component} from "@angular/core";
import {NgForage, NgForageCache} from "ngforage";

@Component({
  selector: 'my-component',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: 'foo',
  providers: [
    NgForage,
    NgForageCache
  ]
})
export class MyComponent {

  constructor(private readonly store: NgForage,
              private readonly cache: NgForageCache) {

  }
}

NgForageCache has the same setters as NgForageConfig whilst NgForage supports all setters except cacheTime.

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, NgForageModule} from "ngforage";
import * as localForage from 'localforage';

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

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

@NgModule({
  imports: [
    NgForageModule
  ]
})
export class DemoModule {

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