faemto v0.2.1

Faemto

Faemto is a signals library for functional reactive programming based on Tim Farland's acto.

• No this, new, or prototype
• ~900 bytes minified + gzipped
• ES2015 modules with pkg.module, IIFE and CJS builds

Install

npm install --save faemto

Test

npm test

Importing

import { create, listen, send /* etc */ } from 'faemto'

Example

import { create, send } from 'faemto'
import { equal, deepEqual } from 'assert'

const signal = create([0, 1, 2]) // function with a minimal interface (see below)
deepEqual(signal(), [0, 1, 2])	 // true

signal([7, 8, 9])
deepEqual(signal(), [7, 8, 9])	 // true

send(signal, 1)
equal(signal(), 1) 		 // true

API

Signal

Signals are simple functions with the following signature and interface.

// Signal<T> (value: T): Signal<any>
// Signal<T> (): T | null
interface Signal<T> {
  v:          	 T | null
  active:    	 boolean
  listeners:	 Array<(T) => any>
  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.