alien-signals

Version 2.0 rethinks and optimizes the reactive system model, with minimal impact on users who only use the surface APIs. If you extend or deeply utilize alien-signals, please pay attention to the "Reactive Model Refactor" section.

Changes to Surface APIs

• Added four new APIs: getCurrentSub, setCurrentSub, getCurrentScope, setCurrentScope

Deferred Signal Value Evaluation

Differences from v1

In v1, assigning a value to a signal immediately propagated the Dirty flag, causing some computed values to be unnecessarily re-evaluated.

// v1
const src = signal(10);
const double = computed(() => src() * 2);

double(); // -> 20

src(999); // double.flags -> Dirty
src(10);  // no effect

double(); // -> 20 (recomputed unnecessarily)

In v2, assigning a value to a signal only propagates the Pending flag, reducing unnecessary recomputation. Actual evaluation occurs during the next read.

// v2
const src = signal(10);
const double = computed(() => src() * 2);

double(); // -> 20

src(999); // src.flags -> Dirty, double.flags -> Pending
src(10);  // no effect

double(); // Checks src state -> unchanged, no recomputation needed

Effect Scope Parent-Child Hierarchy

In v2, recursive cleanup is achieved through a parent-child structure:

const scope1 = effectScope(() => {
	const scope2 = effectScope(() => {
		effect(() => ...);
		computed(() => ...);
	});
});

scope1();

Calling scope1() automatically cleans up its child scope scope2.

To make scope2 independent of scope1, temporarily set activeScope = undefined manually:

const scope1 = effectScope(() => {
	const prev = setCurrentScope(undefined);
	const scope2 = effectScope(() => {
		effect(() => ...);
		computed(() => ...);
	});
	setCurrentScope(prev);
});

Reactive Model Refactor

• Merged Subscriber and Dependency into ReactiveNode
• Trigger unwatched(dep) when all subscribers are lost, without recursively clearing subsequent subscribers
• propagate now only propagates Pending; to immediately mark Dirty, call propagate + shallowPropagate after assignment
• Adjusted naming for EffectFlags and ReactiveFlags; removed unused flags

Updated Options and APIs

• notifyEffect → notify
• updateComputed → update
• Added the unwatched option for custom handling when all subscribers are lost
• Removed processEffectNotifications, processComputedUpdate, processPendingInnerEffects, updateDirtyFlag
• Added unlink, checkDirty

For performance differences, please refer to js-reactivity-benchmark.

Contributors

• @johnsoncodehk
• @sxzz
• @medz
• @wangshunnn
• @jh-leong
• @akshar-dave
• @transitive-bullshit
• @PuruVJ
• @amb26
• @tomByrer
• @zhangenming
• @yamanoku
• @Nicell
• @AimWhy
• @Mox93

Thanks~

<table> <tbody> <tr> <td align="center" valign="middle" colspan="6"> <b>Special Sponsor</b> </td> </tr> <tr> <td align="center" valign="middle" colspan="6"> <br> <a href="https://voidzero.dev/"> <img src="https://raw.githubusercontent.com/johnsoncodehk/sponsors/master/logos/VoidZero.svg" height="60" /> </a> <h3>Next Generation Tooling</h3> </td> </tr> <tr> <td align="center" valign="middle" colspan="6"> <b>Platinum Sponsors</b> </td> </tr> <tr> <td align="center" valign="middle" width="50%" colspan="3"> <a href="https://vuejs.org/"> <img src="https://raw.githubusercontent.com/johnsoncodehk/sponsors/master/logos/Vue.svg" height="80" /> </a> <p>An approachable, performant and versatile framework for building web user interfaces.</p> </td> <td align="center" valign="middle" colspan="3"> <a href="https://stackblitz.com/"> <img src="https://raw.githubusercontent.com/johnsoncodehk/sponsors/master/logos/StackBlitz.svg" width="240" /> </a> <p>Stay in the flow with instant dev experiences.<br>No more hours stashing/pulling/installing locally</p> <p><b> — just click, and start coding.</b></p> </td> <tr> <td align="center" valign="middle" colspan="3"> <a href="https://www.jetbrains.com/"> <img src="https://raw.githubusercontent.com/johnsoncodehk/sponsors/master/logos/JetBrains.svg" width="80" /> </a> <p>Essential tools for software developers and teams.</p> </td> <td align="center" valign="middle" colspan="3"> </td> </tr> <tr> <td align="center" valign="middle" colspan="6"> <b>Silver Sponsors</b> </td> </tr> <tr> <td align="center" valign="middle" width="33.3%" colspan="2"> <a href="https://www.prefect.io/"><img src="https://raw.githubusercontent.com/johnsoncodehk/sponsors/master/logos/Prefect.svg" width="200" /></a> </td> <td align="center" valign="middle" width="33.3%" colspan="2"> <a href="https://antfu.me/"><img src="https://avatars.githubusercontent.com/u/11247099?v=4" height="80" /></a> </td> <td align="center" valign="middle" width="33.3%" colspan="2"> </td> </tr> </tbody> </table>

<p align="center"> <a href="https://github.com/sponsors/johnsoncodehk">You?</a> </p>

<p align="center"> <a href="https://cdn.jsdelivr.net/gh/johnsoncodehk/sponsors/sponsors.svg"> <img src="https://cdn.jsdelivr.net/gh/johnsoncodehk/sponsors/sponsors.png"/> </a> </p>

New createReactiveSystem() API

The core algorithm is now decoupled from the public API, and you can redesign your surface API using the alien-signals algorithm.

(The following example is based on https://github.com/proposal-signals/signal-polyfill/pull/44)

const system = createReactiveSystem({
  updateComputed(computed: Computed) {
    return computed.update();
  },
  notifyEffect(watcher: subtle.Watcher) {
    if (watcher.flags & alien.SubscriberFlags.Dirty) {
      watcher.run();
      return true;
    }
    return false;
  },
});

signal, computed, effect, effectScope are now function-based instead of class-based

The class-based API design can minimize memory usage, but at the same time I think the get() and set() methods of class signal are also significantly worse in DX.

Since the core algorithm is now decoupled from the surface API, we decided to stop caring about scalability and memory footprint and switch to a function-based API to ensure proper DX by default.

For the latest API usage, please refer to the readme: https://github.com/stackblitz/alien-signals#usage

Performance improved by 12% compared to v0.6

With the 1.0 refactor changes, we have again seen performance improvements in our internal benchmark scripts in alien-signals.

Please note that this improvement is only theoretical since the --jitless flag is disabled in the alien-signals bench script, but it is a good thing anyway. :)

<img width="619" alt="image" src="https://github.com/user-attachments/assets/5bd6c20e-d51f-409c-b4b7-50aa2a10cc5d" />