Add paginated result + fix missing total result count

Author: MacFJA

src/Aggregate.php

@@ -33,6 +33,7 @@
 use MacFJA\RediSearch\Aggregate\Result;
 use MacFJA\RediSearch\Aggregate\SortBy;
 use MacFJA\RediSearch\Helper\DataHelper;
+use MacFJA\RediSearch\Helper\PaginatedResult;
 use MacFJA\RediSearch\Helper\RedisHelper;
 use Predis\Client;
 use Throwable;
@@ -217,20 +218,33 @@ public function withFilter(string $filter): Aggregate
 
     /**
      * @return array<Result>
+     *
+     * @deprecated Use \MacFJA\RediSearch\Aggregate::execute
      */
     public function aggregate(): array
+    {
+        return $this->execute()->getItems();
+    }
+
+    /**
+     * @return PaginatedResult<Result>
+     */
+    public function execute()
     {
         $rawResult = $this->redis->executeRaw($this->buildQuery());
 
-        array_shift($rawResult);
+        $totalCount = array_shift($rawResult);
+        assert(is_int($totalCount));
 
-        $results = array_map(function (array $document) {
+        $items = array_map(function (array $document) {
             return new Result(RedisHelper::getPairs($document));
         }, $rawResult);
 
+        $result = new class($totalCount, $items, 0, 0) extends PaginatedResult {
+        };
         $this->reset();
 
-        return $results;
+        return $result;
     }
 
     /**

src/Builder.php

@@ -24,4 +24,9 @@
 interface Builder
 {
     public function reset(): self;
+
+    /**
+     * @return mixed
+     */
+    public function execute();
 }

src/Helper/PaginatedResult.php

@@ -0,0 +1,105 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright MacFJA
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+namespace MacFJA\RediSearch\Helper;
+
+use function ceil;
+use function count;
+
+/**
+ * @template T
+ */
+abstract class PaginatedResult
+{
+    /** @var int */
+    private $totalCount;
+
+    /** @var array<T> */
+    private $items;
+
+    /** @var int */
+    private $offset;
+
+    /** @var int */
+    private $pageSize;
+
+    /**
+     * @param array<T> $items
+     */
+    public function __construct(int $totalCount, array $items, int $offset, int $pageSize)
+    {
+        $this->totalCount = $totalCount;
+        $this->items = $items;
+        $this->offset = $offset;
+        $this->pageSize = $pageSize;
+    }
+
+    public function getTotalCount(): int
+    {
+        return $this->totalCount;
+    }
+
+    /**
+     * @return array<T>
+     */
+    public function getItems(): array
+    {
+        return $this->items;
+    }
+
+    public function getOffset(): int
+    {
+        return $this->offset;
+    }
+
+    public function getPageSize(): int
+    {
+        return $this->pageSize;
+    }
+
+    public function getPageNumber(): int
+    {
+        if (0 === $this->pageSize) {
+            return 0;
+        }
+
+        return (int) ceil($this->getOffset() / $this->pageSize) + 1;
+    }
+
+    public function havePreviousPage(): bool
+    {
+        return $this->offset > 0;
+    }
+
+    public function haveNextPage(): bool
+    {
+        return $this->offset + count($this->items) < $this->totalCount;
+    }
+
+    public function getPageCount(): int
+    {
+        if (0 === $this->pageSize) {
+            return 0;
+        }
+
+        return (int) ceil($this->totalCount / $this->pageSize);
+    }
+}

src/Index/Builder.php

@@ -283,7 +283,15 @@ public function reset(): \MacFJA\RediSearch\Builder
         return $this;
     }
 
+    /**
+     * @deprecated Use \MacFJA\RediSearch\Index\Builder::execute()
+     */
     public function create(): bool
+    {
+        return $this->execute();
+    }
+
+    public function execute(): bool
     {
         $this->validateData();
         $query = $this->createRequest();

src/Search.php

@@ -33,6 +33,7 @@
 use function is_int;
 use function is_string;
 use MacFJA\RediSearch\Helper\DataHelper;
+use MacFJA\RediSearch\Helper\PaginatedResult;
 use MacFJA\RediSearch\Helper\RedisHelper;
 use MacFJA\RediSearch\Index\Builder as IndexBuilder;
 use MacFJA\RediSearch\Search\Exception\UnsupportedLanguageException;
@@ -54,6 +55,10 @@ class Search implements Builder
 
     public const SORT_DESC = 'DESC';
 
+    private const DEFAULT_OFFSET = 0;
+
+    private const DEFAULT_LIMIT = 10;
+
     /** @var Client */
     private $redis;
 
@@ -378,13 +383,24 @@ public function withResultLimit(int $resultLimit): Search
 
     /**
      * @return array<Result>
+     *
+     * @deprecated Use \MacFJA\RediSearch\Search::execute()
      */
     public function search(): array
+    {
+        return $this->execute()->getItems();
+    }
+
+    /**
+     * @return PaginatedResult<Result>
+     */
+    public function execute(): PaginatedResult
     {
         $rawResult = $this->redis->executeRaw($this->buildQuery());
         DataHelper::handleRawResult($rawResult);
 
-        array_shift($rawResult);
+        $totalCount = array_shift($rawResult);
+        assert(is_int($totalCount));
 
         $chunkSize = 2 // Hash + fields
             + ($this->withScores ? 1 : 0)
@@ -393,7 +409,7 @@ public function search(): array
 
         $documents = array_chunk($rawResult, $chunkSize);
 
-        $results = array_map(function ($document) {
+        $items = array_map(function ($document) {
             $hash = array_shift($document) ?? '';
             $score = $this->withScores ? (float) array_shift($document) : null;
             $payload = $this->withPayloads ? array_shift($document) : null;
@@ -409,9 +425,11 @@ public function search(): array
             return new Result($hash, $fields, $score, $payload, $sortKey);
         }, $documents);
 
+        $result = new class($totalCount, $items, $this->resultOffset ?? self::DEFAULT_OFFSET, $this->resultLimit ?? self::DEFAULT_LIMIT) extends PaginatedResult {
+        };
         $this->reset();
 
-        return $results;
+        return $result;
     }
 
     /**