TanStack
diff --git a/‎.changeset/includes-parent-referencing-filters.md‎
Lines changed: 5 additions & 0 deletions b/‎.changeset/includes-parent-referencing-filters.md‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎packages/db/src/query/builder/index.ts‎
Lines changed: 136 additions & 8 deletions b/‎packages/db/src/query/builder/index.ts‎
Lines changed: 136 additions & 8 deletions
@@ -0,0 +1,5 @@
+---
+'@tanstack/db': patch
+---
+
+feat: support parent-referencing WHERE filters in includes child queries
@@ -33,6 +33,7 @@ import type {
   OrderBy,
   OrderByDirection,
   QueryIR,
+  Where,
 } from '../ir.js'
 import type {
   CompareOptions,
@@ -894,6 +895,39 @@ function buildNestedSelect(obj: any, parentAliases: Array<string> = []): any {
   return out
 }
 
+/**
+ * Recursively collects all PropRef nodes from an expression tree.
+ */
+function collectRefsFromExpression(expr: BasicExpression): Array<PropRef> {
+  const refs: Array<PropRef> = []
+  switch (expr.type) {
+    case `ref`:
+      refs.push(expr)
+      break
+    case `func`:
+      for (const arg of (expr as any).args ?? []) {
+        refs.push(...collectRefsFromExpression(arg))
+      }
+      break
+    default:
+      break
+  }
+  return refs
+}
+
+/**
+ * Checks whether a WHERE clause references any parent alias.
+ */
+function referencesParent(where: Where, parentAliases: Array<string>): boolean {
+  const expr =
+    typeof where === `object` && `expression` in where
+      ? where.expression
+      : where
+  return collectRefsFromExpression(expr).some(
+    (ref) => ref.path[0] != null && parentAliases.includes(ref.path[0]),
+  )
+}
+
 /**
  * Builds an IncludesSubquery IR node from a child query builder.
  * Extracts the correlation condition from the child's WHERE clauses by finding
@@ -915,10 +949,12 @@ function buildIncludesSubquery(
     }
   }
 
-  // Walk child's WHERE clauses to find the correlation condition
+  // Walk child's WHERE clauses to find the correlation condition.
+  // The correlation eq() may be a standalone WHERE or nested inside a top-level and().
   let parentRef: PropRef | undefined
   let childRef: PropRef | undefined
   let correlationWhereIndex = -1
+  let correlationAndArgIndex = -1 // >= 0 when found inside an and()
 
   if (childQuery.where) {
     for (let i = 0; i < childQuery.where.length; i++) {
@@ -928,16 +964,15 @@ function buildIncludesSubquery(
           ? where.expression
           : where
 
-      // Look for eq(a, b) where one side references parent and other references child
+      // Try standalone eq()
       if (
         expr.type === `func` &&
         expr.name === `eq` &&
         expr.args.length === 2
       ) {
-        const [argA, argB] = expr.args
         const result = extractCorrelation(
-          argA!,
-          argB!,
+          expr.args[0]!,
+          expr.args[1]!,
           parentAliases,
           childAliases,
         )
@@ -948,6 +983,37 @@ function buildIncludesSubquery(
           break
         }
       }
+
+      // Try inside top-level and()
+      if (
+        expr.type === `func` &&
+        expr.name === `and` &&
+        expr.args.length >= 2
+      ) {
+        for (let j = 0; j < expr.args.length; j++) {
+          const arg = expr.args[j]!
+          if (
+            arg.type === `func` &&
+            arg.name === `eq` &&
+            arg.args.length === 2
+          ) {
+            const result = extractCorrelation(
+              arg.args[0]!,
+              arg.args[1]!,
+              parentAliases,
+              childAliases,
+            )
+            if (result) {
+              parentRef = result.parentRef
+              childRef = result.childRef
+              correlationWhereIndex = i
+              correlationAndArgIndex = j
+              break
+            }
+          }
+        }
+        if (parentRef) break
+      }
     }
   }
 
@@ -959,19 +1025,81 @@ function buildIncludesSubquery(
     )
   }
 
-  // Remove the correlation WHERE from the child query
+  // Remove the correlation eq() from the child query's WHERE clauses.
+  // If it was inside an and(), remove just that arg (collapsing the and() if needed).
   const modifiedWhere = [...childQuery.where!]
-  modifiedWhere.splice(correlationWhereIndex, 1)
+  if (correlationAndArgIndex >= 0) {
+    const where = modifiedWhere[correlationWhereIndex]!
+    const expr =
+      typeof where === `object` && `expression` in where
+        ? where.expression
+        : where
+    const remainingArgs = (expr as any).args.filter(
+      (_: any, idx: number) => idx !== correlationAndArgIndex,
+    )
+    if (remainingArgs.length === 1) {
+      // Collapse and() with single remaining arg to just that expression
+      const isResidual =
+        typeof where === `object` && `expression` in where && where.residual
+      modifiedWhere[correlationWhereIndex] = isResidual
+        ? { expression: remainingArgs[0], residual: true }
+        : remainingArgs[0]
+    } else {
+      // Rebuild and() without the extracted arg
+      const newAnd = new FuncExpr(`and`, remainingArgs)
+      const isResidual =
+        typeof where === `object` && `expression` in where && where.residual
+      modifiedWhere[correlationWhereIndex] = isResidual
+        ? { expression: newAnd, residual: true }
+        : newAnd
+    }
+  } else {
+    modifiedWhere.splice(correlationWhereIndex, 1)
+  }
+
+  // Separate remaining WHEREs into pure-child vs parent-referencing
+  const pureChildWhere: Array<Where> = []
+  const parentFilters: Array<Where> = []
+  for (const w of modifiedWhere) {
+    if (referencesParent(w, parentAliases)) {
+      parentFilters.push(w)
+    } else {
+      pureChildWhere.push(w)
+    }
+  }
+
+  // Collect distinct parent PropRefs from parent-referencing filters
+  let parentProjection: Array<PropRef> | undefined
+  if (parentFilters.length > 0) {
+    const seen = new Set<string>()
+    parentProjection = []
+    for (const w of parentFilters) {
+      const expr = typeof w === `object` && `expression` in w ? w.expression : w
+      for (const ref of collectRefsFromExpression(expr)) {
+        if (
+          ref.path[0] != null &&
+          parentAliases.includes(ref.path[0]) &&
+          !seen.has(ref.path.join(`.`))
+        ) {
+          seen.add(ref.path.join(`.`))
+          parentProjection.push(ref)
+        }
+      }
+    }
+  }
+
   const modifiedQuery: QueryIR = {
     ...childQuery,
-    where: modifiedWhere.length > 0 ? modifiedWhere : undefined,
+    where: pureChildWhere.length > 0 ? pureChildWhere : undefined,
   }
 
   return new IncludesSubquery(
     modifiedQuery,
     parentRef,
     childRef,
     fieldName,
+    parentFilters.length > 0 ? parentFilters : undefined,
+    parentProjection,
     materializeAsArray,
   )
 }
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@tanstack/db': patch
 +---
++
 +feat: support parent-referencing WHERE filters in includes child queries