ascua-query 0.1.0

package/LICENSE-APACHE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Los autores de Ascua
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# ascua-query
+
+Datos remotos para [Ascua](https://ascua.gitweave.run) en **2,15 kB** gzip: una
+caché compartida por clave encima de los signals del runtime. Dos vistas que
+piden lo mismo hacen una sola petición; una mutación invalida lo que cambió y
+todo lo que lo muestra se recarga.
+
+```sh
+stil add ascua-query      # o npm install ascua-query
+```
+
+```ts
+import { invalidate, mutation, remote } from "ascua-query";
+
+const filters = signal({ status: "open", page: 1 });
+
+const conversations = remote({
+  key: () => ["conversations", filters()],          // reactiva: cambia, recarga
+  load: ([, f], { signal }) => api.conversations(f, { signal }),
+  keepPrevious: true,                               // sin pantalla en blanco al paginar
+  interval: 15_000,                                 // sondeo, solo con la pestaña visible
+});
+
+const create = mutation({
+  run: (data: NewUser) => api.createUser(data),
+  onSuccess: () => invalidate(["users"]),           // `pending()` espera a la recarga
+});
+
+view`
+  <Show when=${() => conversations()}>${(c) => view`<Table rows=${c}/>`}</Show>
+  <button disabled=${() => create.pending()} onclick=${() => create.mutate(form())}>Create</button>`;
+```
+
+Sin contexto ni proveedor que instalar, como el router: la caché es del
+módulo. Una consulta se suscribe mientras vive el scope en que se creó; al
+cerrar la vista la suelta, y lo que nadie mira se borra pasado `gcTime`.
+
+## Lo que hay
+
+| | |
+|---|---|
+| `remote({ key, load, … })` | Una consulta. Se lee llamándola; `state()`, `loading()`, `error()`, `placeholder()`, `updatedAt()`, `reload()`. |
+| `mutation({ run, onMutate, onSuccess, onError, onSettled })` | Una escritura: `mutate()`, `mutateAsync()`, `state()`, `pending()`, `data()`, `error()`, `reset()`. |
+| `invalidate(prefix?)` | Caduca lo que empieza por `prefix`; lo que se está mirando, se recarga ya. |
+| `setData(key, value \| (old) => next)` / `getData(key)` | Leer y escribir la caché a mano: actualizaciones optimistas. |
+| `cancel(prefix?)` | Corta las cargas en camino, para que no pisen una escritura optimista. |
+| `prefetch(key, load)` | Cargar antes de que una vista lo pida. |
+| `configure({ staleTime, gcTime, retry, retryDelay, refetchOnFocus })` | Valores por defecto de todas las consultas. |
+| `clearCache()` | Vaciarla: tests y cierres de sesión. |
+
+Los valores por defecto son los de TanStack Query, para que migrar no cambie
+el comportamiento: `staleTime: 0`, `gcTime` de cinco minutos, tres reintentos
+con espera creciente y recarga al volver a la pestaña o a la red.
+
+Lo que no hay que escribir a mano:
+
+- **Deduplicación.** Mientras una clave está cargando, quien la pida espera
+  esa misma carga.
+- **Una respuesta vieja nunca pisa a una nueva.** Una recarga aborta la
+  anterior (el `signal` que recibe `load` se dispara) y descarta su respuesta.
+- **Un sondeo que trae lo mismo no repinta nada.** Lo nuevo reusa cada objeto
+  de lo anterior que no cambió: con un `<For>` con clave, solo se toca la
+  fila que cambió.
+- **La clave es reactiva.** `key: () => id() ? ["messages", id()] : null`: con
+  `null` la consulta queda en `idle`, igual que un `resource`.
+
+`remote` se llama así, y no `query`, porque `ascua-router` ya exporta
+`query()` —los parámetros de la URL— y una vista de lista suele usar los dos.

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+/**
+ * # ascua-query
+ *
+ * Datos remotos para Ascua: una caché compartida por clave encima de los
+ * signals del runtime. Lo que `resource` hace para una vista —cargar, recargar,
+ * cancelar—, aquí lo comparten todas: dos vistas que piden la misma clave
+ * hacen una sola petición, una mutación invalida lo que cambió y todo lo que
+ * lo muestra se recarga.
+ *
+ * Sin contexto ni proveedor que instalar, como el router: la caché es del
+ * módulo. Los valores por defecto son los de TanStack Query, para que migrar
+ * no cambie el comportamiento: los datos caducan al momento (`staleTime: 0`),
+ * la caché de lo que nadie mira dura cinco minutos, se reintenta tres veces y
+ * se recarga al volver a la pestaña.
+ */
+/** La clave de una consulta: `["conversations", { page: 2 }]`. */
+export type QueryKey = readonly unknown[];
+/** En qué está una consulta. Como `ResourceState` del runtime. */
+export type QueryState = "idle" | "loading" | "ready" | "error";
+/** Lo que recibe `load`: con qué cancelar la petición. */
+export interface LoadInfo {
+    signal: AbortSignal;
+}
+/** Lo que se puede configurar para todas las consultas. */
+export interface QueryDefaults {
+    /** Milisegundos durante los que un dato se da por fresco. Por defecto, 0. */
+    staleTime: number;
+    /** Cuánto sigue en caché lo que ninguna vista mira. Por defecto, 5 minutos. */
+    gcTime: number;
+    /** Reintentos tras un fallo. Por defecto, 3. */
+    retry: number;
+    /** Espera antes del reintento `n` (desde 0). Por defecto, 1 s, 2 s, 4 s… hasta 30 s. */
+    retryDelay: (attempt: number) => number;
+    /** Recargar lo caducado al volver a la pestaña o a la red. Por defecto, sí. */
+    refetchOnFocus: boolean;
+}
+export interface RemoteOptions<K extends QueryKey, T, R = T> extends Partial<QueryDefaults> {
+    /**
+     * La clave. Es reactiva: si lee un signal, la consulta sigue a ese signal.
+     * `null`, `undefined` o `false` la desactivan (queda en `idle`).
+     */
+    key: () => K | null | undefined | false;
+    /** Carga los datos de una clave. */
+    load: (key: K, info: LoadInfo) => Promise<T>;
+    /**
+     * Recargar cada tantos milisegundos mientras la vista esté montada y la
+     * pestaña visible. Puede ser reactivo: `() => polling() ? 5000 : false`.
+     */
+    interval?: number | false | (() => number | false);
+    /** Al cambiar de clave, seguir mostrando los datos anteriores hasta que lleguen los nuevos. */
+    keepPrevious?: boolean;
+    /** Transforma lo cargado antes de entregarlo. */
+    select?: (data: T) => R;
+}
+/** Una consulta: se lee llamándola, como un signal. */
+export interface Remote<R> {
+    /** Los datos, o `undefined` hasta que lleguen. Mientras se recarga siguen ahí. */
+    (): R | undefined;
+    state(): QueryState;
+    /** Hay una carga en camino: la primera o una recarga. */
+    loading(): boolean;
+    /** El error de la última carga, o `undefined` si fue bien. */
+    error(): unknown;
+    /** Lo que se ve es de la clave anterior (`keepPrevious`) mientras carga la nueva. */
+    placeholder(): boolean;
+    /** Cuándo llegaron los datos (`Date.now()`), o 0 si aún no. */
+    updatedAt(): number;
+    /** Vuelve a cargar ahora, aunque los datos estén frescos. */
+    reload(): Promise<void>;
+}
+/** Cambia los valores por defecto de todas las consultas. */
+export declare function configure(opciones: Partial<QueryDefaults>): void;
+/**
+ * Datos remotos con caché: `const users = remote({ key: () => ["users"], load: api.users })`.
+ *
+ * Carga al crearse si no hay datos frescos para la clave, y cada vez que la
+ * clave cambia. Se suscribe a la entrada de la caché mientras viva el scope
+ * en que se creó: al cerrar la vista la suelta, y lo que nadie mira se borra
+ * pasado `gcTime`. En el servidor no carga: se queda en `idle`.
+ */
+export declare function remote<K extends QueryKey, T, R = T>(opciones: RemoteOptions<K, T, R>): Remote<R>;
+/**
+ * Da por caducado todo lo que empieza por `prefix` (`["users"]` cubre
+ * `["users", 4]`; sin prefijo, todo). Lo que alguna vista está mirando se
+ * recarga ya, cortando la carga en camino si la hay; el resto, la próxima vez
+ * que se monte. La promesa se cumple cuando terminan las recargas.
+ */
+export declare function invalidate(prefix?: QueryKey, options?: {
+    refetch?: boolean;
+}): Promise<void>;
+/** Los datos en caché de una clave exacta, sin cargar nada. */
+export declare function getData<T>(key: QueryKey): T | undefined;
+/**
+ * Escribe los datos de una clave como si acabaran de llegar: lo que ya se
+ * sabe tras guardar algo, o una actualización optimista.
+ */
+export declare function setData<T>(key: QueryKey, value: T | ((old: T | undefined) => T)): T;
+/**
+ * Corta las cargas en camino de lo que empieza por `prefix`. Antes de una
+ * actualización optimista, para que una respuesta vieja no pise lo escrito.
+ */
+export declare function cancel(prefix?: QueryKey): Promise<void>;
+/** Carga una clave antes de que una vista la pida (si no hay datos frescos). */
+export declare function prefetch<K extends QueryKey, T>(key: K, load: (key: K, info: LoadInfo) => Promise<T>, options?: Partial<QueryDefaults>): Promise<void>;
+/** Vacía la caché entera, cortando lo que esté en camino. Para tests y cierres de sesión. */
+export declare function clearCache(): void;
+/** En qué está una mutación. */
+export type MutationState = "idle" | "pending" | "success" | "error";
+export interface MutationOptions<V, R, C = unknown> {
+    /** Lo que guarda: una petición al servidor. */
+    run: (variables: V) => Promise<R>;
+    /**
+     * Antes de `run`. Lo que devuelva llega como contexto a los demás: el
+     * estado anterior para deshacer una actualización optimista.
+     */
+    onMutate?: (variables: V) => C | Promise<C>;
+    onSuccess?: (data: R, variables: V, context: C | undefined) => unknown;
+    onError?: (error: unknown, variables: V, context: C | undefined) => unknown;
+    /** Al terminar, haya ido bien o mal. */
+    onSettled?: (data: R | undefined, error: unknown, variables: V, context: C | undefined) => unknown;
+}
+/** Sin variables, `mutate()` se llama sin argumentos. */
+type Variables<V> = undefined extends V ? [variables?: V] : [variables: V];
+export interface Mutation<V, R> {
+    /** Lanza la mutación. Un fallo queda en `error()`: no hace falta capturarlo. */
+    mutate(...variables: Variables<V>): void;
+    /** Igual, pero devuelve el resultado y rechaza si falla. */
+    mutateAsync(...variables: Variables<V>): Promise<R>;
+    state(): MutationState;
+    pending(): boolean;
+    /** El resultado de la última que fue bien. */
+    data(): R | undefined;
+    error(): unknown;
+    /** Vuelve a `idle`, olvidando resultado y error. */
+    reset(): void;
+}
+/**
+ * Una escritura con su estado: `const save = mutation({ run: api.save, onSuccess: () => invalidate(["users"]) })`.
+ *
+ * Los `on…` se esperan si devuelven una promesa: `pending()` sigue siendo
+ * `true` mientras `onSuccess` recarga lo que invalidó, así que el botón no se
+ * libera antes de que la lista esté al día.
+ */
+export declare function mutation<V = void, R = unknown, C = unknown>(opciones: MutationOptions<V, R, C>): Mutation<V, R>;
+export {};

package/dist/index.js

@@ -0,0 +1,424 @@
+/**
+ * # ascua-query
+ *
+ * Datos remotos para Ascua: una caché compartida por clave encima de los
+ * signals del runtime. Lo que `resource` hace para una vista —cargar, recargar,
+ * cancelar—, aquí lo comparten todas: dos vistas que piden la misma clave
+ * hacen una sola petición, una mutación invalida lo que cambió y todo lo que
+ * lo muestra se recarga.
+ *
+ * Sin contexto ni proveedor que instalar, como el router: la caché es del
+ * módulo. Los valores por defecto son los de TanStack Query, para que migrar
+ * no cambie el comportamiento: los datos caducan al momento (`staleTime: 0`),
+ * la caché de lo que nadie mira dura cinco minutos, se reintenta tres veces y
+ * se recarga al volver a la pestaña.
+ */
+import { batch, effect, memo, onCleanup, signal, untrack } from "ascua";
+// ---------------------------------------------------------------------------
+// La caché
+// ---------------------------------------------------------------------------
+const porDefecto = {
+    staleTime: 0,
+    gcTime: 5 * 60_000,
+    retry: 3,
+    retryDelay: (n) => Math.min(1000 * 2 ** n, 30_000),
+    refetchOnFocus: true,
+};
+/** Cambia los valores por defecto de todas las consultas. */
+export function configure(opciones) {
+    Object.assign(porDefecto, opciones);
+}
+const cache = new Map();
+/** Un texto estable para una clave: los objetos, con las propiedades ordenadas. */
+function hashDe(clave) {
+    return JSON.stringify(clave, (_, valor) => valor && typeof valor === "object" && !Array.isArray(valor)
+        ? Object.fromEntries(Object.keys(valor)
+            .sort()
+            .map((k) => [k, valor[k]]))
+        : valor);
+}
+/** ¿Empieza `clave` por `prefijo`? `["users"]` cubre `["users", 4]`. */
+function coincide(prefijo, clave) {
+    return prefijo.length <= clave.length && prefijo.every((p, i) => hashDe([p]) === hashDe([clave[i]]));
+}
+function obtener(clave) {
+    const hash = hashDe(clave);
+    let e = cache.get(hash);
+    if (!e) {
+        e = {
+            clave,
+            hash,
+            datos: signal(undefined),
+            estado: signal("idle"),
+            fallo: signal(undefined),
+            actualizado: signal(0),
+            invalidada: false,
+            opciones: { ...porDefecto },
+            oyentes: 0,
+        };
+        cache.set(hash, e);
+        programarRecogida(e);
+    }
+    return e;
+}
+function caducada(e) {
+    const cuando = e.actualizado.peek();
+    return e.invalidada || cuando === 0 || Date.now() - cuando >= e.opciones.staleTime;
+}
+function esperar(ms, señal) {
+    return new Promise((resolver, rechazar) => {
+        const t = setTimeout(resolver, ms);
+        señal.addEventListener("abort", () => {
+            clearTimeout(t);
+            rechazar(señal.reason);
+        });
+    });
+}
+/** Carga una entrada. Si ya hay una carga en camino, es esa: no se duplica. */
+function cargar(e) {
+    if (e.vuelo)
+        return e.vuelo;
+    const fn = e.cargar;
+    if (!fn)
+        return Promise.resolve();
+    const control = new AbortController();
+    const { retry, retryDelay } = e.opciones;
+    e.control = control;
+    e.estado.set("loading");
+    const vuelo = (async () => {
+        for (let intento = 0;; intento++) {
+            try {
+                return await fn(e.clave, { signal: control.signal });
+            }
+            catch (error) {
+                if (control.signal.aborted || intento >= retry)
+                    throw error;
+                await esperar(retryDelay(intento), control.signal);
+            }
+        }
+    })()
+        .then((dato) => {
+        if (control.signal.aborted)
+            return;
+        e.invalidada = false;
+        batch(() => {
+            e.datos.set(compartir(e.datos.peek(), dato));
+            e.fallo.set(undefined);
+            e.actualizado.set(Date.now());
+            e.estado.set("ready");
+        });
+    }, (error) => {
+        if (control.signal.aborted)
+            return;
+        batch(() => {
+            e.fallo.set(error);
+            e.estado.set("error");
+        });
+    })
+        .finally(() => {
+        if (e.control === control) {
+            e.control = undefined;
+            e.vuelo = undefined;
+        }
+    });
+    e.vuelo = vuelo;
+    return vuelo;
+}
+/** Corta la carga en camino y deja el estado como estaba antes de empezarla. */
+function abortar(e) {
+    if (!e.control)
+        return;
+    e.control.abort();
+    e.control = undefined;
+    e.vuelo = undefined;
+    e.estado.set(e.fallo.peek() !== undefined ? "error" : e.datos.peek() !== undefined ? "ready" : "idle");
+}
+function programarRecogida(e) {
+    if (e.gc)
+        clearTimeout(e.gc);
+    const t = setTimeout(() => {
+        if (e.oyentes > 0 || cache.get(e.hash) !== e)
+            return;
+        abortar(e);
+        cache.delete(e.hash);
+    }, e.opciones.gcTime);
+    // En Node, un temporizador de la caché no debe mantener vivo el proceso.
+    t.unref?.();
+    e.gc = t;
+}
+function suscribir(e) {
+    e.oyentes++;
+    if (e.gc) {
+        clearTimeout(e.gc);
+        e.gc = undefined;
+    }
+    escucharFoco();
+}
+function soltar(e) {
+    e.oyentes--;
+    if (e.oyentes === 0)
+        programarRecogida(e);
+}
+const enNavegador = typeof window !== "undefined" && typeof document !== "undefined";
+let escuchando = false;
+function escucharFoco() {
+    if (escuchando || !enNavegador)
+        return;
+    escuchando = true;
+    const alVolver = () => {
+        for (const e of cache.values()) {
+            if (e.oyentes > 0 && e.opciones.refetchOnFocus && caducada(e))
+                void cargar(e);
+        }
+    };
+    document.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "visible")
+            alVolver();
+    });
+    window.addEventListener("online", alVolver);
+}
+function esPlano(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Lo nuevo, pero reusando de lo viejo cada objeto que no cambió. Un sondeo que
+ * trae lo mismo devuelve el mismo objeto, y nada se vuelve a pintar; si cambió
+ * una fila, las demás conservan su identidad.
+ */
+function compartir(viejo, nuevo) {
+    if (viejo === nuevo)
+        return viejo;
+    const arreglos = Array.isArray(viejo) && Array.isArray(nuevo);
+    if (!arreglos && !(esPlano(viejo) && esPlano(nuevo)))
+        return nuevo;
+    const a = viejo;
+    const b = nuevo;
+    const claves = Object.keys(b);
+    const resultado = arreglos ? [] : {};
+    let iguales = claves.length === Object.keys(a).length;
+    for (const k of claves) {
+        const v = compartir(a[k], b[k]);
+        resultado[k] = v;
+        if (v !== a[k] || !(k in a))
+            iguales = false;
+    }
+    return iguales ? viejo : resultado;
+}
+// ---------------------------------------------------------------------------
+// Consultas
+// ---------------------------------------------------------------------------
+/**
+ * Datos remotos con caché: `const users = remote({ key: () => ["users"], load: api.users })`.
+ *
+ * Carga al crearse si no hay datos frescos para la clave, y cada vez que la
+ * clave cambia. Se suscribe a la entrada de la caché mientras viva el scope
+ * en que se creó: al cerrar la vista la suelta, y lo que nadie mira se borra
+ * pasado `gcTime`. En el servidor no carga: se queda en `idle`.
+ */
+export function remote(opciones) {
+    const actual = signal(null);
+    /** La última entrada que tenía datos: lo que `keepPrevious` sigue mostrando. */
+    let anterior = null;
+    effect(() => {
+        const clave = opciones.key();
+        if (clave === null || clave === undefined || clave === false) {
+            actual.set(null);
+            return;
+        }
+        untrack(() => {
+            const e = obtener(clave);
+            e.cargar = opciones.load;
+            e.opciones = {
+                staleTime: opciones.staleTime ?? porDefecto.staleTime,
+                gcTime: opciones.gcTime ?? porDefecto.gcTime,
+                retry: opciones.retry ?? porDefecto.retry,
+                retryDelay: opciones.retryDelay ?? porDefecto.retryDelay,
+                refetchOnFocus: opciones.refetchOnFocus ?? porDefecto.refetchOnFocus,
+            };
+            suscribir(e);
+            onCleanup(() => soltar(e));
+            const previa = actual.peek();
+            if (previa && previa !== e && previa.datos.peek() !== undefined)
+                anterior = previa;
+            actual.set(e);
+            if (enNavegador && !e.vuelo && caducada(e))
+                void cargar(e);
+        });
+    });
+    if (opciones.interval) {
+        effect(() => {
+            const e = actual();
+            const intervalo = opciones.interval;
+            const ms = typeof intervalo === "function" ? intervalo() : intervalo;
+            if (!e || !ms || !enNavegador)
+                return;
+            const t = setInterval(() => {
+                if (document.visibilityState !== "hidden")
+                    void cargar(e);
+            }, ms);
+            onCleanup(() => clearInterval(t));
+        });
+    }
+    const propia = memo(() => actual()?.datos());
+    const placeholder = memo(() => {
+        if (!opciones.keepPrevious || !actual() || propia() !== undefined)
+            return false;
+        return anterior?.datos() !== undefined;
+    });
+    const crudo = memo(() => (placeholder() ? anterior?.datos() : propia()));
+    const seleccion = memo(() => {
+        const dato = crudo();
+        return dato === undefined || !opciones.select ? dato : opciones.select(dato);
+    });
+    const consulta = (() => seleccion());
+    consulta.state = () => actual()?.estado() ?? "idle";
+    consulta.loading = () => consulta.state() === "loading";
+    consulta.error = () => actual()?.fallo();
+    consulta.placeholder = placeholder;
+    consulta.updatedAt = () => actual()?.actualizado() ?? 0;
+    consulta.reload = () => {
+        const e = actual.peek();
+        if (!e)
+            return Promise.resolve();
+        abortar(e);
+        return cargar(e);
+    };
+    return consulta;
+}
+// ---------------------------------------------------------------------------
+// La caché a mano
+// ---------------------------------------------------------------------------
+function entradas(prefijo) {
+    return [...cache.values()].filter((e) => coincide(prefijo, e.clave));
+}
+/**
+ * Da por caducado todo lo que empieza por `prefix` (`["users"]` cubre
+ * `["users", 4]`; sin prefijo, todo). Lo que alguna vista está mirando se
+ * recarga ya, cortando la carga en camino si la hay; el resto, la próxima vez
+ * que se monte. La promesa se cumple cuando terminan las recargas.
+ */
+export function invalidate(prefix = [], options = {}) {
+    const recargas = [];
+    for (const e of entradas(prefix)) {
+        e.invalidada = true;
+        if (e.oyentes > 0 && options.refetch !== false && enNavegador) {
+            abortar(e);
+            recargas.push(cargar(e));
+        }
+    }
+    return Promise.all(recargas).then(() => undefined);
+}
+/** Los datos en caché de una clave exacta, sin cargar nada. */
+export function getData(key) {
+    return cache.get(hashDe(key))?.datos.peek();
+}
+/**
+ * Escribe los datos de una clave como si acabaran de llegar: lo que ya se
+ * sabe tras guardar algo, o una actualización optimista.
+ */
+export function setData(key, value) {
+    const e = obtener(key);
+    const nuevo = typeof value === "function" ? value(e.datos.peek()) : value;
+    e.invalidada = false;
+    batch(() => {
+        e.datos.set(nuevo);
+        e.fallo.set(undefined);
+        e.actualizado.set(Date.now());
+        if (!e.vuelo)
+            e.estado.set("ready");
+    });
+    return nuevo;
+}
+/**
+ * Corta las cargas en camino de lo que empieza por `prefix`. Antes de una
+ * actualización optimista, para que una respuesta vieja no pise lo escrito.
+ */
+export function cancel(prefix = []) {
+    for (const e of entradas(prefix))
+        abortar(e);
+    return Promise.resolve();
+}
+/** Carga una clave antes de que una vista la pida (si no hay datos frescos). */
+export function prefetch(key, load, options = {}) {
+    const e = obtener(key);
+    e.cargar = load;
+    e.opciones = { ...porDefecto, ...options };
+    return caducada(e) ? cargar(e) : Promise.resolve();
+}
+/** Vacía la caché entera, cortando lo que esté en camino. Para tests y cierres de sesión. */
+export function clearCache() {
+    for (const e of cache.values()) {
+        abortar(e);
+        if (e.gc)
+            clearTimeout(e.gc);
+    }
+    cache.clear();
+}
+/**
+ * Una escritura con su estado: `const save = mutation({ run: api.save, onSuccess: () => invalidate(["users"]) })`.
+ *
+ * Los `on…` se esperan si devuelven una promesa: `pending()` sigue siendo
+ * `true` mientras `onSuccess` recarga lo que invalidó, así que el botón no se
+ * libera antes de que la lista esté al día.
+ */
+export function mutation(opciones) {
+    const estado = signal("idle");
+    const datos = signal(undefined);
+    const fallo = signal(undefined);
+    /** Si se lanza otra antes de que termine, el estado es de la última. */
+    let vuelta = 0;
+    const mutateAsync = async (...args) => {
+        const variables = args[0];
+        const esta = ++vuelta;
+        batch(() => {
+            estado.set("pending");
+            fallo.set(undefined);
+        });
+        let contexto;
+        try {
+            contexto = await opciones.onMutate?.(variables);
+            const resultado = await opciones.run(variables);
+            await opciones.onSuccess?.(resultado, variables, contexto);
+            await opciones.onSettled?.(resultado, undefined, variables, contexto);
+            if (esta === vuelta) {
+                batch(() => {
+                    datos.set(resultado);
+                    estado.set("success");
+                });
+            }
+            return resultado;
+        }
+        catch (error) {
+            if (esta === vuelta) {
+                batch(() => {
+                    fallo.set(error);
+                    estado.set("error");
+                });
+            }
+            await opciones.onError?.(error, variables, contexto);
+            await opciones.onSettled?.(undefined, error, variables, contexto);
+            throw error;
+        }
+    };
+    return {
+        mutate: (...variables) => {
+            mutateAsync(...variables).catch(() => { });
+        },
+        mutateAsync,
+        state: () => estado(),
+        pending: () => estado() === "pending",
+        data: () => datos(),
+        error: () => fallo(),
+        reset: () => {
+            vuelta++;
+            batch(() => {
+                estado.set("idle");
+                datos.set(undefined);
+                fallo.set(undefined);
+            });
+        },
+    };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "ascua-query",
+  "version": "0.1.0",
+  "description": "Datos remotos para Ascua: caché por clave, recarga, sondeo, invalidación y mutaciones optimistas. Sin contexto ni proveedor.",
+  "keywords": [
+    "query",
+    "cache",
+    "fetch",
+    "signals",
+    "ascua"
+  ],
+  "homepage": "https://ascua.gitweave.run",
+  "license": "MIT OR Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "size": "node ../../scripts/measure-query.mjs",
+    "prepublishOnly": "tsc -p tsconfig.build.json"
+  },
+  "peerDependencies": {
+    "ascua": "^0.5.0"
+  },
+  "devDependencies": {
+    "vite": "^8.3.0",
+    "vitest": "^5.0.1",
+    "happy-dom": "^20.14.5",
+    "typescript": "^7.0.2",
+    "terser": "^5.51.2"
+  }
+}