feat(database): add tap to query builders

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

@@ -21,7 +21,7 @@
  */
 final class CountQueryBuilder implements BuildsQuery
 {
-    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods;
+    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods, TapsQueryBuilder;
 
     private CountStatement $count;
 
@@ -86,4 +86,9 @@ private function getModel(): ModelInspector
     {
         return $this->model;
     }
+
+    private function clone(): self
+    {
+        return clone $this;
+    }
 }

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

@@ -18,7 +18,7 @@
  */
 final class DeleteQueryBuilder implements BuildsQuery
 {
-    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods;
+    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods, TapsQueryBuilder;
 
     private DeleteStatement $delete;
 
@@ -81,4 +81,9 @@ private function getModel(): ModelInspector
     {
         return $this->model;
     }
+
+    private function clone(): self
+    {
+        return clone $this;
+    }
 }

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

@@ -19,7 +19,7 @@
 
 final class InsertQueryBuilder implements BuildsQuery
 {
-    use HasConditions, OnDatabase;
+    use HasConditions, OnDatabase, TapsQueryBuilder;
 
     private InsertStatement $insert;
 

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

@@ -33,7 +33,7 @@
  */
 final class SelectQueryBuilder implements BuildsQuery
 {
-    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods;
+    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods, TapsQueryBuilder;
 
     private ModelInspector $model;
 
@@ -232,11 +232,6 @@ public function build(mixed ...$bindings): Query
         return new Query($this->select, [...$this->bindings, ...$bindings])->onDatabase($this->onDatabase);
     }
 
-    private function clone(): self
-    {
-        return clone $this;
-    }
-
     /** @return \Tempest\Database\Relation[] */
     private function getIncludedRelations(): array
     {
@@ -270,4 +265,9 @@ private function getModel(): ModelInspector
     {
         return $this->model;
     }
+
+    private function clone(): self
+    {
+        return clone $this;
+    }
 }

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

@@ -0,0 +1,21 @@
+<?php
+
+namespace Tempest\Database\Builder\QueryBuilders;
+
+use function Tempest\Support\tap;
+
+/**
+ * @phpstan-require-implements BuildsQuery
+ */
+trait TapsQueryBuilder
+{
+    /**
+     * Returns a new instance of the query builder with the given callback applied.
+     *
+     * @param callable($this) $callback
+     */
+    public function tap(callable $callback): static
+    {
+        return tap($this->clone(), $callback);
+    }
+}

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

@@ -24,7 +24,7 @@
  */
 final class UpdateQueryBuilder implements BuildsQuery
 {
-    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods;
+    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods, TapsQueryBuilder;
 
     private UpdateStatement $update;
 
@@ -153,4 +153,9 @@ private function getModel(): ModelInspector
     {
         return $this->model;
     }
+
+    private function clone(): self
+    {
+        return clone $this;
+    }
 }

packages/support/src/functions.php

@@ -39,11 +39,11 @@ function path(Stringable|string ...$parts): Path
      * @template T
      *
      * @param T $value
-     * @param (Closure(T): void) $callback
+     * @param (callable(T): void) $callback
      *
      * @return T
      */
-    function tap(mixed $value, Closure $callback): mixed
+    function tap(mixed $value, callable $callback): mixed
     {
         $callback($value);
 

tests/Integration/Database/Builder/CountQueryBuilderTest.php

@@ -212,4 +212,21 @@ public function test_multiple_where_field(): void
 
         $this->assertSameWithoutBackticks($expected, $sql);
     }
+
+    public function test_tap(): void
+    {
+        $this->migrate(CreateMigrationsTable::class, CreatePublishersTable::class, CreateAuthorTable::class);
+
+        query('authors')->insert(
+            ['id' => 1, 'name' => 'Brent'],
+            ['id' => 2, 'name' => 'Other'],
+        )->execute();
+
+        $count = query('authors')
+            ->count()
+            ->tap(fn (CountQueryBuilder $query) => $query->where('id = ?', 1))
+            ->execute();
+
+        $this->assertSame(1, $count);
+    }
 }

tests/Integration/Database/Builder/DeleteQueryBuilderTest.php

@@ -154,4 +154,19 @@ public function test_multiple_where_field(): void
 
         $this->assertSameWithoutBackticks($expected, $sql);
     }
+
+    public function test_tap(): void
+    {
+        $query = query('foo')
+            ->delete()
+            ->tap(fn (DeleteQueryBuilder $query) => $query->where('bar = ?', 'boo'))
+            ->build();
+
+        $this->assertSameWithoutBackticks(<<<SQL
+        DELETE FROM `foo`
+        WHERE bar = ?
+        SQL, $query->toSql());
+
+        $this->assertSameWithoutBackticks('boo', $query->bindings[0]);
+    }
 }

tests/Integration/Database/Builder/SelectQueryBuilderTest.php

@@ -424,6 +424,47 @@ public function test_group_by(): void
         $this->assertSameWithoutBackticks($expected, $sql);
     }
 
+    public function test_tap(): void
+    {
+        $sql = query('authors')
+            ->select()
+            ->tap(fn (SelectQueryBuilder $query) => $query->where('name = ?', 'Brent'))
+            ->toSql();
+
+        $expected = <<<SQL
+        SELECT *
+        FROM authors
+        WHERE name = ?
+        SQL;
+
+        $this->assertSameWithoutBackticks($expected, $sql);
+    }
+
+    public function test_tap_invokable(): void
+    {
+        $sql = query('authors')
+            ->select()
+            ->tap(new readonly class('Brent') {
+                public function __construct(
+                    private string $author,
+                ) {}
+
+                public function __invoke(SelectQueryBuilder $query): void
+                {
+                    $query->where('name = ?', $this->author);
+                }
+            })
+            ->toSql();
+
+        $expected = <<<SQL
+        SELECT *
+        FROM authors
+        WHERE name = ?
+        SQL;
+
+        $this->assertSameWithoutBackticks($expected, $sql);
+    }
+
     public function test_having(): void
     {
         $sql = query('authors')

tests/Integration/Database/Builder/UpdateQueryBuilderTest.php

@@ -331,4 +331,20 @@ public function test_multiple_where_field(): void
 
         $this->assertSameWithoutBackticks($expected, $sql);
     }
+
+    public function test_tap(): void
+    {
+        $query = query(Book::class)
+            ->update(title: 'Chapter 02')
+            ->tap(fn (UpdateQueryBuilder $query) => $query->where('id = ?', 10))
+            ->build();
+
+        $this->assertSameWithoutBackticks(<<<SQL
+        UPDATE `books`
+        SET `title` = ?
+        WHERE `id` = ?
+        SQL, $query->toSql());
+
+        $this->assertSame(['Chapter 02', 10], $query->bindings);
+    }
 }