@lr0pb/idb NPM

📦 IDB.js

Lightweight high-level promise-based wrapper for fast access to IndexedDB API. With React integration ⚛️

Table of content

Usage

To start using IDB.js install it from npm

npm i @lr0pb/idb

Create database

Provide name, version and stores which will be initialized alongside with database

import { IDB } from '@lr0pb/idb';

const db = new IDB('library', 1, [
  { name: 'books', index: { keyPath: 'id' } },
  { name: 'authors', index: { keyPath: 'name' } },
  { name: 'manufacturers', index: { autoIncrement: true } },
  ...
]);

stores is an array of StoreDefinition objects: name of store and index object, which described how should be indexed data inside the store

index is a IDBObjectStoreParameters object, which is a part of original IndexedDB API

You can also provide optional fourth argument options described in new IDB Ref

Delete store

Delete stores by upgrading database version and remove relevant StoreDefinition objects from stores array

const db = new IDB('library', 2, [
  { name: 'books', index: { keyPath: 'id' } },
  { name: 'authors', index: { keyPath: 'name' } }
]);
// 'manufacturers' store was deleted at all, it cannot be longer accessed

IDB methods

REST-like methods to work with data:

Additional helpful methods:

Integrate with React:

Examples

Set items to store

[Ref] Add item to store via db.set(store, item | items[]) method

async function addAuthor(books) {
  await db.set('authors', {
    name: 'Agatha Christie',
    books: []
  });

  await db.set('authors', [
    author1, author2, ...
  ]);
}

Get items from store

[Ref] Get one or more items by key via db.get(store, key | keys[]) and all store items via db.getAll(store)

async function renderAuthor() {
  const author = await db.get('author', 'Agatha Christie');
  // {
  //   name: 'Agatha Christie',
  //   books: [12345, 67890, ...],
  //   ...
  // }
  ...
  const authorsBooks = await db.get('books', author.books);
  // [
  //   {
  //     id: 12345,
  //     title: `Hercule Poirot's Christmas`,
  //     ...
  //   },
  //   {
  //     id: 67890,
  //     title: `Murder on the Orient Express`,
  //     ...
  //   },
  //   ...
  // ]
}

async function renderAllBooks() {
  const books = await db.getAll('books');
  for (let book of books) {
    renderBook(book);
  }
}

Additionally, you can set DataReceivingCallback callback for call it every time new item receives from database

async function renderBooksProgressive() {
  await db.getAll('books', (book) => {
    renderBook(book);
  });
}

DataReceivingCallback function passed to db.getAll must be sync

Update item in store

[Ref] Use db.update(store, key | keys[], UpdateCallback) to update one or more items

async function addBookToAuthor(book) {
  await db.update('authors', book.author, async (author) => {
    // this callback function receives item object and you should apply changes directly to this object
    author.books.push(book.id);
    await sendAnalytics();
  });
}

UpdateCallback function passed to db.update can be async If you provide multiple keys, UpdateCallback will be called for each received item. If you want to use separate UpdateCallback functions for each item, provide array of UpdateCallback functions same length as keys array length

Delete item from store

[Ref] Delete one or more items by key via db.delete(store, key | keys[]) and clear all store entries via db.deleteAll(store)

async function deleteBooks() {
  await db.delete('books', 12345);
  await db.delete('books', [
    67890, 34567, ...
  ]);
  await db.deleteAll('author'); // authors store is still available but have no items
}

Check is store contain item

[Ref] Check if store have certain items via db.has(store, key | keys[] | void) or get count of all items in the store by not passing key argument

async function addBook() {
  const book = {
    id: 12345,
    title: `Hercule Poirot's Christmas`,
    ...
  };
  await db.set('books', book);
  const isBookSaved = await db.has('books', book.id); // true
  const booksCount = await db.has('books'); // 1
}

Listen for store updates

[Ref] You can register multiple listeners to spot changes that happened in the store with db.onDataUpdate(store, StoreUpdatesListener). These callbacks called after actual operation with data in order to time they are registered. To unregister callback, call returned from db.onDataUpdate UnregisterListener function

async signForUpdates() {
  const unregister = await db.onDataUpdate('books', async ({store, type, item}) => {
    // item argument not presented when it was a deleting operation
    if (type === 'set' && isNewBook(item)) {
      await notifyUserAboutNewBookAdded(item);
    }
  });
  ...
  unregister();
}