From 30d0d82946fa13db2829bded5a981d7c84e2bd67 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Damian=20Zaprza=C5=82ek?= <dazet.me@gmail.com>
Date: Fri, 7 Jan 2022 12:29:26 +0100
Subject: [PATCH] Simplify simple operations and add documentation

---
 README.md                                     |   48 +
 docs/examples.md                              | 2068 +++++++++++++----
 examples/ReadmeWriter.php                     |    3 +-
 examples/example/NumberValue-add.php          |   20 +
 examples/example/NumberValue-calculate.php    |   23 +
 examples/example/NumberValue-format.php       |   11 +
 examples/example/NumberValue-round.php        |    7 +
 examples/example/NumberValue-subtract.php     |   20 +
 examples/example/NumbersArray-average.php     |    9 +
 examples/example/NumbersArray-max.php         |    9 +
 examples/example/NumbersArray-min.php         |    9 +
 .../example/NumbersArray-reduceNumber.php     |   15 +
 examples/example/NumbersArray-sum.php         |    9 +
 make-examples.php                             |    4 +
 spec/AssocArraySpec.php                       |   13 +-
 spec/PlainArraySpec.php                       |   15 +-
 spec/PlainNumbersArraySpec.php                |   22 +-
 spec/PlainStringSpec.php                      |    4 +-
 spec/PlainStringsArraySpec.php                |   15 +-
 src/Associable/SortKeys.php                   |    1 +
 src/Numberable/Add.php                        |   12 +-
 src/Numberable/Ceil.php                       |    5 +-
 src/Numberable/Divide.php                     |   11 +-
 src/Numberable/DivideReducer.php              |   23 -
 src/Numberable/Floor.php                      |    5 +-
 src/Numberable/JustNumber.php                 |    2 +-
 src/Numberable/Math.php                       |   16 +-
 src/Numberable/Min.php                        |    1 -
 src/Numberable/Multiply.php                   |   15 +-
 src/Numberable/MultiplyReducer.php            |   17 -
 src/Numberable/Round.php                      |    3 +-
 src/Numberable/Subtract.php                   |   14 +-
 src/Numberable/SubtractReducer.php            |   17 -
 .../{JustNumbers.php => WrapNumbers.php}      |    2 +-
 src/NumbersArray.php                          |    3 +-
 src/PlainNumbersArray.php                     |   14 +-
 src/PlainStringsArray.php                     |    4 +-
 37 files changed, 1908 insertions(+), 581 deletions(-)
 create mode 100644 examples/example/NumberValue-add.php
 create mode 100644 examples/example/NumberValue-calculate.php
 create mode 100644 examples/example/NumberValue-format.php
 create mode 100644 examples/example/NumberValue-round.php
 create mode 100644 examples/example/NumberValue-subtract.php
 create mode 100644 examples/example/NumbersArray-average.php
 create mode 100644 examples/example/NumbersArray-max.php
 create mode 100644 examples/example/NumbersArray-min.php
 create mode 100644 examples/example/NumbersArray-reduceNumber.php
 create mode 100644 examples/example/NumbersArray-sum.php
 delete mode 100644 src/Numberable/DivideReducer.php
 delete mode 100644 src/Numberable/MultiplyReducer.php
 delete mode 100644 src/Numberable/SubtractReducer.php
 rename src/Numberable/{JustNumbers.php => WrapNumbers.php} (93%)

diff --git a/README.md b/README.md
index bc5b296..8ed1d0a 100644
--- a/README.md
+++ b/README.md
@@ -210,6 +210,54 @@ $stringsArray = Wrap::iterable($range(0, 10))
     });
 ```
 
+### `NumberValue`
+
+Object wrapping number (float or int).
+
+```php
+<?php
+
+use GW\Value\Numberable\Math;
+use GW\Value\Wrap;
+
+$number = Wrap::number(100)
+    ->add(20)
+    ->subtract(1)
+    ->multiply(2)
+    ->divide(3)
+    ->modulo(100)
+    ->calculate(Math::sqrt())
+    ->round(2);
+// ...
+
+$formattedNumber = $number->format(2, '.', ',');
+
+```
+
+### `NumbersArray`
+
+Object wrapping array of numbers wrapped in NumberValue.
+
+```php
+<?php
+
+use GW\Value\NumberValue;
+use GW\Value\Wrap;
+
+$numbers = Wrap::numbersArray([1, 2, 3, 4]);
+
+$sum = $numbers->sum()->format(2)->toString();
+$min = $numbers->min()->format(2)->toString();
+$max = $numbers->max()->format(2)->toString();
+$avg = $numbers->average()->format(2)->toString();
+
+$customSum = $numbers->reduceNumber(
+    fn(NumberValue $sum, NumberValue $next): NumberValue => $sum->add($next->round()),
+    0
+);
+
+```
+
 ## Documentation
 
 For full methods reference and more examples see [here](./docs/examples.md).
diff --git a/docs/examples.md b/docs/examples.md
index 1a3fa14..dde1ce3 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -30,10 +30,10 @@ foreach ($array as $item) {
 ```php
 <?php
 /**
- * @param callable $callback function(mixed $value): void
- * @return ArrayValue
+ * @param callable(TValue $value):void $callback
+ * @phpstan-return ArrayValue<TValue>
  */
-public function each(callable $callback);
+public function each(callable $callback): ArrayValue;
 ```
 
 Call some callback on each item of `ArrayValue` and return this `ArrayValue`. 
@@ -62,10 +62,10 @@ abc
 ```php
 <?php
 /**
- * @param callable|null $comparator function(mixed $valueA, mixed $valueB): int{-1, 0, 1}
- * @return ArrayValue
+ * @param (callable(TValue $valueA, TValue $valueB):int)|null $comparator
+ * @phpstan-return ArrayValue<TValue>
  */
-public function unique(?callable $comparator = null);
+public function unique(?callable $comparator = null): ArrayValue;
 ```
 
 Filter `ArrayValue` items removing duplicated items.
@@ -111,7 +111,7 @@ unique by callback = array (
 ```php
 <?php
 /**
- * @return mixed[]
+ * @phpstan-return array<int, TValue>
  */
 public function toArray(): array;
 ```
@@ -123,10 +123,10 @@ Return primitive `array` from subject `ArrayValue`.
 ```php
 <?php
 /**
- * @param callable $filter function(mixed $value): bool
- * @return ArrayValue
+ * @param callable(TValue $value):bool $filter
+ * @phpstan-return ArrayValue<TValue>
  */
-public function filter(callable $filter);
+public function filter(callable $filter): ArrayValue;
 ```
 
 Create new `ArrayValue` with items filtered by callback.
@@ -158,9 +158,9 @@ array (
 ```php
 <?php
 /**
- * @return ArrayValue
+ * @phpstan-return ArrayValue<TValue>
  */
-public function filterEmpty();
+public function filterEmpty(): ArrayValue;
 ```
 
 Filter out empty items from `ArrayValue`.
@@ -191,10 +191,11 @@ array (
 ```php
 <?php
 /**
- * @param callable $transformer function(mixed $value): mixed
- * @return ArrayValue
+ * @template TNewValue
+ * @param callable(TValue $value):TNewValue $transformer
+ * @phpstan-return ArrayValue<TNewValue>
  */
-public function map(callable $transformer);
+public function map(callable $transformer): ArrayValue;
 ```
 
 Create new `ArrayValue` with items mapped by callback.
@@ -227,10 +228,11 @@ array (
 ```php
 <?php
 /**
- * @param callable $transformer function(mixed $value): iterable
- * @return ArrayValue
+ * @template TNewValue
+ * @param callable(TValue $value):iterable<TNewValue> $transformer
+ * @phpstan-return ArrayValue<TNewValue>
  */
-public function flatMap(callable $transformer);
+public function flatMap(callable $transformer): ArrayValue;
 ```
 
 ### ArrayValue::groupBy
@@ -238,8 +240,9 @@ public function flatMap(callable $transformer);
 ```php
 <?php
 /**
- * @param callable $reducer function(mixed $value): string|int|bool
- * @return AssocValue AssocValue<ArrayValue>
+ * @template TNewKey
+ * @param callable(TValue $value):TNewKey $reducer
+ * @phpstan-return AssocValue<TNewKey, ArrayValue<TValue>>
  */
 public function groupBy(callable $reducer): AssocValue;
 ```
@@ -345,9 +348,9 @@ array (
 ```php
 <?php
 /**
- * @return ArrayValue
+ * @phpstan-return ArrayValue<array<int, TValue>>
  */
-public function chunk(int $size);
+public function chunk(int $size): ArrayValue;
 ```
 
 #### Examples
@@ -395,10 +398,10 @@ array (
 ```php
 <?php
 /**
- * @param callable $comparator function(mixed $valueA, mixed $valueB): int{-1, 0, 1}
- * @return ArrayValue
+ * @param callable(TValue $valueA, TValue $valueB): int $comparator
+ * @phpstan-return ArrayValue<TValue>
  */
-public function sort(callable $comparator);
+public function sort(callable $comparator): ArrayValue;
 ```
 
 Create new `ArrayValue` with items sorted by callback.
@@ -454,9 +457,9 @@ descending = array (
 ```php
 <?php
 /**
- * @return ArrayValue
+ * @phpstan-return ArrayValue<TValue>
  */
-public function shuffle();
+public function shuffle(): ArrayValue;
 ```
 
 #### Examples
@@ -472,7 +475,7 @@ echo $words->shuffle()->implode(' ')->toString();
 ```
 
 ```
-no do or there not do try is
+there do do or try not is no
 ```
 
 ### ArrayValue::reverse
@@ -480,9 +483,9 @@ no do or there not do try is
 ```php
 <?php
 /**
- * @return ArrayValue
+ * @phpstan-return ArrayValue<TValue>
  */
-public function reverse();
+public function reverse(): ArrayValue;
 ```
 
 #### Examples
@@ -506,10 +509,10 @@ try no is there not do or do
 ```php
 <?php
 /**
- * @param mixed $value
- * @return ArrayValue
+ * @phpstan-param TValue $value
+ * @phpstan-return ArrayValue<TValue>
  */
-public function unshift($value);
+public function unshift($value): ArrayValue;
 ```
 
 #### Examples
