@pithyjs/signals

Fine-grained reactive signal system for the PithyJS framework. Signals provide O(1) reactive state with automatic dependency tracking — no virtual DOM, no re-renders, only the exact DOM nodes that depend on a signal update.

Installation

npm install @pithyjs/signals

pnpm add @pithyjs/signals

yarn add @pithyjs/signals

import { signal, computed, effect, batch, onCleanup, isSignal } from '@pithyjs/signals';

Quick Start

creates a reactive signal with initial value

const count = signal(0);
count(); // → 0
count.set(1);
count(); // → 1

API Reference

| API | Signature | Stability | Description | | --- | --- | --- | --- | | isSignal | (value: unknown) => value is Signal<any> | stable | - | | onCleanup | (fn: () => void) => void | stable | - | | effect | (fn: () => void) => () => void | stable | - | | batch | (fn: () => void) => void | stable | - | | signal | <T>(initial: T) => Signal<T> | stable | - | | computed | <T>(compute: () => T) => () => T | stable | - |

Examples

creates a reactive signal with initial value

const count = signal(0);
count(); // → 0
count.set(1);
count(); // → 1

supports functional updates via .set()

const count = signal(0);
count.set(n => n + 1);
count(); // → 1
count.set(n => n * 10);
count(); // → 10

tracks signal dependencies and re-runs

const count = signal(0);
let observed = -1;
effect(() => {
  observed = count();
});
observed; // → 0
count.set(5);
observed; // → 5

derives a value from other signals

const a = signal(2);
const b = signal(3);
const sum = computed(() => a() + b());
sum(); // → 5
a.set(10);
sum(); // → 13

defers effect execution until batch completes

const a = signal(1);
const b = signal(2);
let runCount = 0;
effect(() => {
  a();
  b();
  runCount++;
});
runCount; // → 1

batch(() => {
  a.set(10);
  b.set(20);
});
// Effect should have run only once after batch, not twice
runCount; // → 2

runs cleanup on disposal

const count = signal(0);
let cleaned = false;

const dispose = effect(() => {
  count();
  onCleanup(() => {
    cleaned = true;
  });
});

cleaned; // → false
dispose();
cleaned; // → true

detects signal values at runtime

const count = signal(0);
isSignal(count); // → true
isSignal(42); // → false
isSignal(() => {}); // → false
isSignal(null); // → false

Testing

| Feature | Unit | Integration | E2E | Status | | --- | --- | --- | --- | --- | | isSignal | ✓ | - | - | Missing integration | | onCleanup | ✓ | - | - | Missing integration | | effect | ✓ | - | - | Missing integration | | batch | ✓ | - | - | Missing integration | | signal | ✓ | - | - | Missing integration | | computed | ✓ | - | - | Missing integration |

License

MIT