fix(database): support pagination with joins and relations (#1801)

Author: innocenzi

packages/database/src/Builder/QueryBuilders/CountQueryBuilder.php

@@ -9,11 +9,13 @@
 use Tempest\Database\OnDatabase;
 use Tempest\Database\Query;
 use Tempest\Database\QueryStatements\CountStatement;
+use Tempest\Database\QueryStatements\JoinStatement;
 use Tempest\Support\Arr\ImmutableArray;
 use Tempest\Support\Conditions\HasConditions;
 use Tempest\Support\Str\ImmutableString;
 
 use function Tempest\Database\inspect;
+use function Tempest\Support\arr;
 
 /**
  * @template TModel of object
@@ -31,6 +33,9 @@ final class CountQueryBuilder implements BuildsQuery, SupportsWhereStatements
 
     public array $bindings = [];
 
+    /** @var array<JoinStatement|string> */
+    public array $joins = [];
+
     public ImmutableArray $wheres {
         get => $this->count->where;
     }
@@ -65,6 +70,16 @@ public static function fromQueryBuilder(BuildsQuery&SupportsWhereStatements $sou
             $builder->wheres[] = $where;
         }
 
+        if ($source instanceof SupportsJoins) {
+            $builder->joins = $source->joins;
+        }
+
+        if ($source instanceof SupportsRelations) {
+            foreach ($source->getResolvedRelations() as $relation) {
+                $builder->joins[] = $relation->getJoinStatement();
+            }
+        }
+
         return $builder;
     }
 
@@ -122,6 +137,11 @@ public function toRawSql(): ImmutableString
 
     public function build(mixed ...$bindings): Query
     {
+        if ($this->joins !== []) {
+            $this->count->joins = arr($this->joins)
+                ->map(fn (JoinStatement|string $join) => $join instanceof JoinStatement ? $join : new JoinStatement($join));
+        }
+
         return new Query($this->count, [...$this->bindings, ...$bindings])->onDatabase($this->onDatabase);
     }
 }

packages/database/src/Builder/QueryBuilders/SelectQueryBuilder.php

@@ -20,6 +20,7 @@
 use Tempest\Database\QueryStatements\OrderByStatement;
 use Tempest\Database\QueryStatements\RawStatement;
 use Tempest\Database\QueryStatements\SelectStatement;
+use Tempest\Database\Relation;
 use Tempest\Support\Arr\ImmutableArray;
 use Tempest\Support\Conditions\HasConditions;
 use Tempest\Support\Paginator\PaginatedData;
@@ -33,19 +34,21 @@
  * @template TModel of object
  * @implements \Tempest\Database\Builder\QueryBuilders\BuildsQuery<TModel>
  * @implements \Tempest\Database\Builder\QueryBuilders\SupportsWhereStatements<TModel>
+ * @implements \Tempest\Database\Builder\QueryBuilders\SupportsJoins<TModel>
+ * @implements \Tempest\Database\Builder\QueryBuilders\SupportsRelations<TModel>
  * @use \Tempest\Database\Builder\QueryBuilders\HasWhereQueryBuilderMethods<TModel>
  */
-final class SelectQueryBuilder implements BuildsQuery, SupportsWhereStatements
+final class SelectQueryBuilder implements BuildsQuery, SupportsWhereStatements, SupportsJoins, SupportsRelations
 {
     use HasConditions, OnDatabase, HasWhereQueryBuilderMethods, TransformsQueryBuilder;
 
     public ModelInspector $model;
 
     private SelectStatement $select;
 
-    private array $joins = [];
+    public array $joins = [];
 
-    private array $relations = [];
+    public array $relations = [];
 
     public array $bindings = [];
 
@@ -133,7 +136,7 @@ public function get(PrimaryKey $id): mixed
      *
      * @template TSourceModel of object
      * @param (BuildsQuery<TSourceModel>&SupportsWhereStatements<TSourceModel>) $source
-     * @return UpdateQueryBuilder<TSourceModel>
+     * @return SelectQueryBuilder<TSourceModel>
      */
     public static function fromQueryBuilder(BuildsQuery&SupportsWhereStatements $source, mixed ...$fields): SelectQueryBuilder
     {
@@ -144,6 +147,16 @@ public static function fromQueryBuilder(BuildsQuery&SupportsWhereStatements $sou
             $builder->wheres[] = $where;
         }
 
+        if ($source instanceof SupportsJoins) {
+            $builder->joins = $source->joins;
+        }
+
+        if ($source instanceof SupportsRelations) {
+            foreach ($source->getResolvedRelations() as $relation) {
+                $builder->joins[] = $relation->getJoinStatement();
+            }
+        }
+
         return $builder;
     }
 
@@ -336,7 +349,7 @@ public function build(mixed ...$bindings): Query
             $select = $select->withJoin(new JoinStatement($join));
         }
 
