lin-credible / db64

Practical IndexedDB API

db64

A Practical IndexedDB API

A more practical alternative to localStorage. db64 supports all major browsers.

db64

• Promise based API
• Set and get single or multiple entries
• Delete single, multiple or all entries
• No versioning
• 2.47KB minified

E.g.

import db64 from './db64.js'

try {
  // First create a database with stores
  await db64.create('Games', ['Super Nintendo', 'Gameboy'])

  // Assing a variable for modifying a store
  const snes = db64.use('Games', 'Super Nintendo')

  // Set multiple entries into Super Nintendo
  await snes.setEntries({ adventure: 'Mario World', rpg: 'Zelda', fighting: 'Street Fighter II' })

  // Get multiple entries from Super Nintendo
  await snes.getEntries(['adventure', 'fighting']) // { adventure: 'Mario Wrold', fighting: 'Street Fighter II' }

  // Delete an existing db 
  await db64.delete('Games')
...

Why IndexedDB, why not localStorage?

• Better performance
• Asynchronous (localStorage is blocking)
• Larger storage quota (localStorage is capped at 5MB)
• Reliable (no type coercion)
• Uses the structuredClone algorithm

Practical challenges when using IndexedDB

• It's event driven, without promises
• It was designed to encourage versioning, which is not necessary for the majority of projects
• The API is considered as (low level) and can be challenging as a replacement for localStorage
• Removing databases and stores is not straight forward nor necessary, and usually requires versioning

Install

npm i db64

Import

import db64 from 'db64.js'    // ES (native)
// or
import db64 from 'db64'       // ES
// or
const db64 = require('db64')  // CommonJS

Create a database with stores (string, array)

await db64.create('game-consoles', ['n64', 'ps5', 'dreamcast', 'xbox-360'])

Use a store (string, string)

const n64 = db64.use('game-consoles', 'n64')

Set an entry (IDB type, IDB type) See structured clone algorithm for supported types

await n64.set(5, 'Super Mario 64')

Set multiple entries (object | array)

await n64.setEntries({fps: 'GoldenEye 007', space: 'Star Fox 64', adventure: 'Banjo-Kazooie'})
await n64.setEntries(['Wave Race 64', 'The Legend of Zelda'])

Get an entry (IDB type)

const fps = await n64.get('fps') // GoldenEye 007

Get multiple entries (object | array)

const rareware = await n64.getEntries(['fps', 'adventure', 5]) // {fps: 'GoldenEye 007', adventure: 'Banjo-Kazooie', 0: 'Super Mario 64'}

Delete an entry (IDB type | array)

await n64.delete(1)  // Deletes 'The Legend of Zelda'

Delete multiple entries

await n64.delete(['adventure', 0])  // Deletes 'Banjo-Kazooie' and 'Super Mario 64'

Clear a store (string, string)

await db64.clear('game-consoles', 'n64') // All data in n64 is deleted

Delete a DB (string)

await db64.delete('game-consoles') // game-consoles is deleted

Why db64 opts out of deleting object stores

We are avoiding versioning to keep your life simple. Deleting an existing object stores in IndexedDB triggers a version change. (Whilst compaction may optimise, it doesn't ensure the removal of unwanted data)

Here's the db64 workflow:

1. Initialise by creating a DB with stores or multiple DBs with stores.

   • (You won't be able to add stores to an existing DB later, unless you delete the DB in question. This is by design)

2. Use a DB.

   • (You can make multiple transactions concurrently for multiple DBs, or stores)

3. Set, get and clear data.

4. Manage the lifecycle of DB deletion and re-creation:

   • When data cannot be retrieved from the user's IndexedDB
   • When there's an error
     • Data corruption
     • Quota exceeded
     • General errors
   • When in the future you decide to add more stores at initialisation
   • When you want to remove stores, especially for data protection

It's important to consider step 4, if not you may leave users stuck because everything looks fine on your computer. Step 4 isn't specific to IndexedDB, it also applies to localStorage but it's more prevalent with IndexedDB as there's a higher risk of the application breaking if you decide to make chages to the codebase in the future.

If you do require versioning consider using idb. If you're not building a progressive web app (PWA) you probably don't need versioning.

Contributors

Don't hesitate just contribute, it's a tiny library we will figure it out.

If you want to edit ./README.md edit ./src/_readme.md which will update ./README.md when node create-distribution.js is called. This is to keep the minified size accurate.

---

MIT © Julien Etienne 2023