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<T>): State<T> function to create a signal.

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.

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)

// 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!

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.

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)

DONT'S

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

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!

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.

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