feat(database)!: improve orm experience

packages/auth/src/CanAuthenticate.php

@@ -4,11 +4,11 @@
 
 namespace Tempest\Auth;
 
-use Tempest\Database\Id;
+use Tempest\Database\PrimaryKey;
 
 interface CanAuthenticate
 {
-    public ?Id $id {
+    public ?PrimaryKey $id {
         get;
     }
 }

packages/auth/src/Install/Permission.php

@@ -6,12 +6,15 @@
 
 use BackedEnum;
 use Tempest\Database\IsDatabaseModel;
+use Tempest\Database\PrimaryKey;
 use UnitEnum;
 
 final class Permission
 {
     use IsDatabaseModel;
 
+    public PrimaryKey $id;
+
     public function __construct(
         public string $name,
     ) {}

packages/auth/src/Install/User.php

@@ -9,6 +9,7 @@
 use Tempest\Auth\CanAuthenticate;
 use Tempest\Auth\CanAuthorize;
 use Tempest\Database\IsDatabaseModel;
+use Tempest\Database\PrimaryKey;
 use UnitEnum;
 
 use function Tempest\Support\arr;
@@ -17,6 +18,8 @@ final class User implements CanAuthenticate, CanAuthorize
 {
     use IsDatabaseModel;
 
+    public PrimaryKey $id;
+
     public string $password;
 
     public function __construct(
@@ -78,7 +81,9 @@ private function resolvePermission(string|UnitEnum|Permission $permission): Perm
             $permission instanceof UnitEnum => $permission->name,
         };
 
-        $permission = Permission::select()->whereField('name', $name)->first();
+        $permission = Permission::select()
+            ->where('name', $name)
+            ->first();
 
         return $permission ?? new Permission($name)->save();
     }

packages/auth/src/Install/UserPermission.php

@@ -5,11 +5,14 @@
 namespace Tempest\Auth\Install;
 
 use Tempest\Database\IsDatabaseModel;
+use Tempest\Database\PrimaryKey;
 
 final class UserPermission
 {
     use IsDatabaseModel;
 
+    public PrimaryKey $id;
+
     public User $user;
 
     public Permission $permission;

packages/database/src/BelongsTo.php

@@ -6,6 +6,7 @@
 
 use Attribute;
 use Tempest\Database\Builder\ModelInspector;
+use Tempest\Database\Exceptions\ModelDidNotHavePrimaryColumn;
 use Tempest\Database\QueryStatements\FieldStatement;
 use Tempest\Database\QueryStatements\JoinStatement;
 use Tempest\Reflection\PropertyReflector;
@@ -46,14 +47,19 @@ public function getOwnerFieldName(): string
             }
         }
 
-        $relationModel = model($this->property->getType()->asClass());
+        $relationModel = inspect($this->property->getType()->asClass());
+        $primaryKey = $relationModel->getPrimaryKey();
 
-        return str($relationModel->getTableName())->singularizeLastWord() . '_' . $relationModel->getPrimaryKey();
+        if ($primaryKey === null) {
+            throw ModelDidNotHavePrimaryColumn::neededForRelation($relationModel->getName(), 'BelongsTo');
+        }
+
+        return str($relationModel->getTableName())->singularizeLastWord() . '_' . $primaryKey;
     }
 
     public function getSelectFields(): ImmutableArray
     {
-        $relationModel = model($this->property->getType()->asClass());
+        $relationModel = inspect($this->property->getType()->asClass());
 
         return $relationModel
             ->getSelectFields()
@@ -70,8 +76,8 @@ public function getSelectFields(): ImmutableArray
 
     public function getJoinStatement(): JoinStatement
     {
-        $relationModel = model($this->property->getType()->asClass());
-        $ownerModel = model($this->property->getClass());
+        $relationModel = inspect($this->property->getType()->asClass());
+        $ownerModel = inspect($this->property->getClass());
 
         $relationJoin = $this->getRelationJoin($relationModel);
         $ownerJoin = $this->getOwnerJoin($ownerModel);
@@ -97,11 +103,13 @@ private function getRelationJoin(ModelInspector $relationModel): string
             return $relationJoin;
         }
 
-        return sprintf(
-            '%s.%s',
-            $relationModel->getTableName(),
-            $relationModel->getPrimaryKey(),
-        );
+        $primaryKey = $relationModel->getPrimaryKey();
+
+        if ($primaryKey === null) {
+            throw ModelDidNotHavePrimaryColumn::neededForRelation($relationModel->getName(), 'BelongsTo');
+        }
+
+        return sprintf('%s.%s', $relationModel->getTableName(), $primaryKey);
     }
 
     private function getOwnerJoin(ModelInspector $ownerModel): string