-        foreach ($this->getIncludedRelations() as $relation) {
+        foreach ($this->getResolvedRelations() as $relation) {
             $select = $select
                 ->withFields($relation->getSelectFields())
                 ->withJoin($relation->getJoinStatement());
@@ -350,8 +363,12 @@ private function clone(): self
         return clone $this;
     }
 
-    /** @return \Tempest\Database\Relation[] */
-    private function getIncludedRelations(): array
+    /**
+     * Gets all resolved relations with their join statements.
+     *
+     * @return Relation[]
+     */
+    public function getResolvedRelations(): array
     {
         $definition = inspect($this->model->getName());
 

packages/database/src/Builder/QueryBuilders/SupportsJoins.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Tempest\Database\Builder\QueryBuilders;
+
+use Tempest\Database\QueryStatements\JoinStatement;
+
+/**
+ * @template TModel of object
+ */
+interface SupportsJoins
+{
+    /**
+     * The current JOIN statements for this query builder.
+     *
+     * @return array<JoinStatement|string>
+     */
+    public array $joins {
+        get;
+    }
+}

packages/database/src/Builder/QueryBuilders/SupportsRelations.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Tempest\Database\Builder\QueryBuilders;
+
+use Tempest\Database\Relation;
+
+/**
+ * @template TModel of object
+ */
+interface SupportsRelations
+{
+    /**
+     * The current relation names requested for eager loading.
+     *
+     * @return array<string>
+     */
+    public array $relations {
+        get;
+    }
+
+    /**
+     * Gets all resolved relations with their join statements.
+     *
+     * @return Relation[]
+     */
+    public function getResolvedRelations(): array;
+}

packages/database/src/QueryStatements/CountStatement.php

@@ -13,12 +13,14 @@ final class CountStatement implements QueryStatement, HasWhereStatements
 {
     /**
      * @param ImmutableArray<WhereStatement> $where
+     * @param ImmutableArray<JoinStatement> $joins
      */
     public function __construct(
         public readonly TableDefinition $table,
         public ?string $column = null,
         public ImmutableArray $where = new ImmutableArray(),
         public bool $distinct = false,
+        public ImmutableArray $joins = new ImmutableArray(),
     ) {}
 
     public function compile(DatabaseDialect $dialect): string
@@ -34,6 +36,12 @@ public function compile(DatabaseDialect $dialect): string
             sprintf('FROM `%s`', $this->table->name),
         ]);
 
+        if ($this->joins->isNotEmpty()) {
+            foreach ($this->joins as $join) {
+                $query[] = $join->compile($dialect);
+            }
+        }
+
         if ($this->where->isNotEmpty()) {
             $query[] = 'WHERE ' . $this->where
                 ->map(fn (QueryStatement $where) => $where->compile($dialect))

tests/Integration/Database/Builder/SelectQueryBuilderTest.php

@@ -595,9 +595,39 @@ public function test_select_query_builder_from_another_query_builder(): void
         $this->assertSame('LOTR 1.3', $results[2]->title);
     }
 
+    public function test_paginate_preserves_relations(): void
+    {
+        $this->seed();
+
+        $page1 = query(Chapter::class)
+            ->select()
+            ->with('book')
+            ->whereRaw('books.title = ?', 'LOTR 1')
+            ->paginate(itemsPerPage: 5, currentPage: 1);
+
+        $this->assertSame(3, $page1->totalItems);
+        $this->assertCount(3, $page1->data);
+        $this->assertSame('LOTR 1', $page1->data[0]->book->title);
+    }
+
+    public function test_paginate_with_nested_relations(): void
+    {
+        $this->seed();
+
+        $page1 = Chapter::select()
+            ->with('book.author')
+            ->paginate(itemsPerPage: 5, currentPage: 1);
+
+        $this->assertSame(13, $page1->totalItems);
+        $this->assertCount(5, $page1->data);
+
+        $this->assertInstanceOf(Author::class, $page1->data[0]->book->author);
+        $this->assertSame('Tolkien', $page1->data[0]->book->author->name);
+    }
+
     private function seed(): void
     {
-        $this->migrate(
+        $this->database->migrate(
             CreateMigrationsTable::class,
             CreatePublishersTable::class,
             CreateAuthorTable::class,