@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.
This package has no dependencies.
To install this package, run the following command in your terminal:
With npm
npm install @idxdb/promised
With yarn
yarn add @idxdb/promised
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.
export interface DatabaseInterface {
close(): void
createObjectStore(
name: string,
options?: IDBObjectStoreParameters
): ObjectStoreInterface
deleteObjectStore(name: string): void
transaction(
storeNames: string | string[],
mode?: IDBTransactionMode,
options?: IDBTransactionOptions
): TransactionInterface
objectStoreNames: string[]
}
export interface ObjectStoreInterface {
add<V, K extends IDBValidKey>(value: V, key?: K): Promise<K>
clear(): Promise<void>
count<K extends IDBValidKey>(query?: IDBKeyRange | K): Promise<number>
createIndex(
indexName: string,
keyPath: string | string[],
options?: IDBIndexParameters
): IndexInterface
delete<K extends IDBValidKey>(query: IDBKeyRange | K): Promise<void>
deleteIndex(name: string): void
get<R, K extends IDBValidKey>(key: K): Promise<R>
getAll<R, K extends IDBValidKey>(
query?: IDBKeyRange | K,
count?: number
): Promise<R[]>
getAllKeys<K extends IDBValidKey>(
query?: IDBKeyRange | K,
count?: number
): Promise<K[]>
getKey<K extends IDBValidKey>(key: IDBKeyRange | K): Promise<K>
index(name: string): IndexInterface
openCursor<PK extends IDBValidKey, K extends IDBValidKey, R>(
query?: IDBKeyRange | K,
direction?: IDBCursorDirection
): ValueCursorInterface<PK, K, R>
openKeyCursor<PK extends IDBValidKey, K extends IDBValidKey>(
query?: IDBKeyRange | K,
direction?: IDBCursorDirection
): KeyCursorInterface<PK, K>
put<V, K extends IDBValidKey>(value: V, key?: K): Promise<void>
indexNames: string[]
}
export interface IndexInterface {
keyPath: string | string[]
multiEntry: boolean
name: string
objectStore: ObjectStoreInterface
unique: boolean
count<K extends IDBValidKey>(query?: IDBKeyRange | K): Promise<number>
get<R, K extends IDBValidKey>(key: K): Promise<R>
getAll<R, K extends IDBValidKey>(
query?: IDBKeyRange | K,
count?: number
): Promise<R[]>
getAllKeys<K extends IDBValidKey>(
query?: IDBKeyRange | K,
count?: number
): Promise<K[]>
getKey<K extends IDBValidKey>(key: IDBKeyRange | K): Promise<K>
openCursor<PK extends IDBValidKey, K extends IDBValidKey, R>(
query?: IDBKeyRange | K,
direction?: IDBCursorDirection
): ValueCursorInterface<PK, K, R>
openKeyCursor<PK extends IDBValidKey, K extends IDBValidKey>(
query?: IDBKeyRange | K,
direction?: IDBCursorDirection
): KeyCursorInterface<PK, K>
}
export interface ValueCursorInterface<
PK extends IDBValidKey,
K extends IDBValidKey,
R,
> extends KeyCursorInterface<PK, K> {
value: R | undefined
delete(): Promise<void>
update(value: R): Promise<void>
}
export interface KeyCursorInterface<
PK extends IDBValidKey,
K extends IDBValidKey,
> {
primaryKey: PK | undefined
key: K | undefined
direction: IDBCursorDirection
source: ObjectStoreInterface | IndexInterface
request: IDBRequest<IDBCursor>
end(): Promise<boolean>
continue(key?: K): void
advance(count: number): void
continuePrimaryKey(key: K, primaryKey: PK): void
}
export interface TransactionInterface {
abort(): Promise<void>
commit(): Promise<void>
objectStore(name: string): ObjectStoreInterface
objectStoreNames: string[]
db: DatabaseInterface
durability: IDBTransactionDurability
error: DOMException
mode: IDBTransactionMode
}
Database initialization and migration management
import { DatabaseFactory } from '@idxdb/promised';
const migrations = [
{
version: 1,
upgrade: async ({db, transaction, currentVersionUpgrade}) => {
const store = db.createObjectStore('users', { keyPath: 'id' })
store.createIndex('name_idx', 'name', { unique: false });
},
},
{
version: 2,
upgrade: async ({db, transaction, currentVersionUpgrade}) => {
const store = transaction.objectStore('users')
store.createIndex('email_idx', 'email', { unique: true })
},
},
{
version: 3,
upgrade: async ({db, transaction, currentVersionUpgrade}) => {
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);
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
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
This package is licensed under ISC. See the LICENSE file for more information.
If you have any questions or need further assistance, please feel free to reach out to me at Marc MOREAU.
This package uses SemVer for versioning. For the versions available, see the tags on this repository.