Release/1.5.0 (#13)

Author: gustavofreze

.gitattributes

@@ -1,13 +1,14 @@
 /tests export-ignore
 /vendor export-ignore
 
-/README.md export-ignore
 /LICENSE export-ignore
 /Makefile export-ignore
+/README.md export-ignore
 /phpmd.xml export-ignore
 /phpunit.xml export-ignore
 /phpstan.neon.dist export-ignore
 /infection.json.dist export-ignore
 
 /.github export-ignore
 /.gitignore export-ignore
+/.gitattributes export-ignore

README.md

@@ -259,22 +259,30 @@ combining elements.
 
 These methods allow the Collection's elements to be transformed or converted into different formats.
 
-#### Mapping elements
+#### Applying actions without modifying elements
 
-- `map`: Applies transformations to each element in the Collection and returns a new collection with the transformed
-  elements.
+- `each`: Executes actions on each element in the Collection without modification.
+  The method is helpful for performing side effects, such as logging or adding elements to another collection.
 
   ```php
-  $collection->map(transformations: fn(int $value): int => $value * 2);
+  $collection->each(actions: fn(Invoice $invoice): void => $collectionB->add(elements: new InvoiceSummary(amount: $invoice->amount, customer: $invoice->customer)));
   ```
+  
+#### Grouping elements
 
-#### Applying actions without modifying elements
+- `groupBy`: Groups the elements in the Collection based on the provided grouping criterion.
 
-- `each`: Executes actions on each element in the Collection without modification.
-  The method is helpful for performing side effects, such as logging or adding elements to another collection.
+  ```php
+  $collection->groupBy(grouping: fn(Amount $amount): string => $amount->currency->name);
+  ```
+
+#### Mapping elements
+
+- `map`: Applies transformations to each element in the Collection and returns a new collection with the transformed
+  elements.
 
   ```php
-  $collection->each(actions: fn(Invoice $invoice): void => $collectionB->add(elements: new InvoiceSummary(amount: $invoice->amount, customer: $invoice->customer)));
+  $collection->map(transformations: fn(int $value): int => $value * 2);
   ```
 
 #### Convert to array

composer.json

@@ -12,6 +12,7 @@
         "array",
         "yield",
         "iterator",
+        "iterators",
         "generator",
         "collection",
         "tiny-blocks"

phpstan.neon.dist

@@ -6,9 +6,5 @@ parameters:
   ignoreErrors:
     - '#Unsafe usage of new static#'
     - '#does not specify its types#'
-    - '#contains incompatible type#'
-    - '#specified in iterable type iterable#'
-    - '#is not subtype of native type static#'
-    - '#PHPDoc tag @extends has invalid value#'
-    - '#type has no value type specified in iterable type array#'
+    - '#type specified in iterable type#'
   reportUnmatchedIgnoredErrors: false

src/Collectible.php

@@ -27,14 +27,14 @@ interface Collectible extends Countable, IteratorAggregate
      * @param iterable<Element> $elements The elements to initialize the collection with.
      * @return Collectible<Element> A new Collectible instance.
      */
-    public static function createFrom(iterable $elements): static;
+    public static function createFrom(iterable $elements): Collectible;
 
     /**
      * Creates an empty Collectible instance.
      *
      * @return Collectible<Element> An empty Collectible instance.
      */
-    public static function createFromEmpty(): static;
+    public static function createFromEmpty(): Collectible;
 
     /**
      * Adds one or more elements to the collection.
@@ -116,6 +116,15 @@ public function getBy(int $index, mixed $defaultValueIfNotFound = null): mixed;
      */
     public function getIterator(): Traversable;
 
+    /**
+     * Groups the elements in the collection based on the provided criteria.
+     *
+     * @param Closure(Element): Key $grouping The function to define the group key for each element.
+     * @return Collectible<Key, Collectible<Key, Element, Element>, Element> A collection of collections,
+     *                                                                      grouped by the key returned by the closure.
+     */
+    public function groupBy(Closure $grouping): Collectible;
+
     /**
      * Determines if the collection is empty.
      *

src/Collection.php

@@ -17,6 +17,7 @@
 use TinyBlocks\Collection\Internal\Operations\Retrieve\Get;
 use TinyBlocks\Collection\Internal\Operations\Retrieve\Last;
 use TinyBlocks\Collection\Internal\Operations\Transform\Each;
+use TinyBlocks\Collection\Internal\Operations\Transform\GroupBy;
 use TinyBlocks\Collection\Internal\Operations\Transform\Map;
 use TinyBlocks\Collection\Internal\Operations\Transform\MapToArray;
 use TinyBlocks\Collection\Internal\Operations\Transform\MapToJson;
@@ -31,9 +32,6 @@
  * Represents a collection that provides a set of utility methods for operations like adding,
  * filtering, mapping, and transforming elements. Internally uses iterators to apply operations
  * lazily and efficiently.
- *
- * @template Element of mixed
- * @implements Collectible<Element>
  */
 class Collection implements Collectible
 {
@@ -108,6 +106,11 @@ public function getIterator(): Traversable
         yield from $this->iterator->getIterator();
     }
 
+    public function groupBy(Closure $grouping): Collectible
+    {
+        return new static(iterator: $this->iterator->add(operation: GroupBy::from(grouping: $grouping)));
+    }
+
     public function isEmpty(): bool
     {
         return !$this->iterator->getIterator()->valid();

src/Internal/Iterators/InternalIterator.php

@@ -18,6 +18,9 @@
  */
 final class InternalIterator implements IteratorAggregate
 {
+    /**
+     * @var LazyOperation[]
+     */
     private array $operations;
 
     /**

src/Internal/Operations/Filter/Filter.php

@@ -8,7 +8,7 @@
 use Generator;
 use TinyBlocks\Collection\Internal\Operations\LazyOperation;
 
-final class Filter implements LazyOperation
+final readonly class Filter implements LazyOperation
 {
     private array $predicates;
 

src/Internal/Operations/ImmediateOperation.php

@@ -6,8 +6,6 @@
 
 /**
  * Interface for operations that are applied immediately and not lazily.
- *
- * @extends Operation
  */
 interface ImmediateOperation extends Operation
 {

src/Internal/Operations/LazyOperation.php

@@ -11,7 +11,6 @@
  *
  * @template Key of array-key
  * @template Value
- * @extends Operation
  */
 interface LazyOperation extends Operation
 {