add support for composable queries (#232)

Author: samwillis

.changeset/wicked-grapes-thank.md

@@ -0,0 +1,7 @@
+---
+"@tanstack/react-db": patch
+"@tanstack/vue-db": patch
+"@tanstack/db": patch
+---
+
+add support for composable queries

packages/db/src/query/builder/ref-proxy.ts

@@ -1,4 +1,4 @@
-import { Ref, Value } from "../ir.js"
+import { PropRef, Value } from "../ir.js"
 import type { BasicExpression } from "../ir.js"
 
 export interface RefProxy<T = any> {
@@ -124,7 +124,7 @@ export function toExpression<T = any>(value: T): BasicExpression<T>
 export function toExpression(value: RefProxy<any>): BasicExpression<any>
 export function toExpression(value: any): BasicExpression<any> {
   if (isRefProxy(value)) {
-    return new Ref(value.__path)
+    return new PropRef(value.__path)
   }
   // If it's already an Expression (Func, Ref, Value) or Agg, return it directly
   if (

packages/db/src/query/builder/types.ts

@@ -139,6 +139,10 @@ export type RefProxyFor<T> = OmitRefProxy<
         : RefProxy<T>
 >
 
+// This is the public type that is exported from the query builder
+// and is used when constructing reusable query callbacks.
+export type Ref<T> = RefProxyFor<T>
+
 type OmitRefProxy<T> = Omit<T, `__refProxy` | `__path` | `__type`>
 
 // The core RefProxy interface

packages/db/src/query/compiler/evaluators.ts

@@ -1,4 +1,4 @@
-import type { BasicExpression, Func, Ref } from "../ir.js"
+import type { BasicExpression, Func, PropRef } from "../ir.js"
 import type { NamespacedRow } from "../../types.js"
 
 /**
@@ -36,7 +36,7 @@ export function compileExpression(expr: BasicExpression): CompiledExpression {
 /**
  * Compiles a reference expression into an optimized evaluator
  */
-function compileRef(ref: Ref): CompiledExpression {
+function compileRef(ref: PropRef): CompiledExpression {
   const [tableAlias, ...propertyPath] = ref.path
 
   if (!tableAlias) {

packages/db/src/query/compiler/group-by.ts

@@ -1,5 +1,5 @@
 import { filter, groupBy, groupByOperators, map } from "@electric-sql/d2mini"
-import { Func, Ref } from "../ir.js"
+import { Func, PropRef } from "../ir.js"
 import { compileExpression } from "./evaluators.js"
 import type {
   Aggregate,
@@ -372,7 +372,7 @@ function transformHavingClause(
       for (const [alias, selectExpr] of Object.entries(selectClause)) {
         if (selectExpr.type === `agg` && aggregatesEqual(aggExpr, selectExpr)) {
           // Replace with a reference to the computed aggregate
-          return new Ref([`result`, alias])
+          return new PropRef([`result`, alias])
         }
       }
       // If no matching aggregate found in SELECT, throw error
@@ -398,7 +398,7 @@ function transformHavingClause(
         const alias = refExpr.path[0]!
         if (selectClause[alias]) {
           // This is a reference to a SELECT alias, convert to result.alias
-          return new Ref([`result`, alias])
+          return new PropRef([`result`, alias])
         }
       }
       // Return as-is for other refs

packages/db/src/query/index.ts

@@ -41,17 +41,7 @@ export {
 } from "./builder/functions.js"
 
 // Ref proxy utilities
-export { val, toExpression, isRefProxy } from "./builder/ref-proxy.js"
-
-// IR types (for advanced usage)
-export type {
-  QueryIR,
-  BasicExpression as Expression,
-  Aggregate,
-  CollectionRef,
-  QueryRef,
-  JoinClause,
-} from "./ir.js"
+export type { Ref } from "./builder/types.js"
 
 // Compiler
 export { compileQuery } from "./compiler/index.js"

packages/db/src/query/ir.ts

@@ -84,7 +84,7 @@ export class QueryRef extends BaseExpression {
   }
 }
 
-export class Ref<T = any> extends BaseExpression<T> {
+export class PropRef<T = any> extends BaseExpression<T> {
   public type = `ref` as const
   constructor(
     public path: Array<string> // path to the property in the collection, with the alias as the first element
@@ -115,7 +115,7 @@ export class Func<T = any> extends BaseExpression<T> {
 // This is the basic expression type that is used in the majority of expression
 // builder callbacks (select, where, groupBy, having, orderBy, etc.)
 // it doesn't include aggregate functions as those are only used in the select clause
-export type BasicExpression<T = any> = Ref<T> | Value<T> | Func<T>
+export type BasicExpression<T = any> = PropRef<T> | Value<T> | Func<T>
 
 export class Aggregate<T = any> extends BaseExpression<T> {
   public type = `agg` as const

packages/db/src/query/live-query-collection.ts

@@ -1,7 +1,7 @@
 import { D2, MultiSet, output } from "@electric-sql/d2mini"
 import { createCollection } from "../collection.js"
 import { compileQuery } from "./compiler/index.js"
-import { buildQuery } from "./builder/index.js"
+import { buildQuery, getQueryIR } from "./builder/index.js"
 import type { InitialQueryBuilder, QueryBuilder } from "./builder/index.js"
 import type { Collection } from "../collection.js"
 import type {
@@ -55,7 +55,9 @@ export interface LiveQueryCollectionConfig<
   /**
    * Query builder function that defines the live query
    */
-  query: (q: InitialQueryBuilder) => QueryBuilder<TContext>
+  query:
+    | ((q: InitialQueryBuilder) => QueryBuilder<TContext>)
+    | QueryBuilder<TContext>
 
   /**
    * Function to extract the key from result items
@@ -119,8 +121,11 @@ export function liveQueryCollectionOptions<
   // Generate a unique ID if not provided
   const id = config.id || `live-query-${++liveQueryCollectionCounter}`
 
-  // Build the query using the provided query builder function
-  const query = buildQuery<TContext>(config.query)
+  // Build the query using the provided query builder function or instance
+  const query =
+    typeof config.query === `function`
+      ? buildQuery<TContext>(config.query)
+      : getQueryIR(config.query)
 
   // WeakMap to store the keys of the results so that we can retreve them in the
   // getKey function
@@ -401,11 +406,11 @@ export function createLiveQueryCollection<
   if (typeof configOrQuery === `function`) {
     // Simple query function case
     const config: LiveQueryCollectionConfig<TContext, TResult> = {
-      query: configOrQuery,
+      query: configOrQuery as (
+        q: InitialQueryBuilder
+      ) => QueryBuilder<TContext>,
     }
     const options = liveQueryCollectionOptions<TContext, TResult>(config)
-
-    // Use a bridge function that handles the type compatibility cleanly
     return bridgeToCreateCollection(options)
   } else {
     // Config object case
@@ -414,8 +419,6 @@ export function createLiveQueryCollection<
       TResult
     > & { utils?: TUtils }
     const options = liveQueryCollectionOptions<TContext, TResult>(config)
-
-    // Use a bridge function that handles the type compatibility cleanly
     return bridgeToCreateCollection({
       ...options,
       utils: config.utils,

packages/db/tests/query/builder/ref-proxy.test.ts

@@ -5,7 +5,7 @@ import {
   toExpression,
   val,
 } from "../../../src/query/builder/ref-proxy.js"
-import { Ref, Value } from "../../../src/query/ir.js"
+import { PropRef, Value } from "../../../src/query/ir.js"
 
 describe(`ref-proxy`, () => {
   describe(`createRefProxy`, () => {
@@ -170,9 +170,9 @@ describe(`ref-proxy`, () => {
       const userIdProxy = proxy.users.id
 
       const expr = toExpression(userIdProxy)
-      expect(expr).toBeInstanceOf(Ref)
+      expect(expr).toBeInstanceOf(PropRef)
       expect(expr.type).toBe(`ref`)
-      expect((expr as Ref).path).toEqual([`users`, `id`])
+      expect((expr as PropRef).path).toEqual([`users`, `id`])
     })
 
     it(`converts literal values to Value expression`, () => {
@@ -183,7 +183,7 @@ describe(`ref-proxy`, () => {
     })
 
     it(`returns existing expressions unchanged`, () => {
-      const refExpr = new Ref([`users`, `id`])
+      const refExpr = new PropRef([`users`, `id`])
       const valExpr = new Value(42)
 
       expect(toExpression(refExpr)).toBe(refExpr)

packages/db/tests/query/compiler/basic.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "vitest"
 import { D2, MultiSet, output } from "@electric-sql/d2mini"
 import { compileQuery } from "../../../src/query/compiler/index.js"
-import { CollectionRef, Func, Ref, Value } from "../../../src/query/ir.js"
+import { CollectionRef, Func, PropRef, Value } from "../../../src/query/ir.js"
 import type { QueryIR } from "../../../src/query/ir.js"
 import type { CollectionImpl } from "../../../src/collection.js"
 
@@ -82,9 +82,9 @@ describe(`Query2 Compiler`, () => {
       const query: QueryIR = {
         from: new CollectionRef(usersCollection, `users`),
         select: {
-          id: new Ref([`users`, `id`]),
-          name: new Ref([`users`, `name`]),
-          age: new Ref([`users`, `age`]),
+          id: new PropRef([`users`, `id`]),
+          name: new PropRef([`users`, `name`]),
+          age: new PropRef([`users`, `age`]),
         },
       }
 
@@ -150,11 +150,11 @@ describe(`Query2 Compiler`, () => {
       const query: QueryIR = {
         from: new CollectionRef(usersCollection, `users`),
         select: {
-          id: new Ref([`users`, `id`]),
-          name: new Ref([`users`, `name`]),
-          age: new Ref([`users`, `age`]),
+          id: new PropRef([`users`, `id`]),
+          name: new PropRef([`users`, `name`]),
+          age: new PropRef([`users`, `age`]),
         },
-        where: [new Func(`gt`, [new Ref([`users`, `age`]), new Value(20)])],
+        where: [new Func(`gt`, [new PropRef([`users`, `age`]), new Value(20)])],
       }
 
       const graph = new D2()
@@ -203,13 +203,13 @@ describe(`Query2 Compiler`, () => {
       const query: QueryIR = {
         from: new CollectionRef(usersCollection, `users`),
         select: {
-          id: new Ref([`users`, `id`]),
-          name: new Ref([`users`, `name`]),
+          id: new PropRef([`users`, `id`]),
+          name: new PropRef([`users`, `name`]),
         },
         where: [
           new Func(`and`, [
-            new Func(`gt`, [new Ref([`users`, `age`]), new Value(20)]),
-            new Func(`eq`, [new Ref([`users`, `active`]), new Value(true)]),
+            new Func(`gt`, [new PropRef([`users`, `age`]), new Value(20)]),
+            new Func(`eq`, [new PropRef([`users`, `active`]), new Value(true)]),
           ]),
         ],
       }