indexeddb-hooked v0.4.3

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;

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 |

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

if (!fruits) return Loading;

return (

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

); };

</details>

### Update your data

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

```jsx
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

IDBObjectStoreParameters

IndexParams

IDBIndexParameters

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));