super-simple-signal
v0.4.2
Published
A super simple signal implementation in TypeScript for the browser.
Downloads
16
Maintainers
Readme
What Is This?
This is a super simple signal library for browser. It's mostly an experiment which provided good benchmarks and a nice, clean and simple API. It's also very small, weighing in at 296B minified and gzipped.
Installation
npm install super-simple-signal
Usage
Basic
<!-- Load the library from your node_modules or from a CDN -->
<script src="./node_modules/super-simple-signal/index.js"></script>
<script>
// Create a new signal with the initial value of 0
const signal = new Signal(0);
// Subscribe to the signal
signal.subscribe(value => {
console.log(value);
});
// Attach the signal to a DOM node
window.addEventListener("load", () => {
const s1 = document.getElementById("s1");
signal.attachTo(s1);
});
</script>
<div id="s1"></div>
<!-- Update signal value on button click -->
<button onclick="signal.value++">Click me</button>
API
Signal
A Signal
is a reactive javascript variable which can be attached to a DOM node and create a one-way or two-way data binding mechanism with it.
new Signal(value)
Creates a new signal with the given initial value.
new Signal(node)
Creates a new signal which is attached to the given node.
new Signal(node, value)
Creates a new signal which is attached to the given node and has the given initial value.
new Signal(node, value, opts)
Creates a new signal which is attached to the given node and has the given initial value. The opts object can have the following properties:
property
- The property of the node to attach to. Defaults toinnerHTML
.bind
- Whether to bind the signal to the node. Defaults totrue
. If so, the signal will be updated whenever the node'sbindEvents
are fired.bindEvents
- The events to bind to. Defaults to an empty array.render
- A function which will be called whenever the signal's value changes. The function will be called with the new value as the first argument. This means you can have a signal value of any type and render it however you want.allowDirty
- Whether to allow dirty values. Defaults tofalse
. If so, the signal will fire its subscribers and re-render even if the value hasn't changed.
signal.value
The current value of the signal. Setting this will update the signal's value and call all the signal's subscribers and re-render the signal's node.
signal.subscribe(callback)
Subscribes the given callback to the signal. The callback will be called whenever the signal's value changes. The callback will be called with the new value as the first argument and the old value as the second argument.
signal.unsubscribe(callback)
Unsubscribes the given callback from the signal.
signal.attachTo(node, property)
Attaches the signal to the given node. The signal will update the node's given property whenever the signal's value changes. Defaults to innerHTML
. If the signal already has a node attached, it will be detached first.
signal.detach()
Detaches the signal from the current node.
signal.copyTo(node, opts, keepInSync)
Copies the signal's value to the given node. This will actually create a new Signal
. If keepInSync
is true
, the new signal will be updated whenever the initial signal changes. Defaults to true
. To prevent circular updates, we only subscribe to the signal if keepInSync is true and don't subscribe back.
Computed
A Computed
is a Signal
which is dependent on given input signals.
Its API, being a Signal itself, is totally compatible with the Signal, with some differences explained below.
new Computed(dependencies, fn, node, opts)
Creates a new Computed which is attached to the given node and has the given initial value.
It takes the following parameters:
dependencies
: An array of Signals from which the Computed depends.fn
: The function to be called whenever a dependency changes. It takes the Signalvalue
as the first parameter, the SignaloldValue
as the second parameter and thecomputedOldValue
as the third parameter.node
: The node to attach the Computed to.opts
: A Signal-compatible opts parameter.
Benchmarks
If you open the examples/bechmark.html
file in your browser, you can see the time needed to update 3 signals 100.000 times with random numbers. The results are as follows on a 2021 Macbook Pro M1 Max with 32GB of RAM:12ms for 300.000 updates
ToDo
- [ ] Add tests