`useSetCheckpointCallback`

The useSetCheckpointCallback hook returns a parameterized callback that can be used to record a checkpoint of a Store into a Checkpoints object that can be reverted to in the future.

useSetCheckpointCallback<Parameter>(
  getCheckpoint?: (parameter: Parameter) => string,
  getCheckpointDeps?: DependencyList,
  checkpointsOrCheckpointsId?: CheckpointsOrCheckpointsId,
  then?: (checkpointId: string, checkpoints: Checkpoints, label?: string) => void,
  thenDeps?: DependencyList,
): ParameterizedCallback<Parameter>

	Type	Description
`getCheckpoint?`	`(parameter: Parameter) => string`	An optional function which returns a string that will be used to describe the actions leading up to this checkpoint, based on the parameter the callback will receive (and which is most likely a DOM event).
`getCheckpointDeps?`	`DependencyList`	An optional array of dependencies for the `getCheckpoint` function, which, if any change, result in the regeneration of the callback. This parameter defaults to an empty array.
`checkpointsOrCheckpointsId?`	`CheckpointsOrCheckpointsId`	The `Checkpoints` object to be updated: omit for the default context `Checkpoints` object, provide an `Id` for a named context `Checkpoints` object, or provide an explicit reference.
`then?`	`(checkpointId: string, checkpoints: Checkpoints, label?: string) => void`	A function which is called after the checkpoint is set, with the new checkpoint `Id`, a reference to the `Checkpoints` object and the label provided, if any.
`thenDeps?`	`DependencyList`	An optional array of dependencies for the `then` function, which, if any change, result in the regeneration of the callback. This parameter defaults to an empty array.
returns	`ParameterizedCallback<Parameter>`	A parameterized callback for subsequent use.

This hook is useful, for example, when creating an event handler that will set the checkpoint. In this case, the parameter will likely be the event, so that you can use data from it as the checkpoint label.

The optional first parameter is a function which will produce the label that will then be used to name the checkpoint.

If that function has any other dependencies, the changing of which should also cause the callback 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.

For convenience, you can optionally provide a then function (with its own set of dependencies) which will be called just after the checkpoint has been set.

The Checkpoints object for which the callback will set the checkpoint (indicated by the hook's checkpointsOrCheckpointsId parameter) is always automatically used as a hook dependency for the callback.

Example

This example uses the useSetCheckpointCallback hook to create an event handler which sets a checkpoint when the span element is clicked.

import {createCheckpoints, createStore} from 'tinybase';
import React from 'react';
import {createRoot} from 'react-dom/client';
import {useSetCheckpointCallback} from 'tinybase/ui-react';

const store = createStore().setTables({pets: {nemo: {species: 'fish'}}});
const checkpoints = createCheckpoints(store);
const App = () => {
  const handleClick = useSetCheckpointCallback(
    (e) => `with #${e.target.id} button`,
    [],
    checkpoints,
    (checkpointId, checkpoints, label) =>
      console.log(`Checkpoint ${checkpointId} set, ${label}`),
  );
  return (
    <span id="span" onClick={handleClick}>
      Set
    </span>
  );
};

const app = document.createElement('div');
createRoot(app).render(<App />);
const _span = app.querySelector('span');

store.setCell('pets', 'nemo', 'color', 'orange');

// User clicks the <span> element:
// -> _span MouseEvent('click', {bubbles: true})
// -> 'Checkpoint 1 set, with #span button'

Since

v1.0.0