alien-signals

Use signal to create reactive state, computed to create derived state that automatically updates, and effect to run side effects when dependencies change.

import { signal, computed, effect } from 'alien-signals';

const count = signal(1);
const doubleCount = computed(() => count() * 2);

effect(() => {
  console.log(`Count is: ${count()}`);
}); // Console: Count is: 1

console.log(doubleCount()); // 2

count(2); // Console: Count is: 2

console.log(doubleCount()); // 4

Effects can be nested. When an outer effect re-runs, any inner effects created during the previous execution are automatically cleaned up. The system ensures outer effects run before inner effects.

import { signal, effect } from 'alien-signals';

const show = signal(true);
const count = signal(1);

effect(() => {
  if (show()) {
    // This inner effect is created when show() is true
    effect(() => {
      console.log(`Count is: ${count()}`);
    });
  }
}); // Console: Count is: 1

count(2); // Console: Count is: 2

// When show becomes false, the inner effect is cleaned up
show(false); // No output

count(3); // No output (inner effect no longer exists)

If you mutate a signal's value directly (e.g., pushing to an array returned by a signal) without using the signal's setter, downstream dependencies will not automatically update. Use trigger() to manually notify dependencies.

You can trigger a single signal or pass a function to trigger() to notify multiple signals at once.

import { signal, computed, trigger } from 'alien-signals';

// Single signal trigger
const arr = signal<number[]>([]);
const length = computed(() => arr().length);

console.log(length()); // 0

arr().push(1);
console.log(length()); // Still 0

trigger(arr);
console.log(length()); // 1

// Multiple signals trigger
const src1 = signal<number[]>([]);
const src2 = signal<number[]>([]);
const total = computed(() => src1().length + src2().length);

src1().push(1);
src2().push(2);

trigger(() => {
  src1();
  src2();
});

console.log(total()); // 2

Use effectScope to group multiple effects together. Calling the function returned by effectScope (the stop function) will clean up all effects created within that scope.

import { signal, effect, effectScope } from 'alien-signals';

const count = signal(1);

const stopScope = effectScope(() => {
  effect(() => {
    console.log(`Count in scope: ${count()}`);
  }); // Console: Count in scope: 1
});

count(2); // Console: Count in scope: 2

stopScope();

count(3); // No console output

Use createReactiveSystem to instantiate the core reactivity engine. You must provide three callback functions to handle the lifecycle of reactive nodes:

• update(sub: ReactiveNode): boolean: Called to check if a node needs updating. Returns true if the node is dirty.
• notify(sub: ReactiveNode): void: Called when a node's state changes and subscribers need to be notified.
• unwatched(sub: ReactiveNode): void: Called when a node no longer has any dependencies.

The returned object provides methods for managing links between dependencies and subscribers, propagating changes, and checking for dirty states.