refactor(db): embed evaluator factories directly in IR nodes

Replace global registry pattern with embedded factories for true tree-shaking:
- Func nodes now carry their evaluator factory directly
- Aggregate nodes now carry their config (factory + valueTransform) directly
- Remove registry.ts and aggregate-registry.ts files
- Update all operators to pass factory as 3rd argument to Func
- Update all aggregates to pass config as 3rd argument to Aggregate
- Update internal code (optimizer, predicate-utils, expressions) to
  preserve factories when transforming Func nodes
- Add array overloads to and() and or() for internal usage
- Update tests to use builder functions instead of creating IR directly

This design eliminates the need for side-effect imports and ensures
only imported operators/aggregates are bundled.

Author: claude

.changeset/auto-register-operators.md

@@ -2,35 +2,53 @@
 "@tanstack/db": patch
 ---
 
-Add auto-registering operators and aggregates for tree-shaking support and custom extensibility.
+Refactor operators and aggregates to embed their evaluators directly in IR nodes for true tree-shaking support and custom extensibility.
 
-Each operator and aggregate now bundles its builder function and evaluator in a single file, registering itself when imported. This enables:
+Each operator and aggregate now bundles its builder function and evaluator factory in a single file. The factory is embedded directly in the `Func` or `Aggregate` IR node, eliminating the need for a global registry. This enables:
 
-- **Tree-shaking**: Only operators/aggregates you import are included in your bundle
-- **Custom operators**: Use `registerOperator()` to add your own operators
-- **Custom aggregates**: Use `registerAggregate()` to add your own aggregate functions
+- **True tree-shaking**: Only operators/aggregates you import are included in your bundle
+- **No global registry**: No side-effect imports needed; each node is self-contained
+- **Custom operators**: Create custom operators by building `Func` nodes with a factory
+- **Custom aggregates**: Create custom aggregates by building `Aggregate` nodes with a config
 
 **Custom Operator Example:**
 
 ```typescript
-import { registerOperator, type EvaluatorFactory } from "@tanstack/db"
+import {
+  Func,
+  type EvaluatorFactory,
+  type CompiledExpression,
+} from "@tanstack/db"
+import { toExpression } from "@tanstack/db/query"
 
-registerOperator("between", (compiledArgs, _isSingleRow) => {
+const betweenFactory: EvaluatorFactory = (compiledArgs, _isSingleRow) => {
   const [valueEval, minEval, maxEval] = compiledArgs
   return (data) => {
     const value = valueEval!(data)
     return value >= minEval!(data) && value <= maxEval!(data)
   }
-})
+}
+
+function between(value: any, min: any, max: any) {
+  return new Func(
+    "between",
+    [toExpression(value), toExpression(min), toExpression(max)],
+    betweenFactory
+  )
+}
 ```
 
 **Custom Aggregate Example:**
 
 ```typescript
-import { registerAggregate, type ValueExtractor } from "@tanstack/db"
+import {
+  Aggregate,
+  type AggregateConfig,
+  type ValueExtractor,
+} from "@tanstack/db"
+import { toExpression } from "@tanstack/db/query"
 
-// Custom "product" aggregate that multiplies values
-registerAggregate("product", {
+const productConfig: AggregateConfig = {
   factory: (valueExtractor: ValueExtractor) => ({
     preMap: valueExtractor,
     reduce: (values) => {
@@ -42,5 +60,9 @@ registerAggregate("product", {
     },
   }),
   valueTransform: "numeric",
-})
+}
+
+function product<T>(arg: T): Aggregate<number> {
+  return new Aggregate("product", [toExpression(arg)], productConfig)
+}
 ```

packages/db/src/query/builder/aggregates/avg.ts

@@ -1,22 +1,25 @@
 import { groupByOperators } from "@tanstack/db-ivm"
 import { Aggregate } from "../../ir.js"
 import { toExpression } from "../ref-proxy.js"
-import { registerAggregate } from "../../compiler/aggregate-registry.js"
 import type { AggregateReturnType, ExpressionLike } from "../operators/types.js"
 
 // ============================================================
-// BUILDER FUNCTION
+// CONFIG
 // ============================================================
 
-export function avg<T extends ExpressionLike>(arg: T): AggregateReturnType<T> {
-  return new Aggregate(`avg`, [toExpression(arg)]) as AggregateReturnType<T>
+const avgConfig = {
+  factory: groupByOperators.avg,
+  valueTransform: `numeric` as const,
 }
 
 // ============================================================
-// AUTO-REGISTRATION
+// BUILDER FUNCTION
 // ============================================================
 
-registerAggregate(`avg`, {
-  factory: groupByOperators.avg,
-  valueTransform: `numeric`,
-})
+export function avg<T extends ExpressionLike>(arg: T): AggregateReturnType<T> {
+  return new Aggregate(
+    `avg`,
+    [toExpression(arg)],
+    avgConfig
+  ) as AggregateReturnType<T>
+}

packages/db/src/query/builder/aggregates/count.ts

@@ -1,22 +1,21 @@
 import { groupByOperators } from "@tanstack/db-ivm"
 import { Aggregate } from "../../ir.js"
 import { toExpression } from "../ref-proxy.js"
-import { registerAggregate } from "../../compiler/aggregate-registry.js"
 import type { ExpressionLike } from "../operators/types.js"
 
 // ============================================================
-// BUILDER FUNCTION
+// CONFIG
 // ============================================================
 
-export function count(arg: ExpressionLike): Aggregate<number> {
-  return new Aggregate(`count`, [toExpression(arg)])
+const countConfig = {
+  factory: groupByOperators.count,
+  valueTransform: `raw` as const,
 }
 
 // ============================================================
-// AUTO-REGISTRATION
+// BUILDER FUNCTION
 // ============================================================
 
-registerAggregate(`count`, {
-  factory: groupByOperators.count,
-  valueTransform: `raw`,
-})
+export function count(arg: ExpressionLike): Aggregate<number> {
+  return new Aggregate(`count`, [toExpression(arg)], countConfig)
+}

packages/db/src/query/builder/aggregates/max.ts

@@ -1,22 +1,25 @@
 import { groupByOperators } from "@tanstack/db-ivm"
 import { Aggregate } from "../../ir.js"
 import { toExpression } from "../ref-proxy.js"
-import { registerAggregate } from "../../compiler/aggregate-registry.js"
 import type { AggregateReturnType, ExpressionLike } from "../operators/types.js"
 
 // ============================================================
-// BUILDER FUNCTION
+// CONFIG
 // ============================================================
 
-export function max<T extends ExpressionLike>(arg: T): AggregateReturnType<T> {
-  return new Aggregate(`max`, [toExpression(arg)]) as AggregateReturnType<T>
+const maxConfig = {
+  factory: groupByOperators.max,
+  valueTransform: `numericOrDate` as const,
 }
 
 // ============================================================
-// AUTO-REGISTRATION
+// BUILDER FUNCTION
 // ============================================================
 
-registerAggregate(`max`, {
-  factory: groupByOperators.max,
-  valueTransform: `numericOrDate`,
-})
+export function max<T extends ExpressionLike>(arg: T): AggregateReturnType<T> {
+  return new Aggregate(
+    `max`,
+    [toExpression(arg)],
+    maxConfig
+  ) as AggregateReturnType<T>
+}

packages/db/src/query/builder/aggregates/min.ts

@@ -1,22 +1,25 @@
 import { groupByOperators } from "@tanstack/db-ivm"
 import { Aggregate } from "../../ir.js"
 import { toExpression } from "../ref-proxy.js"
-import { registerAggregate } from "../../compiler/aggregate-registry.js"
 import type { AggregateReturnType, ExpressionLike } from "../operators/types.js"
 
 // ============================================================
-// BUILDER FUNCTION
+// CONFIG
 // ============================================================
 
-export function min<T extends ExpressionLike>(arg: T): AggregateReturnType<T> {
-  return new Aggregate(`min`, [toExpression(arg)]) as AggregateReturnType<T>
+const minConfig = {
+  factory: groupByOperators.min,
+  valueTransform: `numericOrDate` as const,
 }
 
 // ============================================================
-// AUTO-REGISTRATION
+// BUILDER FUNCTION
 // ============================================================
 
-registerAggregate(`min`, {
-  factory: groupByOperators.min,
-  valueTransform: `numericOrDate`,
-})
+export function min<T extends ExpressionLike>(arg: T): AggregateReturnType<T> {
+  return new Aggregate(
+    `min`,
+    [toExpression(arg)],
+    minConfig
+  ) as AggregateReturnType<T>
+}

packages/db/src/query/builder/aggregates/sum.ts

@@ -1,22 +1,25 @@
 import { groupByOperators } from "@tanstack/db-ivm"
 import { Aggregate } from "../../ir.js"
 import { toExpression } from "../ref-proxy.js"
-import { registerAggregate } from "../../compiler/aggregate-registry.js"
 import type { AggregateReturnType, ExpressionLike } from "../operators/types.js"
 
 // ============================================================
-// BUILDER FUNCTION
+// CONFIG
 // ============================================================
 
-export function sum<T extends ExpressionLike>(arg: T): AggregateReturnType<T> {
-  return new Aggregate(`sum`, [toExpression(arg)]) as AggregateReturnType<T>
+const sumConfig = {
+  factory: groupByOperators.sum,
+  valueTransform: `numeric` as const,
 }
 
 // ============================================================
-// AUTO-REGISTRATION
+// BUILDER FUNCTION
 // ============================================================
 
-registerAggregate(`sum`, {
-  factory: groupByOperators.sum,
-  valueTransform: `numeric`,
-})
+export function sum<T extends ExpressionLike>(arg: T): AggregateReturnType<T> {
+  return new Aggregate(
+    `sum`,
+    [toExpression(arg)],
+    sumConfig
+  ) as AggregateReturnType<T>
+}

packages/db/src/query/builder/operators/add.ts

@@ -1,23 +1,8 @@
 import { Func } from "../../ir.js"
 import { toExpression } from "../ref-proxy.js"
-import { registerOperator } from "../../compiler/registry.js"
-import type { CompiledExpression } from "../../compiler/registry.js"
+import type { CompiledExpression } from "../../ir.js"
 import type { BinaryNumericReturnType, ExpressionLike } from "./types.js"
 
-// ============================================================
-// BUILDER FUNCTION
-// ============================================================
-
-export function add<T1 extends ExpressionLike, T2 extends ExpressionLike>(
-  left: T1,
-  right: T2
-): BinaryNumericReturnType<T1, T2> {
-  return new Func(`add`, [
-    toExpression(left),
-    toExpression(right),
-  ]) as BinaryNumericReturnType<T1, T2>
-}
-
 // ============================================================
 // EVALUATOR
 // ============================================================
@@ -37,7 +22,16 @@ function addEvaluatorFactory(
 }
 
 // ============================================================
-// AUTO-REGISTRATION
+// BUILDER FUNCTION
 // ============================================================
 
-registerOperator(`add`, addEvaluatorFactory)
+export function add<T1 extends ExpressionLike, T2 extends ExpressionLike>(
+  left: T1,
+  right: T2
+): BinaryNumericReturnType<T1, T2> {
+  return new Func(
+    `add`,
+    [toExpression(left), toExpression(right)],
+    addEvaluatorFactory
+  ) as BinaryNumericReturnType<T1, T2>
+}

packages/db/src/query/builder/operators/and.ts

@@ -1,8 +1,6 @@
 import { Func } from "../../ir.js"
 import { toExpression } from "../ref-proxy.js"
-import { registerOperator } from "../../compiler/registry.js"
-import type { BasicExpression } from "../../ir.js"
-import type { CompiledExpression } from "../../compiler/registry.js"
+import type { BasicExpression, CompiledExpression } from "../../ir.js"
 
 // ============================================================
 // TYPES
@@ -11,32 +9,6 @@ import type { CompiledExpression } from "../../compiler/registry.js"
 // Helper type for any expression-like value
 type ExpressionLike = BasicExpression | any
 
-// ============================================================
-// BUILDER FUNCTION
-// ============================================================
-
-// Overloads for and() - support 2 or more arguments
-export function and(
-  left: ExpressionLike,
-  right: ExpressionLike
-): BasicExpression<boolean>
-export function and(
-  left: ExpressionLike,
-  right: ExpressionLike,
-  ...rest: Array<ExpressionLike>
-): BasicExpression<boolean>
-export function and(
-  left: ExpressionLike,
-  right: ExpressionLike,
-  ...rest: Array<ExpressionLike>
-): BasicExpression<boolean> {
-  const allArgs = [left, right, ...rest]
-  return new Func(
-    `and`,
-    allArgs.map((arg) => toExpression(arg))
-  )
-}
-
 // ============================================================
 // EVALUATOR
 // ============================================================
@@ -77,7 +49,38 @@ function andEvaluatorFactory(
 }
 
 // ============================================================
-// AUTO-REGISTRATION
+// BUILDER FUNCTION
 // ============================================================
 
-registerOperator(`and`, andEvaluatorFactory)
+// Overloads for and() - support 2 or more arguments, or an array
+export function and(
+  left: ExpressionLike,
+  right: ExpressionLike
+): BasicExpression<boolean>
+export function and(
+  left: ExpressionLike,
+  right: ExpressionLike,
+  ...rest: Array<ExpressionLike>
+): BasicExpression<boolean>
+export function and(args: Array<ExpressionLike>): BasicExpression<boolean>
+export function and(
+  leftOrArgs: ExpressionLike | Array<ExpressionLike>,
+  right?: ExpressionLike,
+  ...rest: Array<ExpressionLike>
+): BasicExpression<boolean> {
+  // Handle array overload
+  if (Array.isArray(leftOrArgs) && right === undefined) {
+    return new Func(
+      `and`,
+      leftOrArgs.map((arg) => toExpression(arg)),
+      andEvaluatorFactory
+    )
+  }
+  // Handle variadic overload
+  const allArgs = [leftOrArgs, right!, ...rest]
+  return new Func(
+    `and`,
+    allArgs.map((arg) => toExpression(arg)),
+    andEvaluatorFactory
+  )
+}