@@ -538,10 +541,10 @@ array (
 ```php
 <?php
 /**
- * @param mixed $value
- * @return ArrayValue
+ * @phpstan-param TValue $value
+ * @phpstan-return ArrayValue<TValue>
  */
-public function shift(&$value = null);
+public function shift(&$value = null): ArrayValue;
 ```
 
 #### Examples
@@ -571,10 +574,10 @@ x: a
 ```php
 <?php
 /**
- * @param mixed $value
- * @return ArrayValue
+ * @phpstan-param TValue $value
+ * @phpstan-return ArrayValue<TValue>
  */
-public function push($value);
+public function push($value): ArrayValue;
 ```
 
 #### Examples
@@ -603,10 +606,10 @@ array (
 ```php
 <?php
 /**
- * @param mixed $value
- * @return ArrayValue
+ * @phpstan-param TValue $value
+ * @phpstan-return ArrayValue<TValue>
  */
-public function pop(&$value = null);
+public function pop(&$value = null): ArrayValue;
 ```
 
 #### Examples
@@ -647,7 +650,7 @@ public function offsetExists($offset): bool;
 <?php
 /**
  * @param int $offset
- * @return mixed
+ * @phpstan-return TValue
  */
 public function offsetGet($offset);
 ```
@@ -658,11 +661,10 @@ public function offsetGet($offset);
 <?php
 /**
  * @param int $offset
- * @param mixed $value
- * @return void
- * @throws \BadMethodCallException For immutable types.
+ * @phpstan-param TValue $value
+ * @throws BadMethodCallException For immutable types.
  */
-public function offsetSet($offset, $value);
+public function offsetSet($offset, $value): void;
 ```
 
 ### ArrayValue::offsetUnset
@@ -672,9 +674,9 @@ public function offsetSet($offset, $value);
 /**
  * @param int $offset
  * @return void
- * @throws \BadMethodCallException For immutable types.
+ * @throws BadMethodCallException For immutable types.
  */
-public function offsetUnset($offset);
+public function offsetUnset($offset): void;
 ```
 
 ### ArrayValue::join
@@ -682,9 +684,10 @@ public function offsetUnset($offset);
 ```php
 <?php
 /**
- * @return ArrayValue
+ * @phpstan-param ArrayValue<TValue> $other
+ * @phpstan-return ArrayValue<TValue>
  */
-public function join(ArrayValue $other);
+public function join(ArrayValue $other): ArrayValue;
 ```
 
 #### Examples
@@ -716,9 +719,9 @@ array (
 ```php
 <?php
 /**
- * @return ArrayValue
+ * @phpstan-return ArrayValue<TValue>
  */
-public function slice(int $offset, int $length);
+public function slice(int $offset, int $length): ArrayValue;
 ```
 
 #### Examples
@@ -774,9 +777,10 @@ array (
 ```php
 <?php
 /**
- * @return ArrayValue
+ * @phpstan-param ArrayValue<TValue> $replacement
+ * @phpstan-return ArrayValue<TValue>
  */
-public function splice(int $offset, int $length, ?ArrayValue $replacement = null);
+public function splice(int $offset, int $length, ?ArrayValue $replacement = null): ArrayValue;
 ```
 
 Remove or replace slice of `ArrayValue` items.
@@ -856,10 +860,11 @@ array (
 ```php
 <?php
 /**
- * @param callable|null $comparator function(mixed $valueA, mixed $valueB): int{-1, 0, 1}
- * @return ArrayValue
+ * @phpstan-param ArrayValue<TValue> $other
+ * @param (callable(TValue,TValue):int)|null $comparator
+ * @phpstan-return ArrayValue<TValue>
  */
-public function diff(ArrayValue $other, ?callable $comparator = null);
+public function diff(ArrayValue $other, ?callable $comparator = null): ArrayValue;
 ```
 
 #### Examples
@@ -901,10 +906,11 @@ array (
 ```php
 <?php
 /**
- * @param callable|null $comparator function(mixed $valueA, mixed $valueB): int{-1, 0, 1}
- * @return ArrayValue
+ * @phpstan-param ArrayValue<TValue> $other
+ * @param (callable(TValue,TValue):int)|null $comparator
+ * @phpstan-return ArrayValue<TValue>
  */
-public function intersect(ArrayValue $other, ?callable $comparator = null);
+public function intersect(ArrayValue $other, ?callable $comparator = null): ArrayValue;
 ```
 
 #### Examples
@@ -944,9 +950,10 @@ array (
 ```php
 <?php
 /**
- * @param callable $transformer function(mixed $reduced, mixed $value): mixed
- * @param mixed $start
- * @return mixed
+ * @template TNewValue
+ * @param callable(TNewValue, TValue):TNewValue $transformer
+ * @phpstan-param TNewValue $start
+ * @phpstan-return TNewValue
  */
 public function reduce(callable $transformer, $start);
 ```
@@ -1009,16 +1016,18 @@ a / b / c / d
 ```php
 <?php
 /**
- * @return ArrayValue
+ * @phpstan-return ArrayValue<TValue>
  */
-public function notEmpty();
+public function notEmpty(): ArrayValue;
 ```
 
 ### ArrayValue::toAssocValue
 
 ```php
 <?php
-
+/**
+ * @phpstan-return AssocValue<int, TValue>
+ */
 public function toAssocValue(): AssocValue;
 ```
 
@@ -1033,7 +1042,7 @@ $array = Wrap::array(['a', 'b', 'c', 'd', 'e', 'f', 'g']);
 
 var_export(
     $array->toAssocValue()
-        ->mapKeys(function (string $oldKey, string $value): string {
+        ->mapKeys(function (int $oldKey, string $value): string {
             return "{$oldKey}:{$value}";
         })
         ->toAssocArray()
@@ -1060,6 +1069,14 @@ array (
 public function toStringsArray(): StringsArray;
 ```
 
+### ArrayValue::toNumbersArray
+
+```php
+<?php
+
+public function toNumbersArray(): NumbersArray;
+```
+
 ### ArrayValue::isEmpty
 
 ```php
@@ -1094,7 +1111,7 @@ echo PHP_EOL;
 ```php
 <?php
 /**
- * @return mixed
+ * @phpstan-return TValue|null
  */
 public function first();
 ```
@@ -1120,7 +1137,7 @@ array first: a
 ```php
 <?php
 /**
- * @return mixed
+ * @phpstan-return TValue|null
  */
 public function last();
 ```
@@ -1146,8 +1163,8 @@ array last: c
 ```php
 <?php
 /**
- * @param callable $filter function(mixed $value): bool
- * @return mixed
+ * @param callable(TValue $value):bool $filter
+ * @phpstan-return TValue|null
  */
 public function find(callable $filter);
 ```
@@ -1157,8 +1174,8 @@ public function find(callable $filter);
 ```php
 <?php
 /**
- * @param callable $filter function(mixed $value): bool
- * @return mixed
+ * @param callable(TValue $value): bool $filter
+ * @phpstan-return TValue|null
  */
 public function findLast(callable $filter);
 ```
@@ -1168,7 +1185,7 @@ public function findLast(callable $filter);
 ```php
 <?php
 /**
- * @param mixed $element
+ * @phpstan-param TValue $element
  */
 public function hasElement($element): bool;
 ```
@@ -1178,7 +1195,7 @@ public function hasElement($element): bool;
 ```php
 <?php
 /**
- * @param callable $filter function(mixed $value): bool
+ * @param callable(TValue $value):bool $filter
  */
 public function any(callable $filter): bool;
 ```
@@ -1188,7 +1205,7 @@ public function any(callable $filter): bool;
 ```php
 <?php
 /**
- * @param callable $filter function(mixed $value): bool
+ * @param callable(TValue $value):bool $filter
  */
 public function every(callable $filter): bool;
 ```
@@ -1253,10 +1270,10 @@ foreach ($array as $key => $value) {
 ```php
 <?php
 /**
- * @param callable $callback function(mixed $value): void
- * @return AssocValue
+ * @phpstan-param callable(TValue $value, TKey $key=):void $callback
+ * @phpstan-return AssocValue<TKey, TValue>
  */
-public function each(callable $callback);
+public function each(callable $callback): AssocValue;
 ```
 
 ### AssocValue::unique
@@ -1264,10 +1281,10 @@ public function each(callable $callback);
 ```php
 <?php
 /**
- * @param callable|null $comparator function(mixed $valueA, mixed $valueB): int{-1, 0, 1}
- * @return AssocValue
+ * @phpstan-param (callable(TValue $valueA, TValue $valueB):int)|null $comparator
+ * @phpstan-return AssocValue<TKey, TValue>
  */
-public function unique(?callable $comparator = null);
+public function unique(?callable $comparator = null): AssocValue;
 ```
 
 ### AssocValue::filter
@@ -1275,10 +1292,10 @@ public function unique(?callable $comparator = null);
 ```php
 <?php
 /**
- * @param callable $filter function(mixed $value): bool
- * @return AssocValue
+ * @phpstan-param callable(TValue $value):bool $filter
+ * @phpstan-return AssocValue<TKey, TValue>
  */
-public function filter(callable $filter);
+public function filter(callable $filter): AssocValue;
 ```
 
 ### AssocValue::filterEmpty
@@ -1286,9 +1303,9 @@ public function filter(callable $filter);
 ```php
 <?php
 /**
- * @return AssocValue
+ * @phpstan-return AssocValue<TKey, TValue>
  */
-public function filterEmpty();
+public function filterEmpty(): AssocValue;
 ```
 
 ### AssocValue::map
@@ -1296,10 +1313,11 @@ public function filterEmpty();
 ```php
 <?php
 /**
- * @param callable $transformer function(mixed $value[, string $key]): mixed
- * @return AssocValue
+ * @template TNewValue
+ * @param callable(TValue $value, TKey $key=):TNewValue $transformer
+ * @phpstan-return AssocValue<TKey, TNewValue>
  */
-public function map(callable $transformer);
+public function map(callable $transformer): AssocValue;
 ```
 
 ### AssocValue::sort
@@ -1307,10 +1325,10 @@ public function map(callable $transformer);
 ```php
 <?php
 /**
- * @param callable $comparator function(mixed $valueA, mixed $valueB): int{-1, 0, 1}
- * @return AssocValue
+ * @param callable(TValue $valueA, TValue $valueB):int $comparator
+ * @phpstan-return AssocValue<TKey, TValue>
  */
-public function sort(callable $comparator);
+public function sort(callable $comparator): AssocValue;
 ```
 
 ### AssocValue::shuffle
@@ -1318,9 +1336,9 @@ public function sort(callable $comparator);
 ```php
 <?php
 /**
- * @return AssocValue
+ * @phpstan-return AssocValue<TKey, TValue>
  */
-public function shuffle();
+public function shuffle(): AssocValue;
 ```
 
 ### AssocValue::reverse
@@ -1328,9 +1346,9 @@ public function shuffle();
 ```php
 <?php
 /**
- * @return AssocValue
+ * @phpstan-return AssocValue<TKey, TValue>
  */
-public function reverse();
+public function reverse(): AssocValue;
 ```
 
 ### AssocValue::offsetExists
@@ -1338,7 +1356,7 @@ public function reverse();
 ```php
 <?php
 /**
- * @param string $offset
+ * @phpstan-param TKey $offset
  */
 public function offsetExists($offset): bool;
 ```
@@ -1348,8 +1366,8 @@ public function offsetExists($offset): bool;
 ```php
 <?php
 /**
- * @param string $offset
- * @return mixed
+ * @phpstan-param TKey $offset
+ * @return ?TValue
  */
 public function offsetGet($offset);
 ```
@@ -1359,12 +1377,11 @@ public function offsetGet($offset);
 ```php
 <?php
 /**
- * @param string $offset
- * @param mixed $value
- * @return void
- * @throws \BadMethodCallException For immutable types.
+ * @phpstan-param TKey $offset
+ * @phpstan-param TValue $value
+ * @throws BadMethodCallException For immutable types.
  */
-public function offsetSet($offset, $value);
+public function offsetSet($offset, $value): void;
 ```
 
 ### AssocValue::offsetUnset
@@ -1372,18 +1389,19 @@ public function offsetSet($offset, $value);
 ```php
 <?php
 /**
- * @param string $offset
- * @return void
- * @throws \BadMethodCallException For immutable types.
+ * @phpstan-param TKey $offset
+ * @throws BadMethodCallException For immutable types.
  */
-public function offsetUnset($offset);
+public function offsetUnset($offset): void;
 ```
 
 ### AssocValue::toAssocArray
 
 ```php
 <?php
-
+/**
+ * @phpstan-return array<TKey, TValue>
+ */
 public function toAssocArray(): array;
 ```
 
@@ -1391,15 +1409,19 @@ public function toAssocArray(): array;
 
 ```php
 <?php
-
-public function keys(): StringsArray;
+/**
+ * @phpstan-return ArrayValue<TKey>
+ */
+public function keys(): ArrayValue;
 ```
 
 ### AssocValue::values
 
 ```php
 <?php
-
+/**
+ * @phpstan-return ArrayValue<TValue>
+ */
 public function values(): ArrayValue;
 ```
 
@@ -1408,10 +1430,11 @@ public function values(): ArrayValue;
 ```php
 <?php
 /**
- * @param callable $transformer function(string $key[, mixed $value]): string
- * @return AssocValue
+ * @template TNewKey
+ * @phpstan-param callable(TKey $key, TValue $value=): TNewKey $transformer
+ * @phpstan-return AssocValue<TNewKey, TValue>
  */
-public function mapKeys(callable $transformer);
+public function mapKeys(callable $transformer): AssocValue;
 ```
 
 ### AssocValue::sortKeys
@@ -1419,10 +1442,10 @@ public function mapKeys(callable $transformer);
 ```php
 <?php
 /**
- * @param callable $comparator function(string $keyA, string $keyB): int{-1, 1}
- * @return AssocValue
+ * @phpstan-param callable(TKey $keyA, TKey $keyB): int $comparator
+ * @phpstan-return AssocValue<TKey, TValue>
  */
-public function sortKeys(callable $comparator);
+public function sortKeys(callable $comparator): AssocValue;
 ```
 
 ### AssocValue::with
@@ -1430,10 +1453,11 @@ public function sortKeys(callable $comparator);
 ```php
 <?php
 /**
- * @param mixed $value
- * @return AssocValue
+ * @phpstan-param TKey $key
+ * @phpstan-param TValue $value
+ * @phpstan-return AssocValue<TKey, TValue>
  */
-public function with(string $key, $value);
+public function with($key, $value): AssocValue;
 ```
 
 ### AssocValue::without
@@ -1441,9 +1465,10 @@ public function with(string $key, $value);
 ```php
 <?php
 /**
- * @return AssocValue
+ * @phpstan-param array<int, TKey> $keys
+ * @phpstan-return AssocValue<TKey, TValue>
  */
-public function without(string ...$keys);
+public function without(...$keys): AssocValue;
 ```
 
 ### AssocValue::only
@@ -1451,9 +1476,10 @@ public function without(string ...$keys);
 ```php
 <?php
 /**
- * @return AssocValue
+ * @phpstan-param array<int, TKey> $keys
+ * @phpstan-return AssocValue<TKey, TValue>
  */
-public function only(string ...$keys);
+public function only(...$keys): AssocValue;
 ```
 
 ### AssocValue::withoutElement
@@ -1461,10 +1487,10 @@ public function only(string ...$keys);
 ```php
 <?php
 /**
- * @param mixed $value
- * @return AssocValue
+ * @phpstan-param TValue $value
+ * @phpstan-return AssocValue<TKey, TValue>
  */
-public function withoutElement($value);
+public function withoutElement($value): AssocValue;
 ```
 
 ### AssocValue::merge
@@ -1472,10 +1498,10 @@ public function withoutElement($value);
 ```php
 <?php
 /**
- * @param AssocValue $other
- * @return AssocValue
+ * @phpstan-param AssocValue<TKey, TValue> $other
+ * @phpstan-return AssocValue<TKey, TValue>
  */
-public function merge(AssocValue $other);
+public function merge(AssocValue $other): AssocValue;
 ```
 
 ### AssocValue::reduce
@@ -1483,9 +1509,10 @@ public function merge(AssocValue $other);
 ```php
 <?php
 /**
- * @param callable $transformer function(mixed $reduced, mixed $value, string $key): mixed
- * @param mixed $start
- * @return mixed
+ * @template TNewValue
+ * @param callable(TNewValue $reduced, TValue $value, string $key):TNewValue $transformer
+ * @phpstan-param TNewValue $start
+ * @phpstan-return TNewValue
  */
 public function reduce(callable $transformer, $start);
 ```
@@ -1495,18 +1522,21 @@ public function reduce(callable $transformer, $start);
 ```php
 <?php
 /**
- * @param mixed $default
- * @return mixed
+ * @phpstan-param TKey $key
+ * @phpstan-param ?TValue $default
+ * @phpstan-return ?TValue
  */
-public function get(string $key, $default = null);
+public function get($key, $default = null);
 ```
 
 ### AssocValue::has
 
 ```php
 <?php
-
-public function has(string $key): bool;
+/**
+ * @phpstan-param TKey $key
+ */
+public function has($key): bool;
 ```
 
 ### AssocValue::isEmpty
@@ -1522,7 +1552,7 @@ public function isEmpty(): bool;
 ```php
 <?php
 /**
- * @return mixed
+ * @phpstan-return TValue|null
  */
 public function first();
 ```
@@ -1548,7 +1578,7 @@ assoc first: 1
 ```php
 <?php
 /**
- * @return mixed
+ * @phpstan-return TValue|null
  */
 public function last();
 ```
@@ -1574,8 +1604,8 @@ assoc last: 3
 ```php
 <?php
 /**
- * @param callable $filter function(mixed $value): bool
- * @return mixed
+ * @param callable(TValue $value):bool $filter
+ * @phpstan-return TValue|null
  */
 public function find(callable $filter);
 ```
@@ -1585,8 +1615,8 @@ public function find(callable $filter);
 ```php
 <?php
 /**
- * @param callable $filter function(mixed $value): bool
- * @return mixed
+ * @param callable(TValue $value): bool $filter
+ * @phpstan-return TValue|null
  */
 public function findLast(callable $filter);
 ```
@@ -1596,7 +1626,7 @@ public function findLast(callable $filter);
 ```php
 <?php
 /**
- * @param mixed $element
+ * @phpstan-param TValue $element
  */
 public function hasElement($element): bool;
 ```
@@ -1606,7 +1636,7 @@ public function hasElement($element): bool;
 ```php
 <?php
 /**
- * @param callable $filter function(mixed $value): bool
+ * @param callable(TValue $value):bool $filter
  */
 public function any(callable $filter): bool;
 ```
@@ -1616,7 +1646,7 @@ public function any(callable $filter): bool;
 ```php
 <?php
 /**
- * @param callable $filter function(mixed $value): bool
+ * @param callable(TValue $value):bool $filter
  */
 public function every(callable $filter): bool;
 ```
@@ -1626,7 +1656,7 @@ public function every(callable $filter): bool;
 ```php
 <?php
 /**
- * @return mixed[]
+ * @phpstan-return array<int, TValue>
  */
 public function toArray(): array;
 ```
@@ -1650,10 +1680,10 @@ public function count(): int;
 ```php
 <?php
 /**
- * @param callable $transformer function(string $value): string
+ * @param callable(string $value):(StringValue|string) $transformer
  * @return StringValue
  */
-public function transform(callable $transformer);
+public function transform(callable $transformer): StringValue;
 ```
 
 ### StringValue::stripTags
@@ -1663,7 +1693,7 @@ public function transform(callable $transformer);
 /**
  * @return StringValue
  */
-public function stripTags();
+public function stripTags(): StringValue;
 ```
 
 #### Examples
@@ -1688,8 +1718,9 @@ Html is cool but not always...
 <?php
 /**
  * @return StringValue
+ * @param string|StringValue $characterMask
  */
-public function trim(string $characterMask = self::TRIM_MASK);
+public function trim($characterMask = self::TRIM_MASK): StringValue;
 ```
 
 #### Examples
@@ -1716,8 +1747,9 @@ I ♡ SPACE
 <?php
 /**
  * @return StringValue
+ * @param string|StringValue $characterMask
  */
-public function trimRight(string $characterMask = self::TRIM_MASK);
+public function trimRight($characterMask = self::TRIM_MASK): StringValue;
 ```
 
 #### Examples
@@ -1744,8 +1776,9 @@ echo $text->trimRight(' .:')->toString() . PHP_EOL;
 <?php
 /**
  * @return StringValue
+ * @param string|StringValue $characterMask
  */
-public function trimLeft(string $characterMask = self::TRIM_MASK);
+public function trimLeft($characterMask = self::TRIM_MASK): StringValue;
 ```
 
 #### Examples
@@ -1773,7 +1806,7 @@ I ♡ SPACE :.:
 /**
  * @return StringValue
  */
-public function lower();
+public function lower(): StringValue;
 ```
 
 #### Examples
@@ -1799,7 +1832,7 @@ sometimes i wanna scream!
 /**
  * @return StringValue
  */
-public function upper();
+public function upper(): StringValue;
 ```
 
 #### Examples
@@ -1825,7 +1858,7 @@ IT`S SO QUIET...
 /**
  * @return StringValue
  */
-public function lowerFirst();
+public function lowerFirst(): StringValue;
 ```
 
 #### Examples
@@ -1851,7 +1884,7 @@ camelCaseMethod()
 /**
  * @return StringValue
  */
-public function upperFirst();
+public function upperFirst(): StringValue;
 ```
 
 #### Examples
@@ -1877,7 +1910,7 @@ Words don`t come easy
 /**
  * @return StringValue
  */
-public function upperWords();
+public function upperWords(): StringValue;
 ```
 
 #### Examples
@@ -1902,8 +1935,9 @@ Words Don`t Come Easy
 <?php
 /**
  * @return StringValue
+ * @param string|StringValue $string
  */
-public function padRight(int $length, string $string = ' ');
+public function padRight(int $length, $string = ' '): StringValue;
 ```
 
 #### Examples
@@ -1928,8 +1962,9 @@ cut here ☞----
 <?php
 /**
  * @return StringValue
+ * @param string|StringValue $string
  */
-public function padLeft(int $length, string $string = ' ');
+public function padLeft(int $length, $string = ' '): StringValue;
 ```
 
 #### Examples
@@ -1954,8 +1989,9 @@ echo $text->padLeft(16, '-')->toString();
 <?php
 /**
  * @return StringValue
+ * @param string|StringValue $string
  */
-public function padBoth(int $length, string $string = ' ');
+public function padBoth(int $length, $string = ' '): StringValue;
 ```
 
 #### Examples
@@ -1980,8 +2016,10 @@ echo $text->padBoth(24, '-')->toString();
 <?php
 /**
  * @return StringValue
+ * @param string|StringValue $search
+ * @param string|StringValue $replace
  */
-public function replace(string $search, string $replace);
+public function replace($search, $replace): StringValue;
 ```
 
 #### Examples
@@ -2000,14 +2038,71 @@ echo $text->replace('pink', 'blue')->toString();
 My favourite color is blue!
 ```
 
+### StringValue::replaceAll
+
+```php
+<?php
+/**
+ * @return StringValue
+ * @param array<int,string>|ArrayValue<string> $search
+ * @param string|StringValue $replace
+ */
+public function replaceAll($search, $replace): StringValue;
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+$text = Wrap::string('Your favourite colors are red and black');
+
+echo $text->replaceAll(['red', 'black'], 'blue')->toString();
+```
+
+```
+Your favourite colors are blue and blue
+```
+
+### StringValue::replacePairs
+
+```php
+<?php
+/**
+ * @return StringValue
+ * @param array<string,string>|AssocValue<string,string> $pairs
+ */
+public function replacePairs($pairs): StringValue;
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+$text = Wrap::string('Your favourite colors are red and black');
+
+echo $text->replacePairs(['red' => 'orange', 'black' => 'white'])->toString();
+```
+
+```
+Your favourite colors are orange and white
+```
+
 ### StringValue::replacePattern
 
 ```php
 <?php
 /**
  * @return StringValue
+ * @param string|StringValue $pattern
+ * @param string|StringValue $replacement
  */
-public function replacePattern(string $pattern, string $replacement);
+public function replacePattern($pattern, $replacement): StringValue;
 ```
 
 #### Examples
@@ -2032,8 +2127,9 @@ Y r lkng gd! Rll!
 <?php
 /**
  * @return StringValue
+ * @param string|StringValue $pattern
  */
-public function replacePatternCallback(string $pattern, callable $callback);
+public function replacePatternCallback($pattern, callable $callback): StringValue;
 ```
 
 #### Examples
@@ -2073,8 +2169,9 @@ Yai ori laaking gaad! Riolli!
 <?php
 /**
  * @return StringValue
+ * @param string|StringValue $postfix
  */
-public function truncate(int $length, string $postfix = '...');
+public function truncate(int $length, $postfix = '...'): StringValue;
 ```
 
 #### Examples
@@ -2102,7 +2199,7 @@ This one i+
 /**
  * @return StringValue
  */
-public function substring(int $start, ?int $length = null);
+public function substring(int $start, ?int $length = null): StringValue;
 ```
 
 ### StringValue::postfix
@@ -2111,8 +2208,9 @@ public function substring(int $start, ?int $length = null);
 <?php
 /**
  * @return StringValue
+ * @param string|StringValue $other
  */
-public function postfix(StringValue $other);
+public function postfix($other): StringValue;
 ```
 
 ### StringValue::prefix
@@ -2121,8 +2219,9 @@ public function postfix(StringValue $other);
 <?php
 /**
  * @return StringValue
+ * @param string|StringValue $other
  */
-public function prefix(StringValue $other);
+public function prefix($other): StringValue;
 ```
 
 ### StringValue::length
@@ -2137,16 +2236,20 @@ public function length(): int;
 
 ```php
 <?php
-
-public function position(string $needle): ?int;
+/**
+ * @param string|StringValue $needle
+ */
+public function position($needle): ?int;
 ```
 
 ### StringValue::positionLast
 
 ```php
 <?php
-
-public function positionLast(string $needle): ?int;
+/**
+ * @param string|StringValue $needle
+ */
+public function positionLast($needle): ?int;
 ```
 
 ### StringValue::matchAllPatterns
@@ -2154,9 +2257,10 @@ public function positionLast(string $needle): ?int;
 ```php
 <?php
 /**
- * @return ArrayValue
+ * @param string|StringValue $pattern
+ * @return ArrayValue<string[][]>
  */
-public function matchAllPatterns(string $pattern);
+public function matchAllPatterns($pattern): ArrayValue;
 ```
 
 ### StringValue::matchPatterns
@@ -2164,17 +2268,40 @@ public function matchAllPatterns(string $pattern);
 ```php
 <?php
 /**
+ * @param string|StringValue $pattern
  * @return StringsArray
  */
-public function matchPatterns(string $pattern);
+public function matchPatterns($pattern): StringsArray;
 ```
 
 ### StringValue::isMatching
 
 ```php
 <?php
+/**
+ * @param string|StringValue $pattern
+ */
+public function isMatching($pattern): bool;
+```
+
+### StringValue::startsWith
+
+```php
+<?php
+/**
+ * @param string|StringValue $pattern
+ */
+public function startsWith($pattern): bool;
+```
 
-public function isMatching(string $pattern): bool;
+### StringValue::endsWith
+
+```php
+<?php
+/**
+ * @param string|StringValue $pattern
+ */
+public function endsWith($pattern): bool;
 ```
 
 ### StringValue::splitByPattern
@@ -2183,8 +2310,9 @@ public function isMatching(string $pattern): bool;
 <?php
 /**
  * @return StringsArray
+ * @param string|StringValue $pattern
  */
-public function splitByPattern(string $pattern);
+public function splitByPattern($pattern): StringsArray;
 ```
 
 ### StringValue::explode
@@ -2193,16 +2321,19 @@ public function splitByPattern(string $pattern);
 <?php
 /**
  * @return StringsArray
+ * @param string|StringValue $delimiter
  */
-public function explode(string $delimiter);
+public function explode($delimiter): StringsArray;
 ```
 
 ### StringValue::contains
 
 ```php
 <?php
-
-public function contains(string $substring): bool;
+/**
+ * @param string|StringValue $substring
+ */
+public function contains($substring): bool;
 ```
 
 ### StringValue::toString
@@ -2258,10 +2389,9 @@ echo PHP_EOL;
 ```php
 <?php
 /**
- * @param callable $callback function(StringValue $value): void
- * @return StringsArray
+ * @param callable(StringValue $value): void $callback
  */
-public function each(callable $callback);
+public function each(callable $callback): StringsArray;
 ```
 
 ### StringsArray::unique
@@ -2269,10 +2399,9 @@ public function each(callable $callback);
 ```php
 <?php
 /**
- * @param callable|null $comparator function(StringValue $valueA, StringValue $valueB): int{-1, 0, 1}
- * @return StringsArray
+ * @param callable(StringValue $valueA, StringValue $valueB):int | null $comparator
  */
-public function unique(?callable $comparator = null);
+public function unique(?callable $comparator = null): StringsArray;
 ```
 
 ### StringsArray::toArray
@@ -2280,30 +2409,37 @@ public function unique(?callable $comparator = null);
 ```php
 <?php
 /**
- * @return string[]
+ * @return array<int, StringValue>
  */
 public function toArray(): array;
 ```
 
-### StringsArray::filter
+### StringsArray::toNativeStrings
 
 ```php
 <?php
 /**
- * @param callable $filter function(StringValue $value): bool
- * @return StringsArray
+ * @return string[]
  */
-public function filter(callable $filter);
+public function toNativeStrings(): array;
 ```
 
-### StringsArray::filterEmpty
+### StringsArray::filter
 
 ```php
 <?php
 /**
- * @return StringsArray
+ * @param callable(StringValue $value): bool $filter
  */
-public function filterEmpty();
+public function filter(callable $filter): StringsArray;
+```
+
+### StringsArray::filterEmpty
+
+```php
+<?php
+
+public function filterEmpty(): StringsArray;
 ```
 
 ### StringsArray::map
@@ -2311,10 +2447,9 @@ public function filterEmpty();
 ```php
 <?php
 /**
- * @param callable $transformer function(StringValue $value): StringValue|string
- * @return StringsArray
+ * @param callable(StringValue $value):StringValue $transformer
  */
-public function map(callable $transformer);
+public function map(callable $transformer): StringsArray;
 ```
 
 ### StringsArray::flatMap
@@ -2322,10 +2457,9 @@ public function map(callable $transformer);
 ```php
 <?php
 /**
- * @param callable $transformer function(StringValue $value): iterable
- * @return StringsArray
+ * @param callable(StringValue $value):iterable<StringValue> $transformer
  */
-public function flatMap(callable $transformer);
+public function flatMap(callable $transformer): StringsArray;
 ```
 
 ### StringsArray::groupBy
@@ -2333,8 +2467,9 @@ public function flatMap(callable $transformer);
 ```php
 <?php
 /**
- * @param callable $reducer function(StringValue $value): string|int|bool
- * @return AssocValue AssocValue<StringsArray>
+ * @template TNewKey
+ * @param callable(StringValue $value):TNewKey $reducer
+ * @phpstan-return AssocValue<TNewKey, ArrayValue<StringValue>>
  */
 public function groupBy(callable $reducer): AssocValue;
 ```
@@ -2345,6 +2480,7 @@ public function groupBy(callable $reducer): AssocValue;
 <?php
 
 use GW\Value\StringsArray;
+use GW\Value\StringValue;
 use GW\Value\Wrap;
 
 $text = 'I would like to ask a question about the meaning of life';
@@ -2354,7 +2490,7 @@ $wordGroups = Wrap::string($text)
     ->lower()
     ->explode(' ')
     ->groupBy(function (StringValue $word) use ($stopwords): string {
-        return in_array($word, $stopwords, true) ? 'stopwords' : 'words';
+        return in_array($word->toString(), $stopwords, true) ? 'stopwords' : 'words';
     });
 
 /** @var StringsArray $stopwords */
@@ -2376,30 +2512,25 @@ words: would, like, ask, question, about, meaning, life
 ```php
 <?php
 /**
- * @param callable $comparator function(StringValue $valueA, StringValue $valueB): int{-1, 0, 1}
- * @return StringsArray
+ * @param callable(StringValue $valueA, StringValue $valueB):int $comparator
  */
-public function sort(callable $comparator);
+public function sort(callable $comparator): StringsArray;
 ```
 
 ### StringsArray::shuffle
 
 ```php
 <?php
-/**
- * @return StringsArray
- */
-public function shuffle();
+
+public function shuffle(): StringsArray;
 ```
 
 ### StringsArray::reverse
 
 ```php
 <?php
-/**
- * @return StringsArray
- */
-public function reverse();
+
+public function reverse(): StringsArray;
 ```
 
 ### StringsArray::unshift
@@ -2408,9 +2539,8 @@ public function reverse();
 <?php
 /**
  * @param StringValue|string $value
- * @return StringsArray
  */
-public function unshift($value);
+public function unshift($value): StringsArray;
 ```
 
 ### StringsArray::shift
@@ -2418,10 +2548,9 @@ public function unshift($value);
 ```php
 <?php
 /**
- * @param mixed $value
- * @return StringsArray
+ * @param StringValue|string $value
  */
-public function shift(&$value = null);
+public function shift(&$value = null): StringsArray;
 ```
 
 ### StringsArray::push
@@ -2430,9 +2559,8 @@ public function shift(&$value = null);
 <?php
 /**
  * @param StringValue|string $value
- * @return StringsArray
  */
-public function push($value);
+public function push($value): StringsArray;
 ```
 
 ### StringsArray::pop
@@ -2441,9 +2569,8 @@ public function push($value);
 <?php
 /**
  * @param mixed $value
- * @return StringsArray
  */
-public function pop(&$value = null);
+public function pop(&$value = null): StringsArray;
 ```
 
 ### StringsArray::offsetExists
@@ -2462,9 +2589,8 @@ public function offsetExists($offset): bool;
 <?php
 /**
  * @param int $offset
- * @return StringValue
  */
-public function offsetGet($offset);
+public function offsetGet($offset): StringValue;
 ```
 
 ### StringsArray::offsetSet
@@ -2475,9 +2601,9 @@ public function offsetGet($offset);
  * @param int $offset
  * @param StringValue|string $value
  * @return void
- * @throws \BadMethodCallException For immutable types.
+ * @throws BadMethodCallException For immutable types.
  */
-public function offsetSet($offset, $value);
+public function offsetSet($offset, $value): void;
 ```
 
 ### StringsArray::offsetUnset
@@ -2487,9 +2613,9 @@ public function offsetSet($offset, $value);
 /**
  * @param int $offset
  * @return void
- * @throws \BadMethodCallException For immutable types.
+ * @throws BadMethodCallException For immutable types.
  */
-public function offsetUnset($offset);
+public function offsetUnset($offset): void;
 ```
 
 ### StringsArray::join
@@ -2497,19 +2623,17 @@ public function offsetUnset($offset);
 ```php
 <?php
 /**
- * @return StringsArray
+ * @param StringsArray $other
  */
-public function join(ArrayValue $other);
+public function join(ArrayValue $other): StringsArray;
 ```
 
 ### StringsArray::slice
 
 ```php
 <?php
-/**
- * @return StringsArray
- */
-public function slice(int $offset, int $length);
+
+public function slice(int $offset, int $length): StringsArray;
 ```
 
 ### StringsArray::splice
@@ -2517,10 +2641,9 @@ public function slice(int $offset, int $length);
 ```php
 <?php
 /**
- * @param ArrayValue $replacement ArrayValue<string>|ArrayValue<StringValue>
- * @return StringsArray
+ * @param StringsArray $replacement
  */
-public function splice(int $offset, int $length, ?ArrayValue $replacement = null);
+public function splice(int $offset, int $length, ?ArrayValue $replacement = null): StringsArray;
 ```
 
 ### StringsArray::diff
@@ -2528,10 +2651,10 @@ public function splice(int $offset, int $length, ?ArrayValue $replacement = null
 ```php
 <?php
 /**
- * @param callable|null $comparator function(StringValue $valueA, StringValue $valueB): int{-1, 0, 1}
- * @return StringsArray
+ * @param StringsArray $other
+ * @param (callable(StringValue, StringValue):int)|null $comparator
  */
-public function diff(ArrayValue $other, ?callable $comparator = null);
+public function diff(ArrayValue $other, ?callable $comparator = null): StringsArray;
 ```
 
 ### StringsArray::intersect
@@ -2539,10 +2662,10 @@ public function diff(ArrayValue $other, ?callable $comparator = null);
 ```php
 <?php
 /**
- * @param callable|null $comparator function(StringValue $valueA, StringValue $valueB): int{-1, 0, 1}
- * @return StringsArray
+ * @param StringsArray $other
+ * @param (callable(StringValue $valueA, StringValue $valueB):int)|null $comparator
  */
-public function intersect(ArrayValue $other, ?callable $comparator = null);
+public function intersect(ArrayValue $other, ?callable $comparator = null): StringsArray;
 ```
 
 ### StringsArray::reduce
@@ -2550,9 +2673,10 @@ public function intersect(ArrayValue $other, ?callable $comparator = null);
 ```php
 <?php
 /**
- * @param callable $transformer function(mixed $reduced, StringValue $value): mixed
- * @param mixed $start
- * @return mixed
+ * @template TNewValue
+ * @phpstan-param callable(TNewValue, StringValue):TNewValue $transformer
+ * @phpstan-param TNewValue $start
+ * @phpstan-return TNewValue
  */
 public function reduce(callable $transformer, $start);
 ```
@@ -2572,7 +2696,7 @@ public function implode(string $glue): StringValue;
 /**
  * @return StringsArray
  */
-public function notEmpty();
+public function notEmpty(): StringsArray;
 ```
 
 ### StringsArray::first
@@ -2582,7 +2706,7 @@ public function notEmpty();
 /**
  * @return StringValue|null
  */
-public function first();
+public function first(): ?StringValue;
 ```
 
 ### StringsArray::last
@@ -2592,14 +2716,16 @@ public function first();
 /**
  * @return StringValue|null
  */
-public function last();
+public function last(): ?StringValue;
 ```
 
 ### StringsArray::find
 
 ```php
 <?php
-
+/**
+ * @param callable(StringValue $value): bool $filter
+ */
 public function find(callable $filter): ?StringValue;
 ```
 
@@ -2607,7 +2733,9 @@ public function find(callable $filter): ?StringValue;
 
 ```php
 <?php
-
+/**
+ * @param callable(StringValue $value): bool $filter
+ */
 public function findLast(callable $filter): ?StringValue;
 ```
 
@@ -2616,20 +2744,17 @@ public function findLast(callable $filter): ?StringValue;
 ```php
 <?php
 /**
- * @param callable $transformer function(string $value): string
- * @return StringsArray
+ * @param callable(string $value):(StringValue|string) $transformer
  */
-public function transform(callable $transformer);
+public function transform(callable $transformer): StringsArray;
 ```
 
 ### StringsArray::stripTags
 
 ```php
 <?php
-/**
- * @return StringsArray
- */
-public function stripTags();
+
+public function stripTags(): StringsArray;
 ```
 
 #### Examples
@@ -2646,9 +2771,18 @@ var_export($text->stripTags()->toArray());
 
 ```
 array (
-  0 => 'Story',
-  1 => 'Chapter 1',
-  2 => 'Once upon a time...',
+  0 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'Story',
+  )),
+  1 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'Chapter 1',
+  )),
+  2 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'Once upon a time...',
+  )),
 )
 ```
 
@@ -2657,9 +2791,9 @@ array (
 ```php
 <?php
 /**
- * @return StringsArray
+ * @param string|StringValue $characterMask
  */
-public function trim(string $characterMask = self::TRIM_MASK);
+public function trim($characterMask = self::TRIM_MASK): StringsArray;
 ```
 
 ### StringsArray::trimRight
@@ -2667,9 +2801,9 @@ public function trim(string $characterMask = self::TRIM_MASK);
 ```php
 <?php
 /**
- * @return StringsArray
+ * @param string|StringValue $characterMask
  */
-public function trimRight(string $characterMask = self::TRIM_MASK);
+public function trimRight($characterMask = self::TRIM_MASK): StringsArray;
 ```
 
 ### StringsArray::trimLeft
@@ -2677,19 +2811,17 @@ public function trimRight(string $characterMask = self::TRIM_MASK);
 ```php
 <?php
 /**
- * @return StringsArray
+ * @param string|StringValue $characterMask
  */
-public function trimLeft(string $characterMask = self::TRIM_MASK);
+public function trimLeft($characterMask = self::TRIM_MASK): StringsArray;
 ```
 
 ### StringsArray::lower
 
 ```php
 <?php
-/**
- * @return StringsArray
- */
-public function lower();
+
+public function lower(): StringsArray;
 ```
 
 #### Examples
@@ -2706,10 +2838,22 @@ var_export($text->lower()->toArray());
 
 ```
 array (
-  0 => 'sometimes',
-  1 => 'i',
-  2 => 'wanna',
-  3 => 'scream!',
+  0 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'sometimes',
+  )),
+  1 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'i',
+  )),
+  2 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'wanna',
+  )),
+  3 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'scream!',
+  )),
 )
 ```
 
@@ -2717,10 +2861,8 @@ array (
 
 ```php
 <?php
-/**
- * @return StringsArray
- */
-public function upper();
+
+public function upper(): StringsArray;
 ```
 
 #### Examples
@@ -2737,8 +2879,14 @@ var_export($text->upper()->toArray());
 
 ```
 array (
-  0 => 'IT`S SO QUIET',
-  1 => 'AND PEACEFUL',
+  0 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'IT`S SO QUIET',
+  )),
+  1 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'AND PEACEFUL',
+  )),
 )
 ```
 
@@ -2746,10 +2894,8 @@ array (
 
 ```php
 <?php