packages/database/src/Builder/ModelInspector.php

@@ -6,9 +6,11 @@
 use Tempest\Database\BelongsTo;
 use Tempest\Database\Config\DatabaseConfig;
 use Tempest\Database\Eager;
+use Tempest\Database\Exceptions\ModelDidNotHavePrimaryColumn;
+use Tempest\Database\Exceptions\ModelHadMultiplePrimaryColumns;
 use Tempest\Database\HasMany;
 use Tempest\Database\HasOne;
-use Tempest\Database\Id;
+use Tempest\Database\PrimaryKey;
 use Tempest\Database\Relation;
 use Tempest\Database\Table;
 use Tempest\Database\Virtual;
@@ -21,7 +23,7 @@
 use Tempest\Validation\SkipValidation;
 use Tempest\Validation\Validator;
 
-use function Tempest\Database\model;
+use function Tempest\Database\inspect;
 use function Tempest\get;
 use function Tempest\Support\arr;
 use function Tempest\Support\str;
@@ -292,7 +294,7 @@ public function resolveRelations(string $relationString, string $parent = ''): a
 
         unset($relationNames[0]);
 
-        $relationModel = model($currentRelation);
+        $relationModel = inspect($currentRelation);
 
         $newRelationString = implode('.', $relationNames);
         $currentRelation->setParent($parent);
@@ -334,7 +336,7 @@ public function resolveEagerRelations(string $parent = ''): array
                 $currentRelationName,
             ), '.');
 
-            foreach (model($currentRelation)->resolveEagerRelations($newParent) as $name => $nestedEagerRelation) {
+            foreach (inspect($currentRelation)->resolveEagerRelations($newParent) as $name => $nestedEagerRelation) {
                 $relations[$name] = $nestedEagerRelation;
             }
         }
@@ -357,6 +359,10 @@ public function validate(mixed ...$data): void
                 continue;
             }
 
+            if ($property->getType()->getName() === PrimaryKey::class) {
+                continue;
+            }
+
             $failingRulesForProperty = $this->validator->validateValueForProperty(
                 $property,
                 $value,
@@ -381,17 +387,45 @@ public function getName(): string
         return $this->instance;
     }
 
-    public function getPrimaryFieldName(): string
+    public function getQualifiedPrimaryKey(): ?string
     {
-        return $this->getTableDefinition()->name . '.' . $this->getPrimaryKey();
+        $primaryKey = $this->getPrimaryKey();
+
+        return $primaryKey !== null
+            ? ($this->getTableDefinition()->name . '.' . $primaryKey)
+            : null;
     }
 
-    public function getPrimaryKey(): string
+    public function getPrimaryKey(): ?string
     {
-        return 'id';
+        return $this->getPrimaryKeyProperty()?->getName();
+    }
+
+    public function hasPrimaryKey(): bool
+    {
+        return $this->getPrimaryKeyProperty() !== null;
+    }
+
+    public function getPrimaryKeyProperty(): ?PropertyReflector
+    {
+        if (! $this->isObjectModel()) {
+            return null;
+        }
+
+        $primaryKeys = arr($this->reflector->getProperties())
+            ->filter(fn (PropertyReflector $property) => $property->getType()->matches(PrimaryKey::class));
+
+        return match ($primaryKeys->count()) {
+            0 => null,
+            1 => $primaryKeys->first(),
+            default => throw ModelHadMultiplePrimaryColumns::found(
+                model: $this->model,
+                properties: $primaryKeys->map(fn (PropertyReflector $property) => $property->getName())->toArray(),
+            ),
+        };
     }
 
