@tanstack/db/dist/esm/query/effect.d.ts

A reactive client store for building super fast apps on sync

import { InitialQueryBuilder, QueryBuilder } from './builder/index.js';
import { Context } from './builder/types.js';
import { HealthNode } from '../types.js';
/** Event types for query result deltas */
export type DeltaType = 'enter' | 'exit' | 'update';
/** Delta event emitted when a row enters, exits, or updates within a query result */
export type DeltaEvent<TRow extends object = Record<string, unknown>, TKey extends string | number = string | number> = {
    type: 'enter';
    key: TKey;
    /** Current value for the entering row */
    value: TRow;
    metadata?: Record<string, unknown>;
} | {
    type: 'exit';
    key: TKey;
    /** Current value for the exiting row */
    value: TRow;
    metadata?: Record<string, unknown>;
} | {
    type: 'update';
    key: TKey;
    /** Current value after the update */
    value: TRow;
    /** Previous value before the batch */
    previousValue: TRow;
    metadata?: Record<string, unknown>;
};
/** Context passed to effect handlers */
export interface EffectContext {
    /** ID of this effect (auto-generated if not provided) */
    effectId: string;
    /** Aborted when effect.dispose() is called */
    signal: AbortSignal;
}
/** Query input - can be a builder function or a prebuilt query */
export type EffectQueryInput<TContext extends Context> = ((q: InitialQueryBuilder) => QueryBuilder<TContext>) | QueryBuilder<TContext>;
type EffectEventHandler<TRow extends object = Record<string, unknown>, TKey extends string | number = string | number> = (event: DeltaEvent<TRow, TKey>, ctx: EffectContext) => void | Promise<void>;
type EffectBatchHandler<TRow extends object = Record<string, unknown>, TKey extends string | number = string | number> = (events: Array<DeltaEvent<TRow, TKey>>, ctx: EffectContext) => void | Promise<void>;
/** Effect configuration */
export interface EffectConfig<TRow extends object = Record<string, unknown>, TKey extends string | number = string | number> {
    /** Optional ID for debugging/tracing */
    id?: string;
    /** Query to watch for deltas */
    query: EffectQueryInput<any>;
    /** Called once for each row entering the query result */
    onEnter?: EffectEventHandler<TRow, TKey>;
    /** Called once for each row updating within the query result */
    onUpdate?: EffectEventHandler<TRow, TKey>;
    /** Called once for each row exiting the query result */
    onExit?: EffectEventHandler<TRow, TKey>;
    /** Called once per graph run with all delta events from that batch */
    onBatch?: EffectBatchHandler<TRow, TKey>;
    /** Error handler for exceptions thrown by effect callbacks */
    onError?: (error: Error, event: DeltaEvent<TRow, TKey>) => void;
    /**
     * Called when a source crashes, fails its first load before the effect's
     * initial-query readiness, or is cleaned up while the effect reads it, and
     * when a subset load the effect requests from a source, or its release,
     * fails, before or after that readiness. A cascade cleanup that ends the
     * effect does not call it.
     * The effect is automatically disposed after this callback fires. If not
     * provided, the error is logged to console.error.
     */
    onSourceError?: (error: Error) => void;
    /**
     * Called after the effect's initial-query readiness whenever its health tree
     * changes. A sync problem after initial-query readiness does not dispose the
     * effect; read the health tree to decide what to do.
     */
    onHealthChange?: (health: HealthNode) => void;
    /**
     * Skip deltas during initial collection load.
     * Defaults to false (process all deltas including initial sync).
     * Set to true for effects that should only process new changes.
     */
    skipInitial?: boolean;
}
/** Handle returned by createEffect */
export interface Effect {
    /**
     * Dispose the effect and await in-flight handlers. Calls during one cleanup
     * attempt, including calls from abort/release callbacks, share its outcome.
     */
    dispose: () => Promise<void>;
    /** Whether this effect has been disposed */
    readonly disposed: boolean;
}
export declare function createEffect<TRow extends object = Record<string, unknown>, TKey extends string | number = string | number>(config: EffectConfig<TRow, TKey>): Effect;
export {};