`addRemoteRowIdListener`

The addRemoteRowIdListener method registers a listener function with the Relationships object that will be called whenever a remote Row Id in a Relationship changes.

addRemoteRowIdListener(
  relationshipId: IdOrNull,
  localRowId: IdOrNull,
  listener: RemoteRowIdListener,
): Id

	Type	Description
`relationshipId`	`IdOrNull`	The `Id` of the `Relationship` to listen to, or `null` as a wildcard.
`localRowId`	`IdOrNull`	The `Id` of the local `Row` to listen to, or `null` as a wildcard.
`listener`	`RemoteRowIdListener`	The function that will be called whenever the remote `Row` `Id` changes.
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 localRowId parameters can be wildcarded with null. You can listen to a specific local Row in a specific Relationship, any local Row in a specific Relationship, a specific local Row in any Relationship, or any local Row in any Relationship.

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

Examples

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

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.addRemoteRowIdListener(
  'petSpecies',
  'cujo',
  (relationships, relationshipId, localRowId) => {
    console.log('petSpecies relationship (from cujo) changed');
    console.log(relationships.getRemoteRowId('petSpecies', 'cujo'));
  },
);

store.setCell('pets', 'cujo', 'species', 'wolf');
// -> 'petSpecies relationship (from cujo) changed'
// -> 'wolf'

relationships.delListener(listenerId);

This example creates a Store, a Relationships object, and then registers a listener that responds to any changes to any local Row's remote Row. It also illustrates how you can use the getStore method and the getRemoteRowId method to resolve the remote Row as a whole.

const store = createStore()
  .setTable('pets', {
    fido: {species: 'dog', color: 'brown'},
    felix: {species: 'cat', color: 'black'},
    cujo: {species: 'dog', color: 'brown'},
  })
  .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.addRemoteRowIdListener(
  null,
  null,
  (relationships, relationshipId, localRowId) => {
    console.log(
      `${relationshipId} relationship (from ${localRowId}) changed`,
    );
    console.log(relationships.getRemoteRowId(relationshipId, localRowId));
    console.log(
      relationships
        .getStore()
        .getRow(
          relationships.getRemoteTableId(relationshipId),
          relationships.getRemoteRowId(relationshipId, localRowId),
        ),
    );
  },
);

store.setRow('pets', 'cujo', {species: 'wolf', color: 'grey'});
// -> 'petSpecies relationship (from cujo) changed'
// -> 'wolf'
// -> {price: 10}
// -> 'petColor relationship (from cujo) changed'
// -> 'grey'
// -> {discount: 0.2}

relationships.delListener(listenerId);