^{Social Media Photo by Carlos Alberto Gómez Iñiguez on Unsplash}

A minimalistic Preact-like signals implementation.

Once minified and compressed, this module is actually 0.5KB.

// basic core features
import {
  Signal,     // class for brand check
  Computed,   // extends Signal: brand check
  batch,      // Preact-like API
  computed,   // Preact-like API
  effect,     // Preact-like API
  signal,     // Preact-like API
  untracked,  // Preact-like API
} from '@webreflection/signals';

Exposes a Preact-like createModel utility with a disposable export.

// extra core features
import {
  // extra:
  disposable, // equivalent of createModel(fn)
  // all other exports from core
  ...core
} from '@webreflection/signals/disposable';

• simply (swapped) stack-based, maybe not the best approach, but one that can guarantee reasonable performance with minimal code size.
• only signal and computed subscribe while reading values, unless sig_or_comp.peek() is used.
• any effect updates synchronously but then runs only in isolation. Every effect is disposed of if the outer effect is running, meaning stacked effects work out of the box and always™ do the right thing.
• disposable uses the very same effect logic to dispose itself when not needed anymore.
• batch piles up subscribers and filters at the end for those that didn't get trashed in between (not perfect, yet fast).
• untracked temporarily disables subscription in both read (for symbol and computed) and write (for symbol only).

You know, nowadays it's hard to find libraries that are still 100% under control, minimalistic, not bloated, yet correct, and this one would like to be one of those 😇

Fine-tuned signals are a piece of art:

• fastest possible feedback
• linked graphs with bitwise flags deciding what to do and/or when (alien-signals)
• transpiled and understood ahead of time to produce the best possible outcome (Svelte, SolidJS)
• ad-hoc or coupled DOM manipulation
• specific to JSX syntax (Preact or alternatives)
• ... other attempts/variants out there

That is all good and fine, yet the graph behind signals is, imho, pretty simple in theory (clearly hard in practice) ... and I will tell you how this module keeps that simple concept in mind.

const num = signal(0);

const dispose = effect(() => {
  // subscribe to this signal state
  const value = num.value;

  // make this effect able to dispose itself
  if (2 <= value) {
    // no further changes to num will be observed
    dispose();
  }
  else {
    console.log({ value });
  }
});

// logs: { value: 0 }

// increment by 1
num.value++;
// logs: { value: 1 }

// increment by 1
num.value++;
// logs nothing!

// drop reactivity explicitly!
dispose();

// increment by 1
num.value++;
// also logs nothing!

This module aims to be Preact-like, not a byte-for-byte or behavior-for-behavior clone of Preact Signals. The goal is to keep the core small, predictable, and easy to reason about, while still exposing Signal and Computed classes for projects that want to specialize any behavior.

The following differences are intentional tradeoffs:

• assigning the same value still notifies subscribers. If you want distinct-value semantics, extend Signal and provide your own factory:

import { Signal as WRSignal } from '@webreflection/signals';

class Signal extends WRSignal {
  get value() {
    return super.value;
  }

  set value(value) {
    if (!Object.is(this.peek(), value)) {
      super.value = value;
    }
  }
}

export const signal = value => new Signal(value);

• conditional dependencies are not pruned after every run. Instead, subscribers are kept by the signal or computed reference and are pruned lazily when that source notifies again, skipping disposed effects along the way. This might look "leaky" at first glance, but every Signal and Computed implements native Symbol.dispose, so the latest JavaScript using syntax can deterministically clear retained subscribers when a scope is done:

{
  using count = signal(0);
  using doubled = computed(() => count.value * 2);

  effect(() => console.log(doubled.value));
}
// count and doubled are disposed here

If a source is no longer referenced, normal garbage collection takes care of it; if it is still referenced, the next notification keeps the final value valid and fast enough to retrieve without maintaining a more complex dependency graph.

• mixed direct signal reads and derived computed reads can observe an intermediate stale computed value in the same effect, because there is no graph ordering involved. For example, reading both count.value and doubled.value where doubled is computed from count can briefly see the updated count with the previous doubled before the computed invalidation catches up. This is the little extra cost paid by a not-so-common scenario to keep the library as small as it is.

• batch(callback) coalesces execution, but it does not perform Preact's final-value reconciliation. This follows from the first point: signals do not compare old and new values, so signal.value = signal.value is still a notification. That can be a desirable pattern in some cases; for every other "don't do that" case, extend Signal as shown above.

• effect(callback) callbacks must return either void or a cleanup function, as specified by the TypeScript contract. Returning any other value is unsupported and will throw later if that value is invoked as cleanup.

• extra Preact APIs such as subscribe, valueOf, toJSON, and action are outside the minimal core. You can extend the exported classes to add the hooks that make sense for your project. Preact's createModel API surface is covered as much as this module needs by the explicit @webreflection/signals/disposable entry point and its disposable exported utility, so model-style disposal stays available when imported on purpose without being embedded into the default signals primitive.

Because the public shape intentionally follows the Preact Signals API, this module can also be replaced by the real Preact Signals package whenever a project needs its full graph, helpers, or framework integrations. In that sense, it is meant to make the API familiar without forcing anyone to keep using this smaller implementation, or its intentional constraints, forever.