/warg

A reactive stream thing

Primary LanguageTypeScript

A basic reactive/stream library

This library is designed to make dirty reads impossible - i.e. your computed properties will only be called when there is a consistent state for them to run on.

This library runs calculations synchronously and eagerly. If you have a ton of upstream data changing and want lazy calculations, use shiz.

Install

npm i warg

CommonJS:

const { value, computed } = require('warg')

ESM:

import { value, computed } from 'warg'

Examples

const numbers = value([ 1, 2, 3, 42, 69])
const factor = value(2)
const multipliedArray = computed({
	numbers,
	factor,
}, ({ numbers, factor }) => numbers.map(number => number * factor))

multipliedArray.get() // => [ 2, 4, 6, 84, 138 ]

API

wargObservable = value(initialValue)

Returns a warg observable with a set method.

const wat = value('sup')

wat.get() // => 'sup'

wat.set('dawg')

wat.get() // => 'dawg'

wargObservable = computed(dependencies, computeFunction)

Takes in an object of dependency observables and returns a new warg observable that combines them together with your given function.

const small = value(1)

const bigger = computed({
	number: small
}, ({ number }) => number + 1)

const multiplied = computed({
	a: small,
	b: bigger,
}, ({ a, b }) => a * b)

multiplied.get() // => 2

Warg observable

Besides any methods above, warg observables have these methods:

wargObservable.get()

Returns the current value.

newWargObservable = wargObservable.map(computeFunction)

Sugar for newWargObservable = computed({ wargObservable }, ({ wargObservable }) => computeFunction(wargObservable)).

const a = value(6)
const special = a.map(value => value * 7)
special.get() // 42

unsubscribe = wargObservable.subscribe(callback)

Calls the callback function whenever the observable value changes.

Also calls the callback function with the current value right away when subscribe is called.

value('whu?').subscribe(str => {
	str // => 'whu?'
})

Events

Warg observables are also event emitters, though the events are more for internal library use. You probably won't need them.

These events are fired:

  • dirty - fired whenever a warg observable knows that it, or one of its dependencies, is changed. You may not read from the observable after this point, until it finishes resolving.
  • value - fired whenever a warg observable is resolved and becomes readable again - essentially, whenever its value has changed.

Because warg resolves all changes synchronously in the same tick, you should never need to worry about values becoming dirty and resolving themselves. That all happens behind the scenes before your set call completes.

License

WTFPL