feat: throw UnwrapException with value context from unwrap()/unwrapErr()

README.md

@@ -47,7 +47,7 @@ if ($failure->isErr()) {
 
 // Unwrapping values (throws exception on error)
 $value = $success->unwrap(); // 42
-// $failure->unwrap(); // throws LogicException
+// $failure->unwrap(); // throws UnwrapException
 
 // Safe unwrapping with default values
 $value = $failure->unwrapOr(0); // 0
@@ -202,8 +202,8 @@ All Result types (both Ok and Err) implement these methods:
 - `isErrAnd(callable $fn): bool` - Returns true if the Result is Err and the predicate returns true
 
 #### Value Extraction
-- `unwrap(): mixed` - Returns the success value or throws LogicException
-- `unwrapErr(): mixed` - Returns the error value or throws LogicException
+- `unwrap(): mixed` - Returns the success value or throws UnwrapException (extends LogicException)
+- `unwrapErr(): mixed` - Returns the error value or throws UnwrapException (extends LogicException)
 - `unwrapOr(mixed $default): mixed` - Returns the success value or a default
 - `unwrapOrElse(callable $fn): mixed` - Returns the success value or computes it from the error
 

src/Err.php

@@ -50,7 +50,7 @@ public function isErrAnd(callable $fn): bool
     #[Override]
     public function unwrap(): never
     {
-        throw new \LogicException('called Result::unwrap() on an Err value');
+        throw UnwrapException::unwrapOnErr($this->value);
     }
 
     /**

src/Ok.php

@@ -59,7 +59,7 @@ public function unwrap(): mixed
     #[Override]
     public function unwrapErr(): never
     {
-        throw new \LogicException('called Result::unwrapErr() on an Ok value');
+        throw UnwrapException::unwrapErrOnOk($this->value);
     }
 
     /**

src/Result.php

@@ -60,13 +60,17 @@ public function isErrAnd(callable $fn): bool;
      * 成功値を返します。失敗の場合は例外を投げます.
      *
      * @return ($this is Ok<mixed> ? T : never)
+     *
+     * @throws UnwrapException $this が Err の場合
      */
     public function unwrap(): mixed;
 
     /**
      * エラー値を返します。成功の場合は例外を投げます.
      *
      * @return ($this is Err<mixed> ? E : never)
+     *
+     * @throws UnwrapException $this が Ok の場合
      */
     public function unwrapErr(): mixed;
 

src/UnwrapException.php

@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Valbeat\Result;
+
+/**
+ * unwrap() / unwrapErr() を反対側の変種に対して呼び出したときに送出される例外です.
+ *
+ * \LogicException を継承しているため、既存の catch (\LogicException) はそのまま動作します.
+ * メッセージには保持している値の要約が含まれます（Rust の panic メッセージに相当）.
+ * 注意: スカラー値はメッセージにそのまま（切り詰めの上）現れるため、機微な文字列を
+ * エラー値に載せる場合はログ出力先に注意してください.
+ */
+final class UnwrapException extends \LogicException
+{
+    /**
+     * メッセージに埋め込む値要約の最大長（超過分は切り詰め）.
+     */
+    private const int MAX_SUMMARY_LENGTH = 120;
+
+    /**
+     * Err に対して unwrap() が呼ばれた場合の例外を生成します.
+     */
+    public static function unwrapOnErr(mixed $error): self
+    {
+        return new self(\sprintf('called Result::unwrap() on an Err value: %s', self::describe($error)));
+    }
+
+    /**
+     * Ok に対して unwrapErr() が呼ばれた場合の例外を生成します.
+     */
+    public static function unwrapErrOnOk(mixed $value): self
+    {
+        return new self(\sprintf('called Result::unwrapErr() on an Ok value: %s', self::describe($value)));
+    }
+
+    /**
+     * 例外メッセージ用に値の要約を生成します.
+     *
+     * 要約は単一行に正規化し、MAX_SUMMARY_LENGTH を超える部分は切り詰めます.
+     */
+    private static function describe(mixed $value): string
+    {
+        $summary = match (true) {
+            $value instanceof \Throwable => \sprintf('%s: %s', self::className($value), $value->getMessage()),
+            $value instanceof \UnitEnum => \sprintf('%s::%s', $value::class, $value->name),
+            $value instanceof \Stringable => self::describeStringable($value),
+            \is_object($value) => self::className($value),
+            \is_scalar($value), null === $value => var_export($value, true),
+            default => get_debug_type($value),
+        };
+
+        $summary = str_replace(["\r\n", "\r", "\n"], '\n', $summary);
+        if (\strlen($summary) > self::MAX_SUMMARY_LENGTH) {
+            return substr($summary, 0, self::MAX_SUMMARY_LENGTH) . '... (truncated)';
+        }
+
+        return $summary;
+    }
+
+    /**
+     * Stringable の要約を生成します。__toString() が例外を投げてもこの例外を
+     * 置き換えないよう、失敗時はクラス名のみへフォールバックします.
+     */
+    private static function describeStringable(\Stringable $value): string
+    {
+        try {
+            return \sprintf('%s: %s', self::className($value), (string) $value);
+        } catch (\Throwable) {
+            return self::className($value);
+        }
+    }
+
+    /**
+     * クラス名を返します。匿名クラスはファイルパス・行番号を除いた
+     * 「Foo@anonymous」形式に正規化します.
+     */
+    private static function className(object $value): string
+    {
+        $class = $value::class;
+        $pos = strpos($class, '@anonymous');
+        if ($pos === false) {
+            return $class;
+        }
+
+        return substr($class, 0, $pos + \strlen('@anonymous'));
+    }
+}

tests/ErrTest.php

@@ -8,6 +8,7 @@
 use PHPUnit\Framework\TestCase;
 use Valbeat\Result\Err;
 use Valbeat\Result\Ok;
+use Valbeat\Result\UnwrapException;
 
 class ErrTest extends TestCase
 {
@@ -58,6 +59,93 @@ public function unwrap_throws_exception(): void
         $err->unwrap();
     }
 
+    #[Test]
+    public function unwrap_throwsUnwrapException_withErrorValueInMessage(): void
+    {
+        $err = new Err('error');
+        $this->expectException(UnwrapException::class);
+        $this->expectExceptionMessage("called Result::unwrap() on an Err value: 'error'");
+        $err->unwrap();
+    }
+
+    #[Test]
+    public function unwrap_withThrowableError_includesClassAndMessage(): void
+    {
+        $err = new Err(new \RuntimeException('boom'));
+        $this->expectException(UnwrapException::class);
+        $this->expectExceptionMessage('called Result::unwrap() on an Err value: RuntimeException: boom');
+        $err->unwrap();
+    }
+
+    #[Test]
+    public function unwrap_withArrayError_describesType(): void
+    {
+        $err = new Err(['code' => 500]);
+        $this->expectException(UnwrapException::class);
+        $this->expectExceptionMessage('called Result::unwrap() on an Err value: array');
+        $err->unwrap();
+    }
+
+    #[Test]
+    public function unwrapException_remainsCatchableAsLogicException(): void
+    {
+        $err = new Err('error');
+
+        try {
+            $err->unwrap();
+        } catch (\LogicException $e) {
+            $this->assertInstanceOf(UnwrapException::class, $e);
+        }
+    }
+
+    #[Test]
+    public function unwrap_withThrowingStringableError_stillThrowsUnwrapException(): void
+    {
+        $stringable = new class () implements \Stringable {
+            public function __toString(): string
+            {
+                throw new \RuntimeException('rendering failed');
+            }
+        };
+        $err = new Err($stringable);
+        $this->expectException(UnwrapException::class);
+        $err->unwrap();
+    }
+
+    #[Test]
+    public function unwrap_withEnumError_includesCaseName(): void
+    {
+        $err = new Err(SampleEnumError::NotFound);
+        $this->expectException(UnwrapException::class);
+        $this->expectExceptionMessage('SampleEnumError::NotFound');
+        $err->unwrap();
+    }
+
+    #[Test]
+    public function unwrap_withLongStringError_truncatesMessage(): void
+    {
+        $err = new Err(str_repeat('a', 10000));
+
+        try {
+            $err->unwrap();
+        } catch (UnwrapException $e) {
+            $this->assertLessThan(300, \strlen($e->getMessage()));
+            $this->assertStringContainsString('(truncated)', $e->getMessage());
+        }
+    }
+
+    #[Test]
+    public function unwrap_withMultilineStringError_keepsMessageSingleLine(): void
+    {
+        $err = new Err("line1\nline2");
+
+        try {
+            $err->unwrap();
+        } catch (UnwrapException $e) {
+            $this->assertStringNotContainsString("\n", $e->getMessage());
+        }
+    }
+
     #[Test]
     public function unwrapErr_returns_error_value(): void
     {
@@ -351,3 +439,11 @@ private static function asString(string $value): string
         return $value;
     }
 }
