@maverick-js/signals

Signals is a lightweight (~1kB minzipped) reactivity API designed to provide reactive observables for UI libraries. It follows a "lazy principle" similar to Svelte, ensuring that work is only performed when necessary.

Core Features:

• Reactive Observables: Store state and create computed properties.
• Lazy Evaluation: Computations only re-run when their dependencies change.
• Batched Updates: Uses a microtask scheduler to batch updates.
• Change Detection: Only triggers updates when a value has actually changed.
• Environment Agnostic: Works in both browsers and Node.js.
• Strongly Typed: Built with TypeScript for full type safety.

Computations (like computed or effect) are typically child computations that are destroyed when their parent scope is destroyed. If you create a computation without a parent, it becomes an 'orphan' that lives in memory until garbage collected. To avoid orphans and easily manage groups of computations, use root. It creates a scope and provides a dispose function that cleans up all inner computations at once.

import { root, signal, computed, effect } from '@maverick-js/signals';

root((dispose) => {
  const $a = signal(10);
  const $b = computed(() => $a());

  effect(() => console.log($b()));

  // Disposes of `$a`, `$b`, and `effect`.
  dispose();
});

Install the @maverick-js/signals package using your preferred package manager.

npm i @maverick-js/signals

pnpm i @maverick-js/signals

yarn add @maverick-js/signals

Choosing the right mapping helper depends on how your data changes:

Reactivity in this library is organized into a tree of Scopes.

1. Hierarchy: When a new computation (signal, computed, or effect) is created, it is automatically appended as a child to the currentScope.
2. Context: Each scope can hold a _context object. When getContext is called, the system walks up the parent chain ([SCOPE]) until it finds the requested key. setContext allows you to provide data to an entire branch of the reactivity tree.
3. Disposal: When a scope is disposed via dispose(), it recursively disposes of all its children and executes all registered onDispose handlers. This ensures a clean teardown of the reactive graph.
4. Error Propagation: Errors thrown during computation are caught by the scope's _handlers. If a handler doesn't resolve the error, it bubbles up to the parent scope.

The Scope interface defines the hierarchical lifecycle management in the signals library. Scopes allow you to group related signals, computations, and effects, ensuring they are cleaned up together.

• append(scope: Scope): Adds a child scope to the current scope.
• dispose(): Terminates the scope and all its children, triggering their respective disposal logic.

An object implementing Disposable or Dispose can be used to define custom cleanup logic that runs when a scope is disposed.

Use these utility functions to identify the capabilities of a signal:

• isReadSignal(val): Returns true if the value is a signal that can be read (including computed and readonly signals).
• isWriteSignal(val): Returns true if the value is a signal that supports the .set() write API.

import { signal, computed, readonly, isReadSignal, isWriteSignal } from '@maverick-js/signals';

const $a = signal(10);
const $b = computed(() => 10);
const $c = readonly($a);

isReadSignal($a); // true
isReadSignal($b); // true
isReadSignal($c); // true

isWriteSignal($a); // true
isWriteSignal($b); // false
isWriteSignal($c); // false

Low-level APIs for managing execution context and data:

• getScope(): Returns the currently executing parent scope.
• scoped(fn, scope): Runs a function within a specific existing scope.
• setContext(key, value): Sets a value on the parent scope for the given key.
• getContext(key): Walks up the computation tree from the parent scope to find a value matching the key.

import { root, getScope, scoped, getContext, setContext } from '@maverick-js/signals';

const key = Symbol();

root(() => {
  setContext(key, 100);
  
  root(() => {
    const value = getContext(key); // 100
  });
});

The signal function wraps a value into a reactive signal. You can read the current value by invoking the signal as a function fn(), and update it using the .set() method. Updates can be direct or use a functional updater (prev) => next.

import { signal } from '@maverick-js/signals';

const $a = signal(10);

$a(); // read
$a.set(20); // write
$a.set((prev) => prev + 10); // write using updater

Use these functions to read signal values without triggering dependency tracking or scope tracking:

• peek(signal): Returns the current value of a signal without triggering observer tracking (the signal won't be registered as a dependency).
• untrack(fn): Executes a function while disabling both observer tracking and scope tracking.

import { signal, computed, peek, effect, untrack } from '@maverick-js/signals';

const $a = signal(10);

// peek: $a will not trigger updates on $b
const $b = computed(() => {
  const value = peek($a);
});

// untrack: $a is an orphan and not tracked by the outer effect
effect(() => {
  untrack(() => {
    const $a = signal(10);
  });
});