Merge branch 'v5'

Author: klimick

UPGRADING-v5.md

@@ -1,3 +1,32 @@
+## Remove psalm-pure and psalm-immutable
+
+Before v5 all data structures and most function was pure.
+Since v5 `@psalm-pure` and `@psalm-immutable` has been removed.
+It has many false positives, and it's to difficult use in the real applications.
+
+Some examples with useful code (but with false positives):
+- https://psalm.dev/r/e58c340477
+- https://psalm.dev/r/de37ebb8ed
+- https://psalm.dev/r/627b50d716
+
+Discussion of the problem: https://github.com/vimeo/psalm/issues/8116
+
+This code is invalid since v5:
+```php
+/**
+ * @param ArrayList<int> $list
+ * @return ArrayList<int>
+ * @psalm-pure
+ */
+function pureFn(ArrayList $list): ArrayList
+{
+    // ERROR: ImpureMethodCall
+    return $list->map(fn($i) => $i + 2);
+}
+```
+
+Removing `@psalm-pure` from the `pureFn` fix that problem.
+
 ## Functions BC
 
 - All collection functions with `$callback`/`$predicate` params does not allow key as second parameter anymore.

doc/Combinators.md

@@ -5,6 +5,9 @@
   - [Omit values from tuple or shape](#Omit-values-from-tuple-or-shape)
   - [Ctor function](#Ctor-function)
   - [Caveats](#Caveats)
+- [\*KV combinators](#\*KV-combinators)
+  - [Map](#Map)
+  - [Functions](#Functions)
 
 # \*N combinators
 
@@ -35,6 +38,7 @@ use function Fp\Collection\sequenceOptionT;
 use function Fp\Evidence\proveArray;
 use function Fp\Evidence\proveBool;
 use function Fp\Evidence\proveInt;
+use function Fp\Json\jsonDecode;
 
 $json = <<<JSON
 {
@@ -49,7 +53,7 @@ JSON;
  */
 function fooFromJson(string $json): Option
 {
-    return Option::try(fn(): mixed => json_decode($json, associative: true, flags: JSON_THROW_ON_ERROR))
+    return jsonDecode($json)->toOption()
         ->flatMap(proveArray(...))
         ->flatMap(fn(array $data) => sequenceOptionT(
             fn() => at($data, 'a')->flatMap(proveInt(...)),
@@ -200,3 +204,71 @@ test(...['a' => 1, 'b' => 2, 'c' => 3, 'd' => 4]);
 
 So `ReflectionFunction` used for filtering extra arguments before array
 will be spread.
+
+# \*KV combinators
+
+  - #### Map
+
+Before v5 `Fp\Collections\Map` used `Fp\Collections\Entry` to represents
+kv pair. It was unfriendly for ide (lack autocompletion ability).
+
+Since v5 `Fp\Collections\Entry` has been removed. Instead, each method
+of `Fp\Collections\Map` has \*KV version:
+
+``` php
+<?php
+
+use Fp\Collections\HashMap;
+
+/**
+ * @param HashMap<int, int> $hashMap
+ * @return HashMap<int, int>
+ */
+function addOne(HashMap $hashMap): HashMap
+{
+    return $hashMap->map(fn(int $value) => $value + 2);
+}
+
+/**
+ * @param HashMap<int, int> $hashMap
+ * @return HashMap<int, int>
+ */
+function sumWithKeys(HashMap $hashMap): HashMap
+{
+    return $hashMap->mapKV(fn(int $key, int $value) => $key + $value);
+}
+```
+
+This makes sense since the key and value are rarely needed at the same
+time.
+
+  - #### Functions
+
+Regular functions has \*KV combinators too:
+
+``` php
+<?php
+
+use Fp\Collections\HashMap;
+
+use function Fp\Collection\map;
+use function Fp\Collection\mapKV;
+
+/**
+ * @param array<int, int> $hashMap
+ * @return array<int, int>
+ */
+function addOne(HashMap $hashMap): HashMap
+{
+    return map($hashMap, fn(int $value) => $value + 2);
+}
+
+/**
+ * @param array<int, int> $hashMap
+ * @return array<int, int>
+ */
+function sumWithKeys(array $hashMap): HashMap
+{
+    return mapKV($hashMap, fn(int $key, int $value) => $key + $value);
+}
+```

src/Doc/Md/Combinators/2_KV_combinators.md

@@ -0,0 +1,65 @@
+# *KV combinators
+
+- #### Map
+
+Before v5 `Fp\Collections\Map` used `Fp\Collections\Entry` to represents kv pair.
+It was unfriendly for ide (lack autocompletion ability). 
+
+Since v5 `Fp\Collections\Entry` has been removed. Instead, each method of `Fp\Collections\Map` has *KV version:
+
+```php
+<?php
+
+use Fp\Collections\HashMap;
+
+/**
+ * @param HashMap<int, int> $hashMap
+ * @return HashMap<int, int>
+ */
+function addOne(HashMap $hashMap): HashMap
+{
+    return $hashMap->map(fn(int $value) => $value + 2);
+}
+
+/**
+ * @param HashMap<int, int> $hashMap
+ * @return HashMap<int, int>
+ */
+function sumWithKeys(HashMap $hashMap): HashMap
+{
+    return $hashMap->mapKV(fn(int $key, int $value) => $key + $value);
+}
+```
+
+This makes sense since the key and value are rarely needed at the same time.
+
+- #### Functions
+
+Regular functions has *KV combinators too:
+
+```php
+<?php
+
+use Fp\Collections\HashMap;
+
+use function Fp\Collection\map;
+use function Fp\Collection\mapKV;
+
+/**
+ * @param array<int, int> $hashMap
+ * @return array<int, int>
+ */
+function addOne(HashMap $hashMap): HashMap
+{
+    return map($hashMap, fn(int $value) => $value + 2);
+}
+
+/**
+ * @param array<int, int> $hashMap
+ * @return array<int, int>
+ */
+function sumWithKeys(array $hashMap): HashMap
+{
+    return mapKV($hashMap, fn(int $key, int $value) => $key + $value);
+}
+```