Átomos y mapas: la API mínima de nanostores

Hay librerías cuya API se aprende y librerías cuya API se lee de una sentada. Nanostores pertenece a las segundas, y esa brevedad no es pobreza sino una tesis: casi todo lo que un gestor de estado ofrece de más son atajos que se pueden escribir encima cuando hacen falta. El núcleo son cuatro constructores y tres operaciones. Alrededor, un puñado de paquetes oficiales que resuelven los problemas que ninguna aplicación real se ahorra: persistir entre sesiones, sincronizar entre pestañas, leer la ruta actual, coordinar trabajo asíncrono. Esta lección recorre esa superficie entera con el detalle suficiente para que puedas decidir, ante cada necesidad, si te sirve una pieza del núcleo, una utilidad oficial o quince líneas propias.

atom: un valor y tres operaciones

El constructor atom guarda un valor de cualquier tipo y expone exactamente lo que hace falta para gobernarlo: obtenerlo, sustituirlo y escuchar sus cambios. No hay reductor, ni acción, ni actualizador funcional. La sustitución es total y por identidad, lo que significa que escribir el mismo valor no notifica a nadie.

import { atom } from 'nanostores'

export const tema = atom<'claro' | 'oscuro'>('claro')

export function alternarTema() {
  tema.set(tema.get() === 'claro' ? 'oscuro' : 'claro')
}

const cancelar = tema.subscribe((valor) => console.log('tema', valor))

Dos detalles del comportamiento conviene fijarlos pronto. El primero es que subscribe invoca al oyente de inmediato con el valor actual, además de en cada cambio posterior; si solo quieres los cambios, existe listen, que omite la llamada inicial. El segundo es que la comparación para decidir si hubo cambio es por identidad, de modo que un atom que guarda un objeto y al que le asignas un objeto equivalente pero distinto sí notifica. Esa es la razón de que exista map.

map y deepMap: objetos con clave

Un map es un store cuyo valor es un objeto plano y que además permite escribir una sola clave sin reconstruir el resto. La diferencia con guardar un objeto en un atom es doble: la escritura por clave es más cómoda y, sobre todo, los suscriptores reciben información sobre qué clave cambió, lo que permite a los adaptadores evitar trabajo innecesario.

import { map, deepMap } from 'nanostores'

export const perfil = map({ nombre: 'Ada', ciudad: 'Londres', activo: true })

perfil.setKey('ciudad', 'Cambridge')
perfil.set({ nombre: 'Grace', ciudad: 'Nueva York', activo: false })

export const ajustes = deepMap({
  notificaciones: { correo: true, push: false },
})

ajustes.setKey('notificaciones.push', true)

deepMap extiende la idea a estructuras anidadas mediante rutas por texto, lo que evita reconstruir a mano los niveles intermedios cuando cambia una hoja. Es la respuesta de nanostores al mismo dolor que Valtio resuelve con el proxy y que Redux resolvió con Immer, solo que aquí se paga con una ruta en forma de cadena en vez de con una capa de intercepción. La contrapartida es evidente y honesta: una ruta escrita como texto no la comprueba el sistema de tipos con la misma solidez que un acceso directo, así que el error de tecleo llega hasta el tiempo de ejecución.

Derivación perezosa con computed

computed construye un store nuevo a partir de otros y de una función pura. El resultado es de solo lectura y se recalcula cuando alguna fuente cambia, con la particularidad heredada del núcleo de que no calcula nada mientras nadie lo escucha.

import { atom, computed } from 'nanostores'

export const lineas = atom<Array<{ precio: number; cantidad: number }>>([])
export const iva = atom(0.21)

export const total = computed([lineas, iva], (items, tasa) => {
  const base = items.reduce((suma, l) => suma + l.precio * l.cantidad, 0)
  return base * (1 + tasa)
})

El principio que gobierna esta pieza es el mismo que atraviesa todo el track: lo derivado no se guarda, se calcula. Un total almacenado es una segunda fuente de verdad que puede desincronizarse; un total computado no puede estar mal por definición, porque no existe salvo como función de sus fuentes. La diferencia con Reselect o con los átomos derivados de Jotai no está en la idea sino en el tamaño del mecanismo.

flowchart LR
A[atom lineas] --> C[computed total]
B[atom iva] --> C
C --> V1[isla cabecera]
C --> V2[isla resumen]
C -.->|sin oyentes no calcula| Z[inerte]
style C fill:#f9e2af,color:#11111b
style Z fill:#585b70,color:#cdd6f4

La pereza tiene una consecuencia que sorprende al depurar: poner un registro dentro de la función de un computed no imprime nada hasta que algo se suscribe. No está roto, está dormido. Y tiene una consecuencia de diseño que sí conviene aprovechar: encadenar derivaciones es barato, porque una cadena entera de valores computados permanece inerte mientras la vista final no exista. En una página con islas que se hidratan según visibilidad, eso significa que el trabajo de cálculo llega justo cuando alguien lo va a mirar.

Persistencia y el resto del ecosistema

La utilidad oficial @nanostores/persistent sustituye a atom y map por variantes que se sincronizan con el almacenamiento del navegador. Lo interesante no es que guarden, sino que escuchan el evento de almacenamiento y, por tanto, propagan los cambios entre pestañas del mismo origen sin ninguna configuración adicional.

import { persistentAtom, persistentMap } from '@nanostores/persistent'

export const tema = persistentAtom<'claro' | 'oscuro'>('tema', 'claro')

export const carrito = persistentMap<Record<string, string>>('carrito:', {}, {
  encode: JSON.stringify,
  decode: JSON.parse,
})

Las garantías reales conviene enunciarlas sin adornos. Se persiste texto, así que todo valor que no sea cadena necesita codificación explícita y pierde por el camino los tipos que el formato de intercambio no representa, como fechas o conjuntos. La sincronía entre pestañas es a través de un evento del navegador y por tanto asíncrona: dos pestañas pueden estar momentáneamente desalineadas y no hay resolución de conflictos si ambas escriben a la vez, gana la última. Y en renderizado del lado del servidor no hay almacenamiento, de modo que el valor inicial es el predeterminado y llega al real tras la hidratación, con el parpadeo consiguiente si no lo previenes.

Otra garantía que conviene entender es la de la clave de almacenamiento. Persistir es publicar en un espacio de nombres compartido por todo el origen, así que dos aplicaciones servidas desde el mismo dominio, o dos versiones de la tuya, pueden pisarse. Prefijar las claves y versionarlas cuando cambie la forma del dato es una precaución barata que evita el escenario más desagradable de todos: código nuevo leyendo un valor persistido por código viejo con otra estructura, que no falla al leer sino más tarde, en un sitio sin relación aparente.

El resto del ecosistema oficial sigue la misma filosofía de piezas pequeñas: un router que expone la ruta actual como un store y permite que cualquier isla reaccione a la navegación, y utilidades para coordinar trabajo asíncrono y esperar a que las tareas pendientes terminen, útiles sobre todo en pruebas y en renderizado de servidor. Ninguna es imprescindible, y esa es la prueba de la coherencia del diseño: cuando el núcleo son tres operaciones, casi cualquier utilidad se puede escribir encima en un rato, y la decisión entre adoptar un paquete o escribir quince líneas propias vuelve a ser una decisión honesta de ingeniería.