A small, reactive IndexedDB binding for React.

npm i indexeddb-hooked

Initialize a DB

You define your schema in a config object and establish a database connection via open function somewhere in your app.

import React from 'react';
import { open } from 'indexeddb-hooked';

const config = {
  name: 'FruitDB',
  version: 1,
  objectStores: [
    {
      name: 'fruits',
      options: { autoIncrement: true },
      data: ['apple', 'banana', 'kiwi'],
    },
    {
      name: 'fruit-lists',
      options: { keyPath: 'id', autoIncrement: true },
      indexes: [{ name: 'by_name', keyPath: 'name', options: { unique: true } }],
    },
  ],
  onOpenSuccess: () => console.log('DB is open and delicious'),
};

open(config);

const App = () => {
  return (
      <div>...</div>
  );
};

export default App;

|Value| |Type| | - | - | -: | | name? | Name of your database | string | | version? | Current version of your database | unsigned long long | | objectStores | Definition of your object stores | ObjectStoreParams[] | | onOpenSuccess? | Callback function called if the IDBFactory.open request was successful | IDBRequest.onsuccess | | onOpenError? | Callback function fired when the open request returns an error. | IDBRequest.onerror | | onUpgradeNeeded? | Callback function fired when the database doesn't already exist or if version number is upgraded. Specify this event handler in case you want full control over the creation of your database schema. |(event, objectStores) => void |

Request your data

Once the IDB is open, you access your data via useRead hook:

import React from 'react';
import { useRead } from 'indexeddb-hooked';

const FruitsBasket = () => {
  const [fruits, { isLoading, error }] = useRead('fruits');
  /* Since IDB operations are asynchronous, useRead returns `null`
   (or previous result) at first, then triggers render once the data is obtained.*/

  if (isLoading) return <div>Loading</div>;
  /* You can use isLoading boolean flag and error string 
   to reflect transaction state */
  if (error) return <div>{error}</div>;

  return (
    <ul>
      {fruits.map((fruit) => (
        <li>{fruit}</li>
      ))}
    </ul>
  );
};

To read from IDB, you must specify name of the store you want to read from as a first argument of the useRead function.

Read parameters

To specify request, you must provide a second argument in a form of an object. If only store name is provided, useRead returns all data from specified store. |Value||Type| | - | - | -: | | key? | Returns first data entry with given key | IDBValidKey | | keyRange? | Returns entries within given key range | IDBKeyRange | | direction? | Specify direction of read result | next, nextunique, prev, prevunique | | index? | Specify index to search by other value than the primary key | string | | filter? | Filter function | (value) => boolean | | returnWithKey? | Data is returned with its key in a form of { value, key } object | boolean |

import React from 'react';
import { useRead } from 'indexeddb-hooked';

const FruitsBasket = () => {
const [fruits] = useRead('fruits',{
  returnWithKey: true,
  keyRange: IDBKeyRange.bound(0, 2),
  direction:'prev'
});

if (!fruits) return <div>Loading</div>;

return (
  <ul>
    {fruits.map((result) => (
      <li key={result.key}>{result.value}</li>
    ))}
  </ul>
);
};

Update your data

All data manipulation is happening through update function returned from useUpdate hook:

import React from 'react';
import { useUpdate } from 'indexeddb-hooked';

const AddFruit = () => {
  const [update, { result, error }] = useUpdate();
  const inputEl = useRef(null);

  if (error) console.log(error);

  if (result) console.log(`Added fruit with key ${result}`);

  const onSubmit = (e) => {
    e.preventDefault();
    update('fruits', { value: inputEl.current.value });
  };

  return (
    <form onSubmit={onSubmit}>
      <input ref={inputEl} />
      <button type="submit">Add fruit</button>
    </form>
  );
};

Update triggers re-render on components that read from the updated object store only. You can prevent this rendering by setting the third optional argument of the update function to false.

Update parameters

Behaviour of the update function depends on the definition of your object stores.

To specify update operation, you must provide a second argument in a form of an object. |Value||Type| | - | - | -: | | value | Your input data | boolean, number, string, date, object, array, regexp, undefined, Blob,File, null | | key? | Key of the modified data entry | IDBValidKey | | replace? | If true, then input data overrides (not merges with) the old data entry | boolean |

Deleting data

Delete your data by specifying key and setting the value update parameter to null.

Other types

ObjectStoreParams

|Value||Type| |-|-|-:| | name | Name of the object store | string | | options? | Specify supply of your value keys by a key path or a key generator | IDBObjectStoreParameters | | indexes? | Array containing parameters of indices to create on the database | IndexParams[] | | data? | Input data entries | boolean[], number[], string[], date[], object[], array[], regexp[], undefined[], Blob[],File[] |

IDBObjectStoreParameters

|Value||Type| | - | - | -: | | keyPath? | Defines which value of input object is used as a key. If empty or not specified, the object store is created without a key path and uses out-of-line keys. | string,string[] | | autoIncrement? | If true, the object store has a key generator. Defaults to false. | boolean |

IndexParams

|Value||Type| | - | - | -: | | name | Name of the index | string | | keyPath? | The key path for the index to use | string,string[] | | options? | An object with other index attributes | IDBIndexParameters |

IDBIndexParameters

|Value||Type| | - | - | -: | | unique? | If true, the index will not allow duplicate values for a single key. | boolean | | multiEntry? | If true, the index will add an entry in the index for each array element when the keyPath resolves to an Array. If false, it will add one single entry containing the Array. | boolean |

Usage outside React components

You can also use promise-based alternatives to useRead and useUpdate functions, like so:

import { read, update } from 'indexeddb-hooked';

read('fruits').then(result => console.log(result));

// result is the key or key array of modified object(s)  
update('fruits', { value: 'pear' }).then(result => console.log(result);

Be sure to use these functions after the database connection has been established.

Reacting to store changes

In case you need to react to changes outside of React, you can subscribe listeners to specified store:

import { subscribe } from 'indexeddb-hooked';

// returns function to unsubscribe the listener 
// result is the key or key array of modified object(s)  
const unsub = subscribe('fruits', result => console.log(result));