Signaller

Call a function when a value changes.

Multiple changes are handled efficiently, making this library useful to propagate new application state to components.

390 bytes (minified + gzipped).

If you're viewing this on the web, Signaller, watch(), and use(), are available to try in your JavaScript console.

Installation

Either use src/signaller.js directly as a JavaScript module or install it via a package manager.

npm install signaller

Example

import {Signaller, use} from "signaller.js";

// Create some Signallers to hold state.
const name = new Signaller("Pickles");
const count = new Signaller(10);

// Call a function now and when a value changes.
use([name, count], () => {
    console.log(`${name.value}: ${count.value}`);
});

// Multiple synchronous updates will only call
// the function once with the latest value.
name.value = "Bananas";
name.value = "Cookies";
count.value++;

// Hmmm. More cookies, please.
setTimeout(() => count.value = 200, 1000);

Output:

Pickles: 10
Cookies: 11
Cookies: 200

Tests

deno test

Signaller(initial)

Represents a value that may change multiple times.

Properties

.value

The current value of the Signaller. Setting this property to a value that is not strictly equal to the old value will automatically call signal().

Methods

.signal()

Takes all callbacks from the waiting list (clearing it) and calls each callback synchronously in the order they were added.

You do not need to call this function directly unless you have mutated the underlying value and wish to signal the change to any watchers manually.

.wait(callback)

Appends a callback to the waiting list that will be called on the next signal. The callback function is called with this Signaller instance as its only argument. Its return value is ignored.

Normally, you would use use() or watch() instead of calling this method directly.

.unwait(callback)

Removes the first matching callback from the waiting list (if any). Does nothing if callback has not been registered and will not throw.

Normally, you would use the stop function returned by use() or watch() instead of calling this method directly.

watch(signallers, handler)

Watches an Array of Signallers for changes.

The handler will always be called asynchronously following a signal. Multiple signals before the next handler completes will not queue multiple handler calls. This means not every intermediate value of a Signaller will necessarily be seen by the handler.

The handler receives an Array of Signaller instances that have signalled since the last time the handler was called. If the handler returns a Promise, the handler will not be called again until the Promise completes.

Returns

A function to stop watching for signals. After calling this function, the handler is guaranteed to not be called by again even if a signal is queued.

use(signallers, handler)

Immediately calls the handler with an Array of Signallers, then watches the Signallers for changes.

Multiple signals before the next handler completes will not queue multiple handler calls. This means not every intermediate value of a Signaller will necessarily be seen by the handler.

The handler receives an Array of Signaller instances that have signalled since the last time the handler was called (or all signallers on the first call). If the handler returns a Promise, the handler will not be called again until the Promise completes.

Returns

A function to stop watching for signals. After calling this function, the handler is guaranteed to not be called by again even if a signal is queued.