Installation

npm install @coderundebug/indexeddb-promise

Contents

• Introduction
• Database
• Transaction
• ObjectStore
• Index
• Cursor
• CursorWithValue
• Factory

Introduction

The IndexedDB API is a database in the browser, however it is not the same as a large SQL like database, but more like a simple object store with indexes. It is different compared to other databases you may have used before, but once you understand how to use it, you will find it very useful for storing data on the client end.

All the API tasks are performed on a different thread and any request to do something is performed on that thread. Once the task is performed it sends an event to signal that it has finished (or failed). When doing a number of tasks together, adding and removing records, dealing with the events can become a pain. This package was created to add promises to the tasks, allowing you to use async/await to perform the steps one after the other.

// Create instance of my database
const myDatabase = new MyDatabase();

// Open the database
await myDatabase.open();

// Create transaction
const transaction = myDatabase.transaction('my-object-store', 'readwrite');

// Open my object store (table)
const myObjectStore = transaction.objectStore('my-object-store');

// Add record (object/document)
await myObjectStore.add({ id: 1, text: 'hello' });
await myObjectStore.add({ id: 2, text: 'world' });

// Commit changes
await transaction.commit();

// Close my database
myDatabase.close();

All the classes are wrappers to the IDB interfaces but with promises and one or two extra helpful functions. The goal of this package is to make using the IndexedDB API easier, more understandable, but without replacing the core functions with something totally new.

You will find information on how most of the functions work by looking at the related interface functions associated with them. Their functions and parameters are basically the same.

Database

This class is a wrapper to the IDBDatabase interface, but you cannot use it directly, it needs to be derived from. You create your own class that extends from the Database class and then override the _upgrade function. This is used to create the internal object stores and indexes.

class MyDatabase extends Database {
  constructor() {
    // Call base constructor to set database name and version
    super('my-database', 1);
  }

  _upgrade(transaction, oldVersion, newVersion) {
    // New version (or first time)
    this.createObjectStore('objectStore1');
    this.createObjectStore('objectStore2');
  }
}

Transaction

This class is a wrapper to the IDBTransaction interface.

ObjectStore

This class is a wrapper to the IDBObjectStore interface.

Index

This class is a wrapper to the IDBIndex interface.

Cursor

This class is a wrapper to the IDBCursor interface.

CursorWithValue

This class is a wrapper to the IDBCursorWithValue interface. This is derived from the Cursor class therefore it also contains all the properties and functions from that class.

Factory

This is not a wrapper like the other classes. It is used to add promises to one of the IDBFactor functions.