idb-keyval

What is idb-keyval?

The idb-keyval npm package is a simple key-value store backed by IndexedDB. It provides a straightforward API for storing, retrieving, and managing data in the browser's IndexedDB, making it easier to work with compared to the native IndexedDB API.

What are idb-keyval's main functionalities?

Set a value

This feature allows you to store a value in the IndexedDB with a specified key. The code sample demonstrates how to set a value 'value' with the key 'key'.

import { set } from 'idb-keyval';

set('key', 'value').then(() => console.log('Value set!'));

Get a value

This feature allows you to retrieve a value from the IndexedDB using a specified key. The code sample demonstrates how to get the value associated with the key 'key'.

import { get } from 'idb-keyval';

get('key').then(val => console.log('Value:', val));

Delete a value

This feature allows you to delete a value from the IndexedDB using a specified key. The code sample demonstrates how to delete the value associated with the key 'key'.

import { del } from 'idb-keyval';

del('key').then(() => console.log('Value deleted!'));

Clear all values

This feature allows you to clear all values from the IndexedDB. The code sample demonstrates how to clear all stored values.

import { clear } from 'idb-keyval';

clear().then(() => console.log('All values cleared!'));

Get all keys

This feature allows you to retrieve all keys from the IndexedDB. The code sample demonstrates how to get all keys stored in the database.

import { keys } from 'idb-keyval';

keys().then(keys => console.log('Keys:', keys));

Other packages similar to idb-keyval

localforage

LocalForage is a fast and simple storage library for JavaScript. It improves the offline experience of your web app by using asynchronous storage (IndexedDB or WebSQL) with a simple, localStorage-like API. Compared to idb-keyval, LocalForage offers more flexibility in terms of storage backends and a more extensive API.

dexie

Dexie is a minimalistic wrapper for IndexedDB that provides a more powerful and developer-friendly API. It supports advanced querying, transactions, and versioning. Compared to idb-keyval, Dexie is more feature-rich and suitable for complex use cases involving IndexedDB.

idb

The idb library is a small, well-tested library that makes working with IndexedDB more pleasant. It provides a promise-based API and simplifies many common tasks. Compared to idb-keyval, idb offers a more comprehensive API for interacting with IndexedDB, while idb-keyval focuses on simplicity and ease of use.

README

IDB-Keyval

This is a super-simple-small promise-based keyval store implemented with IndexedDB, largely based on async-storage by Mozilla.

localForage offers similar functionality, but supports older browsers with broken/absent IDB implementations. Because of that, it's 7.4k, whereas idb-keyval is < 600 bytes. Also, it's tree-shaking friendly, so you'll probably end up using fewer than 500 bytes. Pick whichever works best for you!

This is only a keyval store. If you need to do more complex things like iteration & indexing, check out IDB on NPM (a little heavier at 1.7k). The first example in its README is how to recreate this library.

Usage

set:

import { set } from 'idb-keyval';

set('hello', 'world');
set('foo', 'bar');

Since this is IDB-backed, you can store anything structured-clonable (numbers, arrays, objects, dates, blobs etc).

All methods return promises:

import { set } from 'idb-keyval';

set('hello', 'world')
  .then(() => console.log('It worked!'))
  .catch(err => console.log('It failed!', err));

get:

import { get } from 'idb-keyval';

// logs: "world"
get('hello').then(val => console.log(val));

If there is no 'hello' key, then val will be undefined.

keys:

import { keys } from 'idb-keyval';

// logs: ["hello", "foo"]
keys().then(keys => console.log(keys));

del:

import { del } from 'idb-keyval';

del('hello');

clear:

import { clear } from 'idb-keyval';

clear();

Custom stores:

By default, the methods above use an IndexedDB database named keyval-store and an object store named keyval. You can create your own store, and pass it as an additional parameter to any of the above methods:

import { Store, set } from 'idb-keyval';

const customStore = new Store('custom-db-name', 'custom-store-name');
set('foo', 'bar', customStore);

That's it!

Installing

Via npm + webpack/rollup

npm install idb-keyval

Now you can require/import idb-keyval:

import { get, set } from 'idb-keyval';

If you're targeting older versions of IE, you may have more luck with:

const idb = require('idb-keyval/dist/idb-keyval-cjs-compat.min.js');

Via <script>

• dist/idb-keyval.mjs is a valid JS module.
• dist/idb-keyval-iife.js can be used in browsers that don't support modules. idbKeyval is created as a global.
• dist/idb-keyval-iife.min.js As above, but minified.
• dist/idb-keyval-iife-compat.min.js As above, but works in older browsers such as IE 10.
• dist/idb-keyval-amd.js is an AMD module.
• dist/idb-keyval-amd.min.js As above, but minified.

These built versions are also available on jsDelivr, e.g.:

<script src="https://cdn.jsdelivr.net/npm/idb-keyval@3/dist/idb-keyval-iife.min.js"></script>
<!-- Or in modern browsers: -->
<script type="module">
  import { get, set } from 'https://cdn.jsdelivr.net/npm/idb-keyval@3/dist/idb-keyval.mjs';
</script>

Updating from 2.x

2.x exported an object with methods:

// This no longer works in 3.x
import idbKeyval from 'idb-keyval';

idbKeyval.set('foo', 'bar');

Whereas in 3.x you import the methods directly:

import { set } from 'idb-keyval';

set('foo', 'bar');

This is better for minification, and allows tree shaking.