Guía

Reactividad

signal, memo y effect son todo el modelo. Cómo se suscriben solos, cuándo se ejecutan y cómo se liberan.

Tres primitivos

Qué es Tiene valor Se recalcula
signal Estado. Lo único que se escribe. Sí Nunca
memo Un valor derivado de otros. Sí Perezosamente, al leerlo
effect Trabajo con efectos: tocar el DOM, un fetch, un log. No Tras la escritura que lo afecta
ts
import { effect, memo, signal } from "ascua";

const precio = signal(1000);
const cantidad = signal(3);
const total = memo(() => precio() * cantidad());

effect(() => console.log(`Total: ${total()}`));   // Total: 3000
cantidad.set(4);                                   // Total: 4000

Nadie declaró que total depende de precio y cantidad, ni que el efecto depende de total. Se descubre leyendo: mientras un memo o un efecto se ejecuta, el runtime anota qué leyó. Si la próxima vez lee otras cosas —una rama de un if que cambió—, se suscribe a esas y deja de escuchar a las anteriores.

signal

ts
const nombre = signal("Ana");

nombre();                        // leer, y suscribirse si hay alguien escuchando
nombre.set("Luis");              // escribir
nombre.update((n) => n.trim());  // escribir a partir del valor actual
nombre.peek();                   // leer sin suscribirse

Escribir el mismo valor que ya tenía (Object.is) no despierta a nadie.

Un signal guarda una referencia: mutar un array o un objeto por dentro no avisa. Se escribe uno nuevo:

ts
const tareas = signal<Tarea[]>([]);

tareas.update((lista) => [...lista, nueva]);   // ✓ avisa
tareas().push(nueva);                           // ✗ nadie se entera

memo

ts
const visibles = memo(() => tareas().filter((t) => !t.hecha));

Un memo es perezoso: no calcula hasta que alguien lo lee, y no vuelve a calcular mientras sus fuentes no cambien. Y corta la propagación: si al recalcular obtiene el mismo valor, quien lo lee no se entera.

ts
const esGrande = memo(() => cuenta() > 100);
// cuenta: 1 → 2 → 3 … → 100: esGrande sigue siendo false y nadie repinta.

El segundo argumento cambia qué se considera «el mismo valor»:

ts
const punto = memo(() => ({ x: x(), y: y() }), (a, b) => a.x === b.x && a.y === b.y);

effect

ts
effect(() => {
  document.title = `${pendientes()} pendientes`;
});

Se ejecuta una vez al crearse y otra por cada cambio que le afecte. En una plantilla casi nunca se escribe a mano: cada ${() => …} es un efecto que el compilador pone por ti.

Limpieza

ts
effect(() => {
  const id = setInterval(tick, intervalo());
  onCleanup(() => clearInterval(id));
});

onCleanup corre antes de cada reejecución y una última vez cuando el efecto se libera. Es la forma de soltar lo que se adquirió: un intervalo, un listener global, una suscripción.

Sin estados intermedios

Escribir en un signal no ejecuta nada: marca. Primero se marca todo lo que depende de él, y solo cuando la marca terminó de propagarse corren los efectos. De ahí salen dos garantías:

  • Un efecto nunca ve un estado a medias. Si b y c derivan de a y un efecto lee los dos, al cambiar a el efecto corre una vez y ve los dos valores nuevos, nunca uno nuevo y otro viejo.
  • Un efecto corre una vez por cambio, aunque le lleguen avisos por varios caminos.

batch

Varias escrituras seguidas son varios cambios. batch las junta en uno:

ts
batch(() => {
  precio.set(1200);
  cantidad.set(2);
});
// Total: 2400 — una sola vez, no dos.

untrack

Leer sin suscribirse, cuando un efecto necesita un dato pero no debe reaccionar a él:

ts
effect(() => {
  registrar(pagina(), untrack(() => usuario()));   // solo reacciona a pagina
});

Quién es dueño de qué

Todo lo reactivo tiene un dueño: el scope que estaba activo al crearlo. Liberar un dueño libera todo lo que cuelga de él, en orden.

ts
const [app, desmontar] = root(() => {
  const cuenta = signal(0);
  effect(() => console.log(cuenta()));
  return cuenta;
});

desmontar();   // el efecto deja de existir y sus onCleanup corren

No hace falta llamar a root casi nunca: mount, <Show>, <For> y el router crean los suyos. Cuando una rama de <Show> se cierra, todo lo que se creó dentro —efectos, memos, listeners— se libera con ella. Nada queda vivo escuchando a un componente que ya no está.

Cuando un efecto se reejecuta, antes de correr libera lo que creó la vez anterior: un efecto creado dentro de otro efecto no se acumula.

Datos que llegan tarde: resource

