enable a `new Query.from(...) syntax

Author: samwillis

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

@@ -9,7 +9,7 @@ import type {
   OrderBy,
   OrderByClause,
   OrderByDirection,
-  Query,
+  QueryIR,
 } from "../ir.js"
 import type {
   Context,
@@ -27,17 +27,10 @@ import type {
   WithResult,
 } from "./types.js"
 
-export function buildQuery<TContext extends Context>(
-  fn: (builder: InitialQueryBuilder) => QueryBuilder<TContext>
-): Query {
-  const result = fn(new BaseQueryBuilder())
-  return getQuery(result)
-}
-
 export class BaseQueryBuilder<TContext extends Context = Context> {
-  private readonly query: Partial<Query> = {}
+  private readonly query: Partial<QueryIR> = {}
 
-  constructor(query: Partial<Query> = {}) {
+  constructor(query: Partial<QueryIR> = {}) {
     this.query = { ...query }
   }
 
@@ -64,7 +57,7 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
       ref = new CollectionRef(sourceValue, alias)
     } else if (sourceValue instanceof BaseQueryBuilder) {
       const subQuery = sourceValue._getQuery()
-      if (!(subQuery as Partial<Query>).from) {
+      if (!(subQuery as Partial<QueryIR>).from) {
         throw new Error(
           `A sub query passed to a ${context} must have a from clause itself`
         )
@@ -605,28 +598,44 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
     }
   }
 
-  _getQuery(): Query {
+  _getQuery(): QueryIR {
     if (!this.query.from) {
       throw new Error(`Query must have a from clause`)
     }
-    return this.query as Query
+    return this.query as QueryIR
   }
 }
 
-export function getQuery(
+// Internal function to build a query from a callback
+// used by liveQueryCollectionOptions.query
+export function buildQuery<TContext extends Context>(
+  fn: (builder: InitialQueryBuilder) => QueryBuilder<TContext>
+): QueryIR {
+  const result = fn(new BaseQueryBuilder())
+  return getQueryIR(result)
+}
+
+// Internal function to get the QueryIR from a builder
+export function getQueryIR(
   builder: BaseQueryBuilder | QueryBuilder<any> | InitialQueryBuilder
-): Query {
+): QueryIR {
   return (builder as unknown as BaseQueryBuilder)._getQuery()
 }
 
 // Type-only exports for the query builder
 export type InitialQueryBuilder = Pick<BaseQueryBuilder<Context>, `from`>
 
+export type InitialQueryBuilderConstructor = new () => InitialQueryBuilder
+
 export type QueryBuilder<TContext extends Context> = Omit<
   BaseQueryBuilder<TContext>,
   `from` | `_getQuery`
 >
 
+// Main query builder class alias with the constructor type modified to hide all
+// but the from method on the initial instance
+export const Query: InitialQueryBuilderConstructor = BaseQueryBuilder
+
 // Helper type to extract context from a QueryBuilder
 export type ExtractContext<T> =
   T extends BaseQueryBuilder<infer TContext>

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

@@ -4,7 +4,7 @@ import { processJoins } from "./joins.js"
 import { processGroupBy } from "./group-by.js"
 import { processOrderBy } from "./order-by.js"
 import { processSelectToResults } from "./select.js"
-import type { CollectionRef, Query, QueryRef } from "../ir.js"
+import type { CollectionRef, QueryIR, QueryRef } from "../ir.js"
 import type {
   KeyedStream,
   NamespacedAndKeyedStream,
@@ -14,7 +14,7 @@ import type {
 /**
  * Cache for compiled subqueries to avoid duplicate compilation
  */
-type QueryCache = WeakMap<Query, ResultStream>
+type QueryCache = WeakMap<QueryIR, ResultStream>
 
 /**
  * Compiles a query2 IR into a D2 pipeline
@@ -24,7 +24,7 @@ type QueryCache = WeakMap<Query, ResultStream>
  * @returns A stream builder representing the compiled query
  */
 export function compileQuery(
-  query: Query,
+  query: QueryIR,
   inputs: Record<string, KeyedStream>,
   cache: QueryCache = new WeakMap()
 ): ResultStream {

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

@@ -7,7 +7,7 @@ import {
 import { compileExpression } from "./evaluators.js"
 import { compileQuery } from "./index.js"
 import type { IStreamBuilder, JoinType } from "@electric-sql/d2mini"
-import type { CollectionRef, JoinClause, Query, QueryRef } from "../ir.js"
+import type { CollectionRef, JoinClause, QueryIR, QueryRef } from "../ir.js"
 import type {
   KeyedStream,
   NamespacedAndKeyedStream,
@@ -18,7 +18,7 @@ import type {
 /**
  * Cache for compiled subqueries to avoid duplicate compilation
  */
-type QueryCache = WeakMap<Query, ResultStream>
+type QueryCache = WeakMap<QueryIR, ResultStream>
 
 /**
  * Processes all join clauses in a query

packages/db/src/query/index.ts

@@ -3,7 +3,7 @@
 // Query builder exports
 export {
   BaseQueryBuilder,
-  buildQuery,
+  Query,
   type InitialQueryBuilder,
   type QueryBuilder,
   type Context,
@@ -45,7 +45,7 @@ export { val, toExpression, isRefProxy } from "./builder/ref-proxy.js"
 
 // IR types (for advanced usage)
 export type {
-  Query,
+  QueryIR,
   BasicExpression as Expression,
   Aggregate,
   CollectionRef,

packages/db/src/query/ir.ts

@@ -5,7 +5,7 @@ This is the intermediate representation of the query.
 import type { CollectionImpl } from "../collection"
 import type { NamespacedRow } from "../types"
 
-export interface Query {
+export interface QueryIR {
   from: From
   select?: Select
   join?: Join
@@ -77,7 +77,7 @@ export class CollectionRef extends BaseExpression {
 export class QueryRef extends BaseExpression {
   public type = `queryRef` as const
   constructor(
-    public query: Query,
+    public query: QueryIR,
     public alias: string
   ) {
     super()

packages/db/tests/query/builder/buildQuery.test.ts

@@ -3,6 +3,12 @@ import { CollectionImpl } from "../../../src/collection.js"
 import { buildQuery } from "../../../src/query/builder/index.js"
 import { and, eq, gt, or } from "../../../src/query/builder/functions.js"
 
+/**
+ * This is a set of tests for the buildQuery function.
+ * This function is not used directly by the user, but is used by the
+ * liveQueryCollectionOptions.query callback or via a useLiveQuery call.
+ */
+
 // Test schema
 interface Employee {
   id: number