Improve PaginatorInterface and ReadableDataInterface

.github/workflows/bc.yml

@@ -1,6 +1,15 @@
 on:
-  - pull_request
-  - push
+  pull_request:
+    paths:
+      - 'src/**'
+      - '.github/workflows/bc.yml'
+      - 'composer.json'
+  push:
+    branches: ['master']
+    paths:
+      - 'src/**'
+      - '.github/workflows/bc.yml'
+      - 'composer.json'
 
 name: backwards compatibility
 

CHANGELOG.md

@@ -1,8 +1,9 @@
 # Yii Data Change Log
 
-## 1.0.2 under development
+## 2.0.0 under development
 
-- no changes in this release.
+- New #150: Extract `withLimit()` from `ReadableDataInterface` into `LimitableDataInterface` (@vjik)
+- Enh #150: `PaginatorInterface` now extends `ReadableDataInterface` (@vjik)
 
 ## 1.0.1 January 25, 2023
 

README.md

@@ -265,6 +265,7 @@ Additional interfaces could be implemented in order to support different paginat
 
 - `CountableDataInterface` - allows getting total number of items in data reader.
 - `FilterableDataInterface` - allows returning subset of items based on criteria.
+- `LimitableDataInterface` - allows returning limited subset of items.
 - `SortableDataInterface` - allows sorting by one or multiple fields.
 - `OffsetableDataInterface` - allows to skip first N items when reading data.
 

infection.json.dist

@@ -11,6 +11,21 @@
         }
     },
     "mutators": {
-        "@default": true
+        "@default": true,
+        "LogicalAndAllSubExprNegation": {
+            "ignore": [
+                "Yiisoft\\Data\\Paginator\\KeysetPaginator::isOnFirstPage"
+            ]
+        },
+        "IncrementInteger": {
+            "ignore": [
+                "Yiisoft\\Data\\Paginator\\OffsetPaginator::readOne"
+            ]
+        },
+        "DecrementInteger": {
+            "ignore": [
+                "Yiisoft\\Data\\Paginator\\OffsetPaginator::readOne"
+            ]
+        }
     }
 }

psalm-php80.xml

@@ -1,6 +1,8 @@
 <?xml version="1.0"?>
 <psalm
     errorLevel="1"
+    findUnusedBaselineEntry="true"
+    findUnusedCode="false"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="https://getpsalm.org/schema/config"
     xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"

psalm.xml

@@ -1,6 +1,8 @@
 <?xml version="1.0"?>
 <psalm
     errorLevel="1"
+    findUnusedBaselineEntry="true"
+    findUnusedCode="false"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="https://getpsalm.org/schema/config"
     xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"

src/Paginator/KeysetPaginator.php

@@ -13,6 +13,7 @@
 use Yiisoft\Data\Reader\Filter\LessThan;
 use Yiisoft\Data\Reader\Filter\LessThanOrEqual;
 use Yiisoft\Data\Reader\FilterableDataInterface;
+use Yiisoft\Data\Reader\LimitableDataInterface;
 use Yiisoft\Data\Reader\ReadableDataInterface;
 use Yiisoft\Data\Reader\Sort;
 use Yiisoft\Data\Reader\SortableDataInterface;
@@ -49,7 +50,7 @@ final class KeysetPaginator implements PaginatorInterface
     /**
      * Data reader being paginated.
      *
-     * @psalm-var ReadableDataInterface<TKey, TValue>&FilterableDataInterface&SortableDataInterface
+     * @psalm-var ReadableDataInterface<TKey, TValue>&LimitableDataInterface&FilterableDataInterface&SortableDataInterface
      */
     private ReadableDataInterface $dataReader;
 
@@ -82,7 +83,7 @@ final class KeysetPaginator implements PaginatorInterface
 
     /**
      * @param ReadableDataInterface $dataReader Data reader being paginated.
-     * @psalm-param ReadableDataInterface<TKey, TValue>&FilterableDataInterface&SortableDataInterface $dataReader
+     * @psalm-param ReadableDataInterface<TKey, TValue>&LimitableDataInterface&FilterableDataInterface&SortableDataInterface $dataReader
      * @psalm-suppress DocblockTypeContradiction Needed to allow validating `$dataReader`
      */
     public function __construct(ReadableDataInterface $dataReader)
@@ -101,6 +102,13 @@ public function __construct(ReadableDataInterface $dataReader)
             ));
         }
 
+        if (!$dataReader instanceof LimitableDataInterface) {
+            throw new InvalidArgumentException(sprintf(
+                'Data reader should implement "%s" to be used with keyset paginator.',
+                LimitableDataInterface::class,
+            ));
+        }
+
         $sort = $dataReader->getSort();
 
         if ($sort === null) {
@@ -185,6 +193,15 @@ public function read(): iterable
         return $this->readCache = $data;
     }
 
