The reactive library for the spreadsheet driven development
import { cell, formula, swap, deref } from '@snapview/sunrise'
const inc = (a) => a + 1
// Source Cell with initial value 1
const x = cell<number>(1)
// Formula Cell created by incrementing the source cell
const y = formula(inc, x)
// Formula Cell without any value, but with side effect
const printCell = formula(console.log, y)
// Swapping the value of initial source cell
swap(inc, x)
deref(x) // 2
deref(y) // 3, this value is already printed to console because of printCell
Sunrise provides a spreadsheet-like computing environment consisting of source cells and formula cells and introduces the Cell interface to represent both
The source cell is just a container including a value of arbitrary type. To construct the source cell the cell function should be used
const a = cell<number>(1) // a cell of number
const b = cell<string>('hello') // a cell of string
const c = cell({ x: 1, y: 2 }) // an object cell
const d = cell<string | undefined>(undefined) // a cell that can be either string or undefined
To receive the current value of a cell the deref function is used. Unlike many other reactive libraries in Sunrise this is considered to be a totally valid operation. A cell is not a stream or any other magic thing, it's just a box with a value inside
deref(a) // 1
deref(b) // 'hello'
deref(c) // { x: 1, y: 2 }
deref(d) // undefined
There are two ways to change a value inside a cell reset and swap. reset just sets a new value to and swap accepts a function from old value to new value, applies it and swap the cell to the new value
const a = cell<number>(1)
reset(2, a)
deref(a) // 2
swap((x) => x + 1)
deref(a) // 3
reset and swap are async operations, the new value will be set not immediately, but they implement the Software Transaction Memory and they are always consistent.
In case you don't need a cell anymore, the cell can be destroyed with the destroy function. Be careful because destroying the cell will also destroy all the dependent cells as well. After the destruction, any operation on a cell is illegal, and throw the OperationOnDestroyedCellError
const x = cell<number>(1)
const y = formula((a) => a + 1, x)
destroy(x) // both x and y are destroyed now
A formula cell is a sort of materialized view of a function. You can look at it as a cell with a formula inside in some table processor program. To create a formula cell you need a formula (function) and an arbitrary number of source cells as an input
const a = cell<number>(1)
const b = formula((x) => x + 1, a) // now b is always an increment of a
deref(b) // 2
reset(5, a)
deref(b) // 6
You can also use simple values as input to formula instead of cells. This might be quite handy when you don't know if the input is a cell or just a value
const x = cell<number>(1)
const y = cell<number>(2)
const z: number = 3
const sum = formula((a, b, c) => a + b + c, x, y, z)
deref(sum) // 6
reset(5, x)
deref(sum) // 10
There are quite some formula cells predefined for faster cell generations
Object's field
To extract one field from an object you can use the field function
const x = cell({ a: 1, b: 2 })
const fld = field('a', x)
deref(fld) // 1
swap((x) => ({ ...x, a: 2 }), x)
deref(fld) // 2
An element of an array
To extract an element from an array by index you can use the byIndex function. The type of the result is Cell<T | undefined> because it's not guaranteed that the element is presented
const x = cell(['a', 'b', 'c'])
const el = byIndex(1, x)
deref(el) // 'b'
swap((x) => ['z', ...x], x)
deref(el) // 'a'
Convert to boolean
To check that an element is truthy you can use the toBool function.
const x = cell(1)
deref(toBool(x)) // true
const y = cell<string | undefined>(undefined)
deref(toBool(y)) // false
Negation
const x = cell<boolean>(true)
deref(not(x)) // false
const y = cell(1)
deref(not(y)) // false
History
In some cases, it's useful to have both the old cell's value and the new one. For this purpose, history can be used. It serves a tuple with the old and new
values inside. Be aware, initially, the old value is undefined
const x = cell<number>(1)
const hist = history(x)
deref(hist) // [1, undefined]
reset(2, x)
deref(hist) // [2, 1]
Author: snapview
Download Link: Download The Source Code
Official Website: https://github.com/snapview/sunrise
License: MIT
#typescript