README.md

❗ PROJECT SHUT DOWN ❗

I haven't used the library at work or for personal projects since Angular 13 or 14 and it's time to let it rest. I'd recommend switching to using IndexedDB directly (we've made Observable wrappers around its API at work) - browser support is great these days & the API is much more performance and feature-rich.

Peace out and a huge thanks to everyone who's used ngforage over the years!

ngforage

localforage bindings for Angular

---

• Demo
• API documentation

---

Installation

You can also npm install manually:

 npm install localforage@^1.10.0 ngforage@^11.0.0 # Angular 17
 npm install localforage@^1.10.0 ngforage@^10.0.0 # Angular 16
 npm install localforage@^1.10.0 ngforage@^9.0.0 # Angular 15
 npm install localforage@^1.10.0 ngforage@^8.0.0 # Angular 14
 npm install localforage@^1.9.0 ngforage@^7.0.0 # Angular 13
 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

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);
  }
}