+    public function readOne(): array|object|null
+    {
+        foreach ($this->read() as $item) {
+            return $item;
+        }
+
+        return null;
+    }
+
     public function getPageSize(): int
     {
         return $this->pageSize;
@@ -289,7 +306,7 @@ private function reverseData(array $data): array
     }
 
     /**
-     * @psalm-param ReadableDataInterface<TKey, TValue>&FilterableDataInterface&SortableDataInterface $dataReader
+     * @psalm-param ReadableDataInterface<TKey, TValue>&LimitableDataInterface&FilterableDataInterface&SortableDataInterface $dataReader
      */
     private function previousPageExist(ReadableDataInterface $dataReader, Sort $sort): bool
     {

src/Paginator/OffsetPaginator.php

@@ -7,6 +7,7 @@
 use Generator;
 use InvalidArgumentException;
 use Yiisoft\Data\Reader\CountableDataInterface;
+use Yiisoft\Data\Reader\LimitableDataInterface;
 use Yiisoft\Data\Reader\OffsetableDataInterface;
 use Yiisoft\Data\Reader\ReadableDataInterface;
 use Yiisoft\Data\Reader\Sort;
@@ -50,13 +51,13 @@ final class OffsetPaginator implements PaginatorInterface
     /**
      * Data reader being paginated.
      *
-     * @psalm-var ReadableDataInterface<TKey, TValue>&OffsetableDataInterface&CountableDataInterface
+     * @psalm-var ReadableDataInterface<TKey, TValue>&LimitableDataInterface&OffsetableDataInterface&CountableDataInterface
      */
     private ReadableDataInterface $dataReader;
 
     /**
      * @param ReadableDataInterface $dataReader Data reader being paginated.
-     * @psalm-param ReadableDataInterface<TKey, TValue>&OffsetableDataInterface&CountableDataInterface $dataReader
+     * @psalm-param ReadableDataInterface<TKey, TValue>&LimitableDataInterface&OffsetableDataInterface&CountableDataInterface $dataReader
      * @psalm-suppress DocblockTypeContradiction Needed to allow validating `$dataReader`
      */
     public function __construct(ReadableDataInterface $dataReader)
@@ -75,6 +76,13 @@ public function __construct(ReadableDataInterface $dataReader)
             ));
         }
 
+        if (!$dataReader instanceof LimitableDataInterface) {
+            throw new InvalidArgumentException(sprintf(
+                'Data reader should implement "%s" in order to be used with offset paginator.',
+                LimitableDataInterface::class,
+            ));
+        }
+
         $this->dataReader = $dataReader;
     }
 
@@ -213,6 +221,14 @@ public function read(): iterable
             ->read();
     }
 
+    public function readOne(): array|object|null
+    {
+        return $this->dataReader
+            ->withLimit(1)
+            ->withOffset($this->getOffset())
+            ->readOne();
+    }
+
     public function isOnFirstPage(): bool
     {
         return $this->currentPage === 1;

src/Paginator/PaginatorInterface.php

@@ -4,6 +4,7 @@
 
 namespace Yiisoft\Data\Paginator;
 
+use Yiisoft\Data\Reader\ReadableDataInterface;
 use Yiisoft\Data\Reader\Sort;
 
 /**
@@ -14,8 +15,10 @@
  *
  * @template TKey as array-key
  * @template TValue as array|object
+ *
+ * @extends ReadableDataInterface<TKey, TValue>
  */
-interface PaginatorInterface
+interface PaginatorInterface extends ReadableDataInterface
 {
     /**
      * Page size that is used in case it is not set explicitly.

src/Reader/DataReaderInterface.php

@@ -24,6 +24,7 @@
  */
 interface DataReaderInterface extends
     ReadableDataInterface,
+    LimitableDataInterface,
     OffsetableDataInterface,
     CountableDataInterface,
     SortableDataInterface,

src/Reader/LimitableDataInterface.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Data\Reader;
+
+use InvalidArgumentException;
+
+/**
+ * Data that could be limited.
+ */
+interface LimitableDataInterface
+{
+    /**
+     * Get a new instance with limit set.
+     *
+     * @param int $limit Limit. 0 means "no limit".
+     *
+     * @throws InvalidArgumentException If limit is less than 0.
+     *
+     * @return static New instance.
+     * @psalm-return $this
+     */
+    public function withLimit(int $limit): static;
+}

src/Reader/ReadableDataInterface.php

@@ -4,29 +4,14 @@
 
 namespace Yiisoft\Data\Reader;
 
-use InvalidArgumentException;
-
 /**
- * Readable data is a data set that could be read up to number of items
- * defined by limit either one by one or by getting an iterator.
+ * Readable data is a data set that could be read up by getting an iterator or reading one item from set.
  *
  * @template TKey as array-key
  * @template TValue as array|object
  */
 interface ReadableDataInterface
 {
-    /**
-     * Get a new instance with limit set.
-     *
-     * @param int $limit Limit. 0 means "no limit".
-     *
-     * @throws InvalidArgumentException If limit is less than 0.
-     *
-     * @return static New instance.
-     * @psalm-return $this
-     */
-    public function withLimit(int $limit): static;
-
     /**
      * Get iterable for the data set.
      *
@@ -36,7 +21,8 @@ public function withLimit(int $limit): static;
     public function read(): iterable;
 
     /**
-     * Get a next item from the data set.
+     * Get one item from the data set. Which item is returned is up to implementation.
+     * Note that invoking this method does not impact the data set or its pointer.
      *
      * @return array|object|null An item or null if there is none.
      * @psalm-return TValue|null