Support paginations aware of their total items

README.md

@@ -151,14 +151,6 @@ LazyJsonPages::from($source)->lastPage('X-Last-Page');
 
 APIs can expose their length information in the form of numbers (`total_pages: 10`) or URIs (`last_page: "https://example.com?page=10"`), Lazy JSON Pages supports both.
 
-To save more memory when setting the total number of items, we can also define the number of items shown in each page:
-
-```php
-LazyJsonPages::from($source)
-    ->totalItems('pagination.total_items')
-    ->perPage(20);
-```
-
 When dealing with a lot of data, it may be a good idea to fetch only 1 item on the first page and leverage the length information on that page to calculate the total number of pages/items without having to load all the other items of that page.
 
 We can do that by calling `perPage()` with:

src/Paginations/AnyPagination.php

@@ -24,7 +24,7 @@ class AnyPagination extends Pagination
         // LimitPagination::class,
         // LinkHeaderPagination::class,
         // OffsetPagination::class,
-        // TotalItemsAwarePagination::class,
+        TotalItemsAwarePagination::class,
         TotalPagesAwarePagination::class,
     ];
 

src/Paginations/TotalItemsAwarePagination.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cerbero\LazyJsonPages\Paginations;
+
+use Cerbero\LazyJsonPages\Exceptions\InvalidKeyException;
+use Traversable;
+
+/**
+ * The pagination aware of the total number of items.
+ */
+class TotalItemsAwarePagination extends LengthAwarePagination
+{
+    /**
+     * Determine whether the configuration matches this pagination.
+     */
+    public function matches(): bool
+    {
+        return $this->config->totalItemsKey !== null
+            && $this->config->totalPagesKey === null
+            && $this->config->perPage === null;
+    }
+
+    /**
+     * Yield the paginated items.
+     *
+     * @return Traversable<int, mixed>
+     */
+    public function getIterator(): Traversable
+    {
+        $perPage = 0;
+        $generator = $this->yieldItemsAndReturnKey($this->source->response(), $this->config->totalItemsKey);
+
+        foreach ($generator as $item) {
+            yield $item;
+            ++$perPage;
+        }
+
+        if (!is_numeric($totalItems = $generator->getReturn())) {
+            throw new InvalidKeyException($this->config->totalItemsKey);
+        }
+
+        $totalPages = $perPage > 0 ? (int) ceil(intval($totalItems) / $perPage) : 0;
+
+        yield from $this->yieldItemsUntilPage($totalPages);
+    }
+}

tests/Feature/PaginationTest.php

@@ -0,0 +1,29 @@
+<?php
+
+use Cerbero\LazyJsonPages\LazyJsonPages;
+
+it('supports paginations aware of their total pages', function () {
+    $expectedItems = require fixture('items.php');
+    $lazyCollection = LazyJsonPages::from('https://example.com/api/v1/users')
+        ->totalPages('meta.total_pages')
+        ->collect('data.*');
+
+    expect($lazyCollection)->toLoadItemsViaRequests($expectedItems, [
+        'https://example.com/api/v1/users' => 'lengthAware/page1.json',
+        'https://example.com/api/v1/users?page=2' => 'lengthAware/page2.json',
+        'https://example.com/api/v1/users?page=3' => 'lengthAware/page3.json',
+    ]);
+});
+
+it('supports paginations aware of their total items', function () {
+    $expectedItems = require fixture('items.php');
+    $lazyCollection = LazyJsonPages::from('https://example.com/api/v1/users')
+        ->totalItems('meta.total_items')
+        ->collect('data.*');
+
+    expect($lazyCollection)->toLoadItemsViaRequests($expectedItems, [
+        'https://example.com/api/v1/users' => 'lengthAware/page1.json',
+        'https://example.com/api/v1/users?page=2' => 'lengthAware/page2.json',
+        'https://example.com/api/v1/users?page=3' => 'lengthAware/page3.json',
+    ]);
+});