Merge pull request #9 from ghostwriter/feature/refactor-generics

feature/refactor generics

Author: ghostwriter

README.md

@@ -19,22 +19,30 @@ composer require ghostwriter/option
 ## Usage
 
 ```php
-use Ghostwriter\Option\{Some, None, OptionInterface};
+use Ghostwriter\Option\Exception\NullPointerException;
+use Ghostwriter\Option\None;
+use Ghostwriter\Option\Some;
 
-// basic setting and getting of values
 $greeting = Some::create('Hello World!');
-echo $greeting->unwrap(); // echos 'Hello World!'
+echo $greeting->unwrap();        // echos: 'Hello World!'
 
 $name = None::create();
-echo $name->unwrap(); // throws an OptionException
-echo $name->unwrapOr('Unknown'); // echos 'Unknown'
+echo $name->unwrap();            // throws: NullPointerException
+echo $name->unwrapOr('Default Value'); // echos: 'Default Value'
+
+None::create();      // returns: None
+Some::of(null);      // returns: None
+Some::create(null);  // throws: NullPointerException
+
+--- Example
 
 function divide(int $x, int $y): OptionInterface
 {
-  if ($y === 0) {
-    return Nome::create();
-  }
-  return Some::create($x / $y);
+    if ($y === 0) {
+        return Nome::create();
+    }
+
+    return Some::create($x / $y);
 }
 
 divide(1, 0); // None
@@ -56,7 +64,7 @@ Please see [CHANGELOG.md](./CHANGELOG.md) for more information what has changed
 If you discover any security related issues, please email `nathanael.esayeas@protonmail.com` instead of using the issue tracker.
 
 ## Sponsors
-[[Become a GitHub Sponsor](https://github.com/sponsors/ghostwriter)]
+[[`Become a GitHub Sponsor`](https://github.com/sponsors/ghostwriter)]
 
 ## Credits
 

composer.json

@@ -37,9 +37,9 @@
         "phpbench/phpbench": "^1.2.6",
         "phpunit/phpunit": "^9.5.21",
         "psalm/plugin-phpunit": "^0.17.0",
-        "rector/rector": "^0.13.9",
+        "rector/rector": "^0.13.10",
         "symplify/easy-coding-standard": "^11.0.9",
-        "vimeo/psalm": "^4.25.0"
+        "vimeo/psalm": "^4.26"
     },
     "minimum-stability": "stable",
     "prefer-stable": true,

composer.lock

@@ -17,6 +17,6 @@
         "text": "php:\/\/stderr",
         "github": true
     },
-    "minMsi": 0,
-    "minCoveredMsi": 0
+    "minMsi": 100,
+    "minCoveredMsi": 100
 }

infection.json.dist

@@ -7,7 +7,6 @@
 use Ghostwriter\Option\Contract\NoneInterface;
 use Ghostwriter\Option\Contract\OptionInterface;
 use Ghostwriter\Option\Contract\SomeInterface;
-use Ghostwriter\Option\Exception\InvalidReturnTypeException;
 use Ghostwriter\Option\Exception\NullPointerException;
 use Throwable;
 use Traversable;
@@ -42,12 +41,7 @@ public function andThen(callable $function): OptionInterface
             return $this;
         }
 
-        $result = $function($this->value);
-        if ($result instanceof OptionInterface) {
-            return $result;
-        }
-
-        throw new InvalidReturnTypeException();
+        return self::of($function($this->value));
     }
 
     public function contains(mixed $value): bool
@@ -78,13 +72,7 @@ public function filter(callable $function): OptionInterface
 
     public function flatten(): OptionInterface
     {
-        if ($this instanceof NoneInterface) {
-            return $this;
-        }
-
-        $unwrapped = $this->value;
-
-        return $unwrapped instanceof SomeInterface ? $unwrapped : $this;
+        return $this->andThen(fn (mixed $value) => $value instanceof SomeInterface ? $value : $this);
     }
 
     public function getIterator(): Traversable
@@ -110,7 +98,7 @@ public function map(callable $function): OptionInterface
             return $this;
         }
 
-        return Some::create($function($this->value));
+        return self::of($function($this->value));
     }
 
     public function mapOr(callable $function, mixed $fallback): mixed
@@ -159,12 +147,7 @@ public function orElse(callable $function): OptionInterface
             return $this;
         }
 
-        $result = $function();
-        if ($result instanceof OptionInterface) {
-            return $result;
-        }
-
-        throw new InvalidReturnTypeException();
+        return self::of($function());
     }
 
     public function unwrap(): mixed

src/AbstractOption.php

@@ -23,7 +23,11 @@ public function and(self $option): self;
     /**
      * Returns None if the option is None, otherwise calls $function with the wrapped value and returns the result.
      *
-     * @param callable(TValue): OptionInterface $function
+     * @template TAndThen
+     *
+     * @param callable(TValue):TAndThen $function
+     *
+     * @return self<TAndThen|TValue>
      */
     public function andThen(callable $function): self;
 
@@ -38,14 +42,18 @@ public function contains(mixed $value): bool;
      * Returns the contained Some value, consuming the self value.
      *
      * @throws Throwable if the value is a None with a custom $throwable provided
+     *
+     * @return TValue
      */
     public function expect(Throwable $throwable): mixed;
 
     /**
      * Returns None if the option is None, otherwise calls $function with the wrapped value and returns: Some(TValue) if
      * $function returns true (where TValue is the wrapped value), and None if $function returns false.
      *
-     * @param callable(TValue): bool $function
+     * @param callable(TValue):bool $function
+     *
+     * @return self<TValue>
      */
     public function filter(callable $function): self;
 
@@ -71,31 +79,37 @@ public function isSome(): bool;
     /**
      * Maps a Some<TValue> to Some<TValue> by applying the callable $function to the contained value.
      *
-     * @param callable(TValue):TValue $function
+     * @template TMap
      *
-     * @return self<TValue>
+     * @param callable(TValue):TMap $function
+     *
+     * @return self<TMap>
      */
     public function map(callable $function): self;
 
     /**
      * Applies a function to the contained value (if any), or returns the provided default (if not).
      *
-     * @template TFallbackValue
+     * @template TFunction
+     * @template TFallback
      *
-     * @param callable(TValue): TFallbackValue $function
-     * @param TFallbackValue                   $fallback
+     * @param callable(TValue): TFunction $function
+     * @param TFallback                   $fallback
      *
-     * @return TFallbackValue
+     * @return TFallback|TFunction
      */
     public function mapOr(callable $function, mixed $fallback): mixed;
 
     /**
      * Applies a function to the contained value (if any), or computes a default (if not).
      *
-     * @template TFallbackValue
+     * @template TFunction
+     * @template TFallback
+     *
+     * @param callable(TValue):TFunction $function
+     * @param callable():TFallback       $fallback
      *
-     * @param callable(mixed): mixed $function
-     * @param callable(): mixed      $fallback
+     * @return TFallback|TFunction
      */
     public function mapOrElse(callable $function, callable $fallback): mixed;
 
@@ -107,6 +121,8 @@ public function mapOrElse(callable $function, callable $fallback): mixed;
      * @template TNullableValue
      *
      * @param TNullableValue $value the actual value
+     *
+     * @return self<TNullableValue|TValue>
      */
     public static function of(mixed $value): self;
 

src/Contract/OptionInterface.php

@@ -6,6 +6,7 @@
 
 use Ghostwriter\Option\AbstractOption;
 use Ghostwriter\Option\Contract\NoneInterface;
+use Ghostwriter\Option\Contract\OptionInterface;
 use Ghostwriter\Option\Contract\SomeInterface;
 use Ghostwriter\Option\None;
 use Ghostwriter\Option\Some;
@@ -49,10 +50,19 @@ public function ofDataProvider(): Traversable
      *
      * @dataProvider ofDataProvider
      *
+     * @template TValue
+     *
      * @param class-string $expected
+     * @param TValue       $value
      */
     public function testOf(string $expected, mixed $value): void
     {
-        self::assertInstanceOf($expected, AbstractOption::of($value));
+        $option = AbstractOption::of($value);
+
+        if ($value instanceof OptionInterface) {
+            self::assertSame($value, $option);
+        }
+
+        self::assertInstanceOf($expected, $option);
     }
 }