ngx-indexed-db

ngx-indexed-db

ngx-indexed-db is a service that wraps IndexedDB database in an Angular service combined with the power of observables.

Installation

$ npm install ngx-indexed-db

OR

$ yarn add ngx-indexed-db

Usage

Import the NgxIndexedDBModule and initiate it:

import { NgxIndexedDBModule } from 'ngx-indexed-db';

const dbConfig: DBConfig  = {
  name: 'MyDb',
  version: 1,
  objectStoresMeta: [{
    store: 'people',
    storeConfig: { keyPath: 'id', autoIncrement: true },
    storeSchema: [
      { name: 'name', keypath: 'name', options: { unique: false } },
      { name: 'email', keypath: 'email', options: { unique: false } }
    ]
  }]
};

@NgModule({
  ...
  imports: [
    ...
    NgxIndexedDBModule.forRoot(dbConfig)
  ],
  ...
})

Migrations

import { NgxIndexedDBModule, DBConfig } from 'ngx-indexed-db';

// Ahead of time compiles requires an exported function for factories
export function migrationFactory() {
  // The animal table was added with version 2 but none of the existing tables or data needed
  // to be modified so a migrator for that version is not included.
  return {
    1: (db, transaction) => {
      const store = transaction.objectStore('people');
      store.createIndex('country', 'country', { unique: false });
    },
    3: (db, transaction) => {
      const store = transaction.objectStore('people');
      store.createIndex('age', 'age', { unique: false });
    }
  };
}

const dbConfig: DBConfig  = {
  name: 'MyDb',
  version: 3,
  objectStoresMeta: [{
    store: 'people',
    storeConfig: { keyPath: 'id', autoIncrement: true },
    storeSchema: [
      { name: 'name', keypath: 'name', options: { unique: false } },
      { name: 'email', keypath: 'email', options: { unique: false } }
    ]
  }, {
    // animals added in version 2
    store: 'animals',
    storeConfig: { keyPath: 'id', autoIncrement: true },
    storeSchema: [
      { name: 'name', keypath: 'name', options: { unique: true } },
    ]
  }],
  // provide the migration factory to the DBConfig
  migrationFactory
};

@NgModule({
  ...
  imports: [
    ...
    NgxIndexedDBModule.forRoot(dbConfig)
  ],
  ...
})

NgxIndexedDB service

Import and inject the service:

import { NgxIndexedDBService } from 'ngx-indexed-db';

...
  export class AppComponent {
    constructor(private dbService: NgxIndexedDBService){
    }
  }

API

We cover several common methods used to work with the IndexedDB

add(storeName, value, key?): key

Adds new entry in the store and returns its key

• @param storeName The name of the store to add the item
• @param value The entry to be added
• @param key The optional key for the entry

It publishes in the observable the key value of the entry

this.dbService
  .add('people', {
    name: `Bruce Wayne`,
    email: `[e-mail]`,
  })
  .subscribe((key) => {
    console.log('key: ', key);
  });

In the previous example I'm using undefined as the key because the key is configured in the objectStore as auto-generated.

update(storeName, value, key?)

Updates the given value in the objectStore and returns all items from the store after update..

• @param storeName The name of the store to update
• @param value The new value for the entry
• @param key The key of the entry to update if exists

this.dbService
  .update('people', {
    id: 1,
    email: '[e-mail]',
    name: 'Luke Skywalker',
  })
  .subscribe((storeData) => {
    console.log('storeData: ', storeData);
  });

getByKey(storeName, key)

Returns entry by key.

• @param storeName The name of the store to query
• @param key The entry key

this.dbService.getByKey('people', 1).subscribe((people) => {
  console.log(people);
});

getAll(storeName)

Return all elements from one store

• @param storeName The name of the store to select the items

this.dbService.getAll('people').subscribe((peoples) => {
  console.log(peoples);
});

getByIndex(storeName, indexName, key)

Returns entry by index.

• @param storeName The name of the store to query
• @param indexName The index name to filter
• @param key The entry key.

this.dbService.getByIndex('people', 'name', 'Dave').subscribe((people) => {
  console.log(people);
});

createObjectStore(storeSchema, migrationFactory?)

Allows to crate a new object store ad-hoc

• @param storeName The name of the store to be created
• @param migrationFactory The migration factory if exists

const storeSchema: ObjectStoreMeta = {
  store: 'people',
  storeConfig: { keyPath: 'id', autoIncrement: true },
  storeSchema: [
    { name: 'name', keypath: 'name', options: { unique: false } },
    { name: 'email', keypath: 'email', options: { unique: false } },
  ],
};

this.dbService.createObjectStore(storeSchema);

count(storeName, keyRange?)

Returns the number of rows in a store.

• @param storeName The name of the store to query
• @param keyRange The range value and criteria to apply.

this.dbService.count('people').subscribe((peopleCount) => {
  console.log(peopleCount);
});

delete(storeName, key)

Returns all items from the store after delete.

• @param storeName The name of the store to have the entry deleted
• @param key The key of the entry to be deleted

this.dbService.delete('people', 3).subscribe((allPeople) => {
  console.log('all people:', allPeople);
});

openCursor(storeName, keyRange?)

Returns the open cursor event

• @param storeName The name of the store to have the entries deleted
• @param keyRange The key range which the cursor should be open on

this.dbService.openCursor('people', IDBKeyRange.bound("A", "F")).subscribe((evt) => {
    var cursor = (evt.target as IDBOpenDBRequest).result;
    if(cursor) {
        console.log(cursor.value);
        cursor.continue();
    } else {
        console.log('Entries all displayed.');
    }
});

openCursorByIndex(storeName, indexName, keyRange, cursorCallback)

Open a cursor by index filter.

• @param storeName The name of the store to query.
• @param indexName The index name to filter.
• @param keyRange The range value and criteria to apply on the index.

this.dbService.openCursorByIndex('people', 'name', IDBKeyRange.only('john')).subscribe((evt) => {
    var cursor = (evt.target as IDBOpenDBRequest).result;
    if(cursor) {
        console.log(cursor.value);
        cursor.continue();
    } else {
        console.log('Entries all displayed.');
    }
});

getAllByIndex(storeName, indexName, keyRange)

Returns all items by an index.

• @param storeName The name of the store to query
• @param indexName The index name to filter
• @param keyRange The range value and criteria to apply on the index.

this.dbService.getAllByIndex('people', 'name', IDBKeyRange.only('john')).subscribe((allPeopleByIndex) => {
  console.log('All: ', allPeopleByIndex);
});

clear(storeName)

Returns true if successfully delete all entries from the store.

• @param storeName The name of the store to have the entries deleted

this.dbService.clear('people').subscribe((successDeleted) => {
  console.log('success? ', successDeleted);
});

deleteDatabase()

Returns true if successfully delete the DB.

this.dbService.deleteDatabase().subscribe((deleted) => {
  console.log('Database deleted successfully: ', deleted);
});

License

Released under the terms of the MIT License.