Guía

Datos remotos

Una caché compartida por clave con ascua-query. Deduplicación, sondeo, invalidación y actualizaciones optimistas en 2,15 kB.

Cuando un resource no basta

resource carga datos para una vista. Cuando varias vistas muestran los mismos datos —la lista de usuarios en la tabla y en un selector—, o cuando guardar algo tiene que refrescar lo que se ve en otra parte, hace falta una caché compartida. Eso es ascua-query:

sh
stil add ascua-query
ts
import { remote } from "ascua-query";

const users = remote({
  key: () => ["users"],
  load: (_key, { signal }) => fetch("/api/users", { signal }).then((r) => r.json()),
});

view`
  <Show when=${() => users()}>
    ${(list) => view`<For each=${list} key=${(u: User) => u.id}
                            render=${(u: User) => view`<li>${u.name}</li>`}/>`}
  </Show>`;

Se lee igual que un resource: users() son los datos, users.state() dice en qué está, users.error() guarda el fallo y users.reload() vuelve a cargar. La diferencia es la clave: dos consultas con la misma, en cualquier parte de la aplicación, comparten datos y peticiones.

La clave es reactiva

ts
const conversation = signal<string | null>(null);

const messages = remote({
  key: () => (conversation() ? ["messages", conversation()!] : null),
  load: ([, id], { signal }) => api.messages(id, { signal }),
  interval: () => (polling() ? 5_000 : false),
});

Cambiar conversation carga la nueva; null deja la consulta en idle. El intervalo también puede ser reactivo, y solo corre con la pestaña visible.

Para paginar sin que la tabla quede en blanco entre página y página, keepPrevious: true sigue mostrando la anterior mientras llega la nueva; placeholder() dice cuándo lo que se ve es de la clave anterior.

Guardar e invalidar

ts
import { invalidate, mutation } from "ascua-query";

const create = mutation({
  run: (data: NewUser) => api.createUser(data),
  onSuccess: () => invalidate(["users"]),
});

view`<button disabled=${() => create.pending()} onclick=${() => create.mutate(form())}>Create</button>`;

invalidate(["users"]) caduca todo lo que empieza por "users" —también ["users", 4]— y recarga lo que alguna vista está mirando. Como onSuccess devuelve esa promesa, create.pending() sigue en true hasta que la lista está al día: el botón no se libera antes de tiempo.

mutate() no rechaza: si falla, el error queda en create.error(). mutateAsync() devuelve el resultado y rechaza, para usarlo con await.

Lo que depende de esta llamada —un aviso, cerrar el formulario— va en el segundo argumento, como en TanStack Query:

ts
create.mutate(form(), {
  onSuccess: (user) => toast.success(`${user.email} created`),
  onError: () => toast.error("Could not create the user"),
});

Corren después de los on… de la mutación, y solo los de la última llamada: si se lanza otra antes de que termine, los de la anterior no corren. Sin variables, create.mutate(undefined, { … }).

Actualizaciones optimistas

ts
const comment = mutation({
  run: (text: string) => api.addComment(id, text),
  onMutate: async (text) => {
    await cancel(["comments", id]);                    // que una respuesta vieja no pise esto
    const previous = getData<Comment[]>(["comments", id]);
    setData<Comment[]>(["comments", id], (c) => [...(c ?? []), { text, pending: true }]);
    return { previous };
  },
  onError: (_error, _text, ctx) => setData(["comments", id], ctx?.previous),
  onSettled: () => invalidate(["comments", id]),
});

El comentario se ve al momento. Si el servidor falla, onError deja la caché como estaba; en cualquier caso, onSettled recarga la verdad del servidor.

Lo que no hay que escribir a mano

  • Deduplicación. Mientras una clave carga, quien la pida espera esa misma carga.
  • Una respuesta vieja no pisa a una nueva. Recargar aborta la carga en camino y descarta su respuesta.
  • Un sondeo que trae lo mismo no repinta nada. Lo nuevo reusa cada objeto que no cambió, así que un <For> con clave solo toca las filas que cambiaron.
  • Reintentos y recarga al volver. Tres reintentos con espera creciente, y lo caducado se recarga al volver a la pestaña o a la red.

Los valores por defecto son los de TanStack Query, para que migrar una aplicación no cambie cómo se comporta; configure() los cambia para todas las consultas y cada remote() puede cambiarlos para la suya.

Desde TanStack Query

La equivalencia que salió de migrar una aplicación real de React (29 hooks):

TanStack Query ascua-query
useQuery({ queryKey, queryFn }) remote({ key: () => [...], load: (key) => … })
enabled: !!id key devuelve null mientras no hay id
placeholderData: keepPreviousData keepPrevious: true
refetchInterval: polling ? 5000 : false interval: () => (polling() ? 5000 : false)
refetchOnWindowFocus refetchOnFocus
new QueryClient({ defaultOptions }) configure({ … }), sin proveedor
data, isLoading, isFetching r(), r.state() === "loading", r.loading()
useMutation({ mutationFn }) mutation({ run })
mutate(v, { onSuccess }) igual
qc.invalidateQueries({ queryKey }) invalidate(prefix)
qc.getQueryData / setQueryData / cancelQueries getData / setData / cancel

Dos diferencias de forma:

  • Un remote vive lo que vive su scope. Se crea dentro del componente que lo usa, no en un hook que se llama en cada render: el componente se ejecuta una vez.
  • Lo que cambia entra como función. Un hook recibe los filtros de este render; aquí la fábrica recibe cómo leerlos, y la clave los sigue sola:
ts
// React: useConversations(filters)
export function conversations(filters: () => Filters) {
  return remote({
    key: () => ["conversations", filters()] as const,
    load: ([, f]) => api.conversations(f),
    keepPrevious: true,
    interval: 15_000,
  });
}

Un sondeo trae objetos nuevos cada vez, y un <For> no repinta una fila cuya clave no cambió: la fila lee los datos con el segundo parámetro de render.

En el servidor

remote no carga en el servidor: se queda en idle, porque una caché de módulo compartida entre peticiones mezclaría datos de usuarios distintos. Los datos de una página renderizada en el servidor llegan con load() del kit de sitios.