-/**
- * @return StringsArray
- */
-public function lowerFirst();
+
+public function lowerFirst(): StringsArray;
 ```
 
 #### Examples
@@ -2766,8 +2912,14 @@ var_export($text->lowerFirst()->toArray());
 
 ```
 array (
-  0 => 'camelCaseMethod',
-  1 => 'anotherCamel',
+  0 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'camelCaseMethod',
+  )),
+  1 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'anotherCamel',
+  )),
 )
 ```
 
@@ -2775,10 +2927,8 @@ array (
 
 ```php
 <?php
-/**
- * @return StringsArray
- */
-public function upperFirst();
+
+public function upperFirst(): StringsArray;
 ```
 
 #### Examples
@@ -2801,10 +2951,8 @@ var_export($text->upperFirst()->toString());
 
 ```php
 <?php
-/**
- * @return StringsArray
- */
-public function upperWords();
+
+public function upperWords(): StringsArray;
 ```
 
 #### Examples
@@ -2828,9 +2976,9 @@ var_export($text->upperWords()->toString());
 ```php
 <?php
 /**
- * @return StringsArray
+ * @param string|StringValue $string
  */
-public function padRight(int $length, string $string = ' ');
+public function padRight(int $length, $string = ' '): StringsArray;
 ```
 
 ### StringsArray::padLeft
@@ -2838,9 +2986,9 @@ public function padRight(int $length, string $string = ' ');
 ```php
 <?php
 /**
- * @return StringsArray
+ * @param string|StringValue $string
  */
