Build doc

Author: klimick

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);
+}
+```