-    public function getPrimaryKeyValue(): ?Id
+    public function getPrimaryKeyValue(): ?PrimaryKey
     {
         if (! $this->isObjectModel()) {
             return null;
@@ -401,6 +435,16 @@ public function getPrimaryKeyValue(): ?Id
             return null;
         }
 
-        return $this->instance->{$this->getPrimaryKey()};
+        $primaryKeyProperty = $this->getPrimaryKeyProperty();
+
+        if ($primaryKeyProperty === null) {
+            return null;
+        }
+
+        if (! $primaryKeyProperty->isInitialized($this->instance)) {
+            return null;
+        }
+
+        return $primaryKeyProperty->getValue($this->instance);
     }
 }

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

@@ -5,12 +5,12 @@
 use Tempest\Database\Query;
 
 /**
- * @template TModelClass
+ * @template TModel
  */
 interface BuildsQuery
 {
     public function build(mixed ...$bindings): Query;
 
-    /** @return self<TModelClass> */
+    /** @return self<TModel> */
     public function bind(mixed ...$bindings): self;
 }

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

@@ -11,17 +11,18 @@
 use Tempest\Database\QueryStatements\CountStatement;
 use Tempest\Database\QueryStatements\HasWhereStatements;
 use Tempest\Support\Conditions\HasConditions;
+use Tempest\Support\Str\ImmutableString;
 
-use function Tempest\Database\model;
+use function Tempest\Database\inspect;
 
 /**
- * @template T of object
- * @implements \Tempest\Database\Builder\QueryBuilders\BuildsQuery<T>
- * @uses \Tempest\Database\Builder\QueryBuilders\HasWhereQueryBuilderMethods<T>
+ * @template TModel of object
+ * @implements \Tempest\Database\Builder\QueryBuilders\BuildsQuery<TModel>
+ * @use \Tempest\Database\Builder\QueryBuilders\HasWhereQueryBuilderMethods<TModel>
  */
 final class CountQueryBuilder implements BuildsQuery
 {
-    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods;
+    use HasConditions, OnDatabase, HasWhereQueryBuilderMethods, TransformsQueryBuilder;
 
     private CountStatement $count;
 
@@ -30,24 +31,31 @@ final class CountQueryBuilder implements BuildsQuery
     private ModelInspector $model;
 
     /**
-     * @param class-string<T>|string|T $model
+     * @param class-string<TModel>|string|TModel $model
      */
     public function __construct(string|object $model, ?string $column = null)
     {
-        $this->model = model($model);
+        $this->model = inspect($model);
 
         $this->count = new CountStatement(
             table: $this->model->getTableDefinition(),
             column: $column,
         );
     }
 
+    /**
+     * Executes the count query and returns the number of matching records.
+     */
     public function execute(mixed ...$bindings): int
     {
         return $this->build()->fetchFirst(...$bindings)[$this->count->getKey()];
     }
 
-    /** @return self<T> */
+    /**
+     * Modifies the count query to only count distinct values in the specified column.
+     *
+     * @return self<TModel>
+     */
     public function distinct(): self
     {
         if ($this->count->column === null || $this->count->column === '*') {
@@ -59,17 +67,32 @@ public function distinct(): self
         return $this;
     }
 
-    /** @return self<T> */
+    /**
+     * Binds the provided values to the query, allowing for parameterized queries.
+     *
+     * @return self<TModel>
+     */
     public function bind(mixed ...$bindings): self
     {
         $this->bindings = [...$this->bindings, ...$bindings];
 
         return $this;
     }
 
-    public function toSql(): string
+    /**
+     * Compile the query to a SQL statement without the bindings.
+     */
+    public function compile(): ImmutableString
+    {
+        return $this->build()->compile();
+    }
+
+    /**
+     * Returns the SQL statement with bindings. This method may generate syntax errors, it is not recommended to use it other than for debugging.
+     */
+    public function toRawSql(): ImmutableString
     {
-        return $this->build()->toSql();
+        return $this->build()->toRawSql();
     }
 
     public function build(mixed ...$bindings): Query