idb-easier

Overview

idb-easier is a simple wrapper for idb -- which is itself a wrapper for making indexedDB more usable.

Installation

npm i idb-easier

OR

bun i idb-easier

Usage

my-ui-component.ts

import {
  IdbConfig,
  idbConnectDatabase as useDB,
  idbDeleteDatabase,
  idbGet,
  idbSet
} from 'idb-easier'

// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Define indexedDB Configuration
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
const IDB_CONFIG: IdbConfig = Object.freeze({
  dbName: 'myDatabase',
  storeName: 'myStore',

  // OPTIONAL key
  //
  // indexConfig is an optional config key, included
  // if you define an index.
  //
  // Refer to `idb` documentation for more details.
  indexConfig: {
    indexName: 'timestamp',
    keyPath: 'id',
    autoIncrement: true,
  },
})

// The `db` object is returned to optionally give the developer
// direct access to `idb` package's db methods not included/wrapped
// in the this `idb-easier` package.
const db = await useDB(IDB_CONFIG: IdbConfig).catch((err) => {
  console.trace(err.message)
})

await idbSet(myData, 'my-key')

const data = await idbGet('my-key')

Add Record

idbSet() is used in the previous Usage section; it's a straighforward example, passing a value and a key.

There is another context in which idbSet() can be called.

// If the db was configured to use an index with autoIncrement
// set to true, only the value is a required argument.
//
// The key will be auto-generated.
const autoGeneratedKey = await idbSet(myData)

// If the db has an index and autoIncrement was set to false, then
// the developer must supply the key, same as if no db index:
await idbSet(myData, 'user-defined-key')

Delete Database

// Pass in dbName and catch error if delete fails.
await idbDeleteDatabase(IDB_CONFIG.dbName).catch((err) => {
  console.trace(err.message)
})

// If delete has no errors, db no longer exists. idbConnectDatabase()
// must be called again to use the idbSet() and idbGet() methods.

Delete a Record in the Store

await idbDeleteRecord(IDB_CONFIG.storeName, 'my-key')

Get All Records Filtered By Key Prefix

Retrieve all records in which the DB keys match the prefix string.

Limitations

• prefix only, no suffix matching
• matching is case sensitive

// The database's keys have country code prefixes:
//
//   'jp:companyZ'
//   'sg:companyA'
//   'tw:companyL'
//   'sg:companyB'
//   'sg:companyC'
const singaporeanItems = await idbGetAllPrefixFilter(IDB_CONFIG.storeName, 'sg:')

singaporeanItems is an array of 3 items that match the 'sg:' prefix argument.

(Using this colon delimited key format is the same as you'd use in valkey or redis.)

Credits

Gerry Gold

January 2026

Have fun!