From 48b9affd6e84cdd605bdb3f054431d444d11aef6 Mon Sep 17 00:00:00 2001
From: Simon Podlipsky <simon@podlipsky.net>
Date: Sat, 6 Apr 2024 17:02:12 +0200
Subject: [PATCH] feat(math): narrow return type for `min()`, `max()`,
 `median()` and `mean()` (#464)

---
 docs/component/math.md  | 4 ++--
 src/Psl/Math/max.php    | 2 +-
 src/Psl/Math/mean.php   | 4 +++-
 src/Psl/Math/median.php | 6 ++++--
 src/Psl/Math/min.php    | 2 +-
 5 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/docs/component/math.md b/docs/component/math.md
index 9c34903c..73cdfb58 100644
--- a/docs/component/math.md
+++ b/docs/component/math.md
@@ -54,8 +54,8 @@
 - [max](./../../src/Psl/Math/max.php#L19)
 - [max_by](./../../src/Psl/Math/max_by.php#L24)
 - [maxva](./../../src/Psl/Math/maxva.php#L20)
-- [mean](./../../src/Psl/Math/mean.php#L18)
-- [median](./../../src/Psl/Math/median.php#L19)
+- [mean](./../../src/Psl/Math/mean.php#L20)
+- [median](./../../src/Psl/Math/median.php#L21)
 - [min](./../../src/Psl/Math/min.php#L19)
 - [min_by](./../../src/Psl/Math/min_by.php#L24)
 - [minva](./../../src/Psl/Math/minva.php#L20)
diff --git a/src/Psl/Math/max.php b/src/Psl/Math/max.php
index 8596ea00..eaf90f50 100644
--- a/src/Psl/Math/max.php
+++ b/src/Psl/Math/max.php
@@ -12,7 +12,7 @@
  *
  * @param list<T> $numbers
  *
- * @return T|null
+ * @return ($numbers is non-empty-list<T> ? T : null)
  *
  * @pure
  */
diff --git a/src/Psl/Math/mean.php b/src/Psl/Math/mean.php
index fdeaba98..51907e30 100644
--- a/src/Psl/Math/mean.php
+++ b/src/Psl/Math/mean.php
@@ -13,9 +13,11 @@
  *
  * @param list<int|float> $numbers
  *
+ * @return ($numbers is non-empty-list ? float : null)
+ *
  * @pure
  */
-function mean(array $numbers): ?float
+function mean(array $numbers): float|null
 {
     $count = (float) count($numbers);
     if (0.0 === $count) {
diff --git a/src/Psl/Math/median.php b/src/Psl/Math/median.php
index f6a7a6b4..faf12bbe 100644
--- a/src/Psl/Math/median.php
+++ b/src/Psl/Math/median.php
@@ -14,9 +14,11 @@
  *
  * @param list<int|float> $numbers
  *
+ * @return ($numbers is non-empty-list ? float : null)
+ *
  * @pure
  */
-function median(array $numbers): ?float
+function median(array $numbers): float|null
 {
     sort($numbers);
     $count   = count($numbers);
@@ -29,7 +31,7 @@ function median(array $numbers): ?float
     if (0 === $count % 2) {
         return mean(
             [$numbers[$middle_index], $numbers[$middle_index - 1]]
-        ) ?? 0.0;
+        );
     }
 
     return (float) $numbers[$middle_index];
diff --git a/src/Psl/Math/min.php b/src/Psl/Math/min.php
index 082d8a96..6e6a97b4 100644
--- a/src/Psl/Math/min.php
+++ b/src/Psl/Math/min.php
@@ -12,7 +12,7 @@
  *
  * @param list<T> $numbers
  *
- * @return T|null
+ * @return ($numbers is non-empty-list<T> ? T : null)
  *
  * @pure
  */