@rindle/client 0.7.9 → 0.7.11

package/dist/ensure.d.ts

@@ -0,0 +1,68 @@
+import type { AnyQuery } from "./query.ts";
+import type { ColsMap } from "./schema.ts";
+import type { Store } from "./store.ts";
+/** When an {@link QueryEnsureCache.ensure} call may resolve.
+ *
+ * - `complete` waits for the server-authoritative result (the default).
+ * - `present` resolves as soon as the local view contains a result, while the remote retain keeps
+ *   revalidating in the background. An authoritative empty result also resolves it, so a real
+ *   not-found query never waits forever.
+ *
+ * `present` deliberately does not add a `partial` {@link ResultType}: a locally useful answer and
+ * server authority are independent facts. While it resolves early, the view's result type remains
+ * `unknown` until the server says otherwise. */
+export type EnsureQueryUntil = "complete" | "present";
+export interface EnsureQueryOptions {
+    /** Readiness policy. Defaults to `complete`. */
+    until?: EnsureQueryUntil;
+    /** Cancel this caller's wait. The shared query may stay retained for another waiter/prefetch. */
+    signal?: AbortSignal;
+}
+export interface QueryEnsureCacheOptions {
+    /** Keep a completed preload alive for this long so the destination can adopt its rows. */
+    releaseDelayMs?: number;
+    /** Bound retained preloads. In-flight waits are never evicted. */
+    maxEntries?: number;
+}
+/** The structural surface consumed by framework adapters such as `@rindle/tanstack`. */
+export interface QueryEnsurer {
+    ensure(query: AnyQuery, options?: EnsureQueryOptions): Promise<void>;
+}
+/**
+ * Deduplicates route/intent preloads and holds their live view through the navigation handoff.
+ *
+ * The cache materializes the real named query rather than retaining sync coverage alone: that is
+ * what makes `until: "present"` observable for overlapping queries already satisfied by local
+ * normalized rows. Once the server marks the query complete, the entry is kept briefly for a
+ * destination component to take its own retain, then released automatically.
+ */
+export declare class QueryEnsureCache<S extends ColsMap> implements QueryEnsurer {
+    private readonly store;
+    private readonly releaseDelayMs;
+    private readonly maxEntries;
+    private readonly entries;
+    private closed;
+    constructor(store: Store<S>, options?: QueryEnsureCacheOptions);
+    /**
+     * Ensure a named query is retained, resolving according to `options.until`.
+     *
+     * Concurrent calls for the same `(name, args, AST)` share one materialized view and one remote
+     * subscription. A `present` call can resolve from local rows while a concurrent `complete` call
+     * continues waiting for server authority.
+     */
+    ensure<Q extends AnyQuery>(query: Q, options?: EnsureQueryOptions): Promise<void>;
+    /** Release every retained preload and reject outstanding waits. Idempotent. */
+    close(): void;
+    /** Number of retained query entries (primarily useful for tests/devtools). */
+    size(): number;
+    private createEntry;
+    private inspect;
+    private isReady;
+    private touch;
+    private scheduleRelease;
+    private trim;
+    private dispose;
+    private queryError;
+    private detachAbort;
+}
+//# sourceMappingURL=ensure.d.ts.map

package/dist/ensure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure.d.ts","sourceRoot":"","sources":["../src/ensure.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC;;;;;;;;;gDASgD;AAChD,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,SAAS,CAAC;AAEtD,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,iGAAiG;IACjG,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,0FAA0F;IAC1F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE;AA6BD;;;;;;;GAOG;AACH,qBAAa,gBAAgB,CAAC,CAAC,SAAS,OAAO,CAAE,YAAW,YAAY;IACtE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAW;IACjC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,MAAM,CAAS;gBAEX,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,uBAA4B;IAMlE;;;;;;OAMG;IACG,MAAM,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAuC3F,+EAA+E;IAC/E,KAAK,IAAI,IAAI;IAOb,8EAA8E;IAC9E,IAAI,IAAI,MAAM;IAId,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,OAAO;IAsBf,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,KAAK;IAQb,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,IAAI;IAQZ,OAAO,CAAC,OAAO;IAef,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,WAAW;CAGpB"}

package/dist/ensure.js

@@ -0,0 +1,184 @@
+// Query readiness for route loaders and intent prefetching. `ResultType` remains the
+// server-authority axis; this module only decides when a caller has enough data to continue.
+import { stableKey } from "./key.js";
+const DEFAULT_RELEASE_DELAY_MS = 30_000;
+const DEFAULT_MAX_ENTRIES = 32;
+/**
+ * Deduplicates route/intent preloads and holds their live view through the navigation handoff.
+ *
+ * The cache materializes the real named query rather than retaining sync coverage alone: that is
+ * what makes `until: "present"` observable for overlapping queries already satisfied by local
+ * normalized rows. Once the server marks the query complete, the entry is kept briefly for a
+ * destination component to take its own retain, then released automatically.
+ */
+export class QueryEnsureCache {
+    store;
+    releaseDelayMs;
+    maxEntries;
+    entries = new Map();
+    closed = false;
+    constructor(store, options = {}) {
+        this.store = store;
+        this.releaseDelayMs = Math.max(0, options.releaseDelayMs ?? DEFAULT_RELEASE_DELAY_MS);
+        this.maxEntries = Math.max(1, options.maxEntries ?? DEFAULT_MAX_ENTRIES);
+    }
+    /**
+     * Ensure a named query is retained, resolving according to `options.until`.
+     *
+     * Concurrent calls for the same `(name, args, AST)` share one materialized view and one remote
+     * subscription. A `present` call can resolve from local rows while a concurrent `complete` call
+     * continues waiting for server authority.
+     */
+    async ensure(query, options = {}) {
+        if (this.closed)
+            throw new Error("QueryEnsureCache.ensure: cache is closed.");
+        if (options.signal?.aborted)
+            throw abortError();
+        if (typeof query.name !== "string") {
+            throw new Error("QueryEnsureCache.ensure: preloading requires a named query.");
+        }
+        const key = stableKey({ ast: query.ast(), remote: { name: query.name, args: query.args } });
+        let entry = this.entries.get(key);
+        if (!entry)
+            entry = this.createEntry(key, query);
+        this.touch(entry);
+        const until = options.until ?? "complete";
+        if (entry.view.resultType === "error") {
+            const error = this.queryError();
+            this.dispose(entry, error);
+            throw error;
+        }
+        if (this.isReady(entry, until)) {
+            if (entry.view.resultType === "complete")
+                this.scheduleRelease(entry);
+            this.trim();
+            return;
+        }
+        const ready = new Promise((resolve, reject) => {
+            const waiter = { until, resolve, reject, signal: options.signal };
+            if (options.signal) {
+                waiter.onAbort = () => {
+                    if (!entry.waiters.delete(waiter))
+                        return;
+                    reject(abortError());
+                };
+                options.signal.addEventListener("abort", waiter.onAbort, { once: true });
+            }
+            entry.waiters.add(waiter);
+        });
+        this.trim();
+        return ready;
+    }
+    /** Release every retained preload and reject outstanding waits. Idempotent. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const error = new Error("QueryEnsureCache: closed before the query became ready.");
+        for (const entry of [...this.entries.values()])
+            this.dispose(entry, error);
+    }
+    /** Number of retained query entries (primarily useful for tests/devtools). */
+    size() {
+        return this.entries.size;
+    }
+    createEntry(key, query) {
+        const view = this.store.materialize(query);
+        const entry = {
+            key,
+            view,
+            waiters: new Set(),
+            unsubscribe: () => { },
+            lastUsedAt: Date.now(),
+        };
+        this.entries.set(key, entry);
+        entry.unsubscribe = view.subscribe(() => this.inspect(entry));
+        return entry;
+    }
+    inspect(entry) {
+        if (this.entries.get(entry.key) !== entry)
+            return;
+        if (entry.view.resultType === "error") {
+            this.dispose(entry, this.queryError());
+            return;
+        }
+        for (const waiter of [...entry.waiters]) {
+            if (!this.isReady(entry, waiter.until))
+                continue;
+            entry.waiters.delete(waiter);
+            this.detachAbort(waiter);
+            waiter.resolve();
+        }
+        // A present waiter may have continued while authority was still unknown. Keep the retain alive
+        // through that revalidation; only a completed query starts the handoff/expiry clock.
+        if (entry.view.resultType === "complete" && entry.waiters.size === 0) {
+            this.scheduleRelease(entry);
+            this.trim();
+        }
+    }
+    isReady(entry, until) {
+        if (entry.view.resultType === "complete")
+            return true;
+        return until === "present" && hasLocalResult(entry.view.data);
+    }
+    touch(entry) {
+        entry.lastUsedAt = Date.now();
+        if (entry.releaseTimer !== undefined) {
+            clearTimeout(entry.releaseTimer);
+            entry.releaseTimer = undefined;
+        }
+    }
+    scheduleRelease(entry) {
+        if (this.entries.get(entry.key) !== entry || entry.waiters.size > 0)
+            return;
+        if (entry.releaseTimer !== undefined)
+            clearTimeout(entry.releaseTimer);
+        // Even a configured zero delay crosses a task boundary. Some local-first backends publish
+        // `complete` immediately before folding the authoritative catch-up batch; synchronous teardown
+        // here would unregister the view in the middle of that delivery.
+        entry.releaseTimer = setTimeout(() => this.dispose(entry), this.releaseDelayMs);
+        entry.releaseTimer.unref?.();
+    }
+    trim() {
+        if (this.entries.size <= this.maxEntries)
+            return;
+        const idle = [...this.entries.values()]
+            .filter((entry) => entry.waiters.size === 0)
+            .sort((left, right) => left.lastUsedAt - right.lastUsedAt);
+        while (this.entries.size > this.maxEntries && idle.length > 0)
+            this.dispose(idle.shift());
+    }
+    dispose(entry, error) {
+        if (this.entries.get(entry.key) !== entry)
+            return;
+        this.entries.delete(entry.key);
+        if (entry.releaseTimer !== undefined)
+            clearTimeout(entry.releaseTimer);
+        entry.unsubscribe();
+        entry.view.destroy();
+        if (error) {
+            for (const waiter of entry.waiters) {
+                this.detachAbort(waiter);
+                waiter.reject(error);
+            }
+        }
+        entry.waiters.clear();
+    }
+    queryError() {
+        return new Error("QueryEnsureCache.ensure: query entered the error result state.");
+    }
+    detachAbort(waiter) {
+        if (waiter.signal && waiter.onAbort)
+            waiter.signal.removeEventListener("abort", waiter.onAbort);
+    }
+}
+/** A plural query is locally present when it has at least one row; a `.one()` query when non-null. */
+function hasLocalResult(data) {
+    return Array.isArray(data) ? data.length > 0 : data !== null && data !== undefined;
+}
+function abortError() {
+    const error = new Error("QueryEnsureCache.ensure: wait was aborted.");
+    error.name = "AbortError";
+    return error;
+}
+//# sourceMappingURL=ensure.js.map

package/dist/ensure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure.js","sourceRoot":"","sources":["../src/ensure.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from "./operators.ts";
 export * from "./query.ts";
 export * from "./view.ts";
 export * from "./store.ts";
+export * from "./ensure.ts";
 export * from "./ssr.ts";
 export { resolveChange, subRow } from "./resolve.ts";
 export type { NamedRow, ResolvedChange } from "./resolve.ts";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AAEzB,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE7D,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE7E,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,EACL,MAAM,GACP,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,SAAS,EACT,eAAe,EACf,WAAW,EACX,KAAK,EACL,OAAO,EACP,WAAW,EACX,UAAU,EACV,QAAQ,EACR,WAAW,EACX,cAAc,EACd,UAAU,EACV,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE3G,YAAY,EACV,OAAO,EACP,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,OAAO,EACP,UAAU,EACV,MAAM,EACN,QAAQ,EACR,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,OAAO,EACP,WAAW,EACX,UAAU,EACV,QAAQ,EACR,cAAc,EACd,OAAO,EACP,UAAU,EACV,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG9F,YAAY,EACV,SAAS,EACT,GAAG,EACH,KAAK,EACL,SAAS,EACT,kBAAkB,EAClB,WAAW,EACX,GAAG,EACH,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,aAAa,GACd,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AAEzB,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE7D,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE7E,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,EACL,MAAM,GACP,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,SAAS,EACT,eAAe,EACf,WAAW,EACX,KAAK,EACL,OAAO,EACP,WAAW,EACX,UAAU,EACV,QAAQ,EACR,WAAW,EACX,cAAc,EACd,UAAU,EACV,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE3G,YAAY,EACV,OAAO,EACP,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,OAAO,EACP,UAAU,EACV,MAAM,EACN,QAAQ,EACR,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,OAAO,EACP,WAAW,EACX,UAAU,EACV,QAAQ,EACR,cAAc,EACd,OAAO,EACP,UAAU,EACV,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG9F,YAAY,EACV,SAAS,EACT,GAAG,EACH,KAAK,EACL,SAAS,EACT,kBAAkB,EAClB,WAAW,EACX,GAAG,EACH,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,aAAa,GACd,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -6,6 +6,7 @@ export * from "./operators.js"; // eq/ne/gt/ge/lt/le/like/notLike/ilike/notIlike
 export * from "./query.js"; // Query, QueryRoot, queries/newQueryBuilder, defineQuery/NamedQuery, exists, notExists, defineFragment/Fragment/FragmentRef/isFragment
 export * from "./view.js"; // ArrayView, SingularArrayView, FlatArrayView, SingularView, ViewTypes
 export * from "./store.js"; // Store, WriteTx, AssembledNode, DehydratedQuery, DehydratedState
+export * from "./ensure.js"; // QueryEnsureCache, EnsureQueryOptions, QueryEnsurer
 export * from "./ssr.js"; // createServerStore, ServerStore, OneShotBackend, OneShotQueryFn, OneShotResult, ServerStoreOptions
 export { resolveChange, subRow } from "./resolve.js"; // positional FlatChange → named rows (inverse of the wire encoder)
 // shared (generator) mutator seam — one body, sync on the client + async on the server

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,0FAA0F;AAC1F,8CAA8C;AAE9C,cAAc,aAAa,CAAC,CAAC,oMAAoM;AACjO,cAAc,gBAAgB,CAAC,CAAC,mGAAmG;AACnI,cAAc,YAAY,CAAC,CAAC,uIAAuI;AACnK,cAAc,WAAW,CAAC,CAAC,uEAAuE;AAClG,cAAc,YAAY,CAAC,CAAC,kEAAkE;AAC9F,cAAc,UAAU,CAAC,CAAC,oGAAoG;AAE9H,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC,CAAC,mEAAmE;AAIzH,uFAAuF;AACvF,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,EACL,MAAM,GACP,MAAM,mBAAmB,CAAC;AAmB3B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC,CAAC,2DAA2D;AAEjG,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AA8B3G,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,0FAA0F;AAC1F,8CAA8C;AAE9C,cAAc,aAAa,CAAC,CAAC,oMAAoM;AACjO,cAAc,gBAAgB,CAAC,CAAC,mGAAmG;AACnI,cAAc,YAAY,CAAC,CAAC,uIAAuI;AACnK,cAAc,WAAW,CAAC,CAAC,uEAAuE;AAClG,cAAc,YAAY,CAAC,CAAC,kEAAkE;AAC9F,cAAc,aAAa,CAAC,CAAC,qDAAqD;AAClF,cAAc,UAAU,CAAC,CAAC,oGAAoG;AAE9H,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC,CAAC,mEAAmE;AAIzH,uFAAuF;AACvF,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,EACL,MAAM,GACP,MAAM,mBAAmB,CAAC;AAmB3B,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC,CAAC,2DAA2D;AAEjG,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AA8B3G,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rindle/client",
-  "version": "0.7.9",
+  "version": "0.7.11",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/src/ensure.ts

@@ -0,0 +1,248 @@
+// Query readiness for route loaders and intent prefetching. `ResultType` remains the
+// server-authority axis; this module only decides when a caller has enough data to continue.
+
+import { stableKey } from "./key.ts";
+import type { AnyQuery } from "./query.ts";
+import type { ColsMap } from "./schema.ts";
+import type { Store } from "./store.ts";
+import type { ResultType } from "./types.ts";
+
+/** When an {@link QueryEnsureCache.ensure} call may resolve.
+ *
+ * - `complete` waits for the server-authoritative result (the default).
+ * - `present` resolves as soon as the local view contains a result, while the remote retain keeps
+ *   revalidating in the background. An authoritative empty result also resolves it, so a real
+ *   not-found query never waits forever.
+ *
+ * `present` deliberately does not add a `partial` {@link ResultType}: a locally useful answer and
+ * server authority are independent facts. While it resolves early, the view's result type remains
+ * `unknown` until the server says otherwise. */
+export type EnsureQueryUntil = "complete" | "present";
+
+export interface EnsureQueryOptions {
+  /** Readiness policy. Defaults to `complete`. */
+  until?: EnsureQueryUntil;
+  /** Cancel this caller's wait. The shared query may stay retained for another waiter/prefetch. */
+  signal?: AbortSignal;
+}
+
+export interface QueryEnsureCacheOptions {
+  /** Keep a completed preload alive for this long so the destination can adopt its rows. */
+  releaseDelayMs?: number;
+  /** Bound retained preloads. In-flight waits are never evicted. */
+  maxEntries?: number;
+}
+
+/** The structural surface consumed by framework adapters such as `@rindle/tanstack`. */
+export interface QueryEnsurer {
+  ensure(query: AnyQuery, options?: EnsureQueryOptions): Promise<void>;
+}
+
+interface EnsureView {
+  readonly data: unknown;
+  readonly resultType: ResultType;
+  subscribe(listener: () => void): () => void;
+  destroy(): void;
+}
+
+interface EnsureWaiter {
+  until: EnsureQueryUntil;
+  resolve: () => void;
+  reject: (reason: Error) => void;
+  signal?: AbortSignal;
+  onAbort?: () => void;
+}
+
+interface EnsureEntry {
+  key: string;
+  view: EnsureView;
+  waiters: Set<EnsureWaiter>;
+  unsubscribe: () => void;
+  releaseTimer?: ReturnType<typeof setTimeout>;
+  lastUsedAt: number;
+}
+
+const DEFAULT_RELEASE_DELAY_MS = 30_000;
+const DEFAULT_MAX_ENTRIES = 32;
+
+/**
+ * Deduplicates route/intent preloads and holds their live view through the navigation handoff.
+ *
+ * The cache materializes the real named query rather than retaining sync coverage alone: that is
+ * what makes `until: "present"` observable for overlapping queries already satisfied by local
+ * normalized rows. Once the server marks the query complete, the entry is kept briefly for a
+ * destination component to take its own retain, then released automatically.
+ */
+export class QueryEnsureCache<S extends ColsMap> implements QueryEnsurer {
+  private readonly store: Store<S>;
+  private readonly releaseDelayMs: number;
+  private readonly maxEntries: number;
+  private readonly entries = new Map<string, EnsureEntry>();
+  private closed = false;
+
+  constructor(store: Store<S>, options: QueryEnsureCacheOptions = {}) {
+    this.store = store;
+    this.releaseDelayMs = Math.max(0, options.releaseDelayMs ?? DEFAULT_RELEASE_DELAY_MS);
+    this.maxEntries = Math.max(1, options.maxEntries ?? DEFAULT_MAX_ENTRIES);
+  }
+
+  /**
+   * Ensure a named query is retained, resolving according to `options.until`.
+   *
+   * Concurrent calls for the same `(name, args, AST)` share one materialized view and one remote
+   * subscription. A `present` call can resolve from local rows while a concurrent `complete` call
+   * continues waiting for server authority.
+   */
+  async ensure<Q extends AnyQuery>(query: Q, options: EnsureQueryOptions = {}): Promise<void> {
+    if (this.closed) throw new Error("QueryEnsureCache.ensure: cache is closed.");
+    if (options.signal?.aborted) throw abortError();
+    if (typeof query.name !== "string") {
+      throw new Error("QueryEnsureCache.ensure: preloading requires a named query.");
+    }
+
+    const key = stableKey({ ast: query.ast(), remote: { name: query.name, args: query.args } });
+    let entry = this.entries.get(key);
+    if (!entry) entry = this.createEntry(key, query);
+    this.touch(entry);
+
+    const until = options.until ?? "complete";
+    if (entry.view.resultType === "error") {
+      const error = this.queryError();
+      this.dispose(entry, error);
+      throw error;
+    }
+    if (this.isReady(entry, until)) {
+      if (entry.view.resultType === "complete") this.scheduleRelease(entry);
+      this.trim();
+      return;
+    }
+
+    const ready = new Promise<void>((resolve, reject) => {
+      const waiter: EnsureWaiter = { until, resolve, reject, signal: options.signal };
+      if (options.signal) {
+        waiter.onAbort = () => {
+          if (!entry!.waiters.delete(waiter)) return;
+          reject(abortError());
+        };
+        options.signal.addEventListener("abort", waiter.onAbort, { once: true });
+      }
+      entry!.waiters.add(waiter);
+    });
+    this.trim();
+    return ready;
+  }
+
+  /** Release every retained preload and reject outstanding waits. Idempotent. */
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    const error = new Error("QueryEnsureCache: closed before the query became ready.");
+    for (const entry of [...this.entries.values()]) this.dispose(entry, error);
+  }
+
+  /** Number of retained query entries (primarily useful for tests/devtools). */
+  size(): number {
+    return this.entries.size;
+  }
+
+  private createEntry(key: string, query: AnyQuery): EnsureEntry {
+    const view = this.store.materialize(query) as unknown as EnsureView;
+    const entry: EnsureEntry = {
+      key,
+      view,
+      waiters: new Set(),
+      unsubscribe: () => {},
+      lastUsedAt: Date.now(),
+    };
+    this.entries.set(key, entry);
+    entry.unsubscribe = view.subscribe(() => this.inspect(entry));
+    return entry;
+  }
+
+  private inspect(entry: EnsureEntry): void {
+    if (this.entries.get(entry.key) !== entry) return;
+    if (entry.view.resultType === "error") {
+      this.dispose(entry, this.queryError());
+      return;
+    }
+
+    for (const waiter of [...entry.waiters]) {
+      if (!this.isReady(entry, waiter.until)) continue;
+      entry.waiters.delete(waiter);
+      this.detachAbort(waiter);
+      waiter.resolve();
+    }
+
+    // A present waiter may have continued while authority was still unknown. Keep the retain alive
+    // through that revalidation; only a completed query starts the handoff/expiry clock.
+    if (entry.view.resultType === "complete" && entry.waiters.size === 0) {
+      this.scheduleRelease(entry);
+      this.trim();
+    }
+  }
+
+  private isReady(entry: EnsureEntry, until: EnsureQueryUntil): boolean {
+    if (entry.view.resultType === "complete") return true;
+    return until === "present" && hasLocalResult(entry.view.data);
+  }
+
+  private touch(entry: EnsureEntry): void {
+    entry.lastUsedAt = Date.now();
+    if (entry.releaseTimer !== undefined) {
+      clearTimeout(entry.releaseTimer);
+      entry.releaseTimer = undefined;
+    }
+  }
+
+  private scheduleRelease(entry: EnsureEntry): void {
+    if (this.entries.get(entry.key) !== entry || entry.waiters.size > 0) return;
+    if (entry.releaseTimer !== undefined) clearTimeout(entry.releaseTimer);
+    // Even a configured zero delay crosses a task boundary. Some local-first backends publish
+    // `complete` immediately before folding the authoritative catch-up batch; synchronous teardown
+    // here would unregister the view in the middle of that delivery.
+    entry.releaseTimer = setTimeout(() => this.dispose(entry), this.releaseDelayMs);
+    (entry.releaseTimer as { unref?: () => void }).unref?.();
+  }
+
+  private trim(): void {
+    if (this.entries.size <= this.maxEntries) return;
+    const idle = [...this.entries.values()]
+      .filter((entry) => entry.waiters.size === 0)
+      .sort((left, right) => left.lastUsedAt - right.lastUsedAt);
+    while (this.entries.size > this.maxEntries && idle.length > 0) this.dispose(idle.shift()!);
+  }
+
+  private dispose(entry: EnsureEntry, error?: Error): void {
+    if (this.entries.get(entry.key) !== entry) return;
+    this.entries.delete(entry.key);
+    if (entry.releaseTimer !== undefined) clearTimeout(entry.releaseTimer);
+    entry.unsubscribe();
+    entry.view.destroy();
+    if (error) {
+      for (const waiter of entry.waiters) {
+        this.detachAbort(waiter);
+        waiter.reject(error);
+      }
+    }
+    entry.waiters.clear();
+  }
+
+  private queryError(): Error {
+    return new Error("QueryEnsureCache.ensure: query entered the error result state.");
+  }
+
+  private detachAbort(waiter: EnsureWaiter): void {
+    if (waiter.signal && waiter.onAbort) waiter.signal.removeEventListener("abort", waiter.onAbort);
+  }
+}
+
+/** A plural query is locally present when it has at least one row; a `.one()` query when non-null. */
+function hasLocalResult(data: unknown): boolean {
+  return Array.isArray(data) ? data.length > 0 : data !== null && data !== undefined;
+}
+
+function abortError(): Error {
+  const error = new Error("QueryEnsureCache.ensure: wait was aborted.");
+  error.name = "AbortError";
+  return error;
+}

package/src/index.ts

@@ -7,6 +7,7 @@ export * from "./operators.ts"; // eq/ne/gt/ge/lt/le/like/notLike/ilike/notIlike
 export * from "./query.ts"; // Query, QueryRoot, queries/newQueryBuilder, defineQuery/NamedQuery, exists, notExists, defineFragment/Fragment/FragmentRef/isFragment
 export * from "./view.ts"; // ArrayView, SingularArrayView, FlatArrayView, SingularView, ViewTypes
 export * from "./store.ts"; // Store, WriteTx, AssembledNode, DehydratedQuery, DehydratedState
+export * from "./ensure.ts"; // QueryEnsureCache, EnsureQueryOptions, QueryEnsurer
 export * from "./ssr.ts"; // createServerStore, ServerStore, OneShotBackend, OneShotQueryFn, OneShotResult, ServerStoreOptions
 
 export { resolveChange, subRow } from "./resolve.ts"; // positional FlatChange → named rows (inverse of the wire encoder)