`addCheckpointListener`

The addCheckpointListener method registers a listener function with the Checkpoints object that will be called whenever the label of a checkpoint changes.

addCheckpointListener(
  checkpointId: IdOrNull,
  listener: CheckpointListener,
): string

Type Description

	Type	Description
`checkpointId`	`IdOrNull`	The `Id` of the checkpoint to listen to, or `null` as a wildcard.
`listener`	`CheckpointListener`	The function that will be called whenever the checkpoint label changes.
returns	`string`	A unique `Id` for the listener that can later be used to remove it.

checkpointId

IdOrNull

The Id of the checkpoint to listen to, or null as a wildcard.

listener

CheckpointListener

The function that will be called whenever the checkpoint label changes.

returns

string

A unique Id for the listener that can later be used to remove it.

You can either listen to a single checkpoint label (by specifying the checkpoint Id as the method's first parameter), or changes to any checkpoint label (by providing a null wildcard).

The provided listener is a CheckpointListener function, and will be called with a reference to the Checkpoints object, and the Id of the checkpoint whose label changed.

Example

This example creates a Store, a Checkpoints object, and then registers a listener that responds to any changes to a specific checkpoint label, including when the checkpoint no longer exists.

import {createCheckpoints, createStore} from 'tinybase';

const store = createStore().setTables({pets: {fido: {species: 'dog'}}});

const checkpoints = createCheckpoints(store);
console.log(checkpoints.getCheckpointIds());
// -> [[], '0', []]

const listenerId = checkpoints.addCheckpointListener('1', () => {
  console.log('Checkpoint 1 label changed');
  console.log(checkpoints.getCheckpoint('1'));
});

store.setCell('pets', 'fido', 'sold', true);
checkpoints.addCheckpoint('sale');
// -> 'Checkpoint 1 label changed'
// -> 'sale'

checkpoints.setCheckpoint('1', 'sold');
// -> 'Checkpoint 1 label changed'
// -> 'sold'

checkpoints.setCheckpoint('1', 'sold');
// The listener is not called when the label does not change.

checkpoints.goTo('0');
store.setCell('pets', 'fido', 'sold', false);
// -> 'Checkpoint 1 label changed'
// -> undefined
// The checkpoint no longer exists.

checkpoints.delListener(listenerId);

Since

v1.0.0