`addLocalRowIdsListener`

The addLocalRowIdsListener method registers a listener function with the Relationships object that will be called whenever the local Row Ids in a Relationship change.

addLocalRowIdsListener(
  relationshipId: IdOrNull,
  remoteRowId: IdOrNull,
  listener: LocalRowIdsListener,
): Id

	Type	Description
`relationshipId`	`IdOrNull`	The `Id` of the `Relationship` to listen to, or `null` as a wildcard.
`remoteRowId`	`IdOrNull`	The `Id` of the remote `Row` to listen to, or `null` as a wildcard.
`listener`	`LocalRowIdsListener`	The function that will be called whenever the local `Row` `Ids` change.
returns	`Id`	A unique `Id` for the listener that can later be used to remove it.

You can either listen to a single local Row (by specifying the Relationship Id and local Row Id as the method's first two parameters), or changes to any local Row (by providing a null wildcards).

Both, either, or neither of the relationshipId and remoteRowId parameters can be wildcarded with null. You can listen to a specific remote Row in a specific Relationship, any remote Row in a specific Relationship, a specific remote Row in any Relationship, or any remote Row in any Relationship.

The provided listener is a LocalRowIdsListener function, and will be called with a reference to the Relationships object, the Id of the Relationship, and the Id of the remote Row that had its local Row objects change.

Examples

This example creates a Store, a Relationships object, and then registers a listener that responds to any changes to a specific remote Row's local Row objects.

const store = createStore()
  .setTable('pets', {
    fido: {species: 'dog'},
    felix: {species: 'cat'},
    cujo: {species: 'dog'},
  })
  .setTable('species', {
    wolf: {price: 10},
    dog: {price: 5},
    cat: {price: 4},
  });

const relationships = createRelationships(store);
relationships.setRelationshipDefinition(
  'petSpecies',
  'pets',
  'species',
  'species',
);

const listenerId = relationships.addLocalRowIdsListener(
  'petSpecies',
  'dog',
  (relationships, relationshipId, remoteRowId) => {
    console.log('petSpecies relationship (to dog) changed');
    console.log(relationships.getLocalRowIds('petSpecies', 'dog'));
  },
);

store.setRow('pets', 'toto', {species: 'dog'});
// -> 'petSpecies relationship (to dog) changed'
// -> ['fido', 'cujo', 'toto']

relationships.delListener(listenerId);

This example creates a Store, a Relationships object, and then registers a listener that responds to any changes to any remote Row's local Row objects.

const store = createStore()
  .setTable('pets', {
    fido: {species: 'dog', color: 'brown'},
    felix: {species: 'cat', color: 'black'},
    cujo: {species: 'dog', color: 'brown'},
    toto: {species: 'dog', color: 'grey'},
  })
  .setTable('species', {
    wolf: {price: 10},
    dog: {price: 5},
    cat: {price: 4},
  })
  .setTable('color', {
    brown: {discount: 0.1},
    black: {discount: 0},
    grey: {discount: 0.2},
  });

const relationships = createRelationships(store)
  .setRelationshipDefinition('petSpecies', 'pets', 'species', 'species')
  .setRelationshipDefinition('petColor', 'pets', 'color', 'color');

const listenerId = relationships.addLocalRowIdsListener(
  null,
  null,
  (relationships, relationshipId, remoteRowId) => {
    console.log(
      `${relationshipId} relationship (to ${remoteRowId}) changed`,
    );
    console.log(relationships.getLocalRowIds(relationshipId, remoteRowId));
  },
);

store.setRow('pets', 'cujo', {species: 'wolf', color: 'grey'});
// -> 'petSpecies relationship (to dog) changed'
// -> ['fido', 'toto']
// -> 'petSpecies relationship (to wolf) changed'
// -> ['cujo']
// -> 'petColor relationship (to brown) changed'
// -> ['fido']
// -> 'petColor relationship (to grey) changed'
// -> ['toto', 'cujo']

relationships.delListener(listenerId);