ts
const club = resource(
  () => id(),                                   // la fuente: cambia, recarga
  (id, { signal }) => fetch(`/api/clubes/${id}`, { signal }).then((r) => r.json()),
);

view`
  <section>
    <Show when=${() => club.state() === "error"}><p>No se pudo cargar.</p></Show>
    <Show when=${() => club()}>${(c) => view`<h2>${() => c().nombre}</h2>`}</Show>
    <button onclick=${() => club.reload()}>Recargar</button>
  </section>`;

club() es el último valor cargado, club.state() dice en qué está (idle, loading, ready, error), club.error() guarda el error y club.reload() vuelve a cargar. Si la fuente da null, undefined o false, no carga. Sin fuente, resource(({ signal }) => …) carga una vez.

Lo que no hay que escribir a mano:

  • Una carga nueva aborta la anterior, y su respuesta se descarta aunque llegue: un resultado lento no pisa a uno más reciente.
  • Cerrar la vista cancela lo que estaba en camino. El signal que recibe la función se dispara al liberar el scope.
  • Recargar no parpadea. Mientras llega el valor nuevo, club() sigue dando el anterior; para un indicador, club.loading().
  • club.mutate(valor) cambia el valor sin cargar: lo que ya se sabe después de guardar.

Código asíncrono

Después de un await, el scope ya no es el que era: el código corre en otra vuelta del bucle de eventos. Si hay que crear algo reactivo ahí, se captura el scope antes y se restaura:

ts
const scope = currentScope();
const datos = await fetch(url).then((r) => r.json());
withScope(scope, () => {
  effect(() => …);   // pertenece al componente, y se libera con él
});

Temporizadores: timeout e interval

setTimeout y setInterval atados al scope: si el componente se desmonta antes, se cancelan solos. Un aviso que se oculta a los tres segundos no escribe en el signal de un componente que ya no está:

ts
import { interval, timeout } from "ascua";

timeout(3000, () => aviso.set(null));
interval(1000, () => segundos.update((s) => s + 1));

El callback corre como un efecto, en el scope donde se creó: un error va a su onError, y lo que escribe sale en un solo lote. Los dos devuelven un Timer con cancel(); sobre uno que ya corrió no hace nada.

Dentro de un manejador de eventos no hay scope, así que lo que se cree ahí no se cancela solo al desmontar. Es el caso del debounce: se guarda el último y se cancela con onCleanup, que sí corre en el cuerpo del componente.

ts
let pendiente: Timer | undefined;
onCleanup(() => pendiente?.cancel());

const alEscribir = (texto: string) => {
  pendiente?.cancel();
  pendiente = timeout(300, () => buscar(texto));
};

El navegador frena los temporizadores de una pestaña en segundo plano: para medir tiempo de verdad, Date.now() al empezar y al terminar; el intervalo, solo para refrescar lo que se ve.

selector: elegir uno entre mil

El caso es la fila seleccionada de una tabla. Si cada fila lee el signal de la selección, cambiarla despierta mil efectos para repintar dos. Con selector, cada fila se suscribe solo a su clave:

ts
const elegida = signal<number | null>(null);
const esLaElegida = selector(() => elegida());

view`<tr class:seleccionada=${() => esLaElegida(fila.id)}>…</tr>`;

Cambiar elegida avisa a la fila que deja de estarlo y a la que pasa a estarlo. Las otras 998 ni se enteran.

Guardado en el navegador: persisted

Un signal que se guarda en localStorage y se recupera al volver:

ts
import { persisted } from "ascua/persisted";

const theme = persisted<"light" | "dark">("app:theme", "light");
theme.set("dark");   // en memoria y, si se puede, en localStorage
theme.saved();       // false si no se pudo guardar

El almacén falla más de lo que parece: lanza al leer con las cookies bloqueadas o en un iframe con sandbox, lanza al escribir con la cuota llena, y devuelve lo que dejó una versión anterior de la app. persisted no deja que nada de eso tire la página:

  • Lee una vez, al crearse. Si no hay nada, el JSON está roto o el almacén lanza, vale el valor inicial.
  • Cada set escribe. Si falla, el signal sigue en memoria y saved() pasa a false, por si la interfaz quiere avisar.
  • version. Lo guardado lleva su versión ({"v":1,"d":…}). Al cambiar la forma de los datos se sube la versión, y lo viejo se descarta en vez de romper la app. validate comprueba lo leído.
  • sync: true sigue los cambios de la misma clave en otras pestañas; el listener se quita con el scope.
  • Sin almacén —en el servidor, en un test— funciona solo en memoria. storage cambia el almacén: sessionStorage, o uno falso en los tests.

Va en un subpath aparte para que no pese en quien no lo usa: unos 0,3 kB.

Errores

Un error dentro de un efecto sube por los dueños hasta el primero que tenga un onError. Está en Errores y depuración.