IndexedDB Promise

Use the IndexedDB API with promises.
IMPORTANT: This is an ESM only package. It uses the browser's IndexedDB API.

You can find tests and example code on the GitHub repository that will help you understand how to use this package. github.com/StephenHassall/indexeddb-promise

Installation

npm install @coderundebug/indexeddb-promise

Contents

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');
  }
}
Name Information
constructor(name, version) When you have derived your own class from Database, make sure you call the super function with the name of the database and its current version.
iDbDatabase Get the IDBDatabase interface object associated with the database.
version Get the version of the database.
name Get the name of the database.
objectStoreNames Get a list of object store names contained within the database.
open
async/await
Opens the database and calls the _upgrade override function if required.
close Closes the database.
createObjectStore(name, [options]) While upgrading you can create new object stores.
deleteObjectStore(name) While upgrading you can delete existing object stores.
transaction(storeNames, [mode], [options]) When the database is open you can create a transaction.
_upgrade(transaction, oldVersion, newVersion) When the open function is called, if there is a different version number, then the _upgrade function will be called. You need to override this function within your own class and perform any upgrading steps required.

You can use async with this function if required.
_close Override this function to handle when the database is closed unexpectedly. This is not called when the close function is used.
_versionChange Override this function to handle when the database has changed from elsewhere, in another tab for example.

Transaction

This class is a wrapper to the IDBTransaction interface.

Name Information
iDbTransaction Get the IDBTransaction interface object associated with the transaction.
db Get the IDBDatabase interface object that created the transaction object.
durability Get the durability setting used when the transaction was created.
mode Get the mode setting used when the transaction was created.
objectStoreNames Get the list of object store names used when the transaction was created.
error Get the error why the transaction failed.
commit
async/await
Commits any changes made with the transaction to the database.
abort async/await Aborts all the changes made with the transaction.
objectStore(name) Get the object store object. It can only return an object store that was selected when the transaction was created.

ObjectStore

This class is a wrapper to the IDBObjectStore interface.

Name Information
iDbObjectStore Get the IDBObjectStore interface object associated with the object store.
transaction Get the IDBTransaction interface object that created the object store object.
autoIncrement Get the autoIncrement setting used when the objectStore was created (in the _upgrade override function).
keyPath Get the keyPath setting used when the objectStore was created (in the _upgrade override function).
name Get the name of the object store.
indexNames Get a list of all the index names within the object store.
clear()
async/await
Deletes all the objects (records) within the object store.
count([query])
async/await
Counts the number of objects (records) that match the query.
add(value, [key])
async/await
Insert a new object (record) into the object store.
put(value, [key])
async/await
Updates an existing object (record) within the object store.
delete(key)
async/await
Delete one or more objects (records) from the object store.
get(key)
async/await
Get the first found object (record) using the key or key range.
getAll([query], [count])
async/await
Get all the found objects (records) using the key or key range. It will only return up to the given count.
getKey([key])
async/await
Get the first found key using the key or key range.
getAllKeys([query], [count])
async/await
Get all the found keys using the query. It will only return up to the given count.
createIndex(indexName, keyPath, [options]) Create a new index for the object store to use (in the _upgrade override function).
deleteIndex(indexName) Delete an existing index from the object store (in the _upgrade override function).
index(name) Get the index object used by the object store.
openCursor([query], [direction])
async/await
Opens a cursor that is used to move through the matching objects (records).
openKeyCursor([query], [direction])
async/await
Opens a cursor that is used to move through the matching objects (records) and return only the key parts (not the whole object).

Index

This class is a wrapper to the IDBIndex interface.

Name Information
iDbIndex Get the IDBIndex interface object associated with the index.
objectStore Get the IDBObjectStore interface object that created the index object.
keyPath Get the keyPath setting used when the index was created (in the _upgrade override function).
multiEntry Get the multiEntry setting used when the index was created (in the _upgrade override function).
unique Get the unique setting used when the index was created (in the _upgrade override function).
name Get the name of the index.
count([key])
async/await
Counts the number of objects (records) that match the query.
get(key)
async/await
Get the first found object (record) using the key or key range.
getAll([query], [count])
async/await
Get all the found objects (records) using the key or key range. It will only return up to the given count.
getKey([key])
async/await
Get the first found key using the key or key range.
getAllKeys([query], [count])
async/await
Get all the found keys using the query. It will only return up to the given count.
openCursor([range], [direction])
async/await
Opens a cursor that is used to move through the matching objects (records).
openKeyCursor([range], [direction])
async/await
Opens a cursor that is used to move through the matching objects (records) and return only the key parts (not the whole object).

Cursor

This class is a wrapper to the IDBCursor interface.

Name Information
iDbCursor Get the IDBCursor interface object associated with the cursor.
source Get either the IDBObjectStore or IDBIndex interface object that created the cursor object.
request Get the IDBRequest interface object linked to the cursor.
direction Get the direction setting used when creating the cursor object.
key Get the current key value of the object the cursor is looking at.
primaryKey Get the current primary key value for the object the cursor is looking at.
advance(count)
async/await
Make the cursor jump forward by the given number of steps. The promise resolves with true, record found, or false (passed end of list).
continue([key])
async/await
More on to the next object (record). The promise resolves with true, record found, or false (passed end of list).
continuePrimaryKey(key, primaryKey)
async/await
More on to the next object (record). The promise resolves with true, record found, or false (passed end of list).

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.

Name Information
iDbCursorWithValue Get the IDBCursorWithValue interface object associated with the cursor.
value Get the current value, the object (record) itself, where the cursor is positioned at.
delete()
async/await
Deletes the object (record) the cursor is currently positioned at.
update(value)
async/await
Updates the object (record) the cursor is currently positioned at. This replaces the whole object with the existing one. Any indexes will automatically be updated.

Factory

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

Name Information
databases Get a list of all the databases. This information includes the name and version.
deleteDatabase(name, [options])
async/await
Deletes a database.