Add BufferState enum replacing magic buffer values (-1, -2, null, array)

Add EmptyResult, ArrayResult, IteratorResult implementing ResultInterface
Narrow AbstractResultSet::$dataSource type to just ResultInterface
Remove null checks using Null Object pattern with EmptyResult
Add generic type annotations throughout ResultSet classes
Update tests to use intersection types for mocks

Signed-off-by: Simon Mundy <simon.mundy@peptolab.com>

Author: simon-mundy

phpstan.neon.dist

@@ -1,7 +1,7 @@
 includes:
     - phpstan-baseline.neon
 parameters:
-    level: 4
+    level: 8
     paths:
         - src
         - test
@@ -16,4 +16,4 @@ parameters:
         - stubs/Laminas/ServiceManager/Factory/InvokableFactory.stub
         - stubs/Laminas/ServiceManager/Initializer/InitializerInterface.stub
         - stubs/Psr/Container/ContainerInterface.stub
-    treatPhpDocTypesAsCertain: false
+    treatPhpDocTypesAsCertain: false

src/Adapter/Driver/ArrayResult.php

@@ -0,0 +1,119 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpDb\Adapter\Driver;
+
+use ArrayIterator;
+use Override;
+
+use function count;
+
+/**
+ * ResultInterface implementation that wraps an array
+ *
+ * Used when AbstractResultSet is initialized with an array data source,
+ * allowing the dataSource property to be typed as just ResultInterface.
+ *
+ * @template TValue of array<string, mixed>|object
+ */
+final class ArrayResult implements ResultInterface
+{
+    /** @var ArrayIterator<int, TValue> */
+    private ArrayIterator $iterator;
+
+    /** @var int<0, max> */
+    private int $count;
+
+    private int $fieldCount;
+
+    /**
+     * @param array<int, TValue> $data
+     */
+    public function __construct(array $data, int $fieldCount = 0)
+    {
+        $this->iterator   = new ArrayIterator($data);
+        $this->count      = count($data);
+        $this->fieldCount = $fieldCount;
+    }
+
+    #[Override]
+    public function buffer(): void
+    {
+        // Arrays are naturally buffered, nothing to do
+    }
+
+    #[Override]
+    public function isBuffered(): ?bool
+    {
+        return true;
+    }
+
+    #[Override]
+    public function isQueryResult(): bool
+    {
+        return true;
+    }
+
+    #[Override]
+    public function getAffectedRows(): int
+    {
+        return 0;
+    }
+
+    #[Override]
+    public function getGeneratedValue(): mixed
+    {
+        return null;
+    }
+
+    #[Override]
+    public function getResource(): mixed
+    {
+        return $this->iterator->getArrayCopy();
+    }
+
+    #[Override]
+    public function getFieldCount(): int
+    {
+        return $this->fieldCount;
+    }
+
+    /** @return TValue */
+    #[Override]
+    public function current(): mixed
+    {
+        return $this->iterator->current();
+    }
+
+    #[Override]
+    public function key(): int
+    {
+        return $this->iterator->key();
+    }
+
+    #[Override]
+    public function next(): void
+    {
+        $this->iterator->next();
+    }
+
+    #[Override]
+    public function rewind(): void
+    {
+        $this->iterator->rewind();
+    }
+
+    #[Override]
+    public function valid(): bool
+    {
+        return $this->iterator->valid();
+    }
+
+    /** @return int<0, max> */
+    #[Override]
+    public function count(): int
+    {
+        return $this->count;
+    }
+}

src/Adapter/Driver/EmptyResult.php

