feat(database): add transform to query builders

Author: innocenzi

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

@@ -22,7 +22,7 @@
  */
 final class CountQueryBuilder implements BuildsQuery
 {
-    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods;
+    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods, TransformsQueryBuilder;
 
     private CountStatement $count;
 

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

@@ -19,7 +19,7 @@
  */
 final class DeleteQueryBuilder implements BuildsQuery
 {
-    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods;
+    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods, TransformsQueryBuilder;
 
     private DeleteStatement $delete;
 

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

@@ -29,7 +29,7 @@
  */
 final class InsertQueryBuilder implements BuildsQuery
 {
-    use HasConditions, OnDatabase;
+    use HasConditions, OnDatabase, TransformsQueryBuilder;
 
     private InsertStatement $insert;
 

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

@@ -36,7 +36,7 @@
  */
 final class SelectQueryBuilder implements BuildsQuery
 {
-    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods;
+    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods, TransformsQueryBuilder;
 
     private ModelInspector $model;
 

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

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

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

@@ -31,7 +31,7 @@
  */
 final class UpdateQueryBuilder implements BuildsQuery
 {
-    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods;
+    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods, TransformsQueryBuilder;
 
     private UpdateStatement $update;
 

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/TransformsQueryBuilderTest.php

@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Tempest\Integration\Database\Builder;
+
+use Tests\Tempest\Fixtures\Modules\Books\Models\Author;
+use Tests\Tempest\Integration\FrameworkIntegrationTestCase;
+
+use function Tempest\Database\query;
+
+/**
+ * @internal
+ */
+final class TransformsQueryBuilderTest extends FrameworkIntegrationTestCase
+{
+    public function test_select_query_builder_transform(): void
+    {
+        $query = query(Author::class)
+            ->select()
+            ->transform(fn ($builder) => $builder->where('name', 'Frieren'));
+
+        $bindings = $query->build()->bindings;
+
+        $this->assertSame(['Frieren'], $bindings);
+    }
+
+    public function test_count_query_builder_transform(): void
+    {
+        $query = query(Author::class)
+            ->count()
+            ->transform(fn ($builder) => $builder->where('name', 'Himmel'));
+
+        $bindings = $query->build()->bindings;
+
+        $this->assertSame(['Himmel'], $bindings);
+    }
+
+    public function test_update_query_builder_transform(): void
+    {
+        $query = query(Author::class)
+            ->update(name: 'Heiter')
+            ->transform(fn ($builder) => $builder->where('id', 1));
+
+        $bindings = $query->build()->bindings;
+
+        $this->assertSame(['Heiter', 1], $bindings);
+    }
+
+    public function test_delete_query_builder_transform(): void
+    {
+        $query = query(Author::class)
+            ->delete()
+            ->transform(fn ($builder) => $builder->where('name', 'Eisen'));
+
+        $bindings = $query->build()->bindings;
+
+        $this->assertSame(['Eisen'], $bindings);
+    }
+
+    public function test_insert_query_builder_transform(): void
+    {
+        $query = query(Author::class)
+            ->insert(['name' => 'Stark'])
+            ->transform(fn ($builder) => $builder->then(fn () => null));
+
+        $bindings = $query->build()->bindings;
+
+        $this->assertSame(['Stark'], $bindings);
+    }
+
+    public function test_transform_returns_new_instance(): void
+    {
+        $original = query(Author::class)->select();
+
+        $transformed = $original->transform(fn ($builder) => $builder);
+
+        $this->assertNotSame($original, $transformed);
+    }
+}