Signals

Everything that changes in a zerolith application is a signal, and everything that follows a change reads one. The graph has three kinds of node, and the rest of the library is built from them:

A template binding is an effect too: ${count} in a template is an effect that writes one text node. That is why a page stays current without its components running again.

Reading and writing

get() reads a signal and set() writes it. A read inside a computed value or an effect subscribes it; a read anywhere else is a plain read.

import { signal } from "zerolith";

const count = signal(0);
count.set(count.get() + 1);
console.log(count.get());               // 1

const point = signal({ x: 1 }, { equals: (a, b) => a.x === b.x });
point.set({ x: 1 });                    // ignored: `equals` says it is equal

set ignores a value equal to the current one, by Object.is unless the signal was given its own equals. An ignored write notifies nothing, so a write that changes nothing costs nothing downstream.

signal and computed take the same options:

Derived values

A computed value runs its function the first time it is read, remembers the result, and runs again only when a signal it read has changed and something reads it again:

import { computed, signal } from "zerolith";

const price = signal(10);
const quantity = signal(2);
const total = computed(() => price.get() * quantity.get());

console.log(total.get());               // 20
quantity.set(3);
console.log(total.get());               // 30

Dependencies come from what the function actually read on its last run, so a branch it did not take subscribes to nothing, and a computed value nobody reads costs nothing at all.

Effects

An effect runs its function at once, then again after any change to a signal it read. It can return a cleanup function, which runs before its next run and when it is disposed:

import { effect, signal } from "zerolith";

const name = signal("Ada");

const dispose = effect(() =>
{
    const current = name.get();
    console.log(`hello ${current}`);
    return () => console.log(`goodbye ${current}`);
});                                     // prints "hello Ada" right away

name.set("Grace");                      // prints "goodbye Ada", "hello Grace"
dispose();                              // prints "goodbye Grace"

Effects are for the world outside the graph: the document title, storage, a timer, a socket, a third-party widget. An effect created inside another effect belongs to it and is disposed when the outer effect runs again.

An effect that keeps changing what it reads would run forever; after 100 rounds it fails with effect_loop.

Reading without subscribing

untracked reads signals without making the running effect or computed value depend on them, for a value that should be current when the effect runs but should not make it run:

import { effect, signal, untracked } from "zerolith";

const query = signal("zerolith");
const page = signal(1);

effect(() =>
{
    const from = untracked(() => page.get());
    console.log(`search ${query.get()} from page ${from}`);
});                                     // prints "search zerolith from page 1"

page.set(2);                            // prints nothing: page is untracked
query.set("signals");                   // prints "search signals from page 2"

Batching

Writes inside batch are applied together, and the effects they affect run once, after the function returns. Writes inside an effect are batched the same way without asking.

import { batch, effect, signal } from "zerolith";

const first = signal("Ada");
const last = signal("Lovelace");
// Prints "Ada Lovelace" now, and again after each change:
effect(() => console.log(`${first.get()} ${last.get()}`));

batch(() =>
{
    first.set("Grace");
    last.set("Hopper");
});                                     // prints "Grace Hopper", once

Ownership

Every effect belongs to an owner, and disposing the owner stops all of its effects at once. render owns what a view creates, each row of an each and each branch of a when owns what it creates, and each page of the router owns its own. scope makes an owner by hand, and onDispose adds cleanup to the owner that is running:

import { effect, onDispose, scope, signal } from "zerolith";

const tick = signal(0);

const handle = scope(() =>
{
    effect(() => console.log(`tick ${tick.get()}`));
    onDispose(() => console.log("disposed"));
});                                     // prints "tick 0"

tick.set(1);                            // prints "tick 1"
handle.dispose();                       // prints "disposed"
tick.set(2);                            // prints nothing: the effect is gone

Async values

resource loads data from signals. Its params function reads the signals the request depends on, and its loader receives those params and an abort signal. Whenever the params change, the previous request is aborted and the loader runs again; when params returns undefined, the resource waits, idle.

import { resource, signal } from "zerolith";

const userId = signal<number | undefined>(undefined);
const user = resource({
    params: () => userId.get(),
    loader: async ({ params, abort }) =>
    {
        const response = await fetch(`/api/users/${params}`, { signal: abort });
        return (await response.json()) as { id: number; name: string };
    }
});

console.log(user.status.get());         // "idle": params returned undefined
userId.set(7);
console.log(user.status.get());         // "pending"
// Once the loader settles, the status is "resolved" and user.get() is the user.

A resource is itself a signal of its value, with its state beside it:

A result that arrives after newer params have started a load is dropped, so a slow first request never overwrites a fast second one. The abort signal fires when the params change, on reload(), and when the resource's owner is disposed; passing it to fetch, as above, cancels the request itself.

The functions at a glance