Initial generics support

CHANGELOG.md

@@ -32,6 +32,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - The constructor arguments to `Property` are now typed and promoted to constructor properties. An array of properties is no longer accepted.
 - Property definitions must return `Property` objects instead of arrays
 - Renamed the `date` type to `date_unix`
+- Use PHPDoc generics when possible
 
 ### Fixed
 - Rollback database transaction after uncaught exception during model persistence.

src/Iterator.php

@@ -11,16 +11,24 @@
 
 namespace Pulsar;
 
+/**
+ * @template T
+ */
 final class Iterator implements \Iterator, \Countable, \ArrayAccess
 {
+    /** @var Query<T> */
     private Query $query;
     private int $start;
     private int $pointer;
     private int $limit;
     private int|bool $loadedStart = false;
+    /** @var T[] */
     private array $models = [];
     private int|bool $count = false;
 
+    /**
+     * @param Query<T>
+     */
     public function __construct(Query $query)
     {
         $this->query = $query;
@@ -40,6 +48,9 @@ public function __construct(Query $query)
         }
     }
 
+    /**
+     * @return Query<T>
+     */
     public function getQuery(): Query
     {
         return $this->query;
@@ -62,6 +73,8 @@ public function rewind(): void
 
     /**
      * Returns the current element.
+     *
+     * @return T
      */
     #[\ReturnTypeWillChange]
     public function current(): mixed
@@ -132,6 +145,9 @@ public function offsetExists($offset): bool
         return is_numeric($offset) && $offset < $this->count();
     }
 
+    /**
+     * @return T
+     */
     #[\ReturnTypeWillChange]
     public function offsetGet($offset)
     {
@@ -216,6 +232,8 @@ private function rangeStart(int $pointer, int $limit): int
 
     /**
      * Cast Iterator to array.
+     *
+     * @return T[]
      */
     public function toArray(): array
     {

src/Model.php

@@ -30,7 +30,7 @@
 use Throwable;
 
 /**
- * @mixin Query
+ * @mixin Query<static>
  */
 abstract class Model implements ArrayAccess
 {
@@ -1110,6 +1110,8 @@ public function isDeleted(): bool
 
     /**
      * Generates a new query instance.
+     *
+     * @return Query<static>
      */
     public static function query(): Query
     {

src/Query.php

@@ -17,6 +17,8 @@
 
 /**
  * Represents a query against a model type.
+ *
+ * @template T
  */
 class Query
 {
@@ -154,10 +156,10 @@ public function where(array|string $where, mixed $value = null, string|null $con
             $args = func_num_args();
             if ($args > 2) {
                 $this->where[] = [$where, $value, $condition];
-            // handles ii.
+                // handles ii.
             } elseif (2 == $args) {
                 $this->where[$where] = $value;
-            // handles iv.
+                // handles iv.
             } else {
                 $this->where[] = $where;
             }
@@ -232,7 +234,7 @@ public function getWith(): array
     /**
      * Executes the query against the model's driver.
      *
-     * @return Model[] results
+     * @return T[] results
      */
     public function execute(): array
     {
@@ -247,7 +249,7 @@ public function execute(): array
     /**
      * Creates an iterator for a search.
      *
-     * @return Iterator
+     * @return Iterator<T>
      */
     public function all(): mixed
     {
@@ -259,6 +261,8 @@ public function all(): mixed
      * then this function will fail.
      *
      * @throws ModelNotFoundException when the result is not exactly one model
+     *
+     * @return T
      */
     public function one(): Model
     {
@@ -280,6 +284,8 @@ public function one(): Model
      * then this function will return null.
      *
      * @throws ModelNotFoundException when the result is not exactly one model
+     *
+     * @return T|null
      */
     public function oneOrNull(): ?Model
     {
@@ -291,7 +297,7 @@ public function oneOrNull(): ?Model
     /**
      * Executes the query against the model's driver and returns the first result.
      *
-     * @return Model[]
+     * @return T[]
      */
     public function first(int $limit = 1): array
     {
@@ -311,10 +317,8 @@ public function count(): int
 
     /**
      * Gets the sum of a property matching the query.
-     *
-     * @return number
      */
-    public function sum(string $property)
+    public function sum(string $property): float
     {
         $model = $this->model;
         $driver = $model::getDriver();
@@ -324,10 +328,8 @@ public function sum(string $property)
 
     /**
      * Gets the average of a property matching the query.
-     *
-     * @return number
      */
-    public function average(string $property)
+    public function average(string $property): float
     {
         $model = $this->model;
         $driver = $model::getDriver();
@@ -337,10 +339,8 @@ public function average(string $property)
 
     /**
      * Gets the max of a property matching the query.
-     *
-     * @return number
      */
-    public function max(string $property)
+    public function max(string $property): float
     {
         $model = $this->model;
         $driver = $model::getDriver();
@@ -350,10 +350,8 @@ public function max(string $property)
 
     /**
      * Gets the min of a property matching the query.
-     *
-     * @return number
      */
-    public function min(string $property)
+    public function min(string $property): float
     {
         $model = $this->model;
         $driver = $model::getDriver();