@@ -0,0 +1,91 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpDb\Adapter\Driver;
+
+use Override;
+
+/**
+ * Null Object implementation of ResultInterface
+ *
+ * Used as the default data source in AbstractResultSet before initialization,
+ * eliminating the need for null checks throughout the codebase.
+ */
+final class EmptyResult implements ResultInterface
+{
+    #[Override]
+    public function buffer(): void
+    {
+    }
+
+    #[Override]
+    public function isBuffered(): ?bool
+    {
+        return true;
+    }
+
+    #[Override]
+    public function isQueryResult(): bool
+    {
+        return false;
+    }
+
+    #[Override]
+    public function getAffectedRows(): int
+    {
+        return 0;
+    }
+
+    #[Override]
+    public function getGeneratedValue(): mixed
+    {
+        return null;
+    }
+
+    #[Override]
+    public function getResource(): mixed
+    {
+        return null;
+    }
+
+    #[Override]
+    public function getFieldCount(): int
+    {
+        return 0;
+    }
+
+    #[Override]
+    public function current(): mixed
+    {
+        return null;
+    }
+
+    #[Override]
+    public function key(): mixed
+    {
+        return null;
+    }
+
+    #[Override]
+    public function next(): void
+    {
+    }
+
+    #[Override]
+    public function rewind(): void
+    {
+    }
+
+    #[Override]
+    public function valid(): bool
+    {
+        return false;
+    }
+
+    #[Override]
+    public function count(): int
+    {
+        return 0;
+    }
+}

src/Adapter/Driver/IteratorResult.php

@@ -0,0 +1,125 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpDb\Adapter\Driver;
+
+use Countable;
+use Iterator;
+use IteratorAggregate;
+use Override;
+
+/**
+ * ResultInterface implementation that wraps an Iterator or IteratorAggregate
+ *
+ * Used when AbstractResultSet is initialized with an iterator data source,
+ * allowing the dataSource property to be typed as just ResultInterface.
+ *
+ * @template TKey
+ * @template TValue of array<string, mixed>|object
+ */
+final class IteratorResult implements ResultInterface
+{
+    /** @var Iterator<TKey, TValue> */
+    private Iterator $iterator;
+
+    /**
+     * @param Iterator<TKey, TValue>|IteratorAggregate<TKey, TValue> $iterator
+     */
+    public function __construct(Iterator|IteratorAggregate $iterator)
+    {
+        if ($iterator instanceof IteratorAggregate) {
+            /** @var Iterator<TKey, TValue> $innerIterator */
+            $innerIterator  = $iterator->getIterator();
+            $this->iterator = $innerIterator;
+        } else {
+            $this->iterator = $iterator;
+        }
+    }
+
+    #[Override]
+    public function buffer(): void
+    {
+        // Cannot buffer a generic iterator
+    }
+
+    #[Override]
+    public function isBuffered(): ?bool
+    {
+        return false;
+    }
+
+    #[Override]
+    public function isQueryResult(): bool
+    {
+        return true;
+    }
+
+    #[Override]
+    public function getAffectedRows(): int
+    {
+        return 0;
+    }
+
+    #[Override]
+    public function getGeneratedValue(): mixed
+    {
+        return null;
+    }
+
+    #[Override]
+    public function getResource(): mixed
+    {
+        return $this->iterator;
+    }
+
+    #[Override]
+    public function getFieldCount(): int
+    {
+        return 0;
+    }
+
+    /** @return TValue */
+    #[Override]
+    public function current(): mixed
+    {
+        return $this->iterator->current();
+    }
+
+    #[Override]
+    public function key(): mixed
+    {
+        return $this->iterator->key();
+    }
+
+    #[Override]
+    public function next(): void
+    {
+        $this->iterator->next();
+    }
+
+    #[Override]
+    public function rewind(): void
+    {
+        $this->iterator->rewind();
+    }
+
+    #[Override]
+    public function valid(): bool
+    {
+        return $this->iterator->valid();
+    }
+
+    /**
+     * @return int<0, max>
+     */
+    #[Override]
+    public function count(): int
+    {
+        if ($this->iterator instanceof Countable) {
+            return $this->iterator->count();
+        }
+
+        return 0;
+    }
+}