Overview

@idxdb/promised is a lightweight library that wraps the IndexedDB API, providing a more natural way to work with promises. It allows you to easily store and retrieve data in an indexed database using async/await syntax, making it easier to integrate with your existing codebase.

Dependencies

This package has no dependencies.

Installation

To install this package, run the following command in your terminal:

• With npm

npm install @idxdb/promised

• With yarn

yarn add @idxdb/promised

ESM Module

@idxdb/promised is an ECMAScript (ESM) module, which means it can be directly imported in environments that support modules, such as modern browsers or Node.js with ESM enabled.

Usage in the Browser

You can load the module directly from a CDN using the following code:

<script type="module" src="https://cdn.jsdelivr.net/npm/@idxdb/promised@latest/dist/src/index.js"></script>

Once loaded, a DatabaseFactory object will be available in the global scope, allowing you to interact with the @idxdb/promised API directly.

This allows you to use @idxdb/promised without the need to download it locally or set up a bundler like Webpack or Rollup.

Foreword

This package fully respects the original indexedDB API.

The only subtleties are:

• database initialization, to support migrations during version upgrades.

• in the cursors, which allow more natural iteration than the original API.

Usage - API

Database initialization and migration management

import { DatabaseFactory } from '@idxdb/promised';

const migrations = [
    {
        version: 1,
        migration: async ({db, transaction, dbOldVersion, dbNewVersion, migrationVersion}) => {
            const store = db.createObjectStore('users', { keyPath: 'id' })
            store.createIndex('name_idx', 'name', { unique: false });
        },
    },
    {
        version: 2,
        migration: async ({db, transaction, dbOldVersion, dbNewVersion, migrationVersion}) => {
            const store = transaction.objectStore('users')
            store.createIndex('email_idx', 'email', { unique: true })
        },
    },
    {
        version: 3,
        migration: async ({db, transaction, dbOldVersion, dbNewVersion, migrationVersion}) => {
            const store = transaction.objectStore('users')
            store.createIndex('identifier_idx', 'identifier', { unique: true })
            store.deleteIndex('email_idx')
        },
    },
]

const requestedVersion = 3;

const db = await DatabaseFactory.open('mydatabase', requestedVersion, migrations);

What if I don't have any migrations to keep up to date and I just delete my DB every time I change?

All you have to do is keep one migration and you're done.

import { DatabaseFactory } from '@idxdb/promised';

const requestedVersion = 3; // the version you want to open, increase to open anew one and reset your DB scheme

const migrations = [
    {
        version: requestedVersion,
        migration: async ({db, transaction, dbOldVersion, dbNewVersion, migrationVersion}) => {
            for (const store of db.objectStoreNames) {
                db.deleteObjectStore(store) // correctly delete all previous existing stores
            }
            // creates the fresh new stores and their indexes
            const store = db.createObjectStore('users', { keyPath: 'id' })
            store.createIndex('name_idx', 'name', { unique: false });
            //...
        },
    },
]

const db = await DatabaseFactory.open('mydatabase', requestedVersion, migrations);

What happens if my DB is already open and I try to open another version?

A basic error message will inform you that the operation is impossible. However, you can take control by adding a handler for the blocked event and perform the actions you deem necessary:

• Warn the user
• Inform other tabs
• ...

import { DatabaseFactory } from '@idxdb/promised';

let db = await DatabaseFactory.open(dbName, 1)

const bc = new BroadcastChannel('idxdb_channel')

bc.onmessage = (event) => {
    if (event.data.action === 'close-db') {
        db.close();
    }
}

const onBlocked = async ({ oldVersion, newVersion }) => {
    // warn other tabs to close the db
    bc.postMessage({ action: 'close-db' });
    return 'close-db-emitted'
}

db = await DatabaseFactory.open(dbName, 2, [], onBlocked).catch((error) => {
    if (error === 'close-db-emitted') {
        // retry the open
        return  DatabaseFactory.open(dbName, 2)
    }
})

Add some data

import { DatabaseFactory } from '@idxdb/promised';

const db = await DatabaseFactory.open('mydatabase', 1);

const tx = db.transaction(['users'], "readwrite");
const store = tx.objectStore('users');

store.add({ id: 1, name: 'Jane Doe' });

await tx.commit();

Fetch some data

import { DatabaseFactory } from '@idxdb/promised';

const db = await DatabaseFactory.open('mydatabase', 1);

const tx = db.transaction(['users'], "readonly");
const store = tx.objectStore('users');

const result = await store.get(1);
console.log(result.name); // "John Doe"

Iterate over cursor

import { DatabaseFactory } from '@idxdb/promised';

const db = await DatabaseFactory.open('mydatabase', 1);

const tx = db.transaction(['users'], "readonly");
const store = tx.objectStore('users');
const cursor = store.openCursor();

while (!(await cursor.end())) {
    console.log(cursor.value);
    cursor.continue();
}

And all the existing API

The library implements all the methods of the IndexedDB API, you can find the documentation here.

You can also find more examples in the tests

Contributing

If you'd like to contribute to this package, please follow these steps:

• Fork this repository
• Make your changes and commit them
• Create a pull request with a detailed description of the changes

License

This package is licensed under ISC. See the LICENSE file for more information.

Contact

If you have any questions or need further assistance, please feel free to reach out to me at Marc MOREAU.

Versioning

This package uses SemVer for versioning. For the versions available, see the tags on this repository.