set-state

Heavily inspired by PureState, set-state allows simple state management by synchronously updating dependencies and dependants when state changes.

Getting Started

npm install --save set-state

Example

const state = require('set-state')

// Stateful variables are just JS values wrapped with a `state` call.
// Since the resulting function acts like a container, you can use const
const x = state(0)

// This reads a stateful variable; read as "console.log(x)"
console.log(x())

// This writes a stateful variable; read as "x = 1"
x(1)

// Stateful variables can depend on other stateful variables 
const y = state(() => x() + 1)
const z = state(() => [x(), y(), x() + y()])

console.log(x())
console.log(y())
console.log(z())

// Those above output "1", "2", "[1, 2, 3]"

// If you change a stateful variable, all variables that depend on it are updated.

x(10) // sets x to 10

console.log(x())
console.log(y())
console.log(z())

// Now those above output "10", "11", "[10, 11, 21]"

// If you use branching logic in a stateful variable, set the dependencies as default
// parameters to avoid issues with the dependency tree not updating
const a = state(true)
const b = state(2)
const c = state(($b = b()) => a() ? 1 : $b)
a(false)
console.log(c()) // yields `2` (correct)
b(3)
console.log(c()) // yields `3` (correct)

// To serialize your state, set-state provides a .toJSON method
const str_prop = state('str')
const date_prop = state(new Date(0))
JSON.stringify({str_prop, date_prop})

// "{"str_prop":"str","date_prop":"1970-01-01T00:00:00.000Z"}"

// To listen for changes, use the .on() method which returns the cancel function
const noise = state()
const cancel = noise.on(console.log.bind(console, 'I heard a'))
noise('beep') // I heard a beep
noise('boop') // I heard a boop
cancel()
noise('woops')

API

// async methods
state(a).push(a => b<Promise>) // state(b) when b resolves

// creates projections of state(a)
// all projections are sealed
state(a).pluck(path) // acts like a cursor for a(), path can be str or arr 
state(a).map(fn) // state(() => fn(a()))
state(a).flatMap(fn) // state(() => [].concat(...a().map(fn))
state(a).mapcat(fn) // alias for flatMap
state(a).concat(b, ...c) // state(() => [a(), b(), ...c()])
state(a).reduce(fn, b) // state(() => b(fn(b(), a()))), b is optional
state(a).ap(b) // state(() => b()(a())); applicative is similar to map but b is state(() => fn)
state(a).either(f, g) // state(() => f(a()) || g(a()))

// utility methods
state(a).freeze() // state(a) will no longer update, the value is still a
state(a).end() // alias for freeze
state(a).seal() // state(a) will be read-only but continue to update

// statics
// static projections are also sealed
state.merge([...arr]) // state(() => [...arr()])
state.combine({a, b}) // state(() => {a: a(), b: b()})

// static utility methods
state.of(a) // state(a)
state.freeze(a) // state(a) will no longer update, the value is still a
state.end(a) // alias for freeze
state.seal(a) // state(a) will be read-only but continue to update
state.isNode(a) // Boolean
state.isSealed(a) // Boolean
state.isFrozen(a) // Boolean