+
+/**
+ * UnwrapException のメッセージが enum のケース名を含むことを検証するためのフィクスチャ.
+ */
+enum SampleEnumError
+{
+    case NotFound;
+}

tests/OkTest.php

@@ -8,6 +8,7 @@
 use PHPUnit\Framework\TestCase;
 use Valbeat\Result\Err;
 use Valbeat\Result\Ok;
+use Valbeat\Result\UnwrapException;
 
 class OkTest extends TestCase
 {
@@ -89,6 +90,30 @@ public function unwrapErr_throws_exception(): void
         $ok->unwrapErr();
     }
 
+    #[Test]
+    public function unwrapErr_throwsUnwrapException_withValueInMessage(): void
+    {
+        $ok = new Ok(42);
+        $this->expectException(UnwrapException::class);
+        $this->expectExceptionMessage('called Result::unwrapErr() on an Ok value: 42');
+        $ok->unwrapErr();
+    }
+
+    #[Test]
+    public function unwrapErr_withStringableValue_includesClassAndString(): void
+    {
+        $value = new class () implements \Stringable {
+            public function __toString(): string
+            {
+                return 'stringable value';
+            }
+        };
+        $ok = new Ok($value);
+        $this->expectException(UnwrapException::class);
+        $this->expectExceptionMessage('stringable value');
+        $ok->unwrapErr();
+    }
+
     #[Test]
     public function unwrapOr_returns_value(): void
     {