Bulb API

combinators

Working with Signals

Bulb provides many combinator functions for working with signals.

debounce(n, s) curried

Discussion

Debounces the signal s to only emit an event n milliseconds after the last burst of events.

Parameters

n

A number.

s

A signal.

Return Value

A new signal.

dedupe(s)

Discussion

Removes duplicate values from the signal s.

Parameters

s

A signal.

Return Value

A new signal.

dedupeWith(f, s) curried

Discussion

Removes duplicate values from the signal s using the comparator function f.

Parameters

f

A comparator function.

s

A signal.

Return Value

A new signal.

delay(n, s) curried

Discussion

Delays events emitted by the signal s for n milliseconds.

Parameters

n

A number.

s

A signal.

Return Value

A new signal.

encode(s, ss)

Discussion

Switches between the given signals based on the last stream value. The stream value should be the index of the stream to switch to.

Parameters

s

A signal.

ss

A list of signals.

Return Value

A new signal.

filter(p, s) curried

Discussion

Filters the signal s to only emit values that satisfy the predicate p.

Parameters

p

A predicate function.

s

A signal.

Return Value

A new signal.

fold(f, a, s) curried

Discussion

Folds the binary function f over the signal s with the starting value a. The final value is emitted when the signal completes.

Parameters

f

A binary function.

a

A starting value.

s

A signal.

Return Value

A new signal.

hold(s, t) curried

Discussion

Pauses emitting events from signal t if the most recent value from the hold signal s is truthy.

It will resume emitting events after there is a falsey value.

Parameters

s

A signal.

t

A signal.

Return Value

A new signal.

merge(ss)

Discussion

Merges the given signals into a new signal.

The signal completes when all of the input signals have completed.

Parameters

ss

A list of signals.

Return Value

A new signal.

sample(s, t) curried

Discussion

Emits the most recent value from signal t whenever there is an event on the sampler signal s.

Parameters

s

A signal.

t

A signal.

Return Value

A new signal.

scan(f, a, s) curried

Discussion

Scans the binary function f over the signal s with the starting value a. Unlike the fold function, the signal values are emitted incrementally.

Parameters

f

A binary function.

a

A starting value.

s

A signal.

Return Value

A new signal.

stateMachine(f, a, s) curried

Discussion

Folds the transform function f over the signal s with the starting value a.

The transform function f should return the new state. It can also optionally emit values or errors using the emit argument.

Parameters

f

A ternary function.

a

A starting value.

s

A signal.

Return Value

A new signal.

Example

stateMachine((a, b, emit) => {
  emit.next(a * b)
  return a + b
}, 0, s)

switchLatest(s)

Discussion

A higher-order signal function (operates on a signal that emits other signals) that emits events from the most recent signal value.

Parameters

s

A signal.

Return Value

A new signal.

throttle(n, s) curried

Discussion

Limits the rate of events emitted by the signal s to allow at most one event every n milliseconds.

Parameters

n

A number.

s

A signal.

Return Value

A new signal.

zip(ss)

Discussion

Combines corresponding values from the given signals into tuples.

The signal completes when any of the input signals have completed.

Parameters

ss

A list of signals.

Return Value

A new signal.

zipWith(f, ss)

Discussion

Generalises the zip function to combine corresponding values from the given signals using the function f.

The signal completes when any of the input signals have completed.

Parameters

f

A function.

ss

A list of signals.

Return Value

A new signal.

keyboard

Keyboard Signals

This module defines keyboard signals.

keys(target, options)

Creates a keyboard keydown signal.

Discussion

Creates a signal that emits a value if a key is pressed on the target DOM element.

If a key is held down continuously, then the signal will repeatedly emit values at a rate determined by your OS key repeat setting.

Parameters

target

A DOM element.

options

An options object.

Return Value

A new signal.

state(target, options)

Creates a keyboard state signal.

Discussion

Creates a signal that emits a value if the keyboard state changes.

When a key is pressed or released, then the signal will emit an array containing the key codes of all the currently pressed keys.

Parameters

target

A DOM element.

options

An options object.

Return Value

A new signal.

mouse

Mouse Signals

This module defines mouse signals.

buttons(target, options)

Creates a mouse button signal.

Discussion

Creates a signal that emits a value if a mouse button is pressed.

When a mouse button is pressed, then the signal will emit an integer representing the logical sum of the currently pressed button codes (left=1, right=2, middle=4).

Parameters

target

A DOM element.

options

An options object.

Return Value

A new signal.

position(target, options)

Creates a mouse position signal.

Discussion

Creates a signal that emits a value if the mouse is moved.

When the mouse is moved, then the signal will emit an array containing the mouse position.

Parameters

target

A DOM element.

options

An options object.

Return Value

A new signal.

state(target, options)

Creates a mouse state signal.

Discussion

Creates a signal that emits a value if the mouse state changes.

When the mouse is moved or a button is pressed, then the signal will emit an object representing the current state of the mouse.

Parameters

target

A DOM element.

options

An options object.

Return Value

A new signal.

Signal

The Signal class

Creates a new signal.

The mount function is called when an emit subscribes to the signal. The mount function can optionally return another function, which is called when the signal is unmounted.

always(c)

Discussion

Returns a signal that replaces the signal values with a constant.

Parameters

c

The constant value.

Return Value

A new signal.

concatMap(f)

Discussion

Returns a signal that applies the function f to the signal values. The function f must also return a Signal.

Parameters

f

A unary function that returns a new signal.

Return Value

A new signal.

debounce(n)

Discussion

Debounces the signal to only emit an event n milliseconds after the last burst of events.

Parameters

n

A number.

Return Value

