README.md

use-indexeddb

Lightweight (1KB gzipped) hooks w/ promises for easy IndexedDB access in React ⚓

🔧 Installation

npm i use-indexeddb    # npm
yarn add use-indexeddb # yarn

📚 Storybook

see demo on storybook

✨ Features

• 🍃 Lightweight (~3KB gzipped) [no dependencies]
• 🧠 Automatic modal type inference like useIndexedDBStore<YourInterface>()
• ✅ SSR Safe
• 🤞 Simple Promise based api

📦 Examples

1. add
2. getByID
3. getAll
4. getOneByKey
5. getManyByKey
6. update
7. deleteByID
8. deleteAll
9. openCursor

Full Example

import React from "react";
import setupIndexedDB, { useIndexedDBStore } from "use-indexeddb";

// Database Configuration
const idbConfig = {
  databaseName: "fruity-db",
  version: 1,
  stores: [
    {
      name: "fruits",
      id: { keyPath: "id", autoIncrement: true },
      indices: [
        { name: "name", keyPath: "name", options: { unique: false } },
        { name: "quantity", keyPath: "quantity" },
      ],
    },
  ],
};

const Example = () => {
  useEffect(() => {
    setupIndexedDB(idbConfig)
      .then(() => console.log("success"))
      .catch(e => console.error("error / unsupported", e));
  }, []);

  const { add } = useIndexedDBStore("fruits");

  const insertFruit = () => {
    add({ name: "Mango 🥭", quantity: 2 }).then(console.log);
  };

  return <button onClick={insertFruit}>Insert</button>;
};

export default Example;

add(value, key?)

Inserts given value record to selected store, second param is optional key useful if auto-increment is disabled

By default commit is enabled after each transaction so changes are reflected in indexedDB instantly

import { useIndexedDBStore } from "use-indexeddb";

function Example() {
  const { add } = useIndexedDBStore("fruits");

  const onClick = () => {
    add({ name: "Mango 🥭", quantity: 2 })
      .then(d => console.log(`Added Fruit with ID ${d}`))
      .catch(console.error);
  };

  return <button onClick={onClick}>Add</button>;
}

getByID(id)

Retrive record by ID

import { useIndexedDBStore } from "use-indexeddb";

function Example() {
  const { getByID } = useIndexedDBStore("fruits");

  const onClick = () => {
    getByID(1)
      .then(console.log)
      .catch(console.error);
  };

  return <button onClick={onClick}>Get - ID 1</button>;
}

getAll()

Retrive all records from provided store

import { useIndexedDBStore } from "use-indexeddb";

function Example() {
  const { getAll } = useIndexedDBStore("fruits");

  const onClick = () => {
    getAll()
      .then(console.log)
      .catch(console.error);
  };

  return <button onClick={onClick}>Get All Fruits</button>;
}

getOneByKey(keyPath, value)

Retrives single record if any row matches with given keyPath having value

import { useIndexedDBStore } from "use-indexeddb";

function Example() {
  const { getOneByKey } = useIndexedDBStore("fruits");

  const onClick = () => {
    getOneByKey("quantity", 2)
      .then(console.log)
      .catch(console.error);
  };

  return <button onClick={onClick}>Get Fruit w/ Qty 2</button>;
}

getManyByKey(keyPath, value)

Retrives multiple records in form of array if row matches with given keyPath having value

import { useIndexedDBStore } from "use-indexeddb";

function Example() {
  const { getManyByKey } = useIndexedDBStore("fruits");

  const onClick = () => {
    getManyByKey("quantity", 2)
      .then(console.log)
      .catch(console.error);
  };

  return <button onClick={onClick}>Get All Fruits w/ Qty 2</button>;
}

update(value, key?)

Inserts or Updates given value in store by ID

import { useIndexedDBStore } from "use-indexeddb";

function Example() {
  const { update } = useIndexedDBStore("fruits");

  const onClick = () => {
    update({ id: 1, name: "Strawberry 🍓", quantity: 20 })
      .then(console.log)
      .catch(console.error);
  };

  return <button onClick={onClick}>Update Fruid #1 to Strawberry</button>;
}

deleteByID(id)

Deletes record by ID

import { useIndexedDBStore } from "use-indexeddb";

function Example() {
  const { deleteByID } = useIndexedDBStore("fruits");

  const onClick = () => {
    deleteByID(1)
      .then(console.log)
      .catch(console.error);
  };

  return <button onClick={onClick}>Delete Fruit with ID 1</button>;
}

deleteAll()

Deletes all records

import { useIndexedDBStore } from "use-indexeddb";

function Example() {
  const { deleteAll } = useIndexedDBStore("fruits");

  const onClick = () => {
    deleteAll()
      .then(console.log)
      .catch(console.error);
  };

  return <button onClick={onClick}>Delete All Fruits</button>;
}

openCursor(cursorCallback, keyRange?)

You can use openCursor to iterate over objects one by one within given keyRange

import { useIndexedDBStore } from "use-indexeddb";

function Example() {
  const { openCursor } = useIndexedDBStore("fruits");

  const onClick = () => {
    openCursor(e => {
      const c = e.target.result;
      if (c) {
        console.log(c);
        c.continue();
      } else {
        console.log("that's all folks");
      }
    });
  };

  return <button onClick={onClick}>Open Cursor</button>;
}

🤠 Credits

• This library takes inspiration from react-indexed-db
• TypeScript
• TSDX

📜 License

MIT © harshzalavadiya