fake-indexeddb 6.x

Complete instructions

Verified against fake-indexeddb@6.2.5 on 2026-09-08. 3 of 3 examples executed.

fake-indexeddb ^6.0.0

What this package provides

fake-indexeddb is a pure-JavaScript, in-memory implementation of IndexedDB. Data is not persisted to disk. Version 6 requires Node.js >=18 and a native or polyfilled structuredClone.

The package is useful when code expects browser IndexedDB but is running under Node.js. It can either install its implementation on the global object or provide IndexedDB objects for explicit use.

Global setup

Import fake-indexeddb/auto before code that uses the global IndexedDB names. This installs the fake indexedDB implementation and related globals.

import "fake-indexeddb/auto";
import assert from "node:assert/strict";

const request = indexedDB.open("global-example", 1);

await new Promise<void>((resolve, reject) => {
  request.onupgradeneeded = () => {
    const db = request.result;
    const store = db.createObjectStore("books", { keyPath: "isbn" });
    store.createIndex("by_title", "title", { unique: true });
    store.put({ isbn: 123456, title: "Quarry Memories", author: "Fred" });
  };

  request.onsuccess = () => {
    const db = request.result;
    const read = db.transaction("books").objectStore("books").get(123456);
    read.onsuccess = () => {
      assert.deepEqual(read.result, {
        isbn: 123456,
        title: "Quarry Memories",
        author: "Fred",
      });
      db.close();
      resolve();
    };
    read.onerror = () => reject(read.error);
  };
  request.onerror = () => reject(request.error);
});

auto is the global-installing entry point. Import it before wrappers such as Dexie or other code that reads the global IndexedDB implementation.

Explicit imports

For a plain script that does not want global setup, import the objects from the package root. The root exports indexedDB, IDBFactory, IDBKeyRange, IDBCursor, IDBCursorWithValue, IDBDatabase, IDBIndex, IDBObjectStore, IDBOpenDBRequest, IDBRequest, IDBTransaction, and IDBVersionChangeEvent. The default export is the fake factory as well.

import assert from "node:assert/strict";
import { indexedDB, IDBKeyRange } from "fake-indexeddb";

const request = indexedDB.open("explicit-example", 1);

await new Promise<void>((resolve, reject) => {
  request.onupgradeneeded = () => {
    request.result.createObjectStore("numbers");
  };

  request.onsuccess = () => {
    const db = request.result;
    const store = db.transaction("numbers", "readwrite").objectStore("numbers");
    store.put("low", 10);
    store.put("high", 20);

    const readTransaction = db.transaction("numbers");
    const cursorRequest = readTransaction
      .objectStore("numbers")
      .openCursor(IDBKeyRange.lowerBound(15));

    cursorRequest.onsuccess = () => {
      assert.equal(cursorRequest.result.key, 20);
      db.close();
      resolve();
    };
    cursorRequest.onerror = () => reject(cursorRequest.error);
  };
  request.onerror = () => reject(request.error);
});

Use IDBKeyRange from this package with the fake implementation. Do not assume the browser's global IDBKeyRange is present when using explicit imports.

Resetting in-memory state

The database is in memory. To start with a fresh factory and no previous database state, construct a new IDBFactory and replace the global factory when using the auto surface.

import "fake-indexeddb/auto";
import assert from "node:assert/strict";
import { IDBFactory } from "fake-indexeddb";

const first = indexedDB.open("reset-example", 1);
await new Promise<void>((resolve, reject) => {
  first.onupgradeneeded = () => {
    first.result.createObjectStore("items");
  };
  first.onsuccess = () => {
    first.result.close();
    resolve();
  };
  first.onerror = () => reject(first.error);
});

globalThis.indexedDB = new IDBFactory();

const second = indexedDB.open("reset-example", 1);
await new Promise<void>((resolve, reject) => {
  second.onupgradeneeded = () => {
    assert.equal(second.result.objectStoreNames.contains("items"), false);
    second.result.close();
    resolve();
  };
  second.onerror = () => reject(second.error);
});

Resetting replaces the factory; it does not persist or reload data from disk.

Common version-6 mistakes

• Using only import "fake-indexeddb/auto" when explicit objects are needed: auto installs globals. For dependency injection or a script that avoids globals, import indexedDB and the relevant classes from fake-indexeddb.
• Using the old root CommonJS shape: CommonJS is supported, but older examples may use a v4-era default shape. The documented current destructuring form is const { indexedDB, IDBKeyRange } = require("fake-indexeddb"); older code may instead need require("fake-indexeddb").default.
• Expecting persistence: this implementation is in memory only. Create a new IDBFactory when a fresh state is required.
• Expecting the v5 structuredClone polyfill: v5 removed that polyfill, and v6 requires native or polyfilled structuredClone in environments such as jsdom. A supported polyfill setup is import "core-js/stable/structured-clone" before import "fake-indexeddb/auto".
• Assuming old error behavior: v6 uses DOMException rather than ordinary errors for IndexedDB errors.
• Running under an unsupported Node version: v6 declares Node.js >=18.
• Putting runner globals in a standalone script: describe, it, and expect are not provided by this package. Direct scripts should use IndexedDB's request and transaction events, as in the examples.

Other entry points

The package publishes fake-indexeddb/auto and individual fake-indexeddb/lib/* modules, including modules for cursors, factories, key ranges, object stores, and transactions. Both import and require conditions are provided.

The package also exposes the package-specific forceCloseDatabase helper for forcibly closing a database. Its behavior and usage are not demonstrated by the supplied research, so use it only where the package's own API documentation or source has been consulted.

Not covered

This skill does not cover the complete IndexedDB API semantics, every individual exported class or lib/* subpath, the detailed behavior of forceCloseDatabase, jsdom configuration beyond the structuredClone requirement, Jest configuration beyond loading fake-indexeddb/auto, or integration-specific setup for wrappers such as Dexie. It also does not cover persistence, since this package does not provide it.