-public function padLeft(int $length, string $string = ' ');
+public function padLeft(int $length, $string = ' '): StringsArray;
 ```
 
 #### Examples
@@ -2857,9 +3005,18 @@ var_export($text->padLeft(16, '-')->toArray());
 
 ```
 array (
-  0 => '-------------one',
-  1 => '-------------two',
-  2 => '-----------three',
+  0 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => '-------------one',
+  )),
+  1 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => '-------------two',
+  )),
+  2 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => '-----------three',
+  )),
 )
 ```
 
@@ -2868,9 +3025,9 @@ array (
 ```php
 <?php
 /**
- * @return StringsArray
+ * @param string|StringValue $string
  */
-public function padBoth(int $length, string $string = ' ');
+public function padBoth(int $length, $string = ' '): StringsArray;
 ```
 
 #### Examples
@@ -2887,9 +3044,18 @@ var_export($text->padBoth(24, '-')->toArray());
 
 ```
 array (
-  0 => '----------one-----------',
-  1 => '----------two-----------',
-  2 => '---------three----------',
+  0 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => '----------one-----------',
+  )),
+  1 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => '----------two-----------',
+  )),
+  2 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => '---------three----------',
+  )),
 )
 ```
 
@@ -2898,9 +3064,10 @@ array (
 ```php
 <?php
 /**
- * @return StringsArray
+ * @param string|StringValue $search
+ * @param string|StringValue $replace
  */
-public function replace(string $search, string $replace);
+public function replace($search, $replace): StringsArray;
 ```
 
 #### Examples
@@ -2917,20 +3084,31 @@ var_export($text->replace('.', '!!!')->toArray());
 
 ```
 array (
-  0 => 'One!!!',
-  1 => 'Two!!!',
-  2 => 'Three!!!',
+  0 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'One!!!',
+  )),
+  1 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'Two!!!',
+  )),
+  2 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'Three!!!',
+  )),
 )
 ```
 
-### StringsArray::replacePattern
+### StringsArray::replaceAll
 
 ```php
 <?php
 /**
  * @return StringsArray
+ * @param array<int,string>|ArrayValue<string> $search
+ * @param string|StringValue $replace
  */
-public function replacePattern(string $pattern, string $replacement);
+public function replaceAll($search, $replace): StringsArray;
 ```
 
 #### Examples
@@ -2940,28 +3118,37 @@ public function replacePattern(string $pattern, string $replacement);
 
 use GW\Value\Wrap;
 
-$text = Wrap::stringsArray(['Please', 'censor', 'all', 'vowels!']);
+$text = Wrap::stringsArray(['One?', 'Two!', 'Three!?']);
 
-var_export($text->replacePattern('/[aeiouy]/', '*')->toArray());
+var_export($text->replaceAll(['?', '!'], '.')->toArray());
 ```
 
 ```
 array (
-  0 => 'Pl**s*',
-  1 => 'c*ns*r',
-  2 => '*ll',
-  3 => 'v*w*ls!',
+  0 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'One.',
+  )),
+  1 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'Two.',
+  )),
+  2 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'Three..',
+  )),
 )
 ```
 
-### StringsArray::replacePatternCallback
+### StringsArray::replacePairs
 
 ```php
 <?php
 /**
  * @return StringsArray
+ * @param array<string,string>|AssocValue<string,string> $pairs
  */
-public function replacePatternCallback(string $pattern, callable $callback);
+public function replacePairs($pairs): StringsArray;
 ```
 
 #### Examples
@@ -2971,34 +3158,37 @@ public function replacePatternCallback(string $pattern, callable $callback);
 
 use GW\Value\Wrap;
 
-$text = Wrap::stringsArray(['Please', 'censor', 'all', 'vowels!']);
-
-$replacer = function (array $match): string {
-    $letter = $match[0];
-
-    return '(' . $letter . ')';
-};
+$text = Wrap::stringsArray(['One?', 'Two!', 'Three!?']);
 
-var_export($text->replacePatternCallback('/[aeiouy]/', $replacer)->toArray());
+var_export($text->replacePairs(['One' => 'Eleven', 'Two' => 'Twelve'])->toArray());
 ```
 
 ```
 array (
-  0 => 'Pl(e)(a)s(e)',
-  1 => 'c(e)ns(o)r',
-  2 => '(a)ll',
-  3 => 'v(o)w(e)ls!',
+  0 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'Eleven?',
+  )),
+  1 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'Twelve!',
+  )),
+  2 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'Three!?',
+  )),
 )
 ```
 
-### StringsArray::truncate
+### StringsArray::replacePattern
 
 ```php
 <?php
 /**
- * @return StringsArray
+ * @param string|StringValue $pattern
+ * @param string|StringValue $replacement
  */
-public function truncate(int $length, string $postfix = '...');
+public function replacePattern($pattern, $replacement): StringsArray;
 ```
 
 #### Examples
@@ -3008,56 +3198,155 @@ public function truncate(int $length, string $postfix = '...');
 
 use GW\Value\Wrap;
 
-$text = Wrap::stringsArray(['short', 'quite long', 'very very long']);
+$text = Wrap::stringsArray(['Please', 'censor', 'all', 'vowels!']);
 
-var_export($text->truncate(5, '~~')->toArray());
+var_export($text->replacePattern('/[aeiouy]/', '*')->toArray());
 ```
 
 ```
 array (
-  0 => 'short',
-  1 => 'quite~~',
-  2 => 'very ~~',
+  0 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'Pl**s*',
+  )),
+  1 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'c*ns*r',
+  )),
+  2 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => '*ll',
+  )),
+  3 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'v*w*ls!',
+  )),
 )
 ```
 
-### StringsArray::substring
+### StringsArray::replacePatternCallback
 
 ```php
 <?php
 /**
- * @return StringsArray
+ * @param string|StringValue $pattern
  */
-public function substring(int $start, ?int $length = null);
+public function replacePatternCallback($pattern, callable $callback): StringsArray;
 ```
 
-### StringsArray::postfix
+#### Examples
 
 ```php
 <?php
-/**
- * @return StringsArray
- */
-public function postfix(StringValue $other);
-```
 
-### StringsArray::prefix
+use GW\Value\Wrap;
 
-```php
-<?php
-/**
- * @return StringsArray
- */
-public function prefix(StringValue $other);
-```
+$text = Wrap::stringsArray(['Please', 'censor', 'all', 'vowels!']);
 
