@tanstack/db/dist/cjs/query/builder/ref-proxy.d.cts

A reactive client store for building super fast apps on sync

import { BasicExpression } from '../ir.js';
import { IsPlainObject, RefLeaf } from './types.js';
import { VirtualRowProps } from '../../virtual-props.js';
export { isRefProxy } from './ref-proxy-identity.js';
export interface RefProxy<T = any> {
    /** @internal */
    readonly __refProxy: true;
    /** @internal */
    readonly __path: Array<string>;
    /** @internal */
    readonly __sourceAlias?: 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 SingleRowField<V, TKey extends string | number> = [
    NonNullable<V>
] extends [never] ? RefLeaf<V> : IsPlainObject<NonNullable<V>> extends true ? SingleRowRefProxy<NonNullable<V>, TKey, false> | Extract<V, null | undefined> : RefLeaf<V>;
/**
 * Type for creating a RefProxy for a single row/type without namespacing
 * Used in collection indexes and where clauses
 *
 * Inferred row roots include virtual properties ($synced, $origin, $key,
 * $collectionId). The default exported shape is suitable for reusable helpers
 * that can accept either roots or recursively traversed user objects. Use the
 * third parameter as `true` when a helper specifically requires a row root.
 */
export type SingleRowRefProxy<T, TKey extends string | number = string | number, IncludeVirtualProps extends boolean = false> = T extends Record<string, any> ? {
    [K in keyof T]: SingleRowField<T[K], TKey>;
} & RefProxy<T> & (IncludeVirtualProps extends true ? VirtualPropsRefProxy<TKey> : {}) : RefProxy<T> & (IncludeVirtualProps extends true ? 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>, TKey extends string | number = string | number>(): SingleRowRefProxy<T, TKey, true>;
/**
 * 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, string | number, true>;
};
/**
 * Converts a value to an Expression.
 * If it's a RefProxy, creates a PropRef. Throws if the value is a
 * ToArrayWrapper, ConcatToArrayWrapper, CaseWhenWrapper, or MaterializeWrapper
 * (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>;
/**
 * Helper to create a Value expression from a literal
 */
export declare function val<T>(value: T): BasicExpression<T>;