Feature/Add PaginatedResult interface with required methods and tests

Author: othercodes

src/Contracts/PaginatedResult.php

@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ComplexHeart\Domain\Criteria\Contracts;
+
+/**
+ * Domain pagination contract
+ *
+ * Represents a paginated collection of items with metadata.
+ * NO web/URL concerns - pure business pagination logic.
+ *
+ * @author Unay Santisteban <usantisteban@othercode.io>
+ * @package ComplexHeart\Domain\Criteria\Contracts
+ */
+interface PaginatedResult
+{
+    /**
+     * Get the items for the current page
+     *
+     * @return array<int, mixed>
+     */
+    public function items(): array;
+
+    /**
+     * Get total number of items across all pages
+     *
+     * @return int
+     */
+    public function total(): int;
+
+    /**
+     * Get items per page
+     *
+     * @return int
+     */
+    public function perPage(): int;
+
+    /**
+     * Get current page number (1-indexed)
+     *
+     * @return int
+     */
+    public function currentPage(): int;
+
+    /**
+     * Get last page number
+     *
+     * @return int
+     */
+    public function lastPage(): int;
+
+    /**
+     * Check if there are more pages after the current one
+     *
+     * @return bool
+     */
+    public function hasMorePages(): bool;
+
+    /**
+     * Get the count of items on current page
+     *
+     * @return int
+     */
+    public function count(): int;
+
+    /**
+     * Check if the current page is empty
+     *
+     * @return bool
+     */
+    public function isEmpty(): bool;
+
+    /**
+     * Check if the current page is not empty
+     *
+     * @return bool
+     */
+    public function isNotEmpty(): bool;
+}

tests/PaginatedResultContractTest.php

@@ -0,0 +1,70 @@
+<?php
+
+declare(strict_types=1);
+
+use ComplexHeart\Domain\Criteria\Contracts\PaginatedResult;
+
+test('PaginatedResult interface exists and is accessible', function () {
+    expect(interface_exists(PaginatedResult::class))->toBeTrue();
+});
+
+test('PaginatedResult interface has all required methods', function () {
+    $reflection = new ReflectionClass(PaginatedResult::class);
+
+    $expectedMethods = [
+        'items',
+        'total',
+        'perPage',
+        'currentPage',
+        'lastPage',
+        'hasMorePages',
+        'count',
+        'isEmpty',
+        'isNotEmpty',
+    ];
+
+    foreach ($expectedMethods as $method) {
+        expect($reflection->hasMethod($method))
+            ->toBeTrue("Method '{$method}' should exist in PaginatedResult interface");
+    }
+});
+
+test('PaginatedResult methods have correct return types', function () {
+    $reflection = new ReflectionClass(PaginatedResult::class);
+
+    $methodReturnTypes = [
+        'items' => 'array',
+        'total' => 'int',
+        'perPage' => 'int',
+        'currentPage' => 'int',
+        'lastPage' => 'int',
+        'hasMorePages' => 'bool',
+        'count' => 'int',
+        'isEmpty' => 'bool',
+        'isNotEmpty' => 'bool',
+    ];
+
+    foreach ($methodReturnTypes as $methodName => $expectedType) {
+        $method = $reflection->getMethod($methodName);
+        expect($method->hasReturnType())->toBeTrue("Method {$methodName} should have return type");
+
+        $returnType = $method->getReturnType();
+        expect($returnType)->not->toBeNull("Method {$methodName} return type should not be null");
+
+        if ($returnType instanceof ReflectionNamedType) {
+            expect($returnType->getName())->toBe($expectedType, "Method {$methodName} should return {$expectedType}");
+        }
+    }
+});
+
+test('PaginatedResult is an interface not a class', function () {
+    $reflection = new ReflectionClass(PaginatedResult::class);
+
+    expect($reflection->isInterface())->toBeTrue()
+        ->and($reflection->isTrait())->toBeFalse();
+});
+
+test('PaginatedResult interface has correct namespace', function () {
+    expect(PaginatedResult::class)
+        ->toBe('ComplexHeart\Domain\Criteria\Contracts\PaginatedResult');
+});