Add phpstan typing annotations

composer.json

@@ -22,7 +22,8 @@
     "require-dev": {
         "squizlabs/php_codesniffer": "~3.0",
         "phpunit/phpunit": "^7.0 || ^8.0 || ^9.5",
-        "friendsofphp/php-cs-fixer": "^2.17"
+        "friendsofphp/php-cs-fixer": "^2.17",
+        "phpstan/phpstan": "^1.10"
     },
     "autoload": {
         "psr-4": {

src/Functional/Ary.php

@@ -11,11 +11,19 @@
 namespace Functional;
 
 use Functional\Exceptions\InvalidArgumentException;
-use Traversable;
 
 /**
  * Call $func with only abs($count) arguments, taken either from the
  * left or right depending on the sign
+ *
+ * @template V
+ * @template T
+ *
+ * @param callable(T...):V $func
+ * @param non-zero-int $count
+ *
+ * @return callable(T...):V
+ *
  * @no-named-arguments
  */
 function ary(callable $func, int $count): callable
@@ -25,7 +33,7 @@ function ary(callable $func, int $count): callable
     return function (...$args) use ($func, $count) {
         if ($count > 0) {
             return $func(...take_left($args, $count));
-        } else if ($count < 0) {
+        } else {
             return $func(...take_right($args, -$count));
         }
     };

src/Functional/Average.php

@@ -11,13 +11,18 @@
 namespace Functional;
 
 use Functional\Exceptions\InvalidArgumentException;
-use Traversable;
 
 /**
  * Returns the average of all numeric values in the array or null if no numeric value was found
  *
- * @param Traversable|array $collection
- * @return null|float|int
+ * @param iterable<mixed> $collection
+ *
+ * @return ($collection is iterable<int> ? float|int : (
+ *     $collection is iterable<float> ? float : (
+ *         $collection is iterable<int|float|numeric-string> ? float|int : null
+ *     )
+ * ))
+ *
  * @no-named-arguments
  */
 function average($collection)

src/Functional/ButLast.php

@@ -11,13 +11,16 @@
 namespace Functional;
 
 use Functional\Exceptions\InvalidArgumentException;
-use Traversable;
 
 /**
  * Returns an array containing the elements of the list without its last element.
  *
- * @param Traversable|array $collection
- * @return array
+ * @template T
+ *
+ * @param iterable<T> $collection
+ *
+ * @return iterable<T>
+ *
  * @no-named-arguments
  */
 function but_last($collection)

src/Functional/Capture.php

@@ -11,11 +11,15 @@
 namespace Functional;
 
 /**
- * Return a new function that captures the return value of $callback in $result and returns the callbacks return value
+ * Return a new function that captures the return value of $callback in $result and returns the callback's return value
+ *
+ * @template T
+ *
+ * @param callable():T $callback
+ * @param T $result
+ *
+ * @return callable():T
  *
- * @param callable $callback
- * @param mixed $result
- * @return callable
  * @no-named-arguments
  */
 function capture(callable $callback, &$result)

src/Functional/CompareObjectHashOn.php

@@ -13,9 +13,14 @@
 /**
  * Returns a comparison function that can be used with e.g. `usort()`
  *
- * @param callable $comparison A function that compares the two values. Pick e.g. strcmp() or strnatcasecmp()
- * @param callable $keyFunction A function that takes an argument and returns the value that should be compared
- * @return callable
+ * @template V
+ * @template R of int
+ *
+ * @param callable(string,string):R $comparison A function that compares the two values. Pick e.g. strcmp() or strnatcasecmp()
+ * @param null|callable(V):string $keyFunction A function that takes an argument and returns the value that should be compared
+ *
+ * @return callable(object,object):R
+ *
  * @no-named-arguments
  */
 function compare_object_hash_on(callable $comparison, callable $keyFunction = null)

src/Functional/CompareOn.php

@@ -13,9 +13,15 @@
 /**
  * Returns a comparison function that can be used with e.g. `usort()`
  *
- * @param callable $comparison A function that compares the two values. Pick e.g. strcmp() or strnatcasecmp()
- * @param callable $reducer A function that takes an argument and returns the value that should be compared
- * @return callable
+ * @template V
+ * @template V2
+ * @template R of int
+ *
+ * @param callable(V,V):R $comparison A function that compares the two values. Pick e.g. strcmp() or strnatcasecmp()
+ * @param null|callable(V2):V $reducer A function that takes an argument and returns the value that should be compared
+ *
+ * @return ($reducer is null ? callable(V,V):R : callable(V2,V2):R)
+ *
  * @no-named-arguments
  */
 function compare_on(callable $comparison, callable $reducer = null)

src/Functional/Concat.php

@@ -13,8 +13,10 @@
 /**
  * Concatenates zero or more strings
  *
- * @param string[] ...$strings
+ * @param string ...$strings
+ *
  * @return string
+ *
  * @no-named-arguments
  */
 function concat(string ...$strings)

src/Functional/ConstFunction.php

@@ -13,8 +13,12 @@
 /**
  * Wrap value within a function, which will return it, without any modifications.
  *
- * @param mixed $value
- * @return callable
+ * @template V
+ *
+ * @param V $value
+ *
+ * @return callable():V
+ *
  * @no-named-arguments
  */
 function const_function($value)

src/Functional/Contains.php

@@ -11,16 +11,20 @@
 namespace Functional;
 
 use Functional\Exceptions\InvalidArgumentException;
-use Traversable;
 
 /**
  * Returns true if the collection contains the given value. If the third parameter is
  * true values will be compared in strict mode
  *
- * @param Traversable|array $collection
- * @param mixed $value
+ * @template V
+ * @template V2
+ *
+ * @param iterable<V> $collection
+ * @param V2 $value
  * @param bool $strict
- * @return bool
+ *
+ * @return ($strict is true ? (V2 is V ? bool : false) : bool)
+ *
  * @no-named-arguments
  */
 function contains($collection, $value, $strict = true)

src/Functional/Converge.php

@@ -16,9 +16,14 @@
  * The results of each branching function are passed as arguments
  * to the converging function to produce the return value.
  *
- * @param callable $convergingFunction Will be invoked with the return values of all branching functions as its arguments
- * @param callable[] $branchingFunctions A list of functions
- * @return callable A flipped version of the given function
+ * @template R
+ * @template R2
+ *
+ * @param callable(mixed...):R2 $convergingFunction Will be invoked with the return values of all branching functions as its arguments
+ * @param array<callable(mixed...):R> $branchingFunctions A list of functions
+ *
+ * @return callable(mixed...):R2
+ *
  * @no-named-arguments
  */
 function converge($convergingFunction, array $branchingFunctions)

src/Functional/Curry.php

@@ -15,12 +15,16 @@
 use Closure;
 
 /**
- * Return a curryied version of the given function. You can decide if you also
+ * Return a curried version of the given function. You can decide if you also
  * want to curry optional parameters or not.
  *
- * @param callable $function the function to curry
- * @param bool $required curry optional parameters ?
- * @return callable a curryied version of the given function
+ * @template R
+ *
+ * @param callable(mixed...):R $function the function to curry
+ * @param bool $required curry optional parameters?
+ *
+ * @return callable(mixed...):R a curried version of the given function
+ *
  * @no-named-arguments
  */
 function curry(callable $function, $required = true)

src/Functional/CurryN.php

@@ -11,15 +11,19 @@
 namespace Functional;
 
 /**
- * Return a version of the given function where the $count first arguments are curryied.
+ * Return a version of the given function where the $count first arguments are curried.
  *
  * No check is made to verify that the given argument count is either too low or too high.
  * If you give a smaller number you will have an error when calling the given function. If
  * you give a higher number, arguments will simply be ignored.
  *
+ * @template R
+ *
  * @param int $count number of arguments you want to curry
- * @param callable $function the function you want to curry
- * @return callable a curryied version of the given function
+ * @param callable(mixed...):R $function the function you want to curry
+ *
+ * @return callable(mixed...):R a curried version of the given function
+ *
  * @no-named-arguments
  */
 function curry_n($count, callable $function)

src/Functional/Difference.php

@@ -11,14 +11,18 @@
 namespace Functional;
 
 use Functional\Exceptions\InvalidArgumentException;
-use Traversable;
 
 /**
  * Takes a collection and returns the difference of all elements
  *
- * @param Traversable|array $collection
- * @param integer|float $initial
- * @return integer|float
+ * @template V
+ * @template I of int|float
+ *
+ * @param iterable<V> $collection
+ * @param I $initial
+ *
+ * @return (V is int ? ($initial is int ? int : float) : (V is float ? float : int|float))
+ *
  * @no-named-arguments
  */
 function difference($collection, $initial = 0)

src/Functional/DropFirst.php

@@ -11,14 +11,18 @@
 namespace Functional;
 
 use Functional\Exceptions\InvalidArgumentException;
-use Traversable;
 
 /**
  * Drop all elements from a collection until callback returns false
  *
- * @param Traversable|array $collection
- * @param callable $callback
- * @return array
+ * @template K of array-key
+ * @template V
+ *
+ * @param iterable<K, V> $collection
+ * @param callable(V, K, iterable<K, V>):bool $callback
+ *
+ * @return array<K,V>
+ *
  * @no-named-arguments
  */
 function drop_first($collection, callable $callback)

src/Functional/DropLast.php

@@ -11,14 +11,18 @@
 namespace Functional;
 
 use Functional\Exceptions\InvalidArgumentException;
-use Traversable;
 
 /**
  * Drop all elements from a collection after callback returns true
  *
- * @param Traversable|array $collection
- * @param callable $callback
- * @return array
+ * @template K of array-key
+ * @template V
+ *
+ * @param iterable<K, V> $collection
+ * @param callable(V, K, iterable<K, V>):bool $callback
+ *
+ * @return ($collection is list<V> ? list<V> : array<K,V>)
+ *
  * @no-named-arguments
  */
 function drop_last($collection, callable $callback)

src/Functional/Each.php

@@ -11,15 +11,19 @@
 namespace Functional;
 
 use Functional\Exceptions\InvalidArgumentException;
-use Traversable;
 
 /**
  * Iterates over a collection of elements, yielding each in turn to a callback function. Each invocation of $callback
  * is called with three arguments: (element, index, collection)
  *
- * @param Traversable|array $collection
- * @param callable $callback
- * @return null
+ * @template K
+ * @template V
+ *
+ * @param iterable<K,V> $collection
+ * @param callable(V,K,iterable<K,V>):void $callback
+ *
+ * @return void
+ *
  * @no-named-arguments
  */
 function each($collection, callable $callback)

src/Functional/Entries.php

@@ -11,16 +11,21 @@
 namespace Functional;
 
 use Functional\Exceptions\InvalidArgumentException;
-use Traversable;
 
 /**
  * Inspired by JavaScript’s `Object.entries`, and Python’s `enumerate`,
  * convert a key-value map into an array of key-value pairs
  *
- * @see Functional\from_entries
- * @param Traversable|array $collection
+ * @see \Functional\from_entries
+ *
+ * @template K
+ * @template V
+ *
+ * @param iterable<K,V> $collection
  * @param int $start
- * @return array
+ *
+ * @return ($start is 0 ? list<array{K,V}> : array<int, array{K,V}>)
+ *
  * @no-named-arguments
  */
 function entries($collection, int $start = 0)

src/Functional/Equal.php

@@ -15,7 +15,8 @@
  *
  * @param mixed $b the value to compare to
  *
- * @return callable the function to perform the comparison
+ * @return callable(mixed):bool the function to perform the comparison
+ *
  * @no-named-arguments
  */
 function equal($b)