rxdb-hooks

Table of Contents

Click to expand

• About
• Installation
• Example
• Compatibility with RxDB
• Migration Guide
• API
  • Provider
  • useRxDB
  • useRxCollection
  • useRxQuery
  • useRxData
  • useRxDocument
• Recipes
  • Query and Query Constructor memoization
  • Lazy instantiation of RxDatabase & RxCollections
  • Mutations
• LICENSE

About

A set of simple hooks for integrating a React application with RxDB.

Nothing fancy, just conveniently handles common use cases such as:

• subscribing to query observables and translating results into React state
• cleaning up after subscriptions where necessary
• paginating results
• maintaining useful state information (i.e. data fetching or data exhaustion during pagination)
• lazily creating or destroying collections

Installation

1# using npm
2npm install rxdb-hooks
3
4# using yarn
5yarn add rxdb-hooks

Example

Root.jsx:

1import React, { useEffect } from 'react';
2import { Provider } from 'rxdb-hooks';
3import initialize from './initialize';
4
5const Root = () => {
6  const [db, setDb] = useState();
7
8  useEffect(() => {
9    // RxDB instantiation can be asynchronous
10    initialize().then(setDb);
11  }, []);
12
13  // Until db becomes available, consumer hooks that
14  // depend on it will still work, absorbing the delay
15  // by setting their state to isFetching:true
16  return (
17    <Provider db={db}>
18      <App />
19    </Provider>
20  );
21};

Consumer.jsx:

1import React from 'react';
2import { useRxData } from 'rxdb-hooks';
3
4const Consumer = () => {
5  const { result: characters, isFetching } = useRxData(
6    // the collection to be queried
7    'characters',
8    // a function returning the query to be applied
9    collection =>
10      collection.find({
11        selector: {
12          affiliation: 'jedi',
13        },
14      })
15  );
16
17  if (isFetching) {
18    return 'loading characters...';
19  }
20
21  return (
22    <ul>
23      {characters.map((character, idx) => (
24        <li key={idx}>{character.name}</li>
25      ))}
26    </ul>
27  );
28};

initialize.js:

1const initialize = async () => {
2  // create RxDB
3  const db = await createRxDatabase({
4    name: 'test_database',
5  });
6
7  // create a collection
8  const collection = await db.addCollections({
9    characters: {
10      schema: {
11        title: 'characters',
12        version: 0,
13        type: 'object',
14        primaryKey: 'id',
15        properties: {
16          id: {
17            type: 'string',
18            maxLength: 100,
19          },
20          name: {
21            type: 'string',
22          },
23        },
24      },
25    },
26  });
27
28  // maybe sync collection to a remote
29  // ...
30
31  return db;
32};

Compatibility with RxDB

The core API of rxdb-hooks remains largely the same across all major versions beyond 1.x, however some parts of the internal implementation (most notably the plugin) differ based on the version of rxdb we need to target *. Please use the appropriate version of rxdb-hooks as per this table:

rxdb-hooks version	targeted RxDB version
5.x	14.x
4.1.x	13.x
4.0.x	10.x, 11.x, 12.x
3.x	9.x
1.x, 2.x	8.x

* Versions 7.x of RxDB and below have not been tested and are not guaranteed to work with rxdb-hooks

Migration Guide

4.x => 5.x

• useRxDocument has been dropped; for fetching single documents simply use useRxQuery or useRxData
• observing lazily created collection has become an opt-in feature that, if needed, has to be explicitly enabled by using the provided plugin. For more info see Lazy instantiation of RxDatabase & RxCollections

API

Provider

The <Provider /> makes the RxDatabase instance available to nested components and is required for all subsequent hooks to work.

Props

Property	Type	Description
db	RxDatabase	the RxDatabase instance to consume data from

---

useRxDB

Returns the RxDatabase instance made available by the <Provider />

1function useRxDB(): RxDatabase

Example

1const db = useRxDB();

---

useRxCollection

Given a collection name returns an RxCollection instance, if found in RxDatabase.

1function useRxCollection<T>(name: string): RxCollection<T> | null

Example

1const collection = useRxCollection('characters');

---

useRxQuery

Subscribes to given RxQuery object providing query results and some helpful extra state variables.

1function useRxQuery<T>(query: RxQuery, options?: UseRxQueryOptions): RxQueryResult<T>

options: UseRxQueryOptions

Option	Type	Description
pageSize	number	(optional) enables pagination & defines page limit
pagination	"Traditional" | "Infinite"	(optional) determines pagination mode: Traditional: results are split into pages, starts by rendering the first page and total pageCount is returned, allowing for requesting results of any specific page. Infinite: first page of results is rendered, allowing for gradually requesting more. Default: "Traditional"
json	boolean	(optional) when true resulting documents will be converted to plain JavaScript objects; equivalent to manually calling .toJSON() on each RxDocument. Default: false

result: RxQueryResult<T>

Property	Type	Description
result	T[] | RxDocument<T>[]	the resulting array of objects or RxDocument instances, depending on json option
isFetching	boolean	fetching state indicator
currentPage	number	relevant in all pagination modes; holds number of current page
isExhausted	boolean	relevant in Infinite pagination; flags result list as "exhausted", meaning all documents have been already fetched
fetchMore	() => void	relevant in Infinite pagination; a function to be called by the consumer to request documents of the next page
resetList	() => void	relevant in Infinite pagination; a function to be called by the consumer to reset paginated results
pageCount	number	relevant in Traditional pagination; holds the total number of pages available
fetchPage	(page: number) => void	relevant in Traditional pagination; a function to be called by the consumer to request results of a specific page

Simple Example

1const collection = useRxCollection('characters');
2
3const query = collection.find().where('affiliation').equals('Jedi');
4
5const { result } = useRxQuery(query);

Infinite Scroll Pagination Example

1const collection = useRxCollection('characters');
2
3const query = collection.find().where('affiliation').equals('Jedi');
4
5const {
6  result: characters,
7  isFetching,
8  fetchMore,
9  isExhausted,
10} = useRxQuery(query, {
11  pageSize: 5,
12  pagination: 'Infinite',
13});
14
15if (isFetching) {
16  return 'Loading...';
17}
18
19return (
20  <CharacterList>
21    {characters.map((character, index) => (
22      <Character character={character} key={index} />
23    ))}
24    {!isExhausted && <button onClick={fetchMore}>load more</button>}
25  </CharacterList>
26);

Traditional Pagination Example

1const collection = useRxCollection('characters');
2
3const query = collection.find({
4  selector: {
5    affiliation: 'jedi',
6  },
7});
8
9const {
10  result: characters,
11  isFetching,
12  fetchPage,
13  pageCount,
14} = useRxQuery(query, {
15  pageSize: 5,
16  pagination: 'Traditional',
17});
18
19if (isFetching) {
20  return 'Loading...';
21}
22
23// render results and leverage pageCount to render page navigation
24return (
25  <div>
26    <CharacterList>
27      {characters.map((character, index) => (
28        <Character character={character} key={index} />
29      ))}
30    </CharacterList>
31    <div>
32      {Array(pageCount)
33        .fill()
34        .map((x, i) => (
35          <button
36            onClick={() => {
37              fetchPage(i + 1);
38            }}
39          >
40            page {i + 1}
41          </button>
42        ))}
43    </div>
44  </div>
45);

---

useRxData

Convenience wrapper around useRxQuery that expects a collection name & a query constructor function

1function useRxData<T>(
2	collectionName: string,
3	queryConstructor: ((collection: RxCollection<T>) => RxQuery<T> | undefined) | undefined,
4	options?: UseRxQueryOptions
5): RxQueryResult<T>

Example

1const { result } = useRxData('characters', collection =>
2  collection.find().where('affiliation').equals('Jedi')
3);

---

Recipes

Query and Query Constructor memoization

By design, useRxQuery will re-subscribe to query object whenever it changes, allowing for query criteria to be modified during component updates. For this reason, to avoid unnecessary re-subscriptions, query should be memoized (i.e. via react's useMemo):

1const { affiliation } = props;
2const collection = useRxCollection('characters');
3
4const query = useMemo(
5  () =>
6    collection.find({
7      selector: {
8        affiliation,
9      },
10    }),
11  [collection, affiliation]
12);
13
14const { result } = useRxQuery(query);

Same goes for useRxData and the queryConstructor function:

1const { affiliation } = props;
2
3const queryConstructor = useCallback(
4  collection =>
5    collection.find({
6      selector: {
7        affiliation,
8      },
9    }),
10  [affiliation]
11);
12
13const { result } = useRxData('characters', queryConstructor);

Lazy instantiation of RxDatabase & RxCollections

All rxdb-hooks give you the ability to lazily instantiate the database and the collections within it. Initial delay until the above become available is absorbed by indicating the state as fetching (isFetching:true).

Since v5.0.0 of rxdb-hooks, observing newly created collections has become an opt-in feature that, if needed, has to be enabled via the provided observeNewCollections plugin:

1import { addRxPlugin } from 'rxdb';
2import { observeNewCollections } from 'rxdb-hooks';
3
4addRxPlugin(observeNewCollections);

Adding the plugin makes it possible for all rxdb-hooks to pick up data from collections that are lazily added after the inital db initialization.

Also note that lazily instantiating the rxdb instance itself is supported out-of-the-box, the plugin only affects lazy collection creation.

Mutations

Performing mutations on data is possible through the APIs provided by RxDocument and RxCollection:

Example

1const collection = useRxCollection('characters');
2
3collection.upsert({
4  name: 'Luke Skywalker',
5  affiliation: 'Jedi',
6});

LICENSE

MIT