@tanstack/db 0.5.32 → 0.5.33

package/dist/esm/index.d.ts

@@ -17,6 +17,7 @@ export * from './indexes/btree-index.js';
 export * from './indexes/lazy-index.js';
 export { type IndexOptions } from './indexes/index-options.js';
 export * from './query/expression-helpers.js';
+export { createEffect, type DeltaEvent, type DeltaType, type EffectConfig, type EffectContext, type Effect, type EffectQueryInput, } from './query/effect.js';
 export type { Collection } from './collection/index.js';
 export { IR };
 export { operators, type OperatorName } from './query/builder/functions.js';

package/dist/esm/index.js

@@ -13,6 +13,7 @@ import { BaseIndex, IndexOperation } from "./indexes/base-index.js";
 import { BTreeIndex } from "./indexes/btree-index.js";
 import { IndexProxy, LazyIndexWrapper } from "./indexes/lazy-index.js";
 import { extractFieldPath, extractSimpleComparisons, extractValue, parseLoadSubsetOptions, parseOrderByExpression, parseWhereExpression, walkExpression } from "./query/expression-helpers.js";
+import { createEffect } from "./query/effect.js";
 import { add, and, avg, coalesce, concat, count, eq, gt, gte, ilike, inArray, isNull, isUndefined, length, like, lower, lt, lte, max, min, not, operators, or, sum, upper } from "./query/builder/functions.js";
 import { BaseQueryBuilder, Query } from "./query/builder/index.js";
 import { DeduplicatedLoadSubset } from "./query/subset-dedupe.js";
@@ -131,6 +132,7 @@ export {
   createArrayChangeProxy,
   createChangeProxy,
   createCollection,
+  createEffect,
   createLiveQueryCollection,
   createOptimisticAction,
   createPacedMutations,

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/query/effect.d.ts

@@ -0,0 +1,94 @@
+import { InitialQueryBuilder, QueryBuilder } from './builder/index.js';
+import { Context } from './builder/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 collection enters an error or cleaned-up state.
+     * The effect is automatically disposed after this callback fires.
+     * If not provided, the error is logged to console.error.
+     */
+    onSourceError?: (error: Error) => 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. Returns a promise that resolves when in-flight handlers complete. */
+    dispose: () => Promise<void>;
+    /** Whether this effect has been disposed */
+    readonly disposed: boolean;
+}
+/**
+ * Creates a reactive effect that fires handlers when rows enter, exit, or
+ * update within a query result. Effects process deltas only — they do not
+ * maintain or require the full materialised query result.
+ *
+ * @example
+ * ```typescript
+ * const effect = createEffect({
+ *   query: (q) => q.from({ msg: messagesCollection })
+ *     .where(({ msg }) => eq(msg.role, 'user')),
+ *   onEnter: async (event) => {
+ *     await generateResponse(event.value)
+ *   },
+ * })
+ *
+ * // Later: stop the effect
+ * await effect.dispose()
+ * ```
+ */
+export declare function createEffect<TRow extends object = Record<string, unknown>, TKey extends string | number = string | number>(config: EffectConfig<TRow, TKey>): Effect;
+export {};