useResultCellListener
The useResultCellListener
hook registers a listener function with a Queries
object that will be called whenever data in a Cell
changes.
useResultCellListener(
queryId: IdOrNull,
rowId: IdOrNull,
cellId: IdOrNull,
listener: ResultCellListener,
listenerDeps?: DependencyList,
queriesOrQueriesId?: QueriesOrQueriesId,
): void
Type | Description | |
---|---|---|
queryId | IdOrNull | The |
rowId | IdOrNull | The |
cellId | IdOrNull | The |
listener | ResultCellListener | The function that will be called whenever data in the matching result |
listenerDeps? | DependencyList | An optional array of dependencies for the |
queriesOrQueriesId? | QueriesOrQueriesId | The |
returns | void | This has no return value. |
This hook is useful for situations where a component needs to register its own specific listener to do more than simply tracking the value (which is more easily done with the useResultCell
hook).
You can either listen to a single Cell
(by specifying the Table
Id
, Row
Id
, and Cell
Id
as the method's first three parameters) or changes to any Cell
(by providing null
wildcards).
All, some, or none of the queryId
, rowId
, and cellId
parameters can be wildcarded with null
. You can listen to a specific Cell
in a specific result Row
in a specific query, any Cell
in any result Row
in any query, for example - or every other combination of wildcards.
Unlike the addResultCellListener
method, which returns a listener Id
and requires you to remove it manually, the useResultCellListener
hook manages this lifecycle for you: when the listener changes (per its listenerDeps
dependencies) or the component unmounts, the listener on the underlying Queries
object will be deleted.
This example uses the useResultCellListener
hook to create a listener that is scoped to a single component. When the component is unmounted, the listener is removed from the Queries
object.
const App = ({queries}) => (
<Provider queries={queries}>
<Pane />
</Provider>
);
const Pane = () => {
useResultCellListener('petColors', 'fido', 'color', () =>
console.log('Result cell changed'),
);
return <span>App</span>;
};
const store = createStore().setTable('pets', {
fido: {species: 'dog', color: 'brown'},
felix: {species: 'cat', color: 'black'},
cujo: {species: 'dog', color: 'black'},
});
const queries = createQueries(store).setQueryDefinition(
'petColors',
'pets',
({select}) => select('color'),
);
const app = document.createElement('div');
ReactDOM.render(<App queries={queries} />, app);
console.log(queries.getListenerStats().cell);
// -> 1
store.setCell('pets', 'fido', 'color', 'walnut');
// -> 'Result cell changed'
ReactDOM.unmountComponentAtNode(app);
console.log(queries.getListenerStats().cell);
// -> 0
v2.0.0