fake-indexeddb

What is fake-indexeddb?

The fake-indexeddb npm package is a mock implementation of the IndexedDB API, which is useful for testing and development purposes. It allows developers to simulate IndexedDB operations without relying on a real browser environment.

What are fake-indexeddb's main functionalities?

Creating a Database

This feature allows you to create a new IndexedDB database and an object store within it. The code sample demonstrates how to open a database, handle the upgrade event to create an object store, and log the success event.

const { indexedDB } = require('fake-indexeddb');
const request = indexedDB.open('test-db', 1);
request.onupgradeneeded = function(event) {
  const db = event.target.result;
  db.createObjectStore('store', { keyPath: 'id' });
};
request.onsuccess = function(event) {
  const db = event.target.result;
  console.log('Database created:', db);
};

Adding Data to Object Store

This feature allows you to add data to an object store within the IndexedDB database. The code sample demonstrates how to open a database, create a transaction, add data to the object store, and log the completion of the transaction.

const { indexedDB } = require('fake-indexeddb');
const request = indexedDB.open('test-db', 1);
request.onsuccess = function(event) {
  const db = event.target.result;
  const transaction = db.transaction('store', 'readwrite');
  const store = transaction.objectStore('store');
  store.add({ id: 1, name: 'John Doe' });
  transaction.oncomplete = function() {
    console.log('Data added');
  };
};

Retrieving Data from Object Store

This feature allows you to retrieve data from an object store within the IndexedDB database. The code sample demonstrates how to open a database, create a transaction, retrieve data from the object store, and log the retrieved data.

const { indexedDB } = require('fake-indexeddb');
const request = indexedDB.open('test-db', 1);
request.onsuccess = function(event) {
  const db = event.target.result;
  const transaction = db.transaction('store', 'readonly');
  const store = transaction.objectStore('store');
  const getRequest = store.get(1);
  getRequest.onsuccess = function() {
    console.log('Data retrieved:', getRequest.result);
  };
};

Other packages similar to fake-indexeddb

indexeddbshim

The indexeddbshim package is a polyfill that provides a full implementation of the IndexedDB API for browsers that do not support it natively. Unlike fake-indexeddb, which is primarily for testing, indexeddbshim aims to provide a real IndexedDB experience in environments where it is not available.

localforage

LocalForage is a library that provides a simple API for offline storage, using IndexedDB, WebSQL, or localStorage under the hood. It abstracts away the differences between these storage mechanisms, making it easier to use. While fake-indexeddb is focused on testing, LocalForage is designed for actual application use.

dexie

Dexie is a wrapper library for IndexedDB that provides a more developer-friendly API and additional features like versioning and schema management. It is designed for real-world use in applications, whereas fake-indexeddb is intended for testing purposes.

README

fake-indexeddb

This is a pure JS in-memory implementation of the IndexedDB 2.0 API (which technically still is a draft, but is probably not going to substantially change). Its main utility is for testing IndexedDB-dependent code in Node.js.

Installation

npm install fake-indexeddb

Use

Functionally, it works exactly like IndexedDB except data is not persisted to disk.

Import fake-indexeddb/global to have it create (or overwrite) all the default IndexedDB variables like indexedDB, IDBKeyRange, etc.

var indexedDB = require("fake-indexeddb");
var IDBKeyRange = require("fake-indexeddb/lib/FDBKeyRange");

var request = indexedDB.open("test", 3);
request.onupgradeneeded = function () {
    var db = request.result;
    var store = db.createObjectStore("books", {keyPath: "isbn"});
    store.createIndex("by_title", "title", {unique: true});

    store.put({title: "Quarry Memories", author: "Fred", isbn: 123456});
    store.put({title: "Water Buffaloes", author: "Fred", isbn: 234567});
    store.put({title: "Bedrock Nights", author: "Barney", isbn: 345678});
}
request.onsuccess = function (event) {
    var db = event.target.result;

    var tx = db.transaction("books");

    tx.objectStore("books").index("by_title").get("Quarry Memories").addEventListener("success", function (event) {
        console.log("From index:", event.target.result);
    });
    tx.objectStore("books").openCursor(IDBKeyRange.lowerBound(200000)).onsuccess = function (event) {
        var cursor = event.target.result;
        if (cursor) {
            console.log("From cursor:", cursor.value);
            cursor.continue();
        }
    };
    tx.oncomplete = function () {
        console.log("All done!");
    };
};

When importing individual classes directly (like var IDBKeyRange = require("fake-indexeddb/lib/FDBKeyRange"); above), variable names of all the objects are like the normal IndexedDB ones except with F replacing I, e.g. FDBIndex instead of IDBIndex.

Quality

Here's a comparison of fake-indexeddb and real browser IndexedDB implementations on the W3C IndexedDB test suite as of April 28, 2017:

Implementation	Percentage of files that pass completely
Firefox 53	93%
Chrome 57	92%
fake-indexeddb 2.0	88%
Safari 10	83%
Edge 14	59%

For browsers, I ran http://w3c-test.org/tools/runner/index.html and counted the passes. For fake-indexeddb, I ran npm run test-w3c.

88% is pretty good, right? Consider that some of the tests fail for stupid reasons with fake-indexeddb, because it runs in Node.js where failure is guaranteed for tests involving browser APIs like Web Workers. There are definitley still some weak points of fake-indexeddb, all described in src/test/web-platform-tests/run-all.js. Your app will probably run fine, though.

Potential applications:

1. Use as a mock database in unit tests.

2. Use the same API in Node.js and in the browser.

3. Support IndexedDB in old or crappy browsers.

4. Somehow use it within a caching layer on top of IndexedDB in the browser, since IndexedDB can be kind of slow.

5. Abstract the core database functions out, so what is left is a shell that allows the IndexedDB API to easily sit on top of many different backends.

6. Serve as a playground for experimenting with IndexedDB.

License

Apache 2.0

Changelog

2.0.0 (2017-04-29)

• Fully implements the IndexedDB 2.0 API (which technically still is a draft, but is probably not going to substantially change).
• Ported to TypeScript, which hopefully means less bugs.
• Dynamically runs the W3C web-platform-tests rather than using manually ported tests. This means it's easy to run new tests, and the tests written since the original release of fake-indexeddb turned up several minor bugs which have now been fixed. See npm run test-w3c.