IDB

A clean, promise-based wrapper around the IndexedDB API. Store structured data client-side with zero boilerplate — open a database, define stores, and start reading and writing immediately through Aura.idb.

Quick Start

Open a database, insert a record, and read it back in just a few lines.

js
// Open a database with one store
await Aura.idb.open('myApp', 1, [
  { name: 'users', keyPath: 'id', autoIncrement: true }
]);

// Insert a record
const key = await Aura.idb.set('users', { name: 'Alice', role: 'admin' });

// Read it back
const user = await Aura.idb.get('users', key);
console.log(user); // { id: 1, name: 'Alice', role: 'admin' }

open()

Opens or creates an IndexedDB database. If the database does not exist or the version is higher than the current version, object stores are created according to the stores configuration.

Aura.idb.open(name: string, version: number, stores: IDBStoreConfig[]): Promise<void>

Param	Type	Description
name	string	Database name.
version	number	Schema version number. Increment to trigger upgrades.
stores	IDBStoreConfig[]	Array of store definitions to create on upgrade.

Each IDBStoreConfig object accepts:

Property	Type	Description
name	string	Object store name (required).
keyPath	string	Primary key path. Defaults to `"id"`.
autoIncrement	boolean	Auto-generate keys. Defaults to `true`.
indexes	Array	Optional indexes. Each entry: `{ name, keyPath, unique? }`.

js
await Aura.idb.open('shop', 1, [
  {
    name: 'products',
    keyPath: 'sku',
    autoIncrement: false,
    indexes: [
      { name: 'byCategory', keyPath: 'category' },
      { name: 'byPrice', keyPath: 'price' }
    ]
  },
  {
    name: 'orders',
    indexes: [
      { name: 'byEmail', keyPath: 'email', unique: false }
    ]
  }
]);

get()

Retrieves a single record by its primary key. Returns undefined if no record matches.

Aura.idb.get<T>(store: string, key: IDBValidKey): Promise<T | undefined>

Param	Type	Description
store	string	Object store name.
key	IDBValidKey	Primary key of the record to fetch.

js
const user = await Aura.idb.get('users', 1);

if (user) {
  console.log(user.name);
} else {
  console.log('User not found');
}

getAll()

Returns every record in an object store as an array.

Aura.idb.getAll<T>(store: string): Promise<T[]>

Param	Type	Description
store	string	Object store name.

js
const allUsers = await Aura.idb.getAll('users');
console.log(`Found ${allUsers.length} users`);

set()

Inserts a new record or updates an existing one (upsert via put). Returns the primary key of the written record.

Aura.idb.set<T>(store: string, value: T): Promise<IDBValidKey>

Param	Type	Description
store	string	Object store name.
value	T	The record to write. Must include the key property if `autoIncrement` is `false`.

js
// Insert (auto-increment generates the key)
const id = await Aura.idb.set('users', { name: 'Bob', role: 'viewer' });

// Update an existing record
await Aura.idb.set('users', { id: id, name: 'Bob', role: 'editor' });

setMany()

Writes multiple records in a single transaction. More efficient than calling set() in a loop because all writes share one transaction.

Aura.idb.setMany<T>(store: string, values: T[]): Promise<void>

Param	Type	Description
store	string	Object store name.
values	T[]	Array of records to insert or update.

js
await Aura.idb.setMany('products', [
  { sku: 'A1', name: 'Widget',  price: 9.99,  category: 'tools' },
  { sku: 'A2', name: 'Gadget',  price: 24.99, category: 'electronics' },
  { sku: 'A3', name: 'Gizmo',   price: 14.50, category: 'tools' },
]);

delete()

Removes a single record by its primary key.

Aura.idb.delete(store: string, key: IDBValidKey): Promise<void>

Param	Type	Description
store	string	Object store name.
key	IDBValidKey	Primary key of the record to delete.

js
await Aura.idb.delete('users', 3);

clear()

Removes all records from an object store. The store itself is preserved.

Aura.idb.clear(store: string): Promise<void>

Param	Type	Description
store	string	Object store name.

js
await Aura.idb.clear('users');
console.log(await Aura.idb.count('users')); // 0

count()

Returns the total number of records in an object store.

Aura.idb.count(store: string): Promise<number>

Param	Type	Description
store	string	Object store name.

js
const total = await Aura.idb.count('products');
console.log(`${total} products in stock`);

query()

Queries records through an index. Optionally pass an IDBKeyRange to narrow results, or a single key value to match exactly.

Aura.idb.query<T>(store: string, indexName: string, range?: IDBKeyRange | IDBValidKey): Promise<T[]>

Param	Type	Description
store	string	Object store name.
indexName	string	Name of the index to query.
range	IDBKeyRange \| IDBValidKey	Optional. A key range or exact key to filter by. Omit to return all records via the index.

js
// Exact match — all products in the 'tools' category
const tools = await Aura.idb.query('products', 'byCategory', 'tools');

// Range — products priced between 10 and 50
const midRange = await Aura.idb.query(
  'products',
  'byPrice',
  IDBKeyRange.bound(10, 50)
);

// All records via the index (no range)
const all = await Aura.idb.query('products', 'byPrice');

each()

Iterates over every record in a store using a cursor. Return false from the callback to stop iteration early.

Aura.idb.each<T>(store: string, callback: (value: T, key: IDBValidKey) => void | false): Promise<void>

Param	Type	Description
store	string	Object store name.
callback	(value: T, key: IDBValidKey) => void \| false	Called for each record. Return `false` to stop early.

js
// Log every user
await Aura.idb.each('users', (user, key) => {
  console.log(key, user.name);
});

// Stop after finding the first admin
let admin;
await Aura.idb.each('users', (user) => {
  if (user.role === 'admin') {
    admin = user;
    return false; // stop iteration
  }
});

close()

Closes the database connection. After calling this, any read or write operation will throw until open() is called again.

Aura.idb.close(): void

js
Aura.idb.close();
console.log(Aura.idb.isOpen); // false

destroy()

Closes the connection and permanently deletes the entire database. This cannot be undone.

Aura.idb.destroy(): Promise<void>

js
// Nuke everything — use with care
await Aura.idb.destroy();

isOpen

A read-only boolean getter that indicates whether a database connection is currently active.

Aura.idb.isOpen: boolean

js
if (!Aura.idb.isOpen) {
  await Aura.idb.open('myApp', 1, [
    { name: 'settings' }
  ]);
}