TinyBase logoTinyBase

useCreateIndexes

The useCreateIndexes hook is used to create an Indexes object within a React application with convenient memoization.

useCreateIndexes(
  store: undefined | Store,
  create: (store: Store) => Indexes,
  createDeps?: DependencyList,
): Indexes | undefined
TypeDescription
storeundefined | Store

A reference to the Store for which to create a new Indexes object.

create(store: Store) => Indexes

A function for performing the creation steps of the Indexes object for the Store, plus any additional steps such as adding definitions or listeners, and returning it.

createDeps?DependencyList

An optional array of dependencies for the create function, which, if any change, result in its rerun. This parameter defaults to an empty array.

returnsIndexes | undefined

A reference to the Indexes object.

It is possible to create an Indexes object outside of the React app with the regular createIndexes function and pass it in, but you may prefer to create it within the app, perhaps inside the top-level component. To prevent a new Indexes object being created every time the app renders or re-renders, since v5.0 the this hook performs the creation in an effect. As a result it will return undefined on the brief first render (or if the Store is not yet defined), which you should defend against.

If your create function contains other dependencies, the changing of which should also cause the Indexes object to be recreated, you can provide them in an array in the optional second parameter, just as you would for any React hook with dependencies.

This hook ensures the Indexes object is destroyed whenever a new one is created or the component is unmounted.

Examples

This example creates an Indexes object at the top level of a React application. Even though the App component is rendered twice, the Indexes object creation only occurs once by default.

import {createIndexes, createStore} from 'tinybase';
import {useCreateIndexes, useCreateStore} from 'tinybase/ui-react';
import React from 'react';
import {createRoot} from 'react-dom/client';

const App = () => {
  const store = useCreateStore(() =>
    createStore().setTable('pets', {
      fido: {species: 'dog'},
      felix: {species: 'cat'},
      cujo: {species: 'dog'},
    }),
  );
  const indexes = useCreateIndexes(store, (store) => {
    console.log('Indexes created');
    return createIndexes(store).setIndexDefinition(
      'bySpecies',
      'pets',
      'species',
    );
  });
  return <span>{JSON.stringify(indexes?.getSliceIds('bySpecies'))}</span>;
};

const app = document.createElement('div');
const root = createRoot(app);
root.render(<App />);
// -> 'Indexes created'

root.render(<App />);
// No second Indexes creation

console.log(app.innerHTML);
// -> '<span>["dog","cat"]</span>'

This example creates an Indexes object at the top level of a React application. The App component is rendered twice, each with a different top-level prop. The useCreateIndexes hook takes the cellToIndex prop as a dependency, and so the Indexes object is created again on the second render.

import {createIndexes, createStore} from 'tinybase';
import {useCreateIndexes, useCreateStore} from 'tinybase/ui-react';
import React from 'react';
import {createRoot} from 'react-dom/client';

const App = ({cellToIndex}) => {
  const store = useCreateStore(() =>
    createStore().setTable('pets', {
      fido: {species: 'dog', color: 'brown'},
      felix: {species: 'cat', color: 'black'},
      cujo: {species: 'dog', color: 'brown'},
    }),
  );
  const indexes = useCreateIndexes(
    store,
    (store) => {
      console.log(`Index created for ${cellToIndex} cell`);
      return createIndexes(store).setIndexDefinition(
        'byCell',
        'pets',
        cellToIndex,
      );
    },
    [cellToIndex],
  );
  return <span>{JSON.stringify(indexes?.getSliceIds('byCell'))}</span>;
};

const app = document.createElement('div');
const root = createRoot(app);
root.render(<App cellToIndex="species" />);
// -> 'Index created for species cell'

console.log(app.innerHTML);
// -> '<span>["dog","cat"]</span>'

root.render(<App cellToIndex="color" />);
// -> 'Index created for color cell'

console.log(app.innerHTML);
// -> '<span>["brown","black"]</span>'

Since

v1.0.0