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
npm install @coderundebug/indexeddb-promise
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.
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. |
openasync/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. |
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. |
commitasync/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. |
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). |
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). |
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).
|
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. |
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. |