@tanstack/db/dist/esm/query/builder/ref-proxy.d.ts

A reactive client store for building super fast apps on sync

import { BasicExpression } from '../ir.js';
import { RefLeaf } from './types.js';
import { VirtualRowProps } from '../../virtual-props.js';
export interface RefProxy<T = any> {
    /** @internal */
    readonly __refProxy: true;
    /** @internal */
    readonly __path: Array<string>;
    /** @internal */
    readonly __type: T;
}
/**
 * Virtual properties available on all row ref proxies.
 * These allow querying on sync status, origin, key, and collection ID.
 */
export type VirtualPropsRefProxy<TKey extends string | number = string | number> = {
    readonly [K in keyof VirtualRowProps<TKey>]: RefLeaf<VirtualRowProps<TKey>[K]>;
};
/**
 * Type for creating a RefProxy for a single row/type without namespacing
 * Used in collection indexes and where clauses
 *
 * Includes virtual properties ($synced, $origin, $key, $collectionId) for
 * querying on sync status and row metadata.
 */
export type SingleRowRefProxy<T, TKey extends string | number = string | number> = T extends Record<string, any> ? {
    [K in keyof T]: T[K] extends Record<string, any> ? SingleRowRefProxy<T[K], TKey> & RefProxy<T[K]> : RefLeaf<T[K]>;
} & RefProxy<T> & VirtualPropsRefProxy<TKey> : RefProxy<T> & VirtualPropsRefProxy<TKey>;
/**
 * Creates a proxy object that records property access paths for a single row
 * Used in collection indexes and where clauses
 */
export declare function createSingleRowRefProxy<T extends Record<string, any>>(): SingleRowRefProxy<T>;
/**
 * Creates a proxy object that records property access paths
 * Used in callbacks like where, select, etc. to create type-safe references
 */
export declare function createRefProxy<T extends Record<string, any>>(aliases: Array<string>): RefProxy<T> & T;
/**
 * Creates a ref proxy with $selected namespace for SELECT fields
 *
 * Adds a $selected property that allows accessing SELECT fields via $selected.fieldName syntax.
 * The $selected proxy creates paths like ['$selected', 'fieldName'] which directly reference
 * the $selected property on the namespaced row.
 *
 * @param aliases - Array of table aliases to create proxies for
 * @returns A ref proxy with table aliases and $selected namespace
 */
export declare function createRefProxyWithSelected<T extends Record<string, any>>(aliases: Array<string>): RefProxy<T> & T & {
    $selected: SingleRowRefProxy<any>;
};
/**
 * Converts a value to an Expression.
 * If it's a RefProxy, creates a PropRef. Throws if the value is a
 * ToArrayWrapper or ConcatToArrayWrapper (these must be used as direct
 * select fields). Otherwise wraps it as a Value.
 */
export declare function toExpression<T = any>(value: T): BasicExpression<T>;
export declare function toExpression(value: RefProxy<any>): BasicExpression<any>;
/**
 * Type guard to check if a value is a RefProxy
 */
export declare function isRefProxy(value: any): value is RefProxy;
/**
 * Helper to create a Value expression from a literal
 */
export declare function val<T>(value: T): BasicExpression<T>;