API index and search · Build metadata

Supporting declarations

packages/client/src/ensure.ts. These declarations explain referenced types. Only package-page symbols are package exports.

Exact source

/** 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;
}