`setRelationshipDefinition`

The setRelationshipDefinition method lets you set the definition of a Relationship.

setRelationshipDefinition(
  relationshipId: string,
  localTableId: string,
  remoteTableId: string,
  getRemoteRowId: string | (getCell: GetCell, localRowId: string) => string,
): Relationships

	Type	Description
`relationshipId`	`string`	The `Id` of the `Relationship` to define.
`localTableId`	`string`	The `Id` of the local `Table` for the `Relationship`.
`remoteTableId`	`string`	The `Id` of the remote `Table` for the `Relationship` (or the same as the `localTableId` in the case of a linked list).
`getRemoteRowId`	`string \| (getCell: GetCell, localRowId: string) => string`	Either the `Id` of the `Cell` containing, or a function that produces, the `Id` that is used to indicate which `Row` in the remote `Table` a local `Row` is related to.
returns	`Relationships`	A reference to the `Relationships` object.

Every Relationship definition is identified by a unique Id, and if you re-use an existing Id with this method, the previous definition is overwritten.

An Relationship is based on connections between Row objects, often in two different Table objects. Therefore the definition requires the localTableId parameter to specify the 'local' Table to create the Relationship from, and the remoteTableId parameter to specify the 'remote' Table to create Relationship to.

A linked list Relationship is one that has the same Table specified as both local Table Id and remote Table Id, allowing you to create a sequence of Row objects within that one Table.

A local Row is related to a remote Row by specifying which of its (local) Cell values contains the (remote) Row Id, using the getRemoteRowId parameter. Alternatively, a custom function can be provided that produces your own remote Row Id from the local Row as a whole.

Examples

This example creates a Store, creates a Relationships object, and defines a simple Relationship based on the values in the species Cell of the pets Table that relates a Row to another in the species Table.

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

const relationships = createRelationships(store);
relationships.setRelationshipDefinition(
  'petSpecies', // relationshipId
  'pets', //       localTableId to link from
  'species', //    remoteTableId to link to
  'species', //    cellId containing remote key
);

console.log(relationships.getRemoteRowId('petSpecies', 'fido'));
// -> 'dog'
console.log(relationships.getLocalRowIds('petSpecies', 'dog'));
// -> ['fido', 'cujo']

This example creates a Store, creates a Relationships object, and defines a linked list Relationship based on the values in the next Cell of the pets Table that relates a Row to another in the same Table.

import {createRelationships, createStore} from 'tinybase';
const store = createStore().setTable('pets', {
  fido: {species: 'dog', next: 'felix'},
  felix: {species: 'cat', next: 'cujo'},
  cujo: {species: 'dog'},
});

const relationships = createRelationships(store);
relationships.setRelationshipDefinition(
  'petSequence', // relationshipId
  'pets', //        localTableId to link from
  'pets', //        the same remoteTableId to link within
  'next', //        cellId containing link key
);

console.log(relationships.getLinkedRowIds('petSequence', 'fido'));
// -> ['fido', 'felix', 'cujo']

Since

v1.0.0