<center><h2>React Hooks to use Dexie.js IndexDB library</h2></center>

Dexie.js is a gorgeous library to use IndexDB with simple and powerful syntax. However, if you want to use Dexie.js within a React project you need to implement a series of logics that allow asynchronous interaction. For this purpose, useDexie is a library that includes a series of React Hooks that allow you to easily use IndexDB as a data source for React applications. In many cases useDexie allows you to completely replace status libraries such as Redux while ensuring a higher execution speed (data can be pre-loaded) and, of course, persistency.

The use-dexie hooks have been optimized to ensure:

• 🔥 Realtime Refresh of React elements that depend on a data source
• ♻️ Minimizing the number of refreshes to bare minimum
• ⚡️ Maximum Speed and Minimum memory footprint
• 🔦 Dynamic Query Composition
• 🕵🏻‍♂️ Performance and Stats Live monitoring

<h1>Index of Content</h1> <!-- TOC -->

• Installation
• Basic Usage
• Hooks
  • useDexie
    • Params
    • Example DB Initialize and Populate
  • useDexieTable
    • Params
    • Example Fetch entire Table
    • Example Query Table
    • Example Fetch Table with selector Callback
  • useDexieGetTable
    • Params
    • Callback Example
  • useDexieObj
    • Example
  • useDexieMap
    • Example
  • useDexieSet
    • Example
  • useDexieGetItem
    • Params
    • Callback Params
    • Example: Direct
    • Example: Callback
  • useDexieGetItemKey
    • Params
    • Callback Params
    • Example
  • useDexiePutItem
    • Params
    • Callback Params
    • Example
  • useDexiePutItems
    • Params
    • Callback Params
    • Example
  • useDexieUpdateItem
    • Params
    • Callback Params
    • Example
  • useDexieDeleteItem
    • Params
    • Callback Params
    • Example
  • useDexieDeleteByQuery
    • Params
    • Callback Params
    • Example
  • useDexieMonitor
    • Example
• Query Syntax
  • Where Clause
    • Or Clause
    • And Clause
  • Filtering
  • Order By
  • Pagination
  • Count Results
• Example: To-Do-List with Create React App

<!-- /TOC -->

Installation

<a id="markdown-installation" name="installation"></a>

npm install use-dexie

Basic Usage

<a id="markdown-basic-usage" name="basic-usage"></a>

Below is a simple example that shows how to instantiate useDexie, populate a simple database of Tasks and then query the database to receive the list of tasks and render them in the component. For a more detailed example see Example: To-Do-List Create React App.

import React from 'react';
import { useDexie, useDexieTable } from 'use-dexie';

function App() {
  useDexie('TASKS_DB', { tasks: 'id, name, done' }, (db) => {
    db.tasks.bulkPut([
      { id: 'T1', label: 'Learn useDexie', done: 'false' },
      { id: 'T2', label: 'Advanced useDexie', done: 'false' },
    ]);
  });

  const tasks = useDexieTable('tasks') || [];

  return (
    <div>
      {tasks.map((task) => (
        <span>task.label</span>
      ))}
    </div>
  );
}

Hooks

<a id="markdown-hooks" name="hooks"></a>

use-dexie offers a set of hooks to read, write and delete data from a single instance of IndexDB (it is not possible to use use-dexie on multiple databases at the same time. Solution: divide the data into several tables within the same DB). The first and most important hook to use is useDexie to initialize the database to be used.

useDexie

<a id="markdown-usedexie" name="usedexie"></a>

Object: db = useDexie(String: dbName, Object: [dbSchema], Number: dbVersion, function: [callback]);

useDexie is the main hook that should be invoked mandatorily as soon as possible inside your app to instantiate the DB you want to use. To instantiate the DB you need to provide the name, version and schema. The advice is to use useDexie in the root file of your React application to make the DB immediately available to all your components.

Params

<a id="markdown-params" name="params"></a>

| | Description | Example | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | dbName | The name of DB (Mandatory) | "TASKS-DB" | | dbSchema | The schema to create DB. I must follow the Dexie.js syntax | { tasks: 'id, name, done' } | | dbVersion | The version number of DB.Please note that if you want to change an already deployed DB you must change DB version (please check Dexie.js Documentation) | 1 | | callback | useDexie returns the DB asynchronously as soon as it is instantiated. However, if you want to receive the DB synchronously so that you can update it, for example, you can specify a callback that will be called with the DB as soon as it is available. | See example below |

Example DB Initialize and Populate

<a id="markdown-example-db-initialize-and-populate" name="example-db-initialize-and-populate"></a>

useDexie('TASKS_DB', { tasks: 'id, name, done' }, (db) => {
  db.tasks.bulkPut([
    { id: 'T1', label: 'Learn useDexie', done: 'false' },
    { id: 'T2', label: 'Advanced useDexie', done: 'false' },
  ]);
});

useDexieTable

<a id="markdown-usedexietable" name="usedexietable"></a>

Array: results = useDexieTable((String: tableName), (Object: [query]), (Function: [callback]));

useDexieTable is a hook to read data contained in a database table. It can be used in several ways:

• to receive all entries of a table
• to receive only one set of results depending on a query
• as a selector to select and process table content

useDexieTable can be used asynchronously by returning the result when available, or a callback can be provided to process the result inline.

Params

<a id="markdown-params" name="params"></a>

| | Description | Example | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | tableName | The name of the table to operate on | "tasks" | | query | Optional parameter to fetch data using useDexie [Query Syntax] (#query-syntax) | { where:[{ field: 'done', operator: 'equals', value: 'true' }]} | | callback | On optional callback to retrieve and process query/table results. Da notare che il risultato della callback viene restituito dalla funzione useDexieTable dando la possibilità di utilizzarla come un selector. | (results) => doSomething(results) |

Example Fetch entire Table

<a id="markdown-example-fetch-entire-table" name="example-fetch-entire-table"></a>

const task = useDexieTable('tasks');

Example Query Table

<a id="markdown-example-query-table" name="example-qu