or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

database-management.mdevents-utilities.mdindex.mdkey-ranges.mdobject-stores.mdtransactions-cursors.md
tile.json

tessl/npm-fake-indexeddb

A pure JS in-memory implementation of the IndexedDB API for testing IndexedDB-dependent code in Node.js environments

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/fake-indexeddb@6.2.x

To install, run

npx @tessl/cli install tessl/npm-fake-indexeddb@6.2.0

index.mddocs/

fake-indexeddb

fake-indexeddb is a pure JavaScript in-memory implementation of the IndexedDB API specifically designed for testing IndexedDB-dependent code in Node.js environments. It provides complete compatibility with the W3C IndexedDB specification while running entirely in memory without disk persistence, making it ideal for unit testing, continuous integration, and development scenarios.

Package Information

  • Package Name: fake-indexeddb
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install --save-dev fake-indexeddb

Core Imports

Automatic Global Setup (Recommended)

import "fake-indexeddb/auto";

// Now use indexedDB, IDBDatabase, etc. as globals
const request = indexedDB.open("test", 1);

Named Imports

import {
  indexedDB,
  IDBCursor,
  IDBCursorWithValue,
  IDBDatabase,
  IDBFactory,
  IDBIndex,
  IDBKeyRange,
  IDBObjectStore,
  IDBOpenDBRequest,
  IDBRequest,
  IDBTransaction,
  IDBVersionChangeEvent,
} from "fake-indexeddb";

CommonJS

const {
  indexedDB,
  IDBDatabase,
  IDBKeyRange,
  // ... other exports
} = require("fake-indexeddb");

Individual Component Imports

import FDBDatabase from "fake-indexeddb/lib/FDBDatabase";
import FDBKeyRange from "fake-indexeddb/lib/FDBKeyRange";
import forceCloseDatabase from "fake-indexeddb/lib/forceCloseDatabase";

Basic Usage

import "fake-indexeddb/auto";

// Open database with version
const request = indexedDB.open("testdb", 3);

request.onupgradeneeded = function () {
  const db = request.result;
  
  // Create object store with key path
  const store = db.createObjectStore("books", { keyPath: "isbn" });
  
  // Create index for searching
  store.createIndex("by_title", "title", { unique: true });
  
  // Add initial data
  store.put({ title: "JavaScript Guide", author: "Mozilla", isbn: 123456 });
  store.put({ title: "TypeScript Handbook", author: "Microsoft", isbn: 234567 });
};

request.onsuccess = function (event) {
  const db = event.target.result;
  
  // Start transaction 
  const tx = db.transaction("books", "readonly");
  const store = tx.objectStore("books");
  
  // Query by index
  store.index("by_title").get("JavaScript Guide").onsuccess = function (event) {
    console.log("Found book:", event.target.result);
  };
  
  // Cursor iteration with key range
  store.openCursor(IDBKeyRange.lowerBound(200000)).onsuccess = function (event) {
    const cursor = event.target.result;
    if (cursor) {
      console.log("Book:", cursor.value);
      cursor.continue();
    }
  };
  
  tx.oncomplete = function () {
    console.log("Transaction completed");
    db.close();
  };
};

Architecture

fake-indexeddb implements the complete IndexedDB specification with several key components:

  • Factory Pattern: IDBFactory (accessed as indexedDB) creates and manages database connections
  • Database Layer: IDBDatabase represents database connections with object stores and transactions
  • Storage Layer: IDBObjectStore and IDBIndex provide data storage and indexing capabilities
  • Transaction Management: IDBTransaction ensures ACID properties and isolation
  • Cursor System: IDBCursor and IDBCursorWithValue enable efficient data iteration
  • Event System: Full DOM-compatible event handling with success, error, and upgrade events
  • Type Safety: Complete TypeScript definitions matching native IndexedDB types

Capabilities

Database Management

Core database lifecycle operations including opening, creating, upgrading, and deleting databases with full version management support.

interface IDBFactory {
  open(name: string, version?: number): IDBOpenDBRequest;
  deleteDatabase(name: string): IDBOpenDBRequest;
  databases(): Promise<Array<{ name: string; version: number }>>;
}

interface IDBDatabase extends EventTarget {
  readonly name: string;
  readonly version: number;
  readonly objectStoreNames: DOMStringList;
  
  createObjectStore(name: string, options?: {
    keyPath?: string | string[];
    autoIncrement?: boolean;
  }): IDBObjectStore;
  deleteObjectStore(name: string): void;
  transaction(
    storeNames: string | string[],
    mode?: "readonly" | "readwrite" | "versionchange",
    options?: { durability?: "default" | "strict" | "relaxed" }
  ): IDBTransaction;
  close(): void;
}

Database Management

Object Stores and Indexes

Data storage and retrieval operations with support for primary keys, indexes, and complex queries.

interface IDBObjectStore {
  readonly name: string;
  readonly keyPath: string | string[] | null;
  readonly autoIncrement: boolean;
  readonly indexNames: DOMStringList;
  readonly transaction: IDBTransaction;
  
  put(value: any, key?: IDBValidKey): IDBRequest;
  add(value: any, key?: IDBValidKey): IDBRequest;
  delete(key: IDBValidKey | IDBKeyRange): IDBRequest;
  get(key: IDBValidKey | IDBKeyRange): IDBRequest;
  getAll(query?: IDBValidKey | IDBKeyRange, count?: number): IDBRequest;
  count(key?: IDBValidKey | IDBKeyRange): IDBRequest;
  clear(): IDBRequest;
  
  createIndex(name: string, keyPath: string | string[], options?: {
    unique?: boolean;
    multiEntry?: boolean;
  }): IDBIndex;
  index(name: string): IDBIndex;
  deleteIndex(name: string): void;
  
  openCursor(range?: IDBValidKey | IDBKeyRange, direction?: IDBCursorDirection): IDBRequest;
  openKeyCursor(range?: IDBValidKey | IDBKeyRange, direction?: IDBCursorDirection): IDBRequest;
}

Object Stores and Indexes

Transactions and Cursors

Transaction management and cursor-based iteration for efficient data processing and batch operations.

interface IDBTransaction extends EventTarget {
  readonly objectStoreNames: DOMStringList;
  readonly mode: "readonly" | "readwrite" | "versionchange";
  readonly db: IDBDatabase;
  readonly error: DOMException | null;
  
  objectStore(name: string): IDBObjectStore;
  abort(): void;
  commit(): void;
}

interface IDBCursor {
  readonly source: IDBObjectStore | IDBIndex;
  readonly direction: IDBCursorDirection;
  readonly key: IDBValidKey;
  readonly primaryKey: IDBValidKey;
  
  advance(count: number): void;
  continue(key?: IDBValidKey): void;
  continuePrimaryKey(key: IDBValidKey, primaryKey: IDBValidKey): void;
  delete(): IDBRequest;
  update(value: any): IDBRequest;
}

Transactions and Cursors

Key Ranges and Queries

Advanced querying capabilities with key ranges, bounds, and filtering for precise data selection.

interface IDBKeyRangeStatic {
  only(value: IDBValidKey): IDBKeyRange;
  lowerBound(lower: IDBValidKey, open?: boolean): IDBKeyRange;
  upperBound(upper: IDBValidKey, open?: boolean): IDBKeyRange;
  bound(
    lower: IDBValidKey,
    upper: IDBValidKey,
    lowerOpen?: boolean,
    upperOpen?: boolean
  ): IDBKeyRange;
}

interface IDBKeyRange {
  readonly lower: IDBValidKey | undefined;
  readonly upper: IDBValidKey | undefined;
  readonly lowerOpen: boolean;
  readonly upperOpen: boolean;
  
  includes(key: IDBValidKey): boolean;
}

Key Ranges and Queries

Events and Utilities

Event handling, error management, and testing utilities for comprehensive IndexedDB simulation.

interface IDBRequest extends EventTarget {
  readonly result: any;
  readonly error: DOMException | null;
  readonly source: IDBObjectStore | IDBIndex | IDBCursor | null;
  readonly transaction: IDBTransaction | null;
  readonly readyState: "pending" | "done";
  
  onsuccess: ((event: Event) => void) | null;
  onerror: ((event: Event) => void) | null;
}

interface IDBVersionChangeEvent extends Event {
  readonly oldVersion: number;
  readonly newVersion: number | null;
}

// Testing utility for abnormal database closure
declare function forceCloseDatabase(db: IDBDatabase): void;

Events and Utilities

Types

// Valid IndexedDB key types
type IDBValidKey = number | string | Date | BufferSource | IDBValidKey[];

// Cursor iteration directions
type IDBCursorDirection = "next" | "nextunique" | "prev" | "prevunique";

// Transaction durability options
type IDBTransactionDurability = "default" | "strict" | "relaxed";

// Key path specifications
type IDBKeyPath = string | string[];

// Transaction modes
type IDBTransactionMode = "readonly" | "readwrite" | "versionchange";

// Event callback type
type EventCallback = (event: Event) => void;

Error Handling

fake-indexeddb throws standard IndexedDB exceptions:

  • AbortError - Transaction was aborted
  • ConstraintError - Constraint violation (unique index, etc.)
  • DataError - Invalid key or key range
  • InvalidAccessError - Invalid operation for current state
  • InvalidStateError - Operation not allowed in current state
  • NotFoundError - Requested object not found
  • ReadOnlyError - Write operation on readonly transaction
  • TransactionInactiveError - Transaction is not active
  • VersionError - Invalid version number

Testing Features

Force Database Closure

import { forceCloseDatabase } from "fake-indexeddb";

// Simulate abnormal database closure
db.onclose = () => console.log("Database forcibly closed");
forceCloseDatabase(db); // Triggers close event

Multiple Import Strategies

fake-indexeddb supports flexible import patterns to accommodate different testing frameworks and project structures, making it easy to integrate with Jest, Mocha, Vitest, and other testing environments.