Referencia

ascua

Cada función que exporta el runtime, con su firma. Signals, operaciones de DOM, SSR e hidratación.

ts
import { signal, memo, effect, mount, hydrate } from "ascua";
import { renderToString } from "ascua/server";

4,01 kB gzip, sin dependencias. Con hydrate e island, 4,96 kB, y defineIsland suma unos 0,96 kB, resource 0,24 kB, bind 0,08 kB y showValue 0,07 kB; lo que no se importa, el tree-shaking se lo lleva. ascua/server no cuenta: no llega al navegador.

Reactividad

signal

ts
function signal<T>(inicial: T): Signal<T>;

interface Signal<T> {
  (): T;                              // leer y suscribirse
  set(valor: T): void;
  update(fn: (actual: T) => T): void;
  peek(): T;                          // leer sin suscribirse
}

Escribir un valor igual al actual (Object.is) no avisa a nadie.

memo

ts
function memo<T>(calcular: () => T, iguales?: (a: T, b: T) => boolean): () => T;

Perezoso: no calcula hasta que alguien lo lee. Si al recalcular obtiene un valor igual —Object.is o iguales—, sus observadores no se enteran.

effect

ts
function effect(fn: () => void): void;

Se ejecuta al crearse y tras cada cambio que le afecte. Pertenece al scope actual y se libera con él.

batch

ts
function batch<T>(fn: () => T): T;

Las escrituras de dentro producen como mucho una ejecución por efecto afectado.

untrack

ts
function untrack<T>(fn: () => T): T;

Ejecuta fn sin suscribir al cómputo actual a lo que lea.

selector

ts
function selector<T>(fuente: () => T): (clave: T) => boolean;

esLaElegida(clave) vale true para la clave que devuelve fuente. Cada lector se suscribe solo a su clave: un cambio avisa a la que deja de estar elegida y a la que pasa a estarlo.

onCleanup

ts
function onCleanup(fn: () => void): void;

Corre antes de cada reejecución del scope actual y al liberarlo. Fuera de todo scope no hace nada.

onError

ts
function onError(manejador: (error: unknown) => void): void;

Se hace cargo de los errores de este scope y de los de debajo. El manejador corre en su propio scope. Ver Errores.

resource

ts
function resource<T>(cargar: (info: ResourceInfo) => Promise<T>): Resource<T>;
function resource<T, S>(
  fuente: () => S | null | undefined | false,
  cargar: (fuente: S, info: ResourceInfo) => Promise<T>,
): Resource<T>;

interface ResourceInfo { signal: AbortSignal }
type ResourceState = "idle" | "loading" | "ready" | "error";

interface Resource<T> {
  (): T | undefined;
  state(): ResourceState;
  loading(): boolean;
  error(): unknown;
  reload(): void;
  mutate(valor: T | undefined): void;
}

Carga al crearse y cada vez que cambia la fuente; una carga nueva aborta la anterior y descarta su respuesta. Liberar el scope aborta lo pendiente. La guía está en Reactividad.

timeout, interval

ts
function timeout(ms: number, fn: () => void): Timer;
function interval(ms: number, fn: () => void): Timer;

interface Timer {
  cancel(): void;
}

setTimeout y setInterval que se cancelan al liberarse el scope. El callback corre en ese scope y en un batch. En un manejador de eventos no hay scope: ahí se cancela con onCleanup. La guía está en Reactividad.

root

ts
function root<T>(fn: () => T): [T, () => void];

Una raíz reactiva propia: devuelve el resultado y cómo liberarla entera.

currentScope, withScope

ts
function currentScope(): Scope;
function withScope<T>(scope: Scope, fn: () => T): T;

Capturar el scope actual y volver a él más tarde; sirve tras un await.

persisted

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

function persisted<T>(key: string, initial: T, options?: PersistedOptions<T>): Persisted<T>;

interface PersistedOptions<T> {
  version?: number;                              // por defecto, 1
  validate?: (value: unknown) => value is T;
  storage?: Storage | null;                      // por defecto, localStorage
  sync?: boolean;                                // sigue a otras pestañas
}

interface Persisted<T> extends Signal<T> {
  saved(): boolean;
}

Un signal guardado en localStorage que no falla aunque falle el almacén. La guía está en Reactividad.

DOM

Las llamadas que emite el compilador. Se pueden escribir a mano.

Función Qué hace
element(etiqueta, espacio?) document.createElement, o createElementNS dentro de <svg> y <math>.
text(contenido?) Un nodo de texto.
marker() Un comentario vacío: el ancla de una región dinámica.
append(padre, ...hijos) Añade al final.
insert(padre, hijo, antes) insertBefore.
dynamicText(calcular) Un texto atado a una expresión. Devuelve el nodo.
attribute(nodo, nombre, calcular) Atributo reactivo. false, null o undefined lo quitan; true lo deja vacío.
staticAttribute(nodo, nombre, valor) Lo mismo, una vez.
property(nodo, nombre, calcular) Propiedad reactiva: value, checked.
cssClass(nodo, nombre, calcular) Pone o quita una clase.
on(nodo, evento, manejador) El manejador, que se quita solo al liberar. Los eventos que suben se delegan en el documento; los demás son un addEventListener.
bind(nodo, propiedad, signal) bind:: value, checked o valueAsNumber, en los dos sentidos.
component(Componente) Un componente sin props ni hijos: <Menu/>.
template(estructura, caminos, tipos, recorrer?) La parte fija de una plantilla. El compilador la declara una vez por archivo.
cloneTemplate(plantilla) La clona y devuelve los nodos que el código necesita, con su tipo. En el servidor y al hidratar, la construye nodo a nodo.
setText(texto, valor) Escribe una vez en un texto de la plantilla. Como staticText, rechaza una función.
bindText(texto, calcular) Ata un texto de la plantilla a una expresión.

show

ts
function show<T>(
  padre: Node,
  elegir: () => T,
  construir: (valor: T) => Node | readonly Node[] | null,
): void;

La región de un <Show>. construir corre dentro de un scope propio y sin rastrear; se vuelve a llamar solo cuando elegir devuelve otro valor.

showValue

ts
type Present<T> = Exclude<T, null | undefined | false>;

function showValue<T>(
  padre: Node,
  elegir: () => T,
  construir: (valor: () => Present<T>) => Node | readonly Node[] | null,
  siNo?: (() => Node | readonly Node[] | null) | null,
): void;

Un <Show> cuyo hijo es una función. Reconstruye solo cuando el valor aparece o desaparece; construir recibe un accesor ya estrechado.

list

ts
function list<T, K>(
  padre: Node,
  items: () => readonly T[],
  clave: (item: T) => K,
  construir: (item: T, current: () => T) => Node,
): void;

La lista de un <For>. construir se ejecuta una vez por clave; los nodos se conservan y se mueven lo mínimo. Si declara el segundo parámetro, current() da el último item que llegó con esa clave, y es reactivo.

mount

ts
function mount(padre: Node, construir: () => Node): () => void;

Construye dentro de una raíz reactiva, lo añade a padre y devuelve cómo desmontarlo.

SSR e hidratación

defineIsland

ts
function defineIsland<S extends StandardSchema | Shape>(
  nombre: string,
  esquema: S,
  componente: (props: Props<S>) => Node,
): Island<Props<S>>;

Una isla con props validados. Se usa como un componente y se registra en hydrate. El esquema tiene que encajar con los props del componente; si al hidratar no encaja con lo que mandó el servidor, la isla se queda estática y la consola dice qué campo falló. Ver SSR e islas.

p

ts
p.string  p.number  p.boolean
p.array(e)  p.object({ … })  p.optional(e)  p.nullable(e)
p.date  p.url  p.bigint  p.map(k, v)  p.set(e)

Esquemas para los props de una isla. Siguen Standard Schema, así que se mezclan con los de Zod, Valibot o ArkType. Los de la segunda línea convierten al llegar lo que viajó como JSON en Date, URL, bigint, Map o Set.

serializeProps

ts
function serializeProps(props: unknown): string;

Los props como texto para el HTML: JSON, con Map y Set como listas y bigint como texto. Es lo que usa defineIsland; sirve para quien llame a island a mano.

island

ts
function island(nombre: string, construir: () => Node, props?: string): HTMLElement;

La pieza de debajo de defineIsland. Envuelve el contenido en <ascua-island> y deja props en un atributo, sin interpretarlo. En el servidor numera lo de dentro; en el cliente, si se está hidratando, lo adopta.

hydrate

ts
function hydrate(
  islas: Island<any>[] | Record<string, (props: string) => Node>,
  raiz?: ParentNode,
): { adopted: number; created: number; unmount: () => void };

Activa las islas de raiz —el documento, por defecto— adoptando los nodos del servidor. Con una lista de defineIsland, valida los props antes; con un objeto, pasa el texto tal cual. Las islas sin constructor se dejan intactas.

renderToString

ts
import { renderToString } from "ascua/server";

function renderToString(construir: () => Node): string;

Renderiza a HTML sobre un documento en memoria, sin navegador. Los efectos corren una vez y se liberan al terminar.

collectStyles

ts
import { collectStyles } from "ascua/server";

function collectStyles(html: string): string;

El CSS con scope de los componentes que aparecen en un HTML ya renderizado. Las hojas las registra el plugin de Vite al cargar cada módulo en el servidor, con registerStyle, que no hace falta llamar a mano.

Tipos

ts
type Children = (padre: Node) => void;
type AttributeValue = string | number | boolean | null | undefined;
type Memo<T> = () => T;
interface Writable<T> { (): T; set(valor: T): void }

Y dos globales, para que el editor conozca las plantillas sin importarlas:

ts
declare global {
  function view(plantilla: TemplateStringsArray, ...valores: unknown[]): HTMLElement;
  function html(plantilla: TemplateStringsArray, ...valores: unknown[]): HTMLElement;
}