Implement Nexus Result

composer.json

@@ -36,6 +36,7 @@
         "nexusphp/option": "self.version",
         "nexusphp/password": "self.version",
         "nexusphp/phpstan-nexus": "self.version",
+        "nexusphp/result": "self.version",
         "nexusphp/suppression": "self.version"
     },
     "provide": {

src/Nexus/Result/Err.php

@@ -0,0 +1,167 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Result;
+
+/**
+ * @template E
+ *
+ * @implements Result<never, E>
+ */
+final readonly class Err implements Result
+{
+    /**
+     * @param E $err
+     */
+    public function __construct(
+        private mixed $err,
+    ) {}
+
+    public function isOk(): bool
+    {
+        return false;
+    }
+
+    public function isOkAnd(\Closure $predicate): bool
+    {
+        return false;
+    }
+
+    public function isErr(): bool
+    {
+        return true;
+    }
+
+    public function isErrAnd(\Closure $predicate): bool
+    {
+        return $predicate($this->err);
+    }
+
+    /**
+     * @return self<E>
+     */
+    public function map(\Closure $predicate): self
+    {
+        return $this;
+    }
+
+    public function mapOr(mixed $default, \Closure $predicate): mixed
+    {
+        return $default;
+    }
+
+    public function mapOrElse(\Closure $default, \Closure $predicate): mixed
+    {
+        return $default($this->err);
+    }
+
+    /**
+     * @template F
+     *
+     * @param (\Closure(E): F) $predicate
+     *
+     * @return self<F>
+     */
+    public function mapErr(\Closure $predicate): self
+    {
+        return new self($predicate($this->err));
+    }
+
+    public function unwrap(): never
+    {
+        $message = static fn(string $arg): string => \sprintf('Unwrapped an Err result: %s', $arg);
+
+        if ($this->err instanceof \Throwable) {
+            throw new UnwrappedResultException($message($this->err->getMessage()), 0, $this->err);
+        }
+
+        if (\is_scalar($this->err)) {
+            throw new UnwrappedResultException($message(var_export($this->err, true)));
+        }
+
+        throw new UnwrappedResultException('Unwrapped an Err result.');
+    }
+
+    /**
+     * @template U
+     *
+     * @param U $default
+     *
+     * @return U
+     */
+    public function unwrapOr(mixed $default): mixed
+    {
+        return $default;
+    }
+
+    /**
+     * @template U
+     *
+     * @param (\Closure(E): U) $op
+     *
+     * @return U
+     */
+    public function unwrapOrElse(\Closure $op): mixed
+    {
+        return $op($this->err);
+    }
+
+    public function unwrapErr(): mixed
+    {
+        return $this->err;
+    }
+
+    /**
+     * @return self<E>
+     */
+    public function and(Result $res): self
+    {
+        return $this;
+    }
+
+    /**
+     * @return self<E>
+     */
+    public function andThen(\Closure $op): self
+    {
+        return $this;
+    }
+
+    /**
+     * @template T
+     * @template F
+     * @template R of Result<T, F>
+     *
+     * @param R $res
+     *
+     * @return R
+     */
+    public function or(Result $res): Result
+    {
+        return $res;
+    }
+
+    /**
+     * @template T
+     * @template F
+     * @template R of Result<T, F>
+     *
+     * @param (\Closure(E): R) $op
+     *
+     * @return R
+     */
+    public function orElse(\Closure $op): Result
+    {
+        return $op($this->err);
+    }
+}

src/Nexus/Result/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+
+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/Result/Ok.php

@@ -0,0 +1,159 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of the Nexus framework.
+ *
+ * (c) John Paul E. Balandan, CPA <paulbalandan@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Nexus\Result;
+
+/**
+ * @template T
+ *
+ * @implements Result<T, never>
+ */
+final readonly class Ok implements Result
+{
+    /**
+     * @param T $value
+     */
+    public function __construct(
+        private mixed $value,
+    ) {}
+
+    public function isOk(): bool
+    {
+        return true;
+    }
+
+    public function isOkAnd(\Closure $predicate): bool
+    {
+        return $predicate($this->value);
+    }
+
+    public function isErr(): bool
+    {
+        return false;
+    }
+
+    public function isErrAnd(\Closure $predicate): bool
+    {
+        return false;
+    }
+
+    /**
+     * @template U
+     *
+     * @param (\Closure(T): U) $predicate
+     *
+     * @return self<U>
+     */
+    public function map(\Closure $predicate): self
+    {
+        return new self($predicate($this->value));
+    }
+
+    public function mapOr(mixed $default, \Closure $predicate): mixed
+    {
+        return $predicate($this->value);
+    }
+
+    public function mapOrElse(\Closure $default, \Closure $predicate): mixed
+    {
+        return $predicate($this->value);
+    }
+
+    /**
+     * @return self<T>
+     */
+    public function mapErr(\Closure $predicate): self
+    {
+        return $this;
+    }
+
+    public function unwrap(): mixed
+    {
+        return $this->value;
+    }
+
+    /**
+     * @return T
+     */
+    public function unwrapOr(mixed $default): mixed
+    {
+        return $this->value;
+    }
+
+    /**
+     * @return T
+     */
+    public function unwrapOrElse(\Closure $op): mixed
+    {
+        return $this->value;
+    }
+
+    public function unwrapErr(): never
+    {
+        $message = static fn(string $arg): string => \sprintf('Unwrapped an Ok result: %s', $arg);
+
+        if ($this->value instanceof \Throwable) {
+            throw new UnwrappedResultException($message($this->value->getMessage()), 0, $this->value);
+        }
+
+        if (\is_scalar($this->value)) {
+            throw new UnwrappedResultException($message(var_export($this->value, true)));
+        }
+
+        throw new UnwrappedResultException('Unwrapped an Ok result.');
+    }
+
+    /**
+     * @template U
+     * @template E
+     * @template R of Result<U, E>
+     *
+     * @param R $res
+     *
+     * @return R
+     */
+    public function and(Result $res): Result
+    {
+        return $res;
+    }
+
+    /**
+     * @template U
+     * @template E
+     * @template R of Result<U, E>
+     *
+     * @param (\Closure(T): R) $op
+     *
+     * @return R
+     */
+    public function andThen(\Closure $op): Result
+    {
+        return $op($this->value);
+    }
+
+    /**
+     * @return self<T>
+     */
+    public function or(Result $res): self
+    {
+        return $this;
+    }
+
+    /**
+     * @return self<T>
+     */
+    public function orElse(\Closure $op): self
+    {
+        return $this;
+    }
+}