@tanstack/db/dist/esm/collection/change-events.d.ts

A reactive client store for building super fast apps on sync

import { ChangeMessage, CollectionLike, CurrentStateAsChangesOptions, SubscribeChangesOptions } from '../types.js';
import { BasicExpression } from '../query/ir.js';
import { WithVirtualProps } from '../virtual-props.js';
/**
 * Yields visible entries, enriched with virtual properties, whose stored row
 * passes `prefilter`.
 */
export type StoredRowScan<T extends object, TKey extends string | number> = (prefilter: (row: object) => boolean) => Iterable<[TKey, WithVirtualProps<T, TKey>]>;
/**
 * Returns the current state of the collection as an array of changes
 * @param collection - The collection to get changes from
 * @param options - Options including optional where filter, orderBy, and limit
 * @returns An array of changes
 * @example
 * // Get all items as changes
 * const allChanges = currentStateAsChanges(collection)
 *
 * // Get only items matching a condition
 * const activeChanges = currentStateAsChanges(collection, {
 *   where: (row) => row.status === 'active'
 * })
 *
 * // Get only items using a pre-compiled expression
 * const activeChanges = currentStateAsChanges(collection, {
 *   where: eq(row.status, 'active')
 * })
 *
 * // Get items ordered by name with limit
 * const topUsers = currentStateAsChanges(collection, {
 *   orderBy: [{ expression: row.name, compareOptions: { direction: 'asc' } }],
 *   limit: 10
 * })
 *
 * // Get active users ordered by score (highest score first)
 * const topActiveUsers = currentStateAsChanges(collection, {
 *   where: eq(row.status, 'active'),
 *   orderBy: [{ expression: row.score, compareOptions: { direction: 'desc' } }],
 * })
 */
export declare function currentStateAsChanges<T extends object, TKey extends string | number>(collection: CollectionLike<WithVirtualProps<T, TKey>, TKey>, options?: CurrentStateAsChangesOptions, scanStoredRows?: StoredRowScan<T, TKey>): Array<ChangeMessage<WithVirtualProps<T, TKey>, TKey>> | void;
/**
 * Creates a filter function from a pre-compiled expression
 * @param expression - The pre-compiled expression to evaluate
 * @returns A function that takes an item and returns true if it matches the filter
 */
export declare function createFilterFunctionFromExpression<T extends object>(expression: BasicExpression<boolean>): (item: T) => boolean;
/** A field and the string or boolean literal a top-level `eq` requires. */
export type EqualityRoute = {
    path: Array<string>;
    /** Stable identity of `path`, for grouping routes by field. */
    pathKey: string;
    expected: string | boolean;
};
/** Read result for a route path whose property access threw. */
export declare const UNREADABLE_ROUTE_VALUE: unique symbol;
/**
 * Finds a cheap necessary condition for `expression` to be TRUE, or returns
 * undefined when the expression has none.
 *
 * A top-level conjunct `eq(field, literal)` with a string or boolean literal is
 * TRUE only when the field holds the identical string or boolean: equality
 * normalization never maps another type onto a plain string or boolean. A
 * row whose field holds anything else therefore fails the whole expression.
 *
 * With `storedRows`, the condition is read from a stored row instead of its
 * enriched copy, so conjuncts on virtual fields are skipped: stored rows need
 * not carry them.
 */
export declare function findEqualityRoute(expression: BasicExpression<boolean>, { storedRows }?: {
    storedRows?: boolean;
}): EqualityRoute | undefined;
/**
 * Reads a route field the way the single-row evaluator does. A throwing read
 * returns UNREADABLE_ROUTE_VALUE so callers leave the decision to the full
 * predicate.
 */
export declare function readRouteValue(row: unknown, path: ReadonlyArray<string>): unknown;
/**
 * Compiles the route of `expression` as a row test that is false only when
 * the full predicate must be false.
 *
 * The test reads a stored row instead of its enriched copy. The copy holds
 * each enumerable own root property of the stored row and lacks the others, so its field is either the stored value or `undefined`,
 * which never equals the literal. A read that throws passes the row to the
 * full predicate.
 */
export declare function compileEqualityPrefilter(expression: BasicExpression<boolean>): ((row: object) => boolean) | undefined;
/**
 * Creates a filtered callback that only calls the original callback with changes that match the where clause
 * @param originalCallback - The original callback to filter
 * @param options - The subscription options containing the where clause
 * @returns A filtered callback function
 */
export declare function createFilteredCallback<T extends object, TKey extends string | number = string | number>(originalCallback: (changes: Array<ChangeMessage<T>>) => void, options: SubscribeChangesOptions<T, TKey>): (changes: Array<ChangeMessage<T>>) => boolean;