idbx

No-bullshit indexedDB wrapper functions with promises, iterators and shortcuts.

Getting started

import * as idbx from "https://deno.land/x/idbx";

const req = idbx.open("testdb", 1);

// upgrade the database
req.upgrade((event) => {
  const db = event.target.result;
  const store = db.createObjectStore("store");
  store.createIndex("name", "name", { unique: true });
});

const db = await req.ready;

// open a transaction
const tx = db.transaction("store", "readwrite");

// get a store
const store = tx.objectStore("store");

// add items
await idbx.add(store, { name: "foo" });
await idbx.add(store, { name: "bar" });

// add multiple items
await idbx.addBulk(store, [{ name: "baz" }, { name: "qux" }]);

const items = await idbx.getAll(store);
console.log(items);

functions

idbx.open(name: string, version?: number)

Returns a promise that resolves to an IDBDatabase instance.

const req = await idbx.open("testdb", 1);

// upgrade the database
req.upgrade((event) => {
  const db = event.target.result;
  // ...
});

req.blocked((event) => {
  // ...
});

const db = await req.ready;

// ...

idbx.add(store: IDBObjectStore, item: T, key?: IDBValidKey)

Adds an item to the store. Returns a promise that resolves to the key of the added item.

const key = await idbx.add(store, { name: "foo" });

idbx.addBulk(store: IDBObjectStore, items: T[], key?: IDBValidKey)

Adds multiple items to the store. Returns a promise that resolves to the keys of the added items.

const keys = await idbx.addBulk(store, [{ name: "foo" }, { name: "bar" }]);

idbx.put(store: IDBObjectStore, item: T, key?: IDBValidKey)

Adds or updates an item in the store. Returns a promise that resolves to the key of the added or updated item.

const key = await idbx.put(store, { name: "foo" });

idbx.putBulk(store: IDBObjectStore, items: T[], key?: IDBValidKey)

Adds or updates multiple items in the store. Returns a promise that resolves to the keys of the added or updated items.

const keys = await idbx.putBulk(store, [{ name: "foo" }, { name: "bar" }]);

idbx.del(store: IDBObjectStore, key: IDBValidKey)

Deletes an item from the store. Returns a promise that resolves to undefined.

await idbx.del(store, 1);

idbx.delBulk(store: IDBObjectStore, keys: IDBValidKey[])

Deletes multiple items from the store. Returns a promise that resolves to undefined.

await idbx.delBulk(store, [1, 2]);

idbx.get(store: IDBObjectStore, key: IDBValidKey)

Returns a promise that resolves to the item with the given key.

const item = await idbx.get(store, 1);

idbx.getAll(store: IDBObjectStore, query?: IDBValidKeyRange)

Returns a promise that resolves to all items in the store.

const items = await idbx.getAll(store);

idbx.getAllKeys(store: IDBObjectStore, query?: IDBValidKeyRange)

Returns a promise that resolves to all keys in the store.

const keys = await idbx.getAllKeys(store);

idbx.getKey(store: IDBObjectStore, key: IDBValidKey)

Returns a promise that resolves to the key of the item with the given key.

const key = await idbx.getKey(store, 1);

idbx.clear(store: IDBObjectStore)

Clears the store. Returns a promise that resolves to undefined.

await idbx.clear(store);

idbx.count(store: IDBObjectStore, key?: IDBValidKey)

Returns a promise that resolves to the number of items in the store.

const count = await idbx.count(store);

idbx.batch(db: IDBDatabase, commands: IDBXCommand[], mode?: IDBTransactionMode)

Runs multiple commands in a single transaction. Returns a promise that resolves to the result of the last command.

const result = await idbx.batch(db, [
  { command: "add", store: "store", item: { name: "foo" } },
  { command: "add", store: "store", item: { name: "bar" } },
  { command: "getAll", store: "store" },
], "readwrite");

idbx.openCursor(store: IDBObjectStore, query?: IDBValidKeyRange)

Returns a promise that resolves to an IDBCursor instance.

const cursor = idbx.openCursor(store);

for await (const item of cursor) {
  console.log(item);
}

idbx.openKeyCursor(store: IDBObjectStore, query?: IDBValidKeyRange)

Returns a promise that resolves to an IDBCursor instance.

const cursor = idbx.openKeyCursor(store);

for await (const key of cursor) {
  console.log(key);
}