TinyBase

useCreateRelationships

The useCreateRelationships hook is used to create a Relationships object within a React application with convenient memoization.

useCreateRelationships(
  store: Store,
  create: (store: Store) => Relationships,
  createDeps?: DependencyList,
): Relationships
TypeDescription
storeStore

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

create(store: Store) => Relationships

An optional callback for performing post-creation steps on the Relationships object, such as adding definitions or listeners.

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.

returnsRelationships

A reference to the Relationships object.

It is possible to create a Relationships object outside of the React app with the regular createRelationships function and pass it in, but you may prefer to create it within the app, perhaps inside the top-level component. To defend against a new Relationships object being created every time the app renders or re-renders, the useCreateRelationships hook wraps the creation in a memoization.

The useCreateRelationships hook is a very thin wrapper around the React useMemo hook, defaulting to the provided Store as its dependency, so that by default, the creation only occurs once per Store.

If your create function contains other dependencies, the changing of which should also cause the Relationships 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 Relationships object is destroyed whenever a new one is created or the component is unmounted.

Examples

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

const App = () => {
  const store = useCreateStore(() =>
    createStore()
      .setTable('pets', {
        fido: {species: 'dog'},
        felix: {species: 'cat'},
        cujo: {species: 'dog'},
      })
      .setTable('species', {dog: {price: 5}, cat: {price: 4}}),
  );
  const relationships = useCreateRelationships(store, (store) => {
    console.log('Relationships created');
    return createRelationships(store).setRelationshipDefinition(
      'petSpecies',
      'pets',
      'species',
      'species',
    );
  });
  return <span>{relationships.getRemoteRowId('petSpecies', 'fido')}</span>;
};

const app = document.createElement('div');
ReactDOM.render(<App />, app);
// -> 'Relationships created'

ReactDOM.render(<App />, app);
// No second Relationships creation

console.log(app.innerHTML);
// -> '<span>dog</span>'

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

const App = ({remoteTableAndCellToLink}) => {
  const store = useCreateStore(() =>
    createStore()
      .setTable('pets', {
        fido: {species: 'dog', color: 'brown'},
        felix: {species: 'cat', color: 'black'},
        cujo: {species: 'dog', color: 'brown'},
      })
      .setTable('species', {dog: {price: 5}, cat: {price: 4}})
      .setTable('color', {brown: {discount: 0.1}, black: {discount: 0}}),
  );
  const relationships = useCreateRelationships(
    store,
    (store) => {
      console.log(`Relationship created to ${remoteTableAndCellToLink}`);
      return createRelationships(store).setRelationshipDefinition(
        'cellLinked',
        'pets',
        remoteTableAndCellToLink,
        remoteTableAndCellToLink,
      );
    },
    [remoteTableAndCellToLink],
  );
  return <span>{relationships.getRemoteRowId('cellLinked', 'fido')}</span>;
};

const app = document.createElement('div');
ReactDOM.render(<App remoteTableAndCellToLink="species" />, app);
// -> 'Relationship created to species'

console.log(app.innerHTML);
// -> '<span>dog</span>'

ReactDOM.render(<App remoteTableAndCellToLink="color" />, app);
// -> 'Relationship created to color'

console.log(app.innerHTML);
// -> '<span>brown</span>'