[![npm-badge][npm-badge]][npm]
![types-badge][types-badge]

mi-signal

> Signal for reactive behavior

Only weights 0.5kB minified and gzipped.

Signal is the core for any reactive behavior of [mi-element][].
It loosely follows the [TC39 JavaScript Signals standard proposal][].

Table of contents

* Usage
* State, createSignal
* effect
* DONT'S
* Computed Signals

Usage

In your project:

``
npm i mi-signal
`

State, createSignal

Reactive state and its subscribers is managed in this class. With
.set(nextValue) and .get() access to the state is achieved.

For convenience there is a createSignal(initialValue): State function to
create a signal.

`js
import { createSignal, State } from 'mi-signal'

const signal = createSignal(1)
// same as
const signal = new State(1)

signal.get()
//> 1
signal.set(4)
signal.get()
//> 4
`

Instead of .get() or .set(next) .value with either getter or setter can be used.

`js
const signal = createSignal(1)

signal.value
//> 1
signal.value = 4
signal.value
//> 4
`

For controlling the notifications to subscribers, the signal option equals for
a custom comparison function can be used, e.g. to trigger an effect on every
.set(nextValue)

`js
// default is:
const equals = (value, nextValue) => value === nextValue
// changes to trigger change on every .set()
const equals = (value, nextValue) => true
const signal = createSignal(initialValue, { equals })
`

effect

Reactivity is achieved by subscribing to a signals State using an effect
callback function. Such callback function is called for registration to the
signals state as well as to update on any change through
signal.set(nextValue). Within that callback the signal.get() must be called
_synchronously_!

`js
import { createSignal, effect } from 'mi-signal'

const signal = createSignal(1)

const callback = () => console.log('value is %s', signal.get())
// callback is executed with assigning to the effect!
const unsubscribe = effect(callback)
//> "value is 1"
signal.set(4)
//> "value is 4"

// Signal.effect returns a function to unsubscribe callback from the signal
unsubscribe()
signal.set(5)
// gives no console.log output
`

For asynchronous usage, request the value from the signal first. Otherwise no
subscription to the signal will take place.

`js
const signal = createSignal(1)

const callback = async () => {
// synchronously get the value
const value = signal.get()
const p = Promise.withResolvers()
setTimeout(() => {
console.log('value is %s', )
p.resolve()
}, 100)
}.catch(() => {})
// callback is executed with assigning to the effect!
effect(callback)
`

$3

Effects are executed synchronously for a better debugging experience. But be
warned to never set the signal in the an effects callback!

`js
const signal = createSignal(0)

// DON'T DO THIS
effect(() => {
const value = signal.get()
signal.set(value++) //< meeeeh
})
`

The signal value getter triggers the registration of the callback through the
effect. So don't hide a signals getter inside conditionals!

`js
const signal = createSignal(0)
const rand = Math.random()

// DON'T DO THIS
effect(() => {
if (rand < 0.5) {
console.log(signal.get()) //< meeeeh
}
})

// DO THIS
effect(() => {
const value = signal.get() //< much better
if (rand < 0.5) {
console.log(value)
}
})
`

Computed Signals

Computed signals from more than one signal can be obtained from Computed.

`js
const firstName = createSignal('Joe')
const lastName = createSignal('Doe')
// define computed signal
const name = new Computed(() => ${firstName.get()} ${lastName.get()})
const events = []
// apply effect
effect(() => console.log(name.get()))
//> 'Joe Doe'
firstName.set('Alice')
//> 'Alice Doe'
lastName.set('Wonderland')
//> 'Alice Wonderland'
``

License

MIT licensed

[TC39 JavaScript Signals standard proposal]: https://github.com/tc39/proposal-signals
[mi-element]: https://github.com/commenthol/mi-element/tree/main/packages/mi-element

[npm-badge]: https://badgen.net/npm/v/mi-signal
[npm]: https://www.npmjs.com/package/mi-signal
[types-badge]: https://badgen.net/npm/types/mi-signal