Implement the Nexus Option library

Author: paulbalandan

composer.json

@@ -28,12 +28,18 @@
         "phpstan/phpstan-strict-rules": "^1.6",
         "phpunit/phpunit": "^11.2"
     },
+    "replace": {
+        "nexusphp/option": "self.version"
+    },
     "minimum-stability": "dev",
     "prefer-stable": true,
     "autoload": {
         "psr-4": {
             "Nexus\\": "src/Nexus/"
-        }
+        },
+        "files": [
+            "src/Nexus/Option/functions.php"
+        ]
     },
     "autoload-dev": {
         "psr-4": {

phpstan-baseline.php

@@ -0,0 +1,11 @@
+<?php declare(strict_types = 1);
+
+$ignoreErrors = [];
+$ignoreErrors[] = [
+	// identifier: return.unusedType
+	'message' => '#^Method Nexus\\\\Option\\\\Choice\\:\\:from\\(\\) never returns Nexus\\\\Option\\\\Some\\<T of mixed\\> so it can be removed from the return type\\.$#',
+	'count' => 1,
+	'path' => __DIR__ . '/src/Nexus/Option/Choice.php',
+];
+
+return ['parameters' => ['ignoreErrors' => $ignoreErrors]];

phpstan.dist.neon

@@ -1,9 +1,10 @@
 includes:
   - vendor/phpstan/phpstan/conf/bleedingEdge.neon
+  - phpstan-baseline.php
 
 parameters:
   phpVersion: 80200
-  level: 8
+  level: 9
   tmpDir: build/phpstan
   paths:
     - src
@@ -16,7 +17,6 @@ parameters:
     - vendor/autoload.php
   exceptions:
     check:
-      missingCheckedExceptionInThrows: true
       tooWideThrowType: true
   checkTooWideReturnTypesInProtectedAndPublicMethods: true
   checkUninitializedProperties: true
@@ -26,3 +26,4 @@ parameters:
   reportAlwaysTrueInLastCondition: true
   reportAnyTypeWideningInVarTag: true
   checkMissingCallableSignature: true
+  treatPhpDocTypesAsCertain: false

src/Nexus/Option/Choice.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Option;
+
+/**
+ * @internal
+ */
+final class Choice
+{
+    /**
+     * Creates an option from the given `$value`.
+     *
+     * The value of a **None** option can be defined by assigning a `$none` value.
+     * By default, this is equal to `null` but can be another value.
+     *
+     * @template T
+     * @template S
+     *
+     * @param T $value
+     * @param S $none
+     *
+     * @return (T is S ? None : Some<T>)
+     */
+    public static function from(mixed $value, mixed $none = null): Option
+    {
+        if ($value === $none) {
+            return new None();
+        }
+
+        return new Some($value);
+    }
+}

src/Nexus/Option/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 John Paul E. Balandan, CPA <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/Nexus/Option/None.php

@@ -0,0 +1,103 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Option;
+
+/**
+ * @implements Option<never>
+ */
+final readonly class None implements Option
+{
+    public function isSome(): bool
+    {
+        return false;
+    }
+
+    public function isSomeAnd(\Closure $predicate): bool
+    {
+        return false;
+    }
+
+    public function isNone(): bool
+    {
+        return true;
+    }
+
+    public function unwrap(): mixed
+    {
+        throw new NoneException();
+    }
+
+    public function unwrapOr(mixed $default): mixed
+    {
+        return $default;
+    }
+
+    public function unwrapOrElse(\Closure $default): mixed
+    {
+        return $default();
+    }
+
+    public function map(\Closure $predicate): Option
+    {
+        return clone $this;
+    }
+
+    public function mapOr(mixed $default, \Closure $predicate): mixed
+    {
+        return $default;
+    }
+
+    public function mapOrElse(\Closure $default, \Closure $predicate): mixed
+    {
+        return $default();
+    }
+
+    public function and(Option $other): Option
+    {
+        return clone $this;
+    }
+
+    public function andThen(\Closure $predicate): Option
+    {
+        return clone $this;
+    }
+
+    public function filter(\Closure $predicate): Option
+    {
+        return clone $this;
+    }
+
+    public function or(Option $other): Option
+    {
+        return $other;
+    }
+
+    public function orElse(\Closure $other): Option
+    {
+        return $other();
+    }
+
+    public function xor(Option $other): Option
+    {
+        return $other->isSome() ? $other : clone $this;
+    }
+
+    /**
+     * @return \EmptyIterator
+     */
+    public function getIterator(): \Traversable
+    {
+        return new \EmptyIterator();
+    }
+}

src/Nexus/Option/NoneException.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Option;
+
+/**
+ * Exception thrown when accessing the value of a `None` option.
+ */
+final class NoneException extends \UnderflowException
+{
+    public function __construct()
+    {
+        parent::__construct('Attempting to unwrap a None option.');
+    }
+}