acto
A signals library for functional reactive programming. Author: Tim Farland
- Inspired by Elm and Bacon.js.
- Written without the use of
this,new, orprototype- only simple objects and functions. - Miniscule size - ~2kb minified/gzipped.
- For modular use in node or browsers.
- Written in Typescript.
- License: MIT.
Install
npm install --save acto
Test
npm test
Importing
import { create, listen, send /* etc */ } from 'acto' Api
Signal interface
Signals are simple objects with the following interface:
interface Signal<T> {
listeners: Array<(T) => any>
active: boolean
value: T | null
stop?: Function
}Creating signals
fromDomEvent
Capture events on a dom node.
// fromDomEvent (node: Node, eventName: string): Signal<Event>
const clicks = fromDomEvent(document.body, "click", evt => console.log(evt.target))fromCallback
A signal that will emit one value, then terminate.
// fromCallback<T> (f: Callback<T>): Signal<T>
const later = fromCallback(callback => setTimeout(() => callback("Finished"), 1000))fromPromise
A signal that will emit one value or an error from a Promise, then terminate.
// fromPromise (promise: Promise<any>): Signal<any>
const wait = fromPromise(new Promise(resolve => setTimeout(() => resolve("Finished"), 1000)))fromAnimationFrames
// fromAnimationFrames (): Signal<number>
const frames = fromAnimationFrames()A signal that fires on every window.requestAnimationFrame. Useful in combination with sampleOn.
fromInterval
A signal that emits an integer count of millisecond intervals since it was started.
// fromInterval (time: number): Signal<number>
const seconds = fromInterval(1000)create
Low-level signal creation.
// create<T> (initialValue?: T): Signal<T>
const rawSignal = create()
const rawSignalWithInitialValue = create(123)Interacting with signals
listen / unlisten
Subscribe / unsubscribe to values emitted by the signal.
// listen<T> (s: Signal<T>, f: Listener<T>): Signal<T>
// unlisten<T> (s: Signal<T>, f: Listener<T>): Signal<T>
function logger (e) { console.log(e) }
listen(clicks, logger)
unlisten(clicks, logger)send
Send a value to a signal.
// send<T> (s: Signal<T>, v: T): Signal<T>
send(rawSignal, "value")stop
Stop a signal - no more values will be emitted.
// stop<T> (s: Signal<T>): Signal<T>
stop(rawSignal)Transforming signals
map
Map values of a signal
// map<T> (f: Mapper<T>, signal: Signal<any>): Signal<T>
const values = map(evt => evt.target.value, fromDomEvent(input, "keydown"))Map (zip) the latest value of multiple signals
// map<T> (f: Mapper<T>, ...signals: Signal<any>[]): Signal<T>
const areas = map((x, y) => x * y, widthSignal, heightSignal)filter
Filter a signal, will only emit event that pass the test
// filter<T> (f: Filter<T>, s: Signal<T>): Signal<T>
const evens = filter(n => n % 2 === 0, numberSignal)dropRepeats
Only emit if the current value is different to the previous (as compared by ===). Not a full deduplication.
// dropRepeats<T> (s: Signal<T>): Signal<T>
dropRepeats(numbers)fold
Fold a signal over an initial seed value.
// fold<T,U> (f: Folder<T,U>, seed: U, s: Signal<T>): Signal<U>
const sum = fold((a, b) => a + b, 0, numbersStream)merge
Merge many signals into one that emits values from all.
// merge (...signals: Signal<any>[]): Signal<any>
const events = merge(clicks, keypresses)sampleOn
Take the last value of a signal when another signal emits.
// sampleOn<T,U> (s: Signal<T>, s2: Signal<U>): Signal<T>
const mousePositionsBySeconds = sampleOn(mousePosition, fromInterval(1000))slidingWindow
Emit an array of the last n values of a signal.
// slidingWindow<T> (length: number, s: Signal<T>): Signal<T[]>
const trail = slidingWindow(5, mousePosition)flatMap
Map values of a signal to a new signal, then flatten the results of all emitted into one signal.
// flatMap<T,U> (lift: Lifter<T,U>, s: Signal<T>): Signal<U>
const responses = flatMap(evt => fromPromise(ajaxGet("/" + evt.target.value)), keyPresses)flatMapLatest
The same as above, but only emits values from the latest child signal.
// flatMap<T,U> (lift: Lifter<T,U>, s: Signal<T>): Signal<U>
flatMapLatest(v => fromPromise(promiseCreator(v)), valueSignal)debounce
Debounce a signal by a millisecond interval.
// debounce<T> (s: Signal<T>, quiet: number): Signal<T>
const debouncedClicks = debounce(mouseClicks, 1000)Error handling
To put a signal in an error state, send a native Error object to it, which will set it's value to the error, e.g:
const signal = create()
listen(signal, v => console.log(v))
send(signal, 1) // 1
send(signal, new Error("Disaster has struck")) // [Error: Disaster has struck]So your listeners need to be handle the case that the the type of any signal value may also be an Error.
As errors are just values, they're propagated downstream by the same mechanism:
const source = create()
const mapped = map(v => v > 1 ? new Error("I can't handle this") : v, source)
listen(mapped, v => console.log(v))
send(source, 1) // 1
send(source, 2) // [Error: I can't handle this]Errors do not stop signals.