-### StringsArray::toArrayValue
+$replacer = function (array $match): string {
+    $letter = $match[0];
 
-```php
-<?php
-/**
- * @return ArrayValue ArrayValue<StringValue>
- */
+    return '(' . $letter . ')';
+};
+
+var_export($text->replacePatternCallback('/[aeiouy]/', $replacer)->toArray());
+```
+
+```
+array (
+  0 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'Pl(e)(a)s(e)',
+  )),
+  1 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'c(e)ns(o)r',
+  )),
+  2 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => '(a)ll',
+  )),
+  3 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'v(o)w(e)ls!',
+  )),
+)
+```
+
+### StringsArray::truncate
+
+```php
+<?php
+/**
+ * @param string|StringValue $postfix
+ */
+public function truncate(int $length, $postfix = '...'): StringsArray;
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+$text = Wrap::stringsArray(['short', 'quite long', 'very very long']);
+
+var_export($text->truncate(5, '~~')->toArray());
+```
+
+```
+array (
+  0 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'short',
+  )),
+  1 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'quite~~',
+  )),
+  2 => 
+  GW\Value\PlainString::__set_state(array(
+     'value' => 'very ~~',
+  )),
+)
+```
+
+### StringsArray::substring
+
+```php
+<?php
+
+public function substring(int $start, ?int $length = null): StringsArray;
+```
+
+### StringsArray::postfix
+
+```php
+<?php
+/**
+ * @param string|StringValue $other
+ */
+public function postfix($other): StringsArray;
+```
+
+### StringsArray::prefix
+
+```php
+<?php
+/**
+ * @param string|StringValue $other
+ */
+public function prefix($other): StringsArray;
+```
+
+### StringsArray::toArrayValue
+
+```php
+<?php
+/**
+ * @return ArrayValue<StringValue>
+ */
 public function toArrayValue(): ArrayValue;
 ```
 
@@ -3126,7 +3415,7 @@ array (
 ```php
 <?php
 /**
- * @return AssocValue AssocValue<string, StringValue>
+ * @return AssocValue<int, StringValue>
  */
 public function toAssocValue(): AssocValue;
 ```
@@ -3146,7 +3435,7 @@ var_export(
         ->map(function (StringValue $person): string {
             return $person->toString();
         })
-        ->mapKeys(function (string $oldKey, string $person): string {
+        ->mapKeys(function (int $oldKey, string $person): string {
             return $person;
         })
         ->toAssocArray()
@@ -3168,9 +3457,9 @@ array (
 ```php
 <?php
 /**
- * @return ArrayValue
+ * @phpstan-return ArrayValue<array<int, TValue>>
  */
-public function chunk(int $size);
+public function chunk(int $size): ArrayValue;
 ```
 
 ### StringsArray::toStringsArray
@@ -3181,6 +3470,14 @@ public function chunk(int $size);
 public function toStringsArray(): StringsArray;
 ```
 
+### StringsArray::toNumbersArray
+
+```php
+<?php
+
+public function toNumbersArray(): NumbersArray;
+```
+
 ### StringsArray::isEmpty
 
 ```php
@@ -3194,7 +3491,7 @@ public function isEmpty(): bool;
 ```php
 <?php
 /**
- * @param mixed $element
+ * @phpstan-param TValue $element
  */
 public function hasElement($element): bool;
 ```
@@ -3204,7 +3501,7 @@ public function hasElement($element): bool;
 ```php
 <?php
 /**
- * @param callable $filter function(mixed $value): bool
+ * @param callable(TValue $value):bool $filter
  */
 public function any(callable $filter): bool;
 ```
@@ -3214,7 +3511,7 @@ public function any(callable $filter): bool;
 ```php
 <?php
 /**
- * @param callable $filter function(mixed $value): bool
+ * @param callable(TValue $value):bool $filter
  */
 public function every(callable $filter): bool;
 ```
@@ -3242,16 +3539,20 @@ public function length(): int;
 
 ```php
 <?php
-
-public function position(string $needle): ?int;
+/**
+ * @param string|StringValue $needle
+ */
+public function position($needle): ?int;
 ```
 
 ### StringsArray::positionLast
 
 ```php
 <?php
-
-public function positionLast(string $needle): ?int;
+/**
+ * @param string|StringValue $needle
+ */
+public function positionLast($needle): ?int;
 ```
 
 ### StringsArray::matchAllPatterns
@@ -3259,9 +3560,10 @@ public function positionLast(string $needle): ?int;
 ```php
 <?php
 /**
- * @return ArrayValue
+ * @param string|StringValue $pattern
+ * @return ArrayValue<string[][]>
  */
-public function matchAllPatterns(string $pattern);
+public function matchAllPatterns($pattern): ArrayValue;
 ```
 
 ### StringsArray::matchPatterns
@@ -3269,17 +3571,40 @@ public function matchAllPatterns(string $pattern);
 ```php
 <?php
 /**
+ * @param string|StringValue $pattern
  * @return StringsArray
  */
-public function matchPatterns(string $pattern);
+public function matchPatterns($pattern): StringsArray;
 ```
 
 ### StringsArray::isMatching
 
 ```php
 <?php
+/**
+ * @param string|StringValue $pattern
+ */
+public function isMatching($pattern): bool;
+```
+
+### StringsArray::startsWith
+
+```php
+<?php
+/**
+ * @param string|StringValue $pattern
+ */
+public function startsWith($pattern): bool;
+```
 
-public function isMatching(string $pattern): bool;
+### StringsArray::endsWith
+
+```php
+<?php
+/**
+ * @param string|StringValue $pattern
+ */
+public function endsWith($pattern): bool;
 ```
 
 ### StringsArray::splitByPattern
@@ -3288,8 +3613,9 @@ public function isMatching(string $pattern): bool;
 <?php
 /**
  * @return StringsArray
+ * @param string|StringValue $pattern
  */
-public function splitByPattern(string $pattern);
+public function splitByPattern($pattern): StringsArray;
 ```
 
 ### StringsArray::explode
@@ -3298,16 +3624,19 @@ public function splitByPattern(string $pattern);
 <?php
 /**
  * @return StringsArray
+ * @param string|StringValue $delimiter
  */
-public function explode(string $delimiter);
+public function explode($delimiter): StringsArray;
 ```
 
 ### StringsArray::contains
 
 ```php
 <?php
-
-public function contains(string $substring): bool;
+/**
+ * @param string|StringValue $substring
+ */
+public function contains($substring): bool;
 ```
 
 ### StringsArray::toString
@@ -3334,10 +3663,10 @@ public function __toString(): string;
 ```php
 <?php
 /**
- * @param callable $callback function(mixed $value): void
- * @return IterableValue
+ * @phpstan-param callable(TValue $value):void $callback
+ * @phpstan-return IterableValue<TKey, TValue>
  */
-public function each(callable $callback);
+public function each(callable $callback): IterableValue;
 ```
 
 #### Examples
@@ -3362,10 +3691,10 @@ abc
 ```php
 <?php
 /**
- * @param callable $filter function(mixed $value): bool { ... }
- * @return IterableValue
+ * @phpstan-param callable(TValue $value):bool $filter
+ * @phpstan-return IterableValue<TKey, TValue>
  */
-public function filter(callable $filter);
+public function filter(callable $filter): IterableValue;
 ```
 
 #### Examples
@@ -3375,7 +3704,7 @@ public function filter(callable $filter);
 
 use GW\Value\Wrap;
 
-$range = function (int $start, int $end) {
+$range = static function (int $start, int $end): iterable {
     for ($i = $start; $i <= $end; $i++) {
         yield $i;
     }
@@ -3401,9 +3730,9 @@ array (
 ```php
 <?php
 /**
- * @return IterableValue
+ * @phpstan-return IterableValue<TKey, TValue>
  */
-public function filterEmpty();
+public function filterEmpty(): IterableValue;
 ```
 
 #### Examples
@@ -3432,10 +3761,11 @@ array (
 ```php
 <?php
 /**
- * @param callable $transformer function(mixed $value): mixed { ... }
- * @return IterableValue
+ * @template TNewValue
+ * @phpstan-param callable(TValue $value): TNewValue $transformer
+ * @phpstan-return IterableValue<TKey, TNewValue>
  */
-public function map(callable $transformer);
+public function map(callable $transformer): IterableValue;
 ```
 
 #### Examples
@@ -3466,10 +3796,11 @@ array (
 ```php
 <?php
 /**
- * @param callable $transformer function(mixed $value): iterable { ... }
- * @return IterableValue
+ * @phpstan-template TNewValue
+ * @phpstan-param callable(TValue $value): iterable<TNewValue> $transformer
+ * @phpstan-return IterableValue<TKey, TNewValue>
  */
-public function flatMap(callable $transformer);
+public function flatMap(callable $transformer): IterableValue;
 ```
 
 ### IterableValue::join
@@ -3477,9 +3808,10 @@ public function flatMap(callable $transformer);
 ```php
 <?php
 /**
- * @return IterableValue
+ * @phpstan-param iterable<TKey, TValue> $other
+ * @phpstan-return IterableValue<TKey, TValue>
  */
-public function join(iterable $other);
+public function join(iterable $other): IterableValue;
 ```
 
 #### Examples
@@ -3489,7 +3821,7 @@ public function join(iterable $other);
 
 use GW\Value\Wrap;
 
-$range = function (int $start, int $end) {
+$range = function (int $start, int $end): iterable {
     for ($i = $start; $i <= $end; $i++) {
         yield $i;
     }
@@ -3521,9 +3853,9 @@ array (
 ```php
 <?php
 /**
- * @return IterableValue
+ * @phpstan-return IterableValue<TKey, TValue>
  */
-public function slice(int $offset, int $length);
+public function slice(int $offset, int $length): IterableValue;
 ```
 
 #### Examples
@@ -3533,7 +3865,7 @@ public function slice(int $offset, int $length);
 
 use GW\Value\Wrap;
 
-$range = function (int $start, int $end) {
+$range = function (int $start, int $end): iterable {
     for ($i = $start; $i <= $end; $i++) {
         yield $i;
     }
@@ -3578,10 +3910,10 @@ array (
 ```php
 <?php
 /**
- * @param callable|null $comparator function(mixed $valueA, mixed $valueB): int{-1, 0, 1}
- * @return IterableValue
+ * @phpstan-param callable(TValue $valueA, TValue $valueB):int | null $comparator
+ * @phpstan-return IterableValue<TKey, TValue>
  */
-public function unique(?callable $comparator = null);
+public function unique(?callable $comparator = null): IterableValue;
 ```
 
 ### IterableValue::reduce
@@ -3589,9 +3921,10 @@ public function unique(?callable $comparator = null);
 ```php
 <?php
 /**
- * @param callable $transformer function(mixed $reduced, mixed $value): mixed
- * @param mixed $start
- * @return mixed
+ * @template TNewValue
+ * @phpstan-param callable(TNewValue $reduced, TValue $value): TNewValue $transformer
+ * @phpstan-param TNewValue $start
+ * @phpstan-return TNewValue
  */
 public function reduce(callable $transformer, $start);
 ```
@@ -3630,9 +3963,9 @@ Prices:  €10,- €20,- €50,- €120,-
 ```php
 <?php
 /**
- * @return IterableValue
+ * @phpstan-return IterableValue<TKey, TValue>
  */
-public function notEmpty();
+public function notEmpty(): IterableValue;
 ```
 
 ### IterableValue::unshift
@@ -3640,10 +3973,10 @@ public function notEmpty();
 ```php
 <?php
 /**
- * @param mixed $value
- * @return IterableValue
+ * @phpstan-param TValue $value
+ * @phpstan-return IterableValue<TKey, TValue>
  */
-public function unshift($value);
+public function unshift($value): IterableValue;
 ```
 
 ### IterableValue::push
@@ -3651,10 +3984,10 @@ public function unshift($value);
 ```php
 <?php
 /**
- * @param mixed $value
- * @return IterableValue
+ * @phpstan-param TValue $value
+ * @phpstan-return IterableValue<TKey, TValue>
  */
-public function push($value);
+public function push($value): IterableValue;
 ```
 
 ### IterableValue::diff
@@ -3662,10 +3995,11 @@ public function push($value);
 ```php
 <?php
 /**
- * @param callable|null $comparator function(mixed $valueA, mixed $valueB): int{-1, 0, 1}
- * @return IterableValue
+ * @phpstan-param ArrayValue<TValue> $other
+ * @phpstan-param callable(TValue $valueA, TValue $valueB):int | null $comparator
+ * @phpstan-return IterableValue<TKey, TValue>
  */
-public function diff(ArrayValue $other, ?callable $comparator = null);
+public function diff(ArrayValue $other, ?callable $comparator = null): IterableValue;
 ```
 
 ### IterableValue::intersect
@@ -3673,10 +4007,11 @@ public function diff(ArrayValue $other, ?callable $comparator = null);
 ```php
 <?php
 /**
- * @param callable|null $comparator function(mixed $valueA, mixed $valueB): int{-1, 0, 1}
- * @return IterableValue
+ * @phpstan-param ArrayValue<TValue> $other
+ * @phpstan-param callable(TValue $valueA, TValue $valueB):int | null $comparator
+ * @phpstan-return IterableValue<TKey, TValue>
  */
-public function intersect(ArrayValue $other, ?callable $comparator = null);
+public function intersect(ArrayValue $other, ?callable $comparator = null): IterableValue;
 ```
 
 ### IterableValue::first
@@ -3684,7 +4019,7 @@ public function intersect(ArrayValue $other, ?callable $comparator = null);
 ```php
 <?php
 /**
- * @return mixed
+ * @phpstan-return ?TValue
  */
 public function first();
 ```
@@ -3696,7 +4031,7 @@ public function first();
 
 use GW\Value\Wrap;
 
-$range = function (int $start, int $end) {
+$range = function (int $start, int $end): iterable {
     for ($i = $start; $i <= $end; $i++) {
         yield $i;
     }
@@ -3716,7 +4051,7 @@ first: 1
 ```php
 <?php
 /**
- * @return mixed
+ * @phpstan-return ?TValue
  */
 public function last();
 ```
@@ -3725,7 +4060,9 @@ public function last();
 
 ```php
 <?php
-
+/**
+ * @phpstan-return ArrayValue<TValue>
+ */
 public function toArrayValue(): ArrayValue;
 ```
 
@@ -3734,27 +4071,19 @@ public function toArrayValue(): ArrayValue;
 ```php
 <?php
 /**
- * @return mixed[]
+ * @phpstan-return TValue[]
  */
 public function toArray(): array;
 ```
 
-### IterableValue::use
-
-```php
-<?php
-
-public function use(iterable $iterable): IterableValue;
-```
-
 ### IterableValue::chunk
 
 ```php
 <?php
 /**
- * @return IterableValue
+ * @phpstan-return IterableValue<int, array<int, TValue>>
  */
-public function chunk(int $size);
+public function chunk(int $size): IterableValue;
 ```
 
 #### Examples
@@ -3802,9 +4131,9 @@ array (
 ```php
 <?php
 /**
- * @return IterableValue
+ * @phpstan-return IterableValue<TKey, TValue>
  */
-public function flatten();
+public function flatten(): IterableValue;
 ```
 
 ### IterableValue::any
@@ -3812,7 +4141,7 @@ public function flatten();
 ```php
 <?php
 /**
- * @param callable $filter function(mixed $value): bool
+ * @param callable(TValue $value):bool $filter
  */
 public function any(callable $filter): bool;
 ```
@@ -3822,7 +4151,7 @@ public function any(callable $filter): bool;
 ```php
 <?php
 /**
- * @param callable $filter function(mixed $value): bool
+ * @param callable(TValue $value):bool $filter
  */
 public function every(callable $filter): bool;
 ```
@@ -3832,8 +4161,8 @@ public function every(callable $filter): bool;
 ```php
 <?php
 /**
- * @param callable $filter function(mixed $value): bool
- * @return mixed
+ * @param callable(TValue $value):bool $filter
+ * @phpstan-return ?TValue
  */
 public function find(callable $filter);
 ```
@@ -3843,8 +4172,8 @@ public function find(callable $filter);
 ```php
 <?php
 /**
- * @param callable $filter function(mixed $value): bool
- * @return mixed
+ * @param callable(TValue $value):bool $filter
+ * @phpstan-return ?TValue
  */
 public function findLast(callable $filter);
 ```
@@ -3853,4 +4182,837 @@ public function findLast(callable $filter);
 
 *(definition not available)*
 
+## NumberValue
+
+### NumberValue::compare
+
+```php
+<?php
+/**
+ * @param int|float|numeric-string|Numberable $other
+ * @return int {-1, 0, 1}
+ */
+public function compare($other): int;
+```
+
+### NumberValue::equals
+
+```php
+<?php
+/**
+ * @param int|float|numeric-string|Numberable $other
+ */
+public function equals($other): bool;
+```
+
+### NumberValue::add
+
+```php
+<?php
+/**
+ * @param int|float|numeric-string|Numberable $other
+ */
+public function add($other): NumberValue;
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Numberable\JustFloat;
+use GW\Value\Numberable\Sum;
+use GW\Value\Numberable\WrapNumbers;
+use GW\Value\Wrap;
+
+$number = Wrap::number(100);
+
+echo "100 + 50 = ";
+echo $number->add(50)->toNumber();
+echo "\n";
+
+echo "100 + 11.22 = ";
+echo $number->add(new JustFloat(11.22))->toNumber();
+echo "\n";
+
+echo "100 + (10 + 20 + 30) = ";
+echo $number->add(new Sum(new WrapNumbers(10, 20, 30)))->toNumber();
+echo "\n";
+```
+
+```
+100 + 50 = 150
+100 + 11.22 = 111.22
+100 + (10 + 20 + 30) = 160
+```
+
+### NumberValue::subtract
+
+```php
+<?php
+/**
+ * @param int|float|numeric-string|Numberable $other
+ */
+public function subtract($other): NumberValue;
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Numberable\JustFloat;
+use GW\Value\Numberable\Sum;
+use GW\Value\Numberable\WrapNumbers;
+use GW\Value\Wrap;
+
+$number = Wrap::number(100);
+
+echo "100 - 50 = ";
+echo $number->subtract(50)->toNumber();
+echo "\n";
+
+echo "100 - 11.22 = ";
+echo $number->subtract(new JustFloat(11.11))->toNumber();
+echo "\n";
+
+echo "100 - (10 + 20 + 30) = ";
+echo $number->subtract(new Sum(new WrapNumbers(10, 20, 30)))->toNumber();
+echo "\n";
+```
+
+```
+100 - 50 = 50
+100 - 11.22 = 88.89
+100 - (10 + 20 + 30) = 40
+```
+
+### NumberValue::multiply
+
+```php
+<?php
+/**
+ * @param int|float|numeric-string|Numberable $other
+ */
+public function multiply($other): NumberValue;
+```
+
+### NumberValue::divide
+
+```php
+<?php
+/**
+ * @param int|float|numeric-string|Numberable $other
+ */
+public function divide($other): NumberValue;
+```
+
+### NumberValue::abs
+
+```php
+<?php
+
+public function abs(): NumberValue;
+```
+
+### NumberValue::modulo
+
+```php
+<?php
+/**
+ * @param int|float|numeric-string|Numberable $divider
+ */
+public function modulo($divider): NumberValue;
+```
+
+### NumberValue::round
+
+```php
+<?php
+
+public function round(int $precision = 0, ?int $roundMode = null): NumberValue;
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+echo "round(22.55, 1) = ";
+echo Wrap::number(22.55)->round(1)->toNumber();
+echo "\n";
+```
+
+```
+round(22.55, 1) = 22.6
+```
+
+### NumberValue::floor
+
+```php
+<?php
+
+public function floor(): NumberValue;
+```
+
+### NumberValue::ceil
+
+```php
+<?php
+
+public function ceil(): NumberValue;
+```
+
+### NumberValue::calculate
+
+```php
+<?php
+/** @param callable(Numberable):Numberable $formula */
+public function calculate(callable $formula): NumberValue;
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Numberable;
+use GW\Value\Numberable\JustInteger;
+use GW\Value\Numberable\Math;
+use GW\Value\Numberable\Multiply;
+use GW\Value\Wrap;
+
+$number = Wrap::number(100);
+
+echo "100 * 12 = ";
+echo $number
+    ->calculate(fn (Numberable $number): Numberable => new Multiply($number, new JustInteger(12)))
+    ->toNumber();
+echo "\n";
+
+echo "cos(100) = ";
+echo $number->calculate(Math::cos())->toNumber();
+echo "\n";
+
+echo "√100 = ";
+echo $number->calculate(Math::sqrt())->toNumber();
+echo "\n";
+```
+
+```
+100 * 12 = 1200
+cos(100) = 0.86231887228768
+√100 = 10
+```
+
+### NumberValue::isEmpty
+
+```php
+<?php
+/** @return bool true when 0 or 0.0, false otherwise */
+public function isEmpty(): bool;
+```
+
+### NumberValue::format
+
+```php
+<?php
+
+public function format(int $decimals = 0, string $separator = '.' , string $thousandsSeparator = ','): StringValue;
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+$number = Wrap::number(1000.111111111);
+
+echo $number->format(2)->toString();
+echo "\n";
+
+echo $number->format(3, '.', ' ')->toString();
+echo "\n";
+```
+
+```
+1,000.11
+1 000.111
+```
+
+### NumberValue::toStringValue
+
+```php
+<?php
+
+public function toStringValue(): StringValue;
+```
+
+### NumberValue::toInteger
+
+```php
+<?php
+
+public function toInteger(): int;
+```
+
+### NumberValue::toFloat
+
+```php
+<?php
+
+public function toFloat(): float;
+```
+
+### NumberValue::__toString
+
+```php
+<?php
+
+public function __toString(): string;
+```
+
+### NumberValue::toNumber
+
+```php
+<?php
+/**
+ * @return int|float
+ */
+public function toNumber();
+```
+
+
+## NumbersArray
+
+### NumbersArray::sum
+
+```php
+<?php
+
+public function sum(): NumberValue;
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+$numbers = Wrap::numbersArray([1, 2.5, 5, 10]);
+
+echo "1 + 2.5 + 5 + 10 = ";
+echo $numbers->sum()->toNumber();
+echo "\n";
+```
+
+```
+1 + 2.5 + 5 + 10 = 18.5
+```
+
+### NumbersArray::average
+
+```php
+<?php
+
+public function average(): NumberValue;
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+$numbers = Wrap::numbersArray([1, 3, 5, 10]);
+
+echo "avg(1, 3, 5, 10) = ";
+echo $numbers->average()->toNumber();
+echo "\n";
+```
+
+```
+avg(1, 3, 5, 10) = 4.75
+```
+
+### NumbersArray::min
+
+```php
+<?php
+
+public function min(): NumberValue;
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+$numbers = Wrap::numbersArray([100, 10, 50, 80]);
+
+echo "min(100, 10, 50, 80) = ";
+echo $numbers->min()->toNumber();
+echo "\n";
+```
+
+```
+min(100, 10, 50, 80) = 10
+```
+
+### NumbersArray::max
+
+```php
+<?php
+
+public function max(): NumberValue;
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\Wrap;
+
+$numbers = Wrap::numbersArray([100, 10, 50, 80]);
+
+echo "max(100, 10, 50, 80) = ";
+echo $numbers->max()->toNumber();
+echo "\n";
+```
+
+```
+max(100, 10, 50, 80) = 100
+```
+
+### NumbersArray::each
+
+```php
+<?php
+/**
+ * @param callable(NumberValue):void $callback
+ */
+public function each(callable $callback): NumbersArray;
+```
+
+### NumbersArray::unique
+
+```php
+<?php
+/**
+ * @param (callable(NumberValue $valueA, NumberValue $valueB):int)|null $comparator
+ */
+public function unique(?callable $comparator = null): NumbersArray;
+```
+
+### NumbersArray::toArray
+
+```php
+<?php
+/** @return NumberValue[] */
+public function toArray(): array;
+```
+
+### NumbersArray::toNativeNumbers
+
+```php
+<?php
+/** @return array<int|float> */
+public function toNativeNumbers(): array;
+```
+
+### NumbersArray::filter
+
+```php
+<?php
+/**
+ * @param callable(NumberValue):bool $filter
+ */
+public function filter(callable $filter): NumbersArray;
+```
+
+### NumbersArray::filterEmpty
+
+```php
+<?php
+
+public function filterEmpty(): NumbersArray;
+```
+
+### NumbersArray::map
+
+```php
+<?php
+/**
+ * @template TNewValue
+ * @param callable(NumberValue):TNewValue $transformer
+ * @return ArrayValue<TNewValue>
+ */
+public function map(callable $transformer): ArrayValue;
+```
+
+### NumbersArray::flatMap
+
+```php
+<?php
+/**
+ * @template TNewValue
+ * @param callable(NumberValue):iterable<TNewValue> $transformer
+ * @return ArrayValue<TNewValue>
+ */
+public function flatMap(callable $transformer): ArrayValue;
+```
+
+### NumbersArray::groupBy
+
+```php
+<?php
+/**
+ * @template TNewKey
+ * @param callable(NumberValue):TNewKey $reducer
+ * @return AssocValue<TNewKey, ArrayValue<NumberValue>>
+ */
+public function groupBy(callable $reducer): AssocValue;
+```
+
+### NumbersArray::sort
+
+```php
+<?php
+
+public function sort(callable $comparator): NumbersArray;
+```
+
+### NumbersArray::shuffle
+
+```php
+<?php
+
+public function shuffle(): NumbersArray;
+```
+
+### NumbersArray::reverse
+
+```php
+<?php
+
+public function reverse(): NumbersArray;
+```
+
+### NumbersArray::unshift
+
+```php
+<?php
+/**
+ * @param NumberValue $value
+ */
+public function unshift($value): NumbersArray;
+```
+
+### NumbersArray::shift
+
+```php
+<?php
+/**
+ * @param NumberValue|null $value
+ */
+public function shift(&$value = null): NumbersArray;
+```
+
+### NumbersArray::push
+
+```php
+<?php
+/**
+ * @param NumberValue $value
+ */
+public function push($value): NumbersArray;
+```
+
+### NumbersArray::pop
+
+```php
+<?php
+/**
+ * @param NumberValue|null $value
+ */
+public function pop(&$value = null): NumbersArray;
+```
+
+### NumbersArray::offsetExists
+
+```php
+<?php
+
+public function offsetExists($offset): bool;
+```
+
+### NumbersArray::offsetGet
+
+```php
+<?php
+
+public function offsetGet($offset): NumberValue;
+```
+
+### NumbersArray::offsetSet
+
+```php
+<?php
+
+public function offsetSet($offset, $value): void;
+```
+
+### NumbersArray::offsetUnset
+
+```php
+<?php
+
+public function offsetUnset($offset): void;
+```
+
+### NumbersArray::join
+
+```php
+<?php
+/**
+ * @param ArrayValue<NumberValue> $other
+ */
+public function join(ArrayValue $other): NumbersArray;
+```
+
+### NumbersArray::slice
+
+```php
+<?php
+
+public function slice(int $offset, int $length): NumbersArray;
+```
+
+### NumbersArray::splice
+
+```php
+<?php
+/**
+ * @param ArrayValue<NumberValue>|null $replacement
+ */
+public function splice(int $offset, int $length, ?ArrayValue $replacement = null): NumbersArray;
+```
+
+### NumbersArray::diff
+
+```php
+<?php
+/**
+ * @param ArrayValue<NumberValue> $other
+ * @param (callable(NumberValue,NumberValue):int)|null $comparator
+ */
+public function diff(ArrayValue $other, ?callable $comparator = null): NumbersArray;
+```
+
+### NumbersArray::intersect
+
+```php
+<?php
+/**
+ * @param ArrayValue<NumberValue> $other
+ * @param (callable(NumberValue,NumberValue):int)|null $comparator
+ */
+public function intersect(ArrayValue $other, ?callable $comparator = null): NumbersArray;
+```
+
+### NumbersArray::reduce
+
+```php
+<?php
+/**
+ * @template TNewValue
+ * @param callable(TNewValue, NumberValue):TNewValue $transformer
+ * @param TNewValue $start
+ * @return TNewValue
+ */
+public function reduce(callable $transformer, $start);
+```
+
+### NumbersArray::reduceNumber
+
+```php
+<?php
+/**
+ * @param callable(NumberValue $reduced, NumberValue $item):NumberValue $transformer
+ * @param int|float|numeric-string|Numberable $start
+ */
+public function reduceNumber(callable $transformer, $start): NumberValue;
+```
+
+#### Examples
+
+```php
+<?php
+
+use GW\Value\NumberValue;
+use GW\Value\Wrap;
+
+$numbers = Wrap::numbersArray([1, 2, 3, 4, 5]);
+
+echo "5! = ";
+echo $numbers
+    ->reduceNumber(
+        fn (NumberValue $factorial, NumberValue $next): NumberValue => $factorial->multiply($next),
+        1
+    )
+    ->toNumber();
+echo "\n";
+```
+
+```
+5! = 120
+```
+
+### NumbersArray::implode
+
+```php
+<?php
+
+public function implode(string $glue): StringValue;
+```
+
+### NumbersArray::notEmpty
+
+```php
+<?php
+
+public function notEmpty(): NumbersArray;
+```
+
+### NumbersArray::toAssocValue
+
+```php
+<?php
+/**
+ * @return AssocValue<int, NumberValue>
+ */
+public function toAssocValue(): AssocValue;
+```
+
+### NumbersArray::toStringsArray
+
+```php
+<?php
+
+public function toStringsArray(): StringsArray;
+```
+
+### NumbersArray::first
+
+```php
+<?php
+
+public function first(): ?NumberValue;
+```
+
+### NumbersArray::last
+
+```php
+<?php
+
+public function last(): ?NumberValue;
+```
+
+### NumbersArray::find
+
+```php
+<?php
+/**
+ * @param callable(NumberValue):bool $filter
+ */
+public function find(callable $filter): ?NumberValue;
+```
+
+### NumbersArray::findLast
+
+```php
+<?php
+/**
+ * @param callable(NumberValue):bool $filter
+ */
+public function findLast(callable $filter): ?NumberValue;
+```
+
+### NumbersArray::hasElement
+
+```php
+<?php
+/**
+ * @param NumberValue $element
+ */
+public function hasElement($element): bool;
+```
+
+### NumbersArray::any
+
+```php
+<?php
+/**
+ * @param callable(NumberValue):bool $filter
+ */
+public function any(callable $filter): bool;
+```
+
+### NumbersArray::every
+
+```php
+<?php
+/**
+ * @param callable(NumberValue):bool $filter
+ */
+public function every(callable $filter): bool;
+```
+
+### NumbersArray::chunk
+
+```php
+<?php
+/**
+ * @phpstan-return ArrayValue<array<int, TValue>>
+ */
+public function chunk(int $size): ArrayValue;
+```
+
+### NumbersArray::toNumbersArray
+
+```php
+<?php
+
+public function toNumbersArray(): NumbersArray;
+```
+
+### NumbersArray::isEmpty
+
+```php
+<?php
+
+public function isEmpty(): bool;
+```
+
+### NumbersArray::count
+
+```php
+<?php
+
+public function count(): int;
+```
+
+### NumbersArray::getIterator
+
+*(definition not available)*
+
 
diff --git a/examples/ReadmeWriter.php b/examples/ReadmeWriter.php
index a02edca..0dfbe38 100644
--- a/examples/ReadmeWriter.php
+++ b/examples/ReadmeWriter.php
@@ -2,7 +2,6 @@
 
 namespace doc\GW\Value;
 
-use GW\Value\Collection;
 use GW\Value\StringValue;
 use GW\Value\Wrap;
 use ReflectionClass;
@@ -92,7 +91,7 @@ private function methodDeclaration(\ReflectionMethod $method): StringValue
         }
 
         return $this->getFileLines(
-            $method->getFileName(),
+            (string)$method->getFileName(),
             $method->getStartLine() ?: 0,
             $method->getEndLine() ?: 0
         );
diff --git a/examples/example/NumberValue-add.php b/examples/example/NumberValue-add.php
new file mode 100644
index 0000000..c5a5c77
--- /dev/null
+++ b/examples/example/NumberValue-add.php
@@ -0,0 +1,20 @@
+<?php
+
+use GW\Value\Numberable\JustFloat;
+use GW\Value\Numberable\Sum;
+use GW\Value\Numberable\WrapNumbers;
+use GW\Value\Wrap;
+
+$number = Wrap::number(100);
+
+echo "100 + 50 = ";
+echo $number->add(50)->toNumber();
+echo "\n";
+
+echo "100 + 11.22 = ";
+echo $number->add(new JustFloat(11.22))->toNumber();
+echo "\n";
+
+echo "100 + (10 + 20 + 30) = ";
+echo $number->add(new Sum(new WrapNumbers(10, 20, 30)))->toNumber();
+echo "\n";
diff --git a/examples/example/NumberValue-calculate.php b/examples/example/NumberValue-calculate.php
new file mode 100644
index 0000000..cdbf221
--- /dev/null
+++ b/examples/example/NumberValue-calculate.php
@@ -0,0 +1,23 @@
+<?php
+
+use GW\Value\Numberable;
+use GW\Value\Numberable\JustInteger;
+use GW\Value\Numberable\Math;
+use GW\Value\Numberable\Multiply;
+use GW\Value\Wrap;
+
+$number = Wrap::number(100);
+
+echo "100 * 12 = ";
+echo $number
+    ->calculate(fn (Numberable $number): Numberable => new Multiply($number, new JustInteger(12)))
+    ->toNumber();
+echo "\n";
+
+echo "cos(100) = ";
+echo $number->calculate(Math::cos())->toNumber();
+echo "\n";
+
+echo "√100 = ";
+echo $number->calculate(Math::sqrt())->toNumber();
+echo "\n";
diff --git a/examples/example/NumberValue-format.php b/examples/example/NumberValue-format.php
new file mode 100644
index 0000000..d592395
--- /dev/null
+++ b/examples/example/NumberValue-format.php
@@ -0,0 +1,11 @@
+<?php
+
+use GW\Value\Wrap;
+
+$number = Wrap::number(1000.111111111);
+
+echo $number->format(2)->toString();
+echo "\n";
+
+echo $number->format(3, '.', ' ')->toString();
+echo "\n";
diff --git a/examples/example/NumberValue-round.php b/examples/example/NumberValue-round.php
new file mode 100644
index 0000000..418e330
--- /dev/null
+++ b/examples/example/NumberValue-round.php
@@ -0,0 +1,7 @@
+<?php
+
+use GW\Value\Wrap;
+
+echo "round(22.55, 1) = ";
+echo Wrap::number(22.55)->round(1)->toNumber();
+echo "\n";
diff --git a/examples/example/NumberValue-subtract.php b/examples/example/NumberValue-subtract.php
new file mode 100644
index 0000000..833660b
--- /dev/null
+++ b/examples/example/NumberValue-subtract.php
@@ -0,0 +1,20 @@
+<?php
+
+use GW\Value\Numberable\JustFloat;
+use GW\Value\Numberable\Sum;
+use GW\Value\Numberable\WrapNumbers;
+use GW\Value\Wrap;
+
+$number = Wrap::number(100);
+
+echo "100 - 50 = ";
+echo $number->subtract(50)->toNumber();
+echo "\n";
+
+echo "100 - 11.22 = ";
+echo $number->subtract(new JustFloat(11.11))->toNumber();
+echo "\n";
+
+echo "100 - (10 + 20 + 30) = ";
+echo $number->subtract(new Sum(new WrapNumbers(10, 20, 30)))->toNumber();
+echo "\n";
diff --git a/examples/example/NumbersArray-average.php b/examples/example/NumbersArray-average.php
new file mode 100644
index 0000000..d9d0a50
--- /dev/null
+++ b/examples/example/NumbersArray-average.php
@@ -0,0 +1,9 @@
+<?php
+
+use GW\Value\Wrap;
+
+$numbers = Wrap::numbersArray([1, 3, 5, 10]);
+
+echo "avg(1, 3, 5, 10) = ";
+echo $numbers->average()->toNumber();
+echo "\n";
diff --git a/examples/example/NumbersArray-max.php b/examples/example/NumbersArray-max.php
new file mode 100644
index 0000000..668fb0f
--- /dev/null
+++ b/examples/example/NumbersArray-max.php
@@ -0,0 +1,9 @@
+<?php
+
+use GW\Value\Wrap;
+
+$numbers = Wrap::numbersArray([100, 10, 50, 80]);
+
+echo "max(100, 10, 50, 80) = ";
+echo $numbers->max()->toNumber();
+echo "\n";
diff --git a/examples/example/NumbersArray-min.php b/examples/example/NumbersArray-min.php
new file mode 100644
index 0000000..4eb29b8
--- /dev/null
+++ b/examples/example/NumbersArray-min.php
@@ -0,0 +1,9 @@
+<?php
+
+use GW\Value\Wrap;
+
+$numbers = Wrap::numbersArray([100, 10, 50, 80]);
+
+echo "min(100, 10, 50, 80) = ";
+echo $numbers->min()->toNumber();
+echo "\n";
diff --git a/examples/example/NumbersArray-reduceNumber.php b/examples/example/NumbersArray-reduceNumber.php
new file mode 100644
index 0000000..c86d3ba
--- /dev/null
+++ b/examples/example/NumbersArray-reduceNumber.php
@@ -0,0 +1,15 @@
+<?php
+
+use GW\Value\NumberValue;
+use GW\Value\Wrap;
+
+$numbers = Wrap::numbersArray([1, 2, 3, 4, 5]);
+
+echo "5! = ";
+echo $numbers
+    ->reduceNumber(
+        fn (NumberValue $factorial, NumberValue $next): NumberValue => $factorial->multiply($next),
+        1
+    )
+    ->toNumber();
+echo "\n";
diff --git a/examples/example/NumbersArray-sum.php b/examples/example/NumbersArray-sum.php
new file mode 100644
index 0000000..20efeb9
--- /dev/null
+++ b/examples/example/NumbersArray-sum.php
@@ -0,0 +1,9 @@
+<?php
+
+use GW\Value\Wrap;
+
+$numbers = Wrap::numbersArray([1, 2.5, 5, 10]);
+
+echo "1 + 2.5 + 5 + 10 = ";
+echo $numbers->sum()->toNumber();
+echo "\n";
diff --git a/make-examples.php b/make-examples.php
index d599276..109bd7a 100644
--- a/make-examples.php
+++ b/make-examples.php
@@ -4,6 +4,8 @@
 use GW\Value\ArrayValue;
 use GW\Value\AssocValue;
 use GW\Value\IterableValue;
+use GW\Value\NumbersArray;
+use GW\Value\NumberValue;
 use GW\Value\StringsArray;
 use GW\Value\StringValue;
 
@@ -15,6 +17,8 @@
     StringValue::class,
     StringsArray::class,
     IterableValue::class,
+    NumberValue::class,
+    NumbersArray::class,
 ]);
 
 file_put_contents('docs/examples.md', $markdown->toString());
diff --git a/spec/AssocArraySpec.php b/spec/AssocArraySpec.php
index f1810ad..e900097 100644
--- a/spec/AssocArraySpec.php
+++ b/spec/AssocArraySpec.php
@@ -3,10 +3,12 @@
 namespace spec\GW\Value;
 
 use GW\Value\Filters;
-use GW\Value\Wrap;
 use GW\Value\AssocArray;
 use PhpSpec\ObjectBehavior;
 
+/**
+ * @method void shouldHaveOffset(string $key)
+ */
 final class AssocArraySpec extends ObjectBehavior
 {
     function let()
@@ -408,7 +410,7 @@ function it_implements_ArrayAccess()
 
         $this->shouldImplement(\ArrayAccess::class);
 
-        $this->offsetExists('a')->shouldReturn(true);
+        $this->shouldHaveOffset('a');
         $this->offsetGet('b')->shouldReturn('item 2');
         $this['a']->shouldBe('item 1');
     }
@@ -421,4 +423,11 @@ function it_does_not_allow_mutations_trough_ArrayAccess()
         $this->shouldThrow(\BadMethodCallException::class)->during('offsetSet', ['a', 'mutated 1']);
         $this->shouldThrow(\BadMethodCallException::class)->during('offsetUnset', ['a']);
     }
+
+    public function getMatchers(): array
+    {
+        return [
+            'haveOffset' => fn (AssocArray $subject, string $key): bool => $subject->offsetExists($key),
+        ];
+    }
 }
diff --git a/spec/PlainArraySpec.php b/spec/PlainArraySpec.php
index c2201da..3ff934c 100644
--- a/spec/PlainArraySpec.php
+++ b/spec/PlainArraySpec.php
@@ -9,11 +9,13 @@
 use GW\Value\PlainArray;
 use GW\Value\Sorts;
 use GW\Value\StringsArray;
-use GW\Value\Wrap;
 use PhpSpec\Exception\Example\FailureException;
 use PhpSpec\ObjectBehavior;
-use PhpSpec\Wrapper\Subject;
 
+/**
+ * @method void shouldHaveOffset(int $key)
+ * @method void shouldNotHaveOffset(int $key)
+ */
 final class PlainArraySpec extends ObjectBehavior
 {
     function it_is_initializable()
@@ -645,7 +647,7 @@ function it_implements_ArrayAccess()
 
         $this->shouldImplement(\ArrayAccess::class);
 
-        $this->offsetExists(0)->shouldReturn(true);
+        $this->shouldHaveOffset(0);
         $this->offsetGet(0)->shouldReturn('item 1');
         $this[0]->shouldBe('item 1');
     }
@@ -693,4 +695,11 @@ function it_can_tell_if_has_element_or_not()
         $this->hasElement(2)->shouldReturn(false);
         $this->hasElement('five')->shouldReturn(false);
     }
+
+    public function getMatchers(): array
+    {
+        return [
+            'haveOffset' => fn (PlainArray $subject, int $key): bool => $subject->offsetExists($key),
+        ];
+    }
 }
diff --git a/spec/PlainNumbersArraySpec.php b/spec/PlainNumbersArraySpec.php
index 4be3760..e2ad79c 100644
--- a/spec/PlainNumbersArraySpec.php
+++ b/spec/PlainNumbersArraySpec.php
@@ -23,6 +23,10 @@
 use Prophecy\Argument;
 use function range;
 
+/**
+ * @method void shouldHaveOffset(int $key)
+ * @method void shouldNotHaveOffset(int $key)
+ */
 final class PlainNumbersArraySpec extends ObjectBehavior
 {
     function it_calculates_sum_of_integers()
@@ -517,8 +521,8 @@ function it_has_immutable_array_access()
 
         $this[0]->shouldBe($one);
         $this[1]->shouldBe($two);
-        $this->offsetExists(0)->shouldBe(true);
-        $this->offsetExists(2)->shouldBe(false);
+        $this->shouldHaveOffset(0);
+        $this->shouldNotHaveOffset(2);
 
         $this->shouldThrow(BadMethodCallException::class)->during('offsetSet', [1, PlainNumber::from(3)]);
         $this->shouldThrow(BadMethodCallException::class)->during('offsetUnset', [1]);
@@ -564,6 +568,13 @@ function it_can_be_casted_to_strings_array()
         $this->toStringsArray()->toNativeStrings()->shouldBe(['1', '2.5', '3.6', '4', '5']);
     }
 
+    function it_returns_self_on_toNumbersArray()
+    {
+        $this->beConstructedThrough('just', [1, 2.5, 3.6, 4, 5]);
+
+        $this->toNumbersArray()->shouldBe($this);
+    }
+
     private function isEven(): Closure
     {
         return static fn(NumberValue $number) => $number->toNumber() % 2 === 0;
@@ -573,4 +584,11 @@ private function isGreater(int $than): Closure
     {
         return static fn(NumberValue $number) => $number->toNumber() > $than;
     }
+
+    public function getMatchers(): array
+    {
+        return [
+            'haveOffset' => fn (PlainNumbersArray $subject, int $key): bool => $subject->offsetExists($key),
+        ];
+    }
 }
diff --git a/spec/PlainStringSpec.php b/spec/PlainStringSpec.php
index 9339542..ee0804f 100644
--- a/spec/PlainStringSpec.php
+++ b/spec/PlainStringSpec.php
@@ -1,4 +1,4 @@
-<?php 
+<?php
 
 namespace spec\GW\Value;
 
@@ -7,7 +7,7 @@
 use GW\Value\Wrap;
 use PhpSpec\ObjectBehavior;
 
-final class PlainStringSpec extends ObjectBehavior 
+final class PlainStringSpec extends ObjectBehavior
 {
     function it_is_initializable()
     {
diff --git a/spec/PlainStringsArraySpec.php b/spec/PlainStringsArraySpec.php
index b058988..e346799 100644
--- a/spec/PlainStringsArraySpec.php
+++ b/spec/PlainStringsArraySpec.php
@@ -14,6 +14,10 @@
 use PhpSpec\Wrapper\Collaborator;
 use Prophecy\Argument;
 
+/**
+ * @method void shouldHaveOffset(int $key)
+ * @method void shouldNotHaveOffset(int $key)
+ */
 final class PlainStringsArraySpec extends ObjectBehavior
 {
     function it_is_initializable_with_primitive_string()
@@ -309,8 +313,8 @@ function it_is_like_array()
         $this[0]->shouldBeLike(Wrap::string('first'));
         $this->offsetGet(0)->shouldBeLike(Wrap::string('first'));
 
-        $this->offsetExists(0)->shouldReturn(true);
-        $this->offsetExists(2)->shouldReturn(false);
+        $this->shouldHaveOffset(0);
+        $this->shouldNotHaveOffset(2);
     }
 
     function it_is_like_array_but_immutable()
@@ -587,4 +591,11 @@ private function prepareArrayCollaborator($strings): void
         $strings->map(Argument::type('callable'))->willReturn($strings);
         $strings->each(Argument::type('callable'))->willReturn($strings);
     }
+
+    public function getMatchers(): array
+    {
+        return [
+            'haveOffset' => fn (PlainStringsArray $subject, int $key): bool => $subject->offsetExists($key),
+        ];
+    }
 }
diff --git a/src/Associable/SortKeys.php b/src/Associable/SortKeys.php
index 944d9b1..3af6079 100644
--- a/src/Associable/SortKeys.php
+++ b/src/Associable/SortKeys.php
@@ -31,6 +31,7 @@ public function __construct(Associable $associable, callable $comparator)
     public function toAssocArray(): array
     {
         $items = $this->associable->toAssocArray();
+        /** @phpstan-ignore-next-line  */
         uksort($items, $this->comparator);
 
         return $items;
diff --git a/src/Numberable/Add.php b/src/Numberable/Add.php
index 2edc7f1..c5247dd 100644
--- a/src/Numberable/Add.php
+++ b/src/Numberable/Add.php
@@ -2,22 +2,22 @@
 
 namespace GW\Value\Numberable;
 
-use GW\Value\Arrayable\JustArray;
 use GW\Value\Numberable;
-use function array_values;
 
 final class Add implements Numberable
 {
-    private Sum $sum;
+    private Numberable $leftTerm;
+    private Numberable $rightTerm;
 
-    public function __construct(Numberable $term, Numberable ...$terms)
+    public function __construct(Numberable $leftTerm, Numberable $rightTerm)
     {
-        $this->sum = new Sum(new JustArray([$term, ...array_values($terms)]));
+        $this->leftTerm = $leftTerm;
+        $this->rightTerm = $rightTerm;
     }
 
     /** @return int|float */
     public function toNumber()
     {
-        return $this->sum->toNumber();
+        return $this->leftTerm->toNumber() + $this->rightTerm->toNumber();
     }
 }
diff --git a/src/Numberable/Ceil.php b/src/Numberable/Ceil.php
index 2c17307..bd9c99b 100644
--- a/src/Numberable/Ceil.php
+++ b/src/Numberable/Ceil.php
@@ -14,9 +14,8 @@ public function __construct(Numberable $numberable)
         $this->numberable = $numberable;
     }
 
-    /** @return int|float */
-    public function toNumber()
+    public function toNumber(): float
     {
-        return ceil($this->numberable->toNumber());
+        return (float)ceil($this->numberable->toNumber());
     }
 }
diff --git a/src/Numberable/Divide.php b/src/Numberable/Divide.php
index 64feac0..b91b0ce 100644
--- a/src/Numberable/Divide.php
+++ b/src/Numberable/Divide.php
@@ -3,22 +3,21 @@
 namespace GW\Value\Numberable;
 
 use GW\Value\Numberable;
-use function array_reduce;
 
 final class Divide implements Numberable
 {
     private Numberable $dividend;
-    /** @var Numberable[] */
-    private array $divisors;
+    private Numberable $divisor;
 
-    public function __construct(Numberable $dividend, Numberable ...$divisors)
+    public function __construct(Numberable $dividend, Numberable $divisor)
     {
         $this->dividend = $dividend;
-        $this->divisors = $divisors;
+        $this->divisor = $divisor;
     }
 
+    /** @return int|float */
     public function toNumber()
     {
-        return array_reduce($this->divisors, new DivideReducer(), $this->dividend->toNumber());
+        return $this->dividend->toNumber() / $this->divisor->toNumber();
     }
 }
diff --git a/src/Numberable/DivideReducer.php b/src/Numberable/DivideReducer.php
deleted file mode 100644
index 322883f..0000000
--- a/src/Numberable/DivideReducer.php
+++ /dev/null
@@ -1,23 +0,0 @@
-<?php declare(strict_types=1);
-
-namespace GW\Value\Numberable;
-
-use DivisionByZeroError;
-use GW\Value\Numberable;
-
-final class DivideReducer
-{
-    /**
-     * @param int|float $fraction
-     * @return int|float
-     */
-    public function __invoke($fraction, Numberable $divisor)
-    {
-        $divisorNum = $divisor->toNumber();
-        if ($divisorNum === 0) {
-            throw new DivisionByZeroError('Division by zero');
-        }
-
-        return $fraction / $divisorNum;
-    }
-}
diff --git a/src/Numberable/Floor.php b/src/Numberable/Floor.php
index f3dab98..f097ef0 100644
--- a/src/Numberable/Floor.php
+++ b/src/Numberable/Floor.php
@@ -14,9 +14,8 @@ public function __construct(Numberable $numberable)
         $this->numberable = $numberable;
     }
 
-    /** @return int|float */
-    public function toNumber()
+    public function toNumber(): float
     {
-        return floor($this->numberable->toNumber());
+        return (float)floor($this->numberable->toNumber());
     }
 }
diff --git a/src/Numberable/JustNumber.php b/src/Numberable/JustNumber.php
index 58a49f1..8d4f73b 100644
--- a/src/Numberable/JustNumber.php
+++ b/src/Numberable/JustNumber.php
@@ -24,6 +24,6 @@ public static function wrap($number): Numberable
     /** @return int|float */
     public function toNumber()
     {
-        return $this->number + 0;
+        return $this->number;
     }
 }
diff --git a/src/Numberable/Math.php b/src/Numberable/Math.php
index 20f8e2c..150e47f 100644
--- a/src/Numberable/Math.php
+++ b/src/Numberable/Math.php
@@ -17,42 +17,42 @@ public function __construct(callable $fn)
 
     public static function cos(): self
     {
-        return new self('cos');
+        return new self('\cos');
     }
 
     public static function acos(): self
     {
-        return new self('acos');
+        return new self('\acos');
     }
 
     public static function sin(): self
     {
-        return new self('sin');
+        return new self('\sin');
     }
 
     public static function asin(): self
     {
-        return new self('asin');
+        return new self('\asin');
     }
 
     public static function tan(): self
     {
-        return new self('tan');
+        return new self('\tan');
     }
 
     public static function atan(): self
     {
-        return new self('atan');
+        return new self('\atan');
     }
 
     public static function exp(): self
     {
-        return new self('exp');
+        return new self('\exp');
     }
 
     public static function sqrt(): self
     {
-        return new self('sqrt');
+        return new self('\sqrt');
     }
 
     public function __invoke(Numberable $numberable): Numberable
diff --git a/src/Numberable/Min.php b/src/Numberable/Min.php
index daac68c..4b1045f 100644
--- a/src/Numberable/Min.php
+++ b/src/Numberable/Min.php
@@ -5,7 +5,6 @@
 use GW\Value\Arrayable;
 use GW\Value\Arrayable\Map;
 use GW\Value\Numberable;
-use GW\Value\NumberValue;
 use LogicException;
 use function count;
 use function min;
diff --git a/src/Numberable/Multiply.php b/src/Numberable/Multiply.php
index cc3235a..b2b6e27 100644
--- a/src/Numberable/Multiply.php
+++ b/src/Numberable/Multiply.php
@@ -3,22 +3,21 @@
 namespace GW\Value\Numberable;
 
 use GW\Value\Numberable;
-use function array_reduce;
 
 final class Multiply implements Numberable
 {
-    private Numberable $factor;
-    /** @var Numberable[] */
-    private array $factors;
+    private Numberable $right;
+    private Numberable $left;
 
-    public function __construct(Numberable $factor, Numberable ...$factors)
+    public function __construct(Numberable $left, Numberable $right)
     {
-        $this->factor = $factor;
-        $this->factors = $factors;
+        $this->left = $left;
+        $this->right = $right;
     }
 
+    /** @return int|float */
     public function toNumber()
     {
-        return array_reduce($this->factors, new MultiplyReducer(), $this->factor->toNumber());
+        return $this->left->toNumber() * $this->right->toNumber();
     }
 }
diff --git a/src/Numberable/MultiplyReducer.php b/src/Numberable/MultiplyReducer.php
deleted file mode 100644
index ef22873..0000000
--- a/src/Numberable/MultiplyReducer.php
+++ /dev/null
@@ -1,17 +0,0 @@
-<?php declare(strict_types=1);
-
-namespace GW\Value\Numberable;
-
-use GW\Value\Numberable;
-
-final class MultiplyReducer
-{
-    /**
-     * @param int|float $product
-     * @return int|float
-     */
-    public function __invoke($product, Numberable $next)
-    {
-        return $product * $next->toNumber();
-    }
-}
diff --git a/src/Numberable/Round.php b/src/Numberable/Round.php
index 833f2a1..d669964 100644
--- a/src/Numberable/Round.php
+++ b/src/Numberable/Round.php
@@ -19,8 +19,7 @@ public function __construct(Numberable $numberable, int $precision, ?int $mode =
         $this->mode = $mode;
     }
 
-    /** @return int|float */
-    public function toNumber()
+    public function toNumber(): float
     {
         return round($this->numberable->toNumber(), $this->precision, $this->mode ?? PHP_ROUND_HALF_UP);
     }
diff --git a/src/Numberable/Subtract.php b/src/Numberable/Subtract.php
index eb602f9..a378466 100644
--- a/src/Numberable/Subtract.php
+++ b/src/Numberable/Subtract.php
@@ -3,23 +3,21 @@
 namespace GW\Value\Numberable;
 
 use GW\Value\Numberable;
-use function array_reduce;
 
 final class Subtract implements Numberable
 {
-    private Numberable $term;
-    /** @var Numberable[] */
-    private array $terms;
+    private Numberable $minuend;
+    private Numberable $subtrahend;
 
-    public function __construct(Numberable $term, Numberable ...$terms)
+    public function __construct(Numberable $minuend, Numberable $subtrahend)
     {
-        $this->term = $term;
-        $this->terms = $terms;
+        $this->minuend = $minuend;
+        $this->subtrahend = $subtrahend;
     }
 
     /** @return int|float */
     public function toNumber()
     {
-        return array_reduce($this->terms, new SubtractReducer(), $this->term->toNumber());
+        return $this->minuend->toNumber() - $this->subtrahend->toNumber();
     }
 }
diff --git a/src/Numberable/SubtractReducer.php b/src/Numberable/SubtractReducer.php
deleted file mode 100644
index d74e627..0000000
--- a/src/Numberable/SubtractReducer.php
+++ /dev/null
@@ -1,17 +0,0 @@
-<?php declare(strict_types=1);
-
-namespace GW\Value\Numberable;
-
-use GW\Value\Numberable;
-
-final class SubtractReducer
-{
-    /**
-     * @param int|float $diff
-     * @return int|float
-     */
-    public function __invoke($diff, Numberable $next)
-    {
-        return $diff - $next->toNumber();
-    }
-}
diff --git a/src/Numberable/JustNumbers.php b/src/Numberable/WrapNumbers.php
similarity index 93%
rename from src/Numberable/JustNumbers.php
rename to src/Numberable/WrapNumbers.php
index 122ba97..babf8f7 100644
--- a/src/Numberable/JustNumbers.php
+++ b/src/Numberable/WrapNumbers.php
@@ -11,7 +11,7 @@
 /**
  * @implements Arrayable<NumberValue>
  */
-final class JustNumbers implements Arrayable
+final class WrapNumbers implements Arrayable
 {
     /** @var Arrayable<NumberValue> */
     private Arrayable $numbers;
diff --git a/src/NumbersArray.php b/src/NumbersArray.php
index 3cc8aa6..c5c72e9 100644
--- a/src/NumbersArray.php
+++ b/src/NumbersArray.php
@@ -129,8 +129,9 @@ public function reduce(callable $transformer, $start);
 
     /**
      * @param callable(NumberValue $reduced, NumberValue $item):NumberValue $transformer
+     * @param int|float|numeric-string|Numberable $start
      */
-    public function reduceNumber(callable $transformer, NumberValue $start): NumberValue;
+    public function reduceNumber(callable $transformer, $start): NumberValue;
 
     public function implode(string $glue): StringValue;
 
diff --git a/src/PlainNumbersArray.php b/src/PlainNumbersArray.php
index d523f75..b8ed29e 100644
--- a/src/PlainNumbersArray.php
+++ b/src/PlainNumbersArray.php
@@ -4,7 +4,7 @@
 
 use BadMethodCallException;
 use GW\Value\Numberable\Average;
-use GW\Value\Numberable\JustNumbers;
+use GW\Value\Numberable\WrapNumbers;
 use GW\Value\Numberable\Max;
 use GW\Value\Numberable\Min;
 use GW\Value\Numberable\Sum;
@@ -31,7 +31,7 @@ public static function fromArrayable(Arrayable $numbers): self
     /** @param int|float|numeric-string|Numberable ...$numbers */
     public static function just(...$numbers): self
     {
-        return self::fromArrayable(new JustNumbers(...$numbers));
+        return self::fromArrayable(new WrapNumbers(...$numbers));
     }
 
     public function sum(): NumberValue
@@ -143,7 +143,6 @@ public function groupBy(callable $reducer): AssocValue
 
     /**
      * @return ArrayValue<array<int, NumberValue>>
-     * @phpstan-ignore-next-line shrug
      */
     public function chunk(int $size): ArrayValue
     {
@@ -220,7 +219,7 @@ public function offsetGet($offset): NumberValue
      */
     public function offsetSet($offset, $value): void
     {
-        $this->numbers->offsetSet($offset, $value);
+        throw new BadMethodCallException('PlainNumbersArray is immutable');
     }
 
     /**
@@ -229,7 +228,7 @@ public function offsetSet($offset, $value): void
      */
     public function offsetUnset($offset): void
     {
-        $this->numbers->offsetUnset($offset);
+        throw new BadMethodCallException('PlainNumbersArray is immutable');
     }
 
     /**
@@ -284,10 +283,11 @@ public function reduce(callable $transformer, $start)
 
     /**
      * @param callable(NumberValue $reduced, NumberValue $item):NumberValue $transformer
+     * @param int|float|numeric-string|Numberable $start
      */
-    public function reduceNumber(callable $transformer, NumberValue $start): NumberValue
+    public function reduceNumber(callable $transformer, $start): NumberValue
     {
-        return $this->reduce($transformer, $start);
+        return $this->numbers->reduce($transformer, Wrap::number($start));
     }
 
     public function implode(string $glue): StringValue
diff --git a/src/PlainStringsArray.php b/src/PlainStringsArray.php
index c25964e..d00a242 100644
--- a/src/PlainStringsArray.php
+++ b/src/PlainStringsArray.php
@@ -97,8 +97,7 @@ public function flatMap(callable $transformer): PlainStringsArray
 
     /**
      * @param callable(StringValue $value):string $reducer
-     * @phpstan-return AssocValue<string, ArrayValue<StringValue>>
-     * @phpstan-ignore-next-line shrug
+     * @return AssocValue<string, ArrayValue<StringValue>>
      */
     public function groupBy(callable $reducer): AssocValue
     {
@@ -114,7 +113,6 @@ public function groupBy(callable $reducer): AssocValue
 
     /**
      * @return ArrayValue<array<int, StringValue>>
-     * @phpstan-ignore-next-line shrug
      */
     public function chunk(int $size): ArrayValue
     {