Referencia
ascua
Cada función que exporta el runtime, con su firma. Signals, operaciones de DOM, SSR e hidratación.
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
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
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
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
function batch<T>(fn: () => T): T;Las escrituras de dentro producen como mucho una ejecución por efecto afectado.
untrack
function untrack<T>(fn: () => T): T;Ejecuta fn sin suscribir al cómputo actual a lo que lea.
selector
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
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
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
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
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
function root<T>(fn: () => T): [T, () => void];Una raíz reactiva propia: devuelve el resultado y cómo liberarla entera.
currentScope, withScope
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
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
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
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
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
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
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
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
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
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
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
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
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
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:
declare global {
function view(plantilla: TemplateStringsArray, ...valores: unknown[]): HTMLElement;
function html(plantilla: TemplateStringsArray, ...valores: unknown[]): HTMLElement;
}