add leftJoin, rightJoin, innerJoin and fullJoin aliases of the main join method (#269)

Author: samwillis

.changeset/loud-cycles-spend.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/db": patch
+---
+
+Add `leftJoin`, `rightJoin`, `innerJoin` and `fullJoin` aliases of the main `join` method on the query builder.

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

@@ -184,6 +184,110 @@ export class BaseQueryBuilder<TContext extends Context = Context> {
     }) as any
   }
 
+  /**
+   * Perform a LEFT JOIN with another table or subquery
+   *
+   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
+   * @param onCallback - A function that receives table references and returns the join condition
+   * @returns A QueryBuilder with the left joined table available
+   *
+   * @example
+   * ```ts
+   * // Left join users with posts
+   * query
+   *   .from({ users: usersCollection })
+   *   .leftJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
+   * ```
+   */
+  leftJoin<TSource extends Source>(
+    source: TSource,
+    onCallback: JoinOnCallback<
+      MergeContext<TContext, SchemaFromSource<TSource>>
+    >
+  ): QueryBuilder<
+    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, `left`>
+  > {
+    return this.join(source, onCallback, `left`)
+  }
+
+  /**
+   * Perform a RIGHT JOIN with another table or subquery
+   *
+   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
+   * @param onCallback - A function that receives table references and returns the join condition
+   * @returns A QueryBuilder with the right joined table available
+   *
+   * @example
+   * ```ts
+   * // Right join users with posts
+   * query
+   *   .from({ users: usersCollection })
+   *   .rightJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
+   * ```
+   */
+  rightJoin<TSource extends Source>(
+    source: TSource,
+    onCallback: JoinOnCallback<
+      MergeContext<TContext, SchemaFromSource<TSource>>
+    >
+  ): QueryBuilder<
+    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, `right`>
+  > {
+    return this.join(source, onCallback, `right`)
+  }
+
+  /**
+   * Perform an INNER JOIN with another table or subquery
+   *
+   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
+   * @param onCallback - A function that receives table references and returns the join condition
+   * @returns A QueryBuilder with the inner joined table available
+   *
+   * @example
+   * ```ts
+   * // Inner join users with posts
+   * query
+   *   .from({ users: usersCollection })
+   *   .innerJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
+   * ```
+   */
+  innerJoin<TSource extends Source>(
+    source: TSource,
+    onCallback: JoinOnCallback<
+      MergeContext<TContext, SchemaFromSource<TSource>>
+    >
+  ): QueryBuilder<
+    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, `inner`>
+  > {
+    return this.join(source, onCallback, `inner`)
+  }
+
+  /**
+   * Perform a FULL JOIN with another table or subquery
+   *
+   * @param source - An object with a single key-value pair where the key is the table alias and the value is a Collection or subquery
+   * @param onCallback - A function that receives table references and returns the join condition
+   * @returns A QueryBuilder with the full joined table available
+   *
+   * @example
+   * ```ts
+   * // Full join users with posts
+   * query
+   *   .from({ users: usersCollection })
+   *   .fullJoin({ posts: postsCollection }, ({users, posts}) => eq(users.id, posts.userId))
+   * ```
+   */
+  fullJoin<TSource extends Source>(
+    source: TSource,
+    onCallback: JoinOnCallback<
+      MergeContext<TContext, SchemaFromSource<TSource>>
+    >
+  ): QueryBuilder<
+    MergeContextWithJoinType<TContext, SchemaFromSource<TSource>, `full`>
+  > {
+    return this.join(source, onCallback, `full`)
+  }
+
   /**
    * Filter rows based on a condition
    *

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

@@ -232,4 +232,173 @@ describe(`QueryBuilder.join`, () => {
     expect(builtQuery.select).toHaveProperty(`employee`)
     expect(builtQuery.select).toHaveProperty(`department`)
   })
+
+  describe(`join alias methods`, () => {
+    it(`leftJoin produces same result as join with 'left' type`, () => {
+      const builder = new Query()
+      const explicitQuery = builder
+        .from({ employees: employeesCollection })
+        .join(
+          { departments: departmentsCollection },
+          ({ employees, departments }) =>
+            eq(employees.department_id, departments.id),
+          `left`
+        )
+
+      const aliasQuery = builder
+        .from({ employees: employeesCollection })
+        .leftJoin(
+          { departments: departmentsCollection },
+          ({ employees, departments }) =>
+            eq(employees.department_id, departments.id)
+        )
+
+      const explicitQueryIR = getQueryIR(explicitQuery)
+      const aliasQueryIR = getQueryIR(aliasQuery)
+
+      expect(aliasQueryIR.join).toEqual(explicitQueryIR.join)
+      expect(aliasQueryIR.join![0]!.type).toBe(`left`)
+    })
+
+    it(`rightJoin produces same result as join with 'right' type`, () => {
+      const builder = new Query()
+      const explicitQuery = builder
+        .from({ employees: employeesCollection })
+        .join(
+          { departments: departmentsCollection },
+          ({ employees, departments }) =>
+            eq(employees.department_id, departments.id),
+          `right`
+        )
+
+      const aliasQuery = builder
+        .from({ employees: employeesCollection })
+        .rightJoin(
+          { departments: departmentsCollection },
+          ({ employees, departments }) =>
+            eq(employees.department_id, departments.id)
+        )
+
+      const explicitQueryIR = getQueryIR(explicitQuery)
+      const aliasQueryIR = getQueryIR(aliasQuery)
+
+      expect(aliasQueryIR.join).toEqual(explicitQueryIR.join)
+      expect(aliasQueryIR.join![0]!.type).toBe(`right`)
+    })
+
+    it(`innerJoin produces same result as join with 'inner' type`, () => {
+      const builder = new Query()
+      const explicitQuery = builder
+        .from({ employees: employeesCollection })
+        .join(
+          { departments: departmentsCollection },
+          ({ employees, departments }) =>
+            eq(employees.department_id, departments.id),
+          `inner`
+        )
+
+      const aliasQuery = builder
+        .from({ employees: employeesCollection })
+        .innerJoin(
+          { departments: departmentsCollection },
+          ({ employees, departments }) =>
+            eq(employees.department_id, departments.id)
+        )
+
+      const explicitQueryIR = getQueryIR(explicitQuery)
+      const aliasQueryIR = getQueryIR(aliasQuery)
+
+      expect(aliasQueryIR.join).toEqual(explicitQueryIR.join)
+      expect(aliasQueryIR.join![0]!.type).toBe(`inner`)
+    })
+
+    it(`fullJoin produces same result as join with 'full' type`, () => {
+      const builder = new Query()
+      const explicitQuery = builder
+        .from({ employees: employeesCollection })
+        .join(
+          { departments: departmentsCollection },
+          ({ employees, departments }) =>
+            eq(employees.department_id, departments.id),
+          `full`
+        )
+
+      const aliasQuery = builder
+        .from({ employees: employeesCollection })
+        .fullJoin(
+          { departments: departmentsCollection },
+          ({ employees, departments }) =>
+            eq(employees.department_id, departments.id)
+        )
+
+      const explicitQueryIR = getQueryIR(explicitQuery)
+      const aliasQueryIR = getQueryIR(aliasQuery)
+
+      expect(aliasQueryIR.join).toEqual(explicitQueryIR.join)
+      expect(aliasQueryIR.join![0]!.type).toBe(`full`)
+    })
+
+    it(`supports chaining join aliases with different types`, () => {
+      const projectsCollection = new CollectionImpl<{
+        id: number
+        name: string
+        department_id: number
+      }>({
+        id: `projects`,
+        getKey: (item) => item.id,
+        sync: { sync: () => {} },
+      })
+
+      const builder = new Query()
+      const query = builder
+        .from({ employees: employeesCollection })
+        .leftJoin(
+          { departments: departmentsCollection },
+          ({ employees, departments }) =>
+            eq(employees.department_id, departments.id)
+        )
+        .innerJoin(
+          { projects: projectsCollection },
+          ({ departments, projects }) =>
+            eq(departments.id, projects.department_id)
+        )
+
+      const builtQuery = getQueryIR(query)
+      expect(builtQuery.join).toBeDefined()
+      expect(builtQuery.join).toHaveLength(2)
+
+      const firstJoin = builtQuery.join![0]!
+      const secondJoin = builtQuery.join![1]!
+
+      expect(firstJoin.type).toBe(`left`)
+      expect(firstJoin.from.alias).toBe(`departments`)
+      expect(secondJoin.type).toBe(`inner`)
+      expect(secondJoin.from.alias).toBe(`projects`)
+    })
+
+    it(`join aliases work in select and where clauses`, () => {
+      const builder = new Query()
+      const query = builder
+        .from({ employees: employeesCollection })
+        .innerJoin(
+          { departments: departmentsCollection },
+          ({ employees, departments }) =>
+            eq(employees.department_id, departments.id)
+        )
+        .where(({ departments }) => gt(departments.budget, 1000000))
+        .select(({ employees, departments }) => ({
+          id: employees.id,
+          name: employees.name,
+          department_name: departments.name,
+          department_budget: departments.budget,
+        }))
+
+      const builtQuery = getQueryIR(query)
+      expect(builtQuery.join).toBeDefined()
+      expect(builtQuery.join![0]!.type).toBe(`inner`)
+      expect(builtQuery.where).toBeDefined()
+      expect(builtQuery.select).toBeDefined()
+      expect(builtQuery.select).toHaveProperty(`department_name`)
+    })
+  })
 })