🚀 react-idbstore

IndexedDB stores for React made easy.

Overview

react-idbstore is a highly optimized, type-safe data factory designed to simplify persistent local storage management in React applications. It utilizes the robust Dexie.js library to wrap IndexedDB, providing a clean, reusable pattern for creating isolated, live-syncing data stores.

This factory eliminates boilerplate, ensures zero-conflict data storage, and provides high-performance rendering controls.

Features

• Isolated Stores: Creates a unique, independent IndexedDB database for every store instance (createIDBStore), guaranteeing zero data interference between different application modules (e.g., 'contacts' vs. 'users').

• Automatic Live Sync & Tab Sync: The useRecords hook uses Dexie's liveQuery to automatically update your components whenever data changes in the database, including real-time synchronization across multiple browser tabs or windows (Tab Sync).

• Powerful Imperative Reads: Supports fast, single-use data fetching with findFirst, findLast, and findMany for scenarios outside of React components.

• Smart Performance: Implements deep equality checks at the subscription level to prevent unnecessary React re-renders when the fetched data is content-identical to the previous state.

• Advanced Querying: Supports MongoDB-style $and and $or logical operators for complex client-side filtering.

• Full Type Safety: Built with TypeScript, ensuring all CRUD operations and query parameters (WhereClause<T>) strictly adhere to your defined schema.

Data Relationships & The Isolation Trade-Off ⚠️

The architecture of react-idbstore prioritizes isolation and reusability by creating a separate IndexedDB database for every store instance.

No Native Joins

Because each store is a physically separate database, native database-level joins (like SQL JOINs or Dexie’s link queries) are not possible. IndexedDB transactions cannot span across multiple databases.

This is a conscious trade-off that offers significant benefits:

| Con (Trade-Off) | Pro (Benefit) | | :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | | No Native Joins | Absolute Data Isolation: Zero risk of schema or data conflicts between application modules. | | Multiple Reads Required | Modular Simplicity: Easy schema maintenance and component-level fetching (only fetch the related data you need, when you need it). |

Handling Related Data (Client-Side Joining)

To link data, fetch related records in parallel and combine them in your component's logic.

Example: Linking a Post and its Author

import { PostStore, UserStore } from './stores';

function PostDetail({ postId }) {
  // 1. Fetch the primary record
  const post = PostStore.useRecords({ where: { id: postId } })?.[0];

  // 2. Fetch the related record using the FK (post.object.authorId)
  const author = UserStore.useRecords({ where: { id: post?.object.authorId } })?.[0];

  return (
    // ... render combined data ...
  );
}

Live demo

View live demo here

Installation & Setup

Start by installing react-idbstore:

bun add react-idbstore

(You can use npm or yarn too)

Define Your Stores

// stores.ts

import { createIDBStore } from "react-idbstore";

interface TodoItem {
  title: string;
  completed: boolean;
  priority: "low" | "high";
  dueDate: number;
}

// Creates the isolated 'todos' database
export const TodoStore = createIDBStore<TodoItem>({ name: "todos" });

// Creates the isolated 'logs' database
export const LogStore = createIDBStore<{ timestamp: number; message: string }>({
  name: "app_logs",
});

Usage

Live Querying (useRecords)

The hook returns an array of records { id: number, object: StoreSchema }.

import React from "react";
import { TodoStore } from "./stores";

function TodoList() {
  // Fetches items where (completed === false) AND (priority === 'high')
  const highPriorityTodos = TodoStore.useRecords({
    where: { completed: false, priority: "high" },
  });

  if (!highPriorityTodos.length) return <div>Loading...</div>;

  return (
    <ul>
      {highPriorityTodos.map((record) => (
        <li key={record.id}>
          {/* Access the payload via .object */}
          {record.object.title}
        </li>
      ))}
    </ul>
  );
}

Complex Filtering ($and / $or)

Filter logic can be combined for powerful, stable client-side queries.

// Example: Show tasks that are NOT completed OR are overdue (dueDate < current time)
const urgentTasks = TodoStore.useRecords({
  where: {
    $or: [
      { completed: false },
      { dueDate: Date.now() }, // Note: Equality checks are used here. For range queries, use custom filter.
    ],
  },
});

// Example: Show tasks that are high priority AND (uncompleted OR overdue)
const criticalTasks = TodoStore.useRecords({
  where: {
    $and: [
      { priority: "high" },
      {
        $or: [{ completed: false }, { dueDate: Date.now() }],
      },
    ],
  },
});

CRUD Operations

All write operations return a Promise and should be wrapped in try/catch for robust error handling.

| Operation | Usage | Notes | | :--------------- | :---------------------------------------------------- | :-------------------------------------------------------------- | | addItem | await TodoStore.addItem({ title: 'New' }) | Returns the id of the new item. | | addMany | await TodoStore.addMany([item1, item2]) | High-performance bulk insert. Returns the key of the last item. | | updateItem | await TodoStore.updateItem(id, { completed: true }) | Supports partial object updates or function-based updates. | | deleteItem | await TodoStore.deleteItem(id) | Deletes a single record by primary key. | | deleteMany | await TodoStore.deleteMany([id1, id2]) | High-performance bulk delete. |

API Reference

The createIDBStore<StoreSchema>(definition) factory returns an object with the following interface:

I. Read Hook

| Function | Signature | Description | | :--------------- | :----------------------- | :----------------------------------------------------------------------- | | useRecords | ({ where?, onError? }) | Live subscribes to the collection. Returns StoreRecord<StoreSchema>[]. |

II. Query Types

| Type | Structure | Description | | :------------------- | :------------------------------------------------------- | :------------------------------------------------------------- | | WhereClause<T> | { key: value }, { $and: [...] }, or { $or: [...] } | The strongly typed query object used in the useRecords hook. |

API Reference

The createIDBStore<StoreSchema>(definition) factory returns an object with the following interface:

I. Read Hook (Reactive)

| Function | Signature | Description | | :--------------- | :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | useRecords | ({ where?, onError? }) | Live Hook: Returns StoreRecord<StoreSchema>[]. Subscribes to collection changes, applies filtering, and uses smart comparison to prevent unnecessary React re-renders. |

II. Read Operations (Async)

| Function | Signature | Description | | :-------------- | :------------------------ | :---------------------------------------------------------------------------------------------------------------------------- | | findFirst | (where: WhereClause<T>) | Returns the first record (lowest ID) matching the criteria. Optimized with a forward cursor, stopping on the first match. | | findLast | (where: WhereClause<T>) | Returns the last record (highest ID) matching the criteria. Optimized with a reverse cursor, stopping on the first match. | | findMany | (where: WhereClause<T>) | Returns all records matching the criteria. Useful for imperative data fetching outside of components. |

III. Write Operations (Async)

| Operation | Signature | Notes | | :--------------- | :------------------------------------------------------------ | :-------------------------------------------------------------------- | | addItem | (item: T) | Adds a single new item. Returns the new item's id. | | addMany | (items: T[]) | High-performance bulk insert. Returns the key of the last added item. | | updateItem | (id: number, update: Partial<T> \| (prev: T) => Partial<T>) | Supports partial object updates or function-based state transitions. | | deleteItem | (id: number) | Deletes a single record by primary key. | | deleteMany | (ids: number[]) | High-performance bulk delete. |

IV. Query Types

| Type | Structure | Description | | :------------------- | :------------------------------------------------------- | :-------------------------------------------------------------------------------------- | | WhereClause<T> | { key: value }, { $and: [...] }, or { $or: [...] } | The strongly typed query object used in the useRecords and imperative read functions. |