@tanstack/db
Version:
A reactive client store for building super fast apps on sync
133 lines (132 loc) • 6.44 kB
TypeScript
import { Collection } from './collection/index.js';
import { CollectionStatus } from './types.js';
import { Context, QueryBuilder } from './query/builder/index.js';
export type LiveQueryWindowInputKind = `collection` | `query`;
/** @internal The supported, enabled input forms for infinite-query adapters. */
export type ResolvedLiveQueryWindowInput<TContext extends Context> = {
kind: `collection`;
collection: Collection<any, any, any>;
} | {
kind: `query`;
query: QueryBuilder<TContext>;
};
/**
* Classify an infinite-query input without invoking its query callback.
* Frameworks use this during lifecycle comparison so unchanged React renders
* do not execute the callback again.
*
* @internal This contract is unstable while RFC #1623 is being implemented.
*/
export declare function getLiveQueryWindowInputKind(input: unknown): LiveQueryWindowInputKind;
/**
* Resolve a supported infinite-query input and invoke a query callback once.
* A function may resolve to a collection for framework getter compatibility.
* Nullable/disabled and config-object inputs are intentionally not supported.
*
* @internal This contract is unstable while RFC #1623 is being implemented.
*/
export declare function resolveLiveQueryWindowInput<TContext extends Context>(input: unknown): ResolvedLiveQueryWindowInput<TContext>;
/** @internal This contract is unstable while RFC #1623 is being implemented. */
export declare function normalizeLiveQueryWindowPageSize(pageSize: number | undefined): number;
type WindowResult = true | Promise<void>;
type LiveQueryWindow = {
offset: number;
limit: number;
};
/** @internal Shared adapter view of a collection with an ordered window. */
export type LiveQueryWindowCollection = Collection<any, any, any> & {
utils: {
setWindow: (options: LiveQueryWindow) => WindowResult;
getWindow: () => LiveQueryWindow | undefined;
};
};
/** @internal Whether an infinite-query controller currently owns this window. */
export declare function hasLiveQueryWindowLeases(target: object): boolean;
/** @internal Shared validation for infinite-query adapters. */
export declare function assertLiveQueryWindowManyResult(collection: Collection<any, any, any>): void;
/** @internal Whether a collection exposes an active ordered window. */
export declare function isLiveQueryWindowCollection(collection: Collection<any, any, any>): collection is LiveQueryWindowCollection;
/**
* Validate a pre-created infinite-query collection and describe any window
* adjustment the adapter should warn about.
*
* @internal Shared validation for infinite-query adapters.
*/
export declare function getLiveQueryWindowCollectionWarning(collection: Collection<any, any, any>, expectedLimit: number): string | undefined;
/** @internal Compare adapter dependencies by identity and structure. */
export declare function compareLiveQueryWindowDependencies(previous: ReadonlyArray<unknown> | null | undefined, current: ReadonlyArray<unknown>): {
changed: boolean;
structurallyEqual: boolean;
};
/** @internal Shared page-depth preservation policy for framework adapters. */
export declare function shouldPreserveLiveQueryWindowPageCount(options: {
hasPreviousController: boolean;
previousInputKind: `collection` | `query` | undefined;
inputKind: `collection` | `query`;
sameCollection: boolean;
dependenciesChanged: boolean;
dependenciesStructurallyEqual: boolean;
pageShapeChanged: boolean;
}): boolean;
/**
* A page-windowed view of a live query at a point in time.
*
* @internal This contract is unstable while RFC #1623 is being implemented.
*/
export interface LiveQueryWindowSnapshot<T extends object, TKey extends string | number> {
/** Rows across all committed pages, with the peek-ahead row removed. */
data: ReadonlyArray<T>;
/** Rows grouped into committed pages of `pageSize`. */
pages: ReadonlyArray<ReadonlyArray<T>>;
/** `initialPageParam + i` for each committed page. */
pageParams: ReadonlyArray<number>;
hasNextPage: boolean;
isFetchingNextPage: boolean;
/** The last pagination failure, cleared when a retry begins. */
error: unknown;
/** Keyed results for the physical window, or `undefined` when disabled. */
state: ReadonlyMap<TKey, T> | undefined;
collection: Collection<T, TKey, any> | undefined;
status: CollectionStatus | `disabled`;
isLoading: boolean;
isReady: boolean;
isIdle: boolean;
isError: boolean;
isCleanedUp: boolean;
isEnabled: boolean;
}
/** @internal This contract is unstable while RFC #1623 is being implemented. */
export interface CreateLiveQueryWindowControllerOptions {
/** Rows per page (default 20). Invalid values use the default. */
pageSize?: number;
/** Value of the first page's `pageParam` (default 0). */
initialPageParam?: number;
/** Committed pages to preserve when a framework binding changes page shape. */
initialPageCount?: number;
}
/** @internal This contract is unstable while RFC #1623 is being implemented. */
export interface LiveQueryWindowController<T extends object, TKey extends string | number> {
getSnapshot: () => LiveQueryWindowSnapshot<T, TKey>;
subscribe: (listener: () => void) => () => void;
/** Load one more page, resolving only after that page is committed. */
fetchNextPage: () => Promise<void>;
/** Reset to the first page, resolving after the smaller window is accepted. */
reset: () => Promise<void>;
preload: () => Promise<void>;
dispose: () => void;
}
/**
* Run an adapter-facing page fetch. The controller records failures in its
* snapshot; consuming the rejection here keeps event handlers safe while the
* returned promise still settles with the request.
*
* @internal This contract is unstable while RFC #1623 is being implemented.
*/
export declare function fetchNextLiveQueryWindowPage(controller: Pick<LiveQueryWindowController<object, string | number>, `fetchNextPage`>): Promise<void>;
/**
* Create an internal forward-window controller for an ordered live query.
*
* @internal This factory is unstable while RFC #1623 is being implemented.
*/
export declare function createLiveQueryWindowController<T extends object, TKey extends string | number>(collection: Collection<T, TKey, any> | null | undefined, options?: CreateLiveQueryWindowControllerOptions): LiveQueryWindowController<T, TKey>;
export {};