rename stuff and tidy

Author: samwillis

packages/db/src/errors.ts

@@ -409,32 +409,32 @@ export class UnsupportedJoinTypeError extends JoinError {
   }
 }
 
-export class InvalidJoinConditionSameTableError extends JoinError {
-  constructor(tableAlias: string) {
+export class InvalidJoinConditionSameSourceError extends JoinError {
+  constructor(sourceAlias: string) {
     super(
-      `Invalid join condition: both expressions refer to the same table "${tableAlias}"`
+      `Invalid join condition: both expressions refer to the same source "${sourceAlias}"`
     )
   }
 }
 
-export class InvalidJoinConditionTableMismatchError extends JoinError {
+export class InvalidJoinConditionSourceMismatchError extends JoinError {
   constructor() {
-    super(`Invalid join condition: expressions must reference table aliases`)
+    super(`Invalid join condition: expressions must reference source aliases`)
   }
 }
 
-export class InvalidJoinConditionLeftTableError extends JoinError {
-  constructor(tableAlias: string) {
+export class InvalidJoinConditionLeftSourceError extends JoinError {
+  constructor(sourceAlias: string) {
     super(
-      `Invalid join condition: left expression refers to an unavailable table "${tableAlias}"`
+      `Invalid join condition: left expression refers to an unavailable source "${sourceAlias}"`
     )
   }
 }
 
-export class InvalidJoinConditionRightTableError extends JoinError {
-  constructor(tableAlias: string) {
+export class InvalidJoinConditionRightSourceError extends JoinError {
+  constructor(sourceAlias: string) {
     super(
-      `Invalid join condition: right expression does not refer to the joined table "${tableAlias}"`
+      `Invalid join condition: right expression does not refer to the joined source "${sourceAlias}"`
     )
   }
 }
@@ -581,3 +581,24 @@ export class WhereClauseConversionError extends QueryOptimizerError {
     )
   }
 }
+
+export class SubscriptionNotFoundError extends QueryCompilationError {
+  constructor(
+    resolvedAlias: string,
+    originalAlias: string,
+    collectionId: string,
+    availableAliases: Array<string>
+  ) {
+    super(
+      `Internal error: subscription for alias '${resolvedAlias}' (remapped from '${originalAlias}', collection '${collectionId}') is missing in join pipeline. Available aliases: ${availableAliases.join(`, `)}. This indicates a bug in alias tracking.`
+    )
+  }
+}
+
+export class AggregateNotSupportedError extends QueryCompilationError {
+  constructor() {
+    super(
+      `Aggregate expressions are not supported in this context. Use GROUP BY clause for aggregates.`
+    )
+  }
+}

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

@@ -8,11 +8,12 @@ import {
 import {
   CollectionInputNotFoundError,
   InvalidJoinCondition,
-  InvalidJoinConditionLeftTableError,
-  InvalidJoinConditionRightTableError,
-  InvalidJoinConditionSameTableError,
-  InvalidJoinConditionTableMismatchError,
+  InvalidJoinConditionLeftSourceError,
+  InvalidJoinConditionRightSourceError,
+  InvalidJoinConditionSameSourceError,
+  InvalidJoinConditionSourceMismatchError,
   JoinCollectionNotFoundError,
+  SubscriptionNotFoundError,
   UnsupportedJoinSourceTypeError,
   UnsupportedJoinTypeError,
 } from "../../errors.js"
@@ -179,7 +180,7 @@ function processJoin(
   // Prepare the main pipeline for joining
   let mainPipeline = pipeline.pipe(
     map(([currentKey, namespacedRow]) => {
-      // Extract the join key from the main table expression
+      // Extract the join key from the main source expression
       const mainKey = compiledMainExpr(namespacedRow)
 
       // Return [joinKey, [originalKey, namespacedRow]]
@@ -196,7 +197,7 @@ function processJoin(
       // Wrap the row in a namespaced structure
       const namespacedRow: NamespacedRow = { [joinedSource]: row }
 
-      // Extract the join key from the joined table expression
+      // Extract the join key from the joined source expression
       const joinedKey = compiledJoinedExpr(namespacedRow)
 
       // Return [joinKey, [originalKey, namespacedRow]]
@@ -269,8 +270,8 @@ function processJoin(
       > = activePipeline.pipe(
         tap((data) => {
           // For outer joins (LEFT/RIGHT), the driving side determines which alias's
-          // subscription we consult for lazy loading. The main table drives LEFT joins,
-          // joined table drives RIGHT joins.
+          // subscription we consult for lazy loading. The main source drives LEFT joins,
+          // joined source drives RIGHT joins.
           const lazyAliasCandidate =
             activeSource === `main` ? joinedSource : mainSource
 
@@ -284,8 +285,11 @@ function processJoin(
           const lazySourceSubscription = subscriptions[resolvedAlias]
 
           if (!lazySourceSubscription) {
-            throw new Error(
-              `Internal error: subscription for alias '${resolvedAlias}' (remapped from '${lazyAliasCandidate}', collection '${lazySource.id}') is missing in join pipeline. Available aliases: ${Object.keys(subscriptions).join(`, `)}. This indicates a bug in alias tracking.`
+            throw new SubscriptionNotFoundError(
+              resolvedAlias,
+              lazyAliasCandidate,
+              lazySource.id,
+              Object.keys(subscriptions)
             )
           }
 
@@ -324,90 +328,89 @@ function processJoin(
 }
 
 /**
- * Analyzes join expressions to determine which refers to which table
- * and returns them in the correct order (available table expression first, joined table expression second)
+ * Analyzes join expressions to determine which refers to which source
+ * and returns them in the correct order (available source expression first, joined source expression second)
  */
 function analyzeJoinExpressions(
   left: BasicExpression,
   right: BasicExpression,
-  allAvailableTableAliases: Array<string>,
+  allAvailableSourceAliases: Array<string>,
   joinedSource: string
 ): { mainExpr: BasicExpression; joinedExpr: BasicExpression } {
-  // Filter out the joined table alias from the available table aliases
-  const availableSources = allAvailableTableAliases.filter(
+  // Filter out the joined source alias from the available source aliases
+  const availableSources = allAvailableSourceAliases.filter(
     (alias) => alias !== joinedSource
   )
 
-  const leftTableAlias = getTableAliasFromExpression(left)
-  const rightTableAlias = getTableAliasFromExpression(right)
+  const leftSourceAlias = getSourceAliasFromExpression(left)
+  const rightSourceAlias = getSourceAliasFromExpression(right)
 
-  // If left expression refers to an available table and right refers to joined table, keep as is
+  // If left expression refers to an available source and right refers to joined source, keep as is
   if (
-    leftTableAlias &&
-    availableSources.includes(leftTableAlias) &&
-    rightTableAlias === joinedSource
+    leftSourceAlias &&
+    availableSources.includes(leftSourceAlias) &&
+    rightSourceAlias === joinedSource
   ) {
     return { mainExpr: left, joinedExpr: right }
   }
 
-  // If left expression refers to joined table and right refers to an available table, swap them
+  // If left expression refers to joined source and right refers to an available source, swap them
   if (
-    leftTableAlias === joinedSource &&
-    rightTableAlias &&
-    availableSources.includes(rightTableAlias)
+    leftSourceAlias === joinedSource &&
+    rightSourceAlias &&
+    availableSources.includes(rightSourceAlias)
   ) {
     return { mainExpr: right, joinedExpr: left }
   }
 
-  // If one expression doesn't refer to any table, this is an invalid join
-  if (!leftTableAlias || !rightTableAlias) {
-    // For backward compatibility, use the first available table alias in error message
-    throw new InvalidJoinConditionTableMismatchError()
+  // If one expression doesn't refer to any source, this is an invalid join
+  if (!leftSourceAlias || !rightSourceAlias) {
+    throw new InvalidJoinConditionSourceMismatchError()
   }
 
   // If both expressions refer to the same alias, this is an invalid join
-  if (leftTableAlias === rightTableAlias) {
-    throw new InvalidJoinConditionSameTableError(leftTableAlias)
+  if (leftSourceAlias === rightSourceAlias) {
+    throw new InvalidJoinConditionSameSourceError(leftSourceAlias)
   }
 
-  // Left side must refer to an available table
+  // Left side must refer to an available source
   // This cannot happen with the query builder as there is no way to build a ref
-  // to an unavailable table, but just in case, but could happen with the IR
-  if (!availableSources.includes(leftTableAlias)) {
-    throw new InvalidJoinConditionLeftTableError(leftTableAlias)
+  // to an unavailable source, but just in case, but could happen with the IR
+  if (!availableSources.includes(leftSourceAlias)) {
+    throw new InvalidJoinConditionLeftSourceError(leftSourceAlias)
   }
 
-  // Right side must refer to the joined table
-  if (rightTableAlias !== joinedSource) {
-    throw new InvalidJoinConditionRightTableError(joinedSource)
+  // Right side must refer to the joined source
+  if (rightSourceAlias !== joinedSource) {
+    throw new InvalidJoinConditionRightSourceError(joinedSource)
   }
 
   // This should not be reachable given the logic above, but just in case
   throw new InvalidJoinCondition()
 }
 
 /**
- * Extracts the table alias from a join expression
+ * Extracts the source alias from a join expression
  */
-function getTableAliasFromExpression(expr: BasicExpression): string | null {
+function getSourceAliasFromExpression(expr: BasicExpression): string | null {
   switch (expr.type) {
     case `ref`:
-      // PropRef path has the table alias as the first element
+      // PropRef path has the source alias as the first element
       return expr.path[0] || null
     case `func`: {
-      // For function expressions, we need to check if all arguments refer to the same table
-      const tableAliases = new Set<string>()
+      // For function expressions, we need to check if all arguments refer to the same source
+      const sourceAliases = new Set<string>()
       for (const arg of expr.args) {
-        const alias = getTableAliasFromExpression(arg)
+        const alias = getSourceAliasFromExpression(arg)
         if (alias) {
-          tableAliases.add(alias)
+          sourceAliases.add(alias)
         }
       }
-      // If all arguments refer to the same table, return that table alias
-      return tableAliases.size === 1 ? Array.from(tableAliases)[0]! : null
+      // If all arguments refer to the same source, return that source alias
+      return sourceAliases.size === 1 ? Array.from(sourceAliases)[0]! : null
     }
     default:
-      // Values (type='val') don't reference any table
+      // Values (type='val') don't reference any source
       return null
   }
 }
@@ -567,7 +570,7 @@ function processJoinResults(joinType: string) {
 /**
  * Returns the active and lazy collections for a join clause.
  * The active collection is the one that we need to fully iterate over
- * and it can be the main table (i.e. left collection) or the joined table (i.e. right collection).
+ * and it can be the main source (i.e. left collection) or the joined source (i.e. right collection).
  * The lazy collection is the one that we should join-in lazily based on matches in the active collection.
  * @param joinClause - The join clause to analyze
  * @param leftCollection - The left collection

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

@@ -1,5 +1,6 @@
 import { map } from "@tanstack/db-ivm"
 import { PropRef, Value as ValClass, isExpressionLike } from "../ir.js"
+import { AggregateNotSupportedError } from "../../errors.js"
 import { compileExpression } from "./evaluators.js"
 import type { Aggregate, BasicExpression, Select } from "../ir.js"
 import type {
@@ -157,9 +158,7 @@ export function processArgument(
   namespacedRow: NamespacedRow
 ): any {
   if (isAggregateExpression(arg)) {
-    throw new Error(
-      `Aggregate expressions are not supported in this context. Use GROUP BY clause for aggregates.`
-    )
+    throw new AggregateNotSupportedError()
   }
 
   // Pre-compile the expression and evaluate immediately

packages/db/tests/query/join.test.ts

@@ -1327,7 +1327,7 @@ function createJoinTests(autoIndex: `off` | `eager`): void {
       })
     })
 
-    test(`should throw error when both expressions refer to the same table`, () => {
+    test(`should throw error when both expressions refer to the same source`, () => {
       const usersCollection = createCollection(
         mockSyncCollectionOptions<User>({
           id: `test-users-same-table`,
@@ -1349,11 +1349,11 @@ function createJoinTests(autoIndex: `off` | `eager`): void {
             ),
         })
       }).toThrow(
-        `Invalid join condition: both expressions refer to the same table "user"`
+        `Invalid join condition: both expressions refer to the same source "user"`
       )
     })
 
-    test(`should throw error when expressions don't reference table aliases`, () => {
+    test(`should throw error when expressions don't reference source aliases`, () => {
       const usersCollection = createCollection(
         mockSyncCollectionOptions<User>({
           id: `test-users-no-refs`,
@@ -1375,11 +1375,11 @@ function createJoinTests(autoIndex: `off` | `eager`): void {
             ),
         })
       }).toThrow(
-        `Invalid join condition: expressions must reference table aliases`
+        `Invalid join condition: expressions must reference source aliases`
       )
     })
 
-    test(`should throw error when right side doesn't match joined table`, () => {
+    test(`should throw error when right side doesn't match joined source`, () => {
       const usersCollection = createCollection(
         mockSyncCollectionOptions<User>({
           id: `test-users-no-refs`,
@@ -1410,11 +1410,11 @@ function createJoinTests(autoIndex: `off` | `eager`): void {
               ),
         })
       }).toThrow(
-        `Invalid join condition: right expression does not refer to the joined table "dept2"`
+        `Invalid join condition: right expression does not refer to the joined source "dept2"`
       )
     })
 
-    test(`should throw error when function expression has mixed table references`, () => {
+    test(`should throw error when function expression has mixed source references`, () => {
       const usersCollection = createCollection(
         mockSyncCollectionOptions<User>({
           id: `test-users-mixed-refs`,
@@ -1436,7 +1436,7 @@ function createJoinTests(autoIndex: `off` | `eager`): void {
             ),
         })
       }).toThrow(
-        `Invalid join condition: both expressions refer to the same table "user"`
+        `Invalid join condition: both expressions refer to the same source "user"`
       )
     })
 
@@ -1595,7 +1595,9 @@ function createJoinTests(autoIndex: `off` | `eager`): void {
               ({ employee, manager }) => eq(employee.manager_id, manager.id),
               `left`
             )
-            .where(({ manager }) => or(isNull(manager.id), gt(manager.age, 35)))
+            .where(({ manager }) =>
+              or(isNull(manager?.id), gt(manager?.age, 35))
+            )
             .select(({ employee, manager }) => ({
               employeeId: employee.id,
               employeeName: employee.name,

packages/db/tests/query/order-by.test.ts

@@ -1491,12 +1491,12 @@ function createOrderByTests(autoIndex: `off` | `eager`): void {
                   ({ employees, departments }) =>
                     eq(employees.department_id, departments.id)
                 )
-                .orderBy(({ departments }) => departments.name, `asc`)
+                .orderBy(({ departments }) => departments?.name, `asc`)
                 .limit(5)
                 .select(({ employees, departments }) => ({
                   employeeId: employees.id,
                   employeeName: employees.name,
-                  departmentName: departments.name,
+                  departmentName: departments?.name,
                 }))
             )