A new signal.

dedupe()

Discussion

Removes duplicate values from the signal.

Parameters

Return Value

A new signal.

dedupeWith(f)

Discussion

Removes duplicate values from the signal using the comparator function f.

Parameters

f

A comparator function.

Return Value

A new signal.

delay(n)

Discussion

Delays events emitted by the signal for n milliseconds.

Parameters

n

A number.

Return Value

A new signal.

empty() static

Discussion

Returns a signal that never emits any values and has already completed.

It is not very useful on its own, but it can be used with other combinators (e.g. fold, scan, etc).

Parameters

Return Value

A new signal.

encode(ss)

Discussion

Switches between the given signals based on the last stream value. The stream value should be the index of the stream to switch to.

Parameters

ss

A list of signals.

Return Value

A new signal.

filter(p)

Discussion

Returns a signal that filters the signal values using the predicate p.

Parameters

p

A predicate function that returns truthy of falsey for a given signal value.

Return Value

A new signal.

fold(f, a)

Discussion

Returns a signal that folds the signal values with the starting value a and a binary function f. The final value is emitted when the signal completes.

Parameters

f

A binary function.

a

A starting value.

Return Value

A new signal.

fromArray(as) static

Discussion

Returns a signal that emits values from the array of as. It completes after the last value in the array has been emitted.

Parameters

as

An array of values.

Return Value

A new signal.

fromCallback(f) static

Discussion

Returns a signal that emits the result of the callback function f.

Parameters

f

A callback function.

Return Value

A new signal.

fromEvent(type, target) static

Discussion

Returns a signal that emits events of type from the EventListener-compatible target object (e.g. a DOM element).

Parameters

type

A string representing the event type to listen for.

target

A DOM element.

Return Value

A new signal.

fromPromise(p) static

Discussion

Returns a signal that emits the result of the promise p. It completes after the promise has resolved.

Parameters

p

A Promises/A+ conformant promise.

Return Value

A new signal.

hold(s)

Discussion

Pauses emitting values from the given signal s if the most recent value from the sampler signal is truthy. It will resume emitting events after there is a falsey value.

Parameters

s

A signal.

Return Value

A new signal.

map(f)

Discussion

Returns a signal that applies the function f to the signal values.

Parameters

f

A unary function that returns a new signal value.

Return Value

A new signal.

merge(ss)

Discussion

Merges the signal with the given signals.

The signal completes when all of the input signals have completed.

Parameters

ss

A list of signals.

Return Value

A new signal.

mount(emit)

Discussion

Mounts the signal with an emit.

The mount function optionally returns another function. We call this function when we want to unmount the signal.

Parameters

emit

An observer.

never() static

Discussion

Returns a signal that never emits any values or completes.

It is not very useful on its own, but it can be used with other combinators (e.g. fold, scan, etc).

Parameters

Return Value

A new signal.

of(a) static

Discussion

Returns a signal that emits a single value a. It completes after the value has been emited.

Parameters

a

A value.

Return Value

A new signal.

periodic(n) static

Discussion

Returns a signal that periodically emits a value every n milliseconds.

Parameters

n

The number of milliseconds between each emitted value.

Return Value

A new signal.

Example

// A signal that emits the value 'x' every second.
  Signal.periodic(1000).always('x')

sample(s)

Discussion

Emits the most recent value from the given signal s whenever there is an event on the sampler signal.

Parameters

s

A signal.

Return Value

A new signal.

scan(f, a)

Discussion

Returns a signal that scans the signal values with the starting value a and a binary function f.

Unlike the fold function, the signal values are emitted incrementally.

Parameters

f

A binary function that returns a new signal value for the given starting value and signal value.

a

A starting value.

Return Value

A new signal.

sequential(n, as) static

Discussion

Returns a signal that emits a value from the array of as every n milliseconds.

Parameters

n

The number of milliseconds between each clock tick.

as

A list.

Return Value

A new signal.

startWith(a)

Discussion

Creates a new signal that emits the signal value a before all other values.

Parameters

a

A signal value.

Return Value

A new signal.

stateMachine(f, a)

Discussion

Returns a new signal that runs a state machine, with the starting value a and transform function f.

The transform function should return the new state. It can also optionally emit values or errors using the emit argument.

Parameters

f

A ternary function.

a

A starting value.

Return Value

A new signal.

Example

signal.stateMachine((a, b, emit) => {
    emit.next(a * b)
    return a + b
  }, 0)

subscribe(next, error, complete)

Discussion

Subscribes to the signal with the callback functions next, error, and complete.

Parameters

next

A callback function.

error

A callback function.

complete

A callback function.

Return Value

A new subscription.

switchLatest()

Discussion

A higher-order signal function (operates on a signal that emits other signals) that emits events from the most recent signal value.

Parameters

Return Value

A new signal.

throttle(n)

Discussion

Limits the rate of events emitted by the signal to allow at most one event every n milliseconds.

Parameters

n

A number.

Return Value

A new signal.

unmount()

Discussion

Unmounts the signal.

Parameters

zip(s)

Discussion

Combines corresponding values from the given signals into tuples.

The signal completes when any of the input signals have completed.

Parameters

s

A signal.

Return Value

A new signal.

zipWith(f, ss)

Discussion

Generalises the zip function to combine corresponding values from the given signals using the function f.

The signal completes when any of the input signals have completed.

Parameters

f

A function.

ss

A list of signals.

Return Value

A new signal.

Subscription

The Subscription class

Creates a new subscription for the emit object.

The observer may unsubscribe from the signal by calling the unsubscribe method.

unsubscribe

Discussion

Unsubscribes the observer from the signal.