Skip to main content

Getting Started with cells

Install​

To get started install the package using npm or yarn:

npm i @okcontract/cells

How to use​

import { Sheet } from "@okcontract/cells";

// create a new Sheet, typically one per application
const sheet = new Sheet();

// that's a cell
const cellA = sheet.new(1);

// no need to wait for anything, values and computations will
// be called automatically when they're ready
const cellB = sheet.new(getValueAfterDelay(2, 100));

// that's a _mapped_ cell, that is recomputed automatically when
// either dependent cells are updated
const sum = sheet.map([cellA, cellB], (a, b) => a + b);

// you can map a single cell directly
// and feel free to define mapped cells before their values are available
const prod = cellB.map((v) => 2 * v);

// we await _only_ when we need results
expect(await prod.get()).toBe(4);

// you can update _value_ cells directly (no await)
cellA.set(3);
expect(await sum.get()).toBe(5);

// map computations can be async too
const ok = someCell.map(async (v) => {
  const errors = await validate(v);
  return errors.length === 0;
});

Note that:

  • .get() never returns undefined and cells semantics waits until cell values are defined. If you need to immediately return a value, use null instead.
  • At any time, the actual cell value is accessible through cell.value (possibly undefined) but it's advisable to avoid relying on a value that could be updated at any moment.