Equivalence

You can control how the value of a cell is compared to determine if it needs to be updated by specifying an equality function.

tsx
import { Cell } from "@starbeam/universal";
 
const person = { name: "John", age: 30 };
 
const cell = Cell(person, {
  equals: (a, b) => a.name === b.name && a.age === b.age,
});

tsx
import { Cell } from "@starbeam/universal";
 
const person = { name: "John", age: 30 };
 
const cell = Cell(person, {
  equals: (a, b) => a.name === b.name && a.age === b.age,
});

If we update the cell with an equivalent value (according to the equals function), the original object will remain in the cell.

tsx
cell.set({ name: "John", age: 30 });
expect(cell.current).toBe(person);

tsx
cell.set({ name: "John", age: 30 });
expect(cell.current).toBe(person);

If we update the cell with a non-equivalent value, the value will update.

tsx
cell.set({ name: "John", age: 31 });
expect(cell.current).not.toBe(person);

tsx
cell.set({ name: "John", age: 31 });
expect(cell.current).not.toBe(person);

This example using Object.is to demonstrate that the original value is still in the cell.

In actual code, if you find yourself caring about the identity of the value in the cell, you probably don't want to use an equals function that causes objects with new identities to be ignored.

Equivalence ​

Equivalence