From e3c9d61eb6153602553d975688545c36e2a98371 Mon Sep 17 00:00:00 2001 From: Takuma Kajikawa Date: Thu, 9 Jul 2026 18:16:21 +0900 Subject: [PATCH] chore: translate Japanese comments and docs to English MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Translate all Japanese docblocks, inline comments, and CodeRabbit review instructions to English across src/, tests/, and .coderabbit.yaml. Also switch CodeRabbit review language from ja to en-US. The multibyte test fixture (str_repeat('あ', 200)) is kept as-is since it verifies UTF-8 truncation behavior. Claude-Session: https://claude.ai/code/session_014UL25HVV4YV6N7uZc9bZA1 --- .coderabbit.yaml | 30 +++++++------- src/Err.php | 2 +- src/Ok.php | 2 +- src/Result.php | 76 +++++++++++++++++----------------- src/Results.php | 22 +++++----- src/UnwrapException.php | 35 ++++++++-------- tests/ErrTest.php | 8 ++-- tests/OkTest.php | 2 +- tests/ResultsTest.php | 2 +- tests/Types/result.php | 90 ++++++++++++++++++++--------------------- 10 files changed, 135 insertions(+), 134 deletions(-) diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 2eeda0a..3760271 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -1,9 +1,9 @@ # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json -language: ja +language: en-US early_access: false tone_instructions: | - 日本語で簡潔かつ建設的にレビューしてください。 - 指摘の根拠（PHPのバージョン依存、型安全性、Result型の不変条件など）を明示してください。 + Review concisely and constructively. + Make the rationale for each comment explicit (PHP version dependencies, type safety, Result type invariants, etc.). reviews: profile: assertive @@ -29,24 +29,24 @@ reviews: path_instructions: - path: "src/**/*.php" instructions: | - - PHP 8.4 以上の構文・機能を前提にレビューする。 - - Rust の Result に倣った API 設計を尊重し、Ok / Err / Result の不変条件を崩していないか確認する。 - - 例外による暗黙のエラー伝播ではなく、Result 型での明示的なエラーハンドリングを推奨する。 - - readonly / final / 型宣言（戻り値・引数・プロパティ）の徹底をチェックする。 - - 公開 API の破壊的変更がある場合は明示的に指摘する。 + - Review assuming PHP 8.4+ syntax and features. + - Respect the API design modeled after Rust's Result, and check that the Ok / Err / Result invariants are not broken. + - Prefer explicit error handling via the Result type over implicit error propagation through exceptions. + - Check for thorough use of readonly / final / type declarations (return, parameter, and property types). + - Explicitly point out any breaking changes to the public API. - path: "tests/**/*.php" instructions: | - - PHPUnit のテストとして、t-wada 流 TDD の Red→Green→Refactor を意識しているかをチェックする。 - - 1 テスト 1 アサーション主義に偏りすぎず、振る舞い単位で検証されているか確認する。 - - エッジケース（Ok/Err 双方、ネスト、map/and_then などのコンビネータ）が網羅されているかを見る。 + - As PHPUnit tests, check whether they follow t-wada-style TDD's Red→Green→Refactor. + - Without over-adhering to one-assertion-per-test dogma, check that they verify behavior units. + - Check that edge cases are covered (both Ok/Err, nesting, combinators such as map/and_then). - path: "**/*.md" instructions: | - - サンプルコードは PHP 8.4+ で実行可能か確認する。 - - README の API 説明と src の実装が一致しているかを確認する。 + - Check that sample code is runnable on PHP 8.4+. + - Check that the README's API descriptions match the implementation in src. - path: ".github/workflows/**" instructions: | - - 使用するアクションはバージョンを固定（SHA か明示的なタグ）しているかを確認する。 - - secrets の取り扱いに不適切なものがないかをチェックする。 + - Check that the actions used are version-pinned (by SHA or an explicit tag). + - Check for any improper handling of secrets. tools: phpstan: diff --git a/src/Err.php b/src/Err.php index e02203d..e5f3558 100644 --- a/src/Err.php +++ b/src/Err.php @@ -7,7 +7,7 @@ use Override; /** - * Err はエラー値を表します. + * Err represents an error value. * * @template-covariant E * diff --git a/src/Ok.php b/src/Ok.php index 32be4a6..c770cbe 100644 --- a/src/Ok.php +++ b/src/Ok.php @@ -7,7 +7,7 @@ use Override; /** - * Ok は成功値を表します. + * Ok represents a success value. * * @template-covariant T * diff --git a/src/Result.php b/src/Result.php index 89b75f8..7a9f3aa 100644 --- a/src/Result.php +++ b/src/Result.php @@ -5,21 +5,21 @@ namespace Valbeat\Result; /** - * Result型は、成功（Ok）または失敗（Err）を表現します。 + * The Result type represents either success (Ok) or failure (Err). * - * 注意: instanceof による絞り込みでは型引数が失われます（PHPStan の既知の制限。 - * Result が型引数なしの Ok になり unwrap() は mixed になる）。 - * 値を取り出す分岐では isOk() / isErr() で絞り込んでください。 + * Note: narrowing via instanceof loses the type arguments (a known PHPStan + * limitation; Result becomes an Ok without type arguments and unwrap() + * returns mixed). In branches that extract the value, narrow with isOk() / isErr(). * - * @template-covariant T 成功時の値の型 - * @template-covariant E 失敗時のエラーの型 + * @template-covariant T the type of the success value + * @template-covariant E the type of the error value * * @phpstan-sealed Ok|Err */ interface Result { /** - * 結果が成功（Ok）の場合に true を返します. + * Returns true if the result is a success (Ok). * * @phpstan-assert-if-true Ok $this * @phpstan-assert-if-false Err $this @@ -29,7 +29,7 @@ interface Result public function isOk(): bool; /** - * 結果が成功（Ok）でありコールバックが true を返す場合に true を返します. + * Returns true if the result is a success (Ok) and the callback returns true. * * @param callable(T): bool $fn * @@ -38,7 +38,7 @@ public function isOk(): bool; public function isOkAnd(callable $fn): bool; /** - * 結果が失敗（Err）の場合に true を返します. + * Returns true if the result is a failure (Err). * * @phpstan-assert-if-true Err $this * @phpstan-assert-if-false Ok $this @@ -48,7 +48,7 @@ public function isOkAnd(callable $fn): bool; public function isErr(): bool; /** - * 結果が失敗（Err）でありコールバックが true を返す場合に true を返します. + * Returns true if the result is a failure (Err) and the callback returns true. * * @param callable(E): bool $fn * @@ -57,47 +57,47 @@ public function isErr(): bool; public function isErrAnd(callable $fn): bool; /** - * 成功値を返します。失敗の場合は例外を投げます. + * Returns the success value. Throws an exception on failure. * * @return ($this is Ok ? T : never) * - * @throws UnwrapException $this が Err の場合 + * @throws UnwrapException if $this is Err */ public function unwrap(): mixed; /** - * エラー値を返します。成功の場合は例外を投げます. + * Returns the error value. Throws an exception on success. * * @return ($this is Err ? E : never) * - * @throws UnwrapException $this が Ok の場合 + * @throws UnwrapException if $this is Ok */ public function unwrapErr(): mixed; /** - * 成功値を返します。失敗の場合は指定したメッセージで例外を投げます. + * Returns the success value. On failure, throws an exception with the given message. * - * @param string $message 失敗時の例外メッセージ（エラー値の要約が付加されます） + * @param string $message the exception message on failure (a summary of the error value is appended) * * @return ($this is Ok ? T : never) * - * @throws UnwrapException $this が Err の場合 + * @throws UnwrapException if $this is Err */ public function expect(string $message): mixed; /** - * エラー値を返します。成功の場合は指定したメッセージで例外を投げます. + * Returns the error value. On success, throws an exception with the given message. * - * @param string $message 成功時の例外メッセージ（成功値の要約が付加されます） + * @param string $message the exception message on success (a summary of the success value is appended) * * @return ($this is Err ? E : never) * - * @throws UnwrapException $this が Ok の場合 + * @throws UnwrapException if $this is Ok */ public function expectErr(string $message): mixed; /** - * 成功値またはデフォルト値を返します. + * Returns the success value or a default value. * * @template U * @param U $default @@ -106,7 +106,7 @@ public function expectErr(string $message): mixed; public function unwrapOr(mixed $default): mixed; /** - * 成功値またはクロージャーの結果を返します. + * Returns the success value or the result of the closure. * * @template U * @param callable(E): U $fn @@ -116,7 +116,7 @@ public function unwrapOr(mixed $default): mixed; public function unwrapOrElse(callable $fn): mixed; /** - * 成功値に関数を適用します. + * Applies a function to the success value. * * @template U * @@ -127,7 +127,7 @@ public function unwrapOrElse(callable $fn): mixed; public function map(callable $fn): self; /** - * エラー値に関数を適用します. + * Applies a function to the error value. * * @template F * @@ -138,7 +138,7 @@ public function map(callable $fn): self; public function mapErr(callable $fn): self; /** - * 成功値に副作用を適用します. + * Applies a side effect to the success value. * * @param callable(T): void $fn * @@ -147,7 +147,7 @@ public function mapErr(callable $fn): self; public function inspect(callable $fn): self; /** - * エラー値に副作用を適用します. + * Applies a side effect to the error value. * * @param callable(E): void $fn * @@ -156,7 +156,7 @@ public function inspect(callable $fn): self; public function inspectErr(callable $fn): self; /** - * 成功値に関数を適用するか、デフォルト値を返します. + * Applies a function to the success value, or returns a default value. * * @template U * @@ -168,7 +168,7 @@ public function inspectErr(callable $fn): self; public function mapOr(mixed $default, callable $fn): mixed; /** - * 成功値に関数を適用するか、クロージャーの結果を返します. + * Applies a function to the success value, or returns the result of the closure. * * @template U * @@ -180,7 +180,7 @@ public function mapOr(mixed $default, callable $fn): mixed; public function mapOrElse(callable $defaultFn, callable $fn): mixed; /** - * 成功の場合は第2の結果を返し、失敗の場合は最初のエラーを返します. + * Returns the second result on success, or the first error on failure. * * @template U * @template F @@ -192,9 +192,9 @@ public function mapOrElse(callable $defaultFn, callable $fn): mixed; public function and(self $res): self; /** - * 成功の場合は関数を適用し、失敗の場合は現在のエラーを返します. + * Applies a function on success, or returns the current error on failure. * - * 関数は元と異なるエラー型を返せます。エラー型は E|F に合成されます. + * The function may return a different error type; the error type is combined into E|F. * * @template U * @template F @@ -206,7 +206,7 @@ public function and(self $res): self; public function andThen(callable $fn): self; /** - * 失敗の場合は第2の結果を返し、成功の場合は最初の値を返します. + * Returns the second result on failure, or the first value on success. * * @template U * @template F @@ -218,9 +218,9 @@ public function andThen(callable $fn): self; public function or(self $res): self; /** - * 失敗の場合は関数を適用し、成功の場合は現在の値を返します. + * Applies a function on failure, or returns the current value on success. * - * 関数は元と異なる成功型を返せます。成功型は T|U に合成されます. + * The function may return a different success type; the success type is combined into T|U. * * @template U * @template F @@ -232,15 +232,15 @@ public function or(self $res): self; public function orElse(callable $fn): self; /** - * 成功の場合はokを、失敗の場合はerrを適用します. + * Applies ok on success, or err on failure. * * @template U * @template V * - * @param callable(T): U $ok 成功値に適用する関数 - * @param callable(E): V $err エラー値に適用する関数 + * @param callable(T): U $ok the function applied to the success value + * @param callable(E): V $err the function applied to the error value * - * @return U|V 適用された関数の結果 + * @return U|V the result of the applied function */ public function match(callable $ok, callable $err): mixed; } diff --git a/src/Results.php b/src/Results.php index 71f1f5f..7fddfa2 100644 --- a/src/Results.php +++ b/src/Results.php @@ -5,12 +5,12 @@ namespace Valbeat\Result; /** - * Result を生成・合成する静的ヘルパーです. + * Static helpers for creating and composing Results. */ final class Results { /** - * 静的ヘルパーのためインスタンス化を禁止します. + * Prevents instantiation since this is a static helper. * * @codeCoverageIgnore */ @@ -19,10 +19,10 @@ private function __construct() } /** - * 例外を投げうる処理を実行し、結果を Result に包みます. + * Executes a callable that may throw and wraps the result in a Result. * - * 成功時は戻り値を Ok に、\Throwable が送出された場合は Err に包んで返します. - * 例外ベースの既存コードを Result の世界に持ち込む入口として使います. + * On success the return value is wrapped in Ok; if a \Throwable is thrown it is wrapped in Err. + * Use it as an entry point for bringing existing exception-based code into the Result world. * * @template T * @@ -40,9 +40,9 @@ public static function try(callable $fn): Result } /** - * 複数の Result を 1 つに合成します. + * Combines multiple Results into one. * - * すべて成功なら値のリストを Ok で返し、失敗が含まれる場合は最初の Err を返します. + * If all are successes, returns the list of values as an Ok; if any failure is present, returns the first Err. * * @template T * @template E @@ -65,11 +65,11 @@ public static function combine(iterable $results): Result } /** - * ネストした Result を 1 段平坦化します. + * Flattens a nested Result by one level. * - * インスタンスメソッドにしないのは、PHPStan の条件型ではテンプレート T を - * Result に分解できない（infer がない）ため。静的ヘルパーなら - * パラメータ側のテンプレートで内側の型を正確に推論できます. + * This is not an instance method because PHPStan's conditional types cannot + * decompose the template T into Result (there is no infer). As a static + * helper, the inner type can be inferred precisely from the parameter-side template. * * @template T * @template E1 diff --git a/src/UnwrapException.php b/src/UnwrapException.php index 7f4a5ac..8bba1be 100644 --- a/src/UnwrapException.php +++ b/src/UnwrapException.php @@ -5,22 +5,22 @@ namespace Valbeat\Result; /** - * unwrap() / unwrapErr() を反対側の変種に対して呼び出したときに送出される例外です. + * The exception thrown when unwrap() / unwrapErr() is called on the opposite variant. * - * \LogicException を継承しているため、既存の catch (\LogicException) はそのまま動作します. - * メッセージには保持している値の要約が含まれます（Rust の panic メッセージに相当）. - * 注意: スカラー値はメッセージにそのまま（切り詰めの上）現れるため、機微な文字列を - * エラー値に載せる場合はログ出力先に注意してください. + * It extends \LogicException, so existing catch (\LogicException) blocks keep working. + * The message contains a summary of the held value (analogous to Rust's panic message). + * Note: scalar values appear in the message verbatim (after truncation), so be careful + * about where you log if you put sensitive strings in the error value. */ final class UnwrapException extends \LogicException { /** - * メッセージに埋め込む値要約の最大長（超過分は切り詰め）. + * The maximum length of the value summary embedded in the message (excess is truncated). */ private const int MAX_SUMMARY_LENGTH = 120; /** - * Err に対して unwrap() が呼ばれた場合の例外を生成します. + * Creates the exception for when unwrap() is called on an Err. */ public static function unwrapOnErr(mixed $error): self { @@ -28,7 +28,7 @@ public static function unwrapOnErr(mixed $error): self } /** - * Ok に対して unwrapErr() が呼ばれた場合の例外を生成します. + * Creates the exception for when unwrapErr() is called on an Ok. */ public static function unwrapErrOnOk(mixed $value): self { @@ -36,7 +36,7 @@ public static function unwrapErrOnOk(mixed $value): self } /** - * expect() / expectErr() 用に、呼び出し側のメッセージと値の要約から例外を生成します. + * Creates the exception for expect() / expectErr() from the caller's message and a value summary. */ public static function withMessage(string $message, mixed $value): self { @@ -44,9 +44,9 @@ public static function withMessage(string $message, mixed $value): self } /** - * 例外メッセージ用に値の要約を生成します. + * Builds a value summary for the exception message. * - * 要約は単一行に正規化し、MAX_SUMMARY_LENGTH を超える部分は切り詰めます. + * The summary is normalized to a single line and truncated beyond MAX_SUMMARY_LENGTH. */ private static function describe(mixed $value): string { @@ -61,8 +61,9 @@ private static function describe(mixed $value): string $summary = str_replace(["\r\n", "\r", "\n"], '\n', $summary); if (\strlen($summary) > self::MAX_SUMMARY_LENGTH) { - // バイト上限を守りつつ文字境界で切るため mb_strcut を使う（substr だと - // マルチバイト文字の途中で切れて不正な UTF-8 になり json_encode が失敗する）. + // Use mb_strcut to cut at a character boundary while respecting the byte limit + // (substr would cut in the middle of a multibyte character, producing invalid + // UTF-8 and making json_encode fail). return mb_strcut($summary, 0, self::MAX_SUMMARY_LENGTH, 'UTF-8') . '... (truncated)'; } @@ -70,8 +71,8 @@ private static function describe(mixed $value): string } /** - * Stringable の要約を生成します。__toString() が例外を投げてもこの例外を - * 置き換えないよう、失敗時はクラス名のみへフォールバックします. + * Builds a summary for a Stringable. To avoid replacing this exception when + * __toString() throws, it falls back to the class name only on failure. */ private static function describeStringable(\Stringable $value): string { @@ -83,8 +84,8 @@ private static function describeStringable(\Stringable $value): string } /** - * クラス名を返します。匿名クラスはファイルパス・行番号を除いた - * 「Foo@anonymous」形式に正規化します. + * Returns the class name. Anonymous classes are normalized to the + * "Foo@anonymous" form, stripping the file path and line number. */ private static function className(object $value): string { diff --git a/tests/ErrTest.php b/tests/ErrTest.php index e15c37c..57d473c 100644 --- a/tests/ErrTest.php +++ b/tests/ErrTest.php @@ -144,7 +144,7 @@ public function unwrap_withMultilineStringError_keepsMessageSingleLine(): void #[Test] public function unwrap_withLongMultibyteError_keepsValidUtf8Message(): void { - // 各文字 3 バイトなので、120 バイトの切り詰め境界が文字の途中に落ちる + // Each character is 3 bytes, so the 120-byte truncation boundary falls in the middle of a character $err = new Err(str_repeat('あ', 200)); try { @@ -379,7 +379,7 @@ public function chainingOperations_applies_transformations(): void } /** - * リテラル型を int に広げます（共変テンプレートは定数型を保持するため）. + * Widens a literal type to int (covariant templates preserve constant types). */ private static function asInt(int $value): int { @@ -387,7 +387,7 @@ private static function asInt(int $value): int } /** - * リテラル型を string に広げます（共変テンプレートは定数型を保持するため）. + * Widens a literal type to string (covariant templates preserve constant types). */ private static function asString(string $value): string { @@ -396,7 +396,7 @@ private static function asString(string $value): string } /** - * UnwrapException のメッセージが enum のケース名を含むことを検証するためのフィクスチャ. + * Fixture for verifying that the UnwrapException message contains the enum case name. */ enum SampleEnumError { diff --git a/tests/OkTest.php b/tests/OkTest.php index 3824549..27ba054 100644 --- a/tests/OkTest.php +++ b/tests/OkTest.php @@ -288,7 +288,7 @@ public function chainingOperations_applies_transformations(): void } /** - * リテラル型を int に広げます（共変テンプレートは定数型を保持するため）. + * Widens a literal type to int (covariant templates preserve constant types). */ private static function asInt(int $value): int { diff --git a/tests/ResultsTest.php b/tests/ResultsTest.php index ad4463d..47b6376 100644 --- a/tests/ResultsTest.php +++ b/tests/ResultsTest.php @@ -103,7 +103,7 @@ public function flatten_err_returns_outer_err(): void } /** - * リテラル型を Result, string> に widening するためのヘルパ. + * Helper for widening a literal type to Result, string>. * * @param Result, string> $result * diff --git a/tests/Types/result.php b/tests/Types/result.php index b7a0a0d..961be21 100644 --- a/tests/Types/result.php +++ b/tests/Types/result.php @@ -16,8 +16,8 @@ use Valbeat\Result\Results; /** - * 共変性のテスト: Ok (= Result) を - * Result として返せる. + * Covariance test: an Ok (= Result) can be + * returned as a Result. * * @return Result */ @@ -48,7 +48,7 @@ function findNameById(int $id): Result */ function testAndThenComposesErrorTypes(Result $result): void { - // andThen は異なるエラー型を返すコールバックを受け取れ、エラー型は E|F に合成される + // andThen accepts a callback that returns a different error type; the error type is combined into E|F $chained = $result->andThen(findNameById(...)); assertType('Valbeat\Result\Result', $chained); } @@ -67,7 +67,7 @@ function testAndComposesErrorTypes(Result $result, Result $other): void */ function testOrElseComposesSuccessTypes(Result $result): void { - // orElse は異なる成功型を返すコールバックを受け取れ、成功型は T|U に合成される + // orElse accepts a callback that returns a different success type; the success type is combined into T|U $recovered = $result->orElse(static fn (RuntimeException $e): Result => findNameById(0)); assertType('Valbeat\Result\Result', $recovered); } @@ -96,7 +96,7 @@ function testIsOkNarrowing(Result $result): void } /** - * isErr によるナローイング: true 側で Err、false 側で Ok に絞り込まれる. + * Narrowing via isErr: narrowed to Err on the true branch and Ok on the false branch. * * @param Result $result */ @@ -112,8 +112,8 @@ function testIsErrNarrowing(Result $result): void } /** - * 既知の制限: instanceof Ok の true 側分岐ではジェネリクスが失われ、unwrap は mixed になる. - * 型引数を保ったまま絞り込みたい場合は isOk() / isErr() を使う（testIsOkNarrowing 参照）. + * Known limitation: on the true branch of instanceof Ok the generics are lost, and unwrap becomes mixed. + * To narrow while preserving the type arguments, use isOk() / isErr() (see testIsOkNarrowing). * * @param Result $result */ @@ -126,7 +126,7 @@ function testInstanceofOkNarrowing(Result $result): void } /** - * sealed のテスト: instanceof Ok の else 分岐で Err に絞り込まれる. + * Sealed test: on the else branch of instanceof Ok, narrowed to Err. * * @param Result $result */ @@ -135,14 +135,14 @@ function testInstanceofNarrowing(Result $result): bool if ($result instanceof Ok) { return true; } - // sealed の効果: instanceof Ok の else 分岐で Err に絞り込まれる + // Effect of sealed: on the else branch of instanceof Ok, narrowed to Err assertType('Valbeat\Result\Err', $result); return false; } /** - * sealed の効果: Ok と Err で全ケース網羅と判断され、match が非網羅エラーにならない. + * Effect of sealed: Ok and Err are deemed to cover all cases, so match does not raise a non-exhaustive error. * * @param Result $result */ @@ -155,8 +155,8 @@ function testExhaustiveMatch(Result $result): string } /** - * 既知の制限: match 式の instanceof アームではジェネリクスが失われ mixed になる. - * 型引数を保ちたい場合は isOk() アームを使う（testMatchArmNarrowingWithIsOk 参照）. + * Known limitation: in a match expression's instanceof arm the generics are lost and become mixed. + * To preserve the type arguments, use an isOk() arm (see testMatchArmNarrowingWithIsOk). * * @param Result $result */ @@ -170,7 +170,7 @@ function testMatchArmNarrowing(Result $result): void } /** - * match 式のアーム内ナローイング: isOk() でも assert-if-true が効く. + * In-arm narrowing in a match expression: assert-if-true also works with isOk(). * * @param Result $result */ @@ -184,7 +184,7 @@ function testMatchArmNarrowingWithIsOk(Result $result): void } /** - * match() メソッドの戻り値は両コールバックの戻り値型 U|V に合成される. + * The return value of the match() method is combined into U|V from both callbacks' return types. * * @param Result $result */ @@ -198,7 +198,7 @@ function testMatchMethodComposesReturnTypes(Result $result, float $fallback): vo } /** - * inspect / inspectErr は型を変えない. + * inspect / inspectErr do not change the type. * * @param Result $result */ @@ -211,7 +211,7 @@ function testInspectPreservesType(Result $result): void } /** - * isOkAnd / isErrAnd / inspect のコールバック引数の型が推論される. + * The callback parameter types of isOkAnd / isErrAnd / inspect are inferred. * * @param Result $result */ @@ -236,7 +236,7 @@ function testCallbackParamInference(Result $result): void } /** - * コンストラクタからの型推論: new Ok / new Err で型引数が決まる. + * Type inference from the constructor: new Ok / new Err determine the type arguments. */ function testConstructorInference(int $value, RuntimeException $error): void { @@ -245,7 +245,7 @@ function testConstructorInference(int $value, RuntimeException $error): void } /** - * ジェネリック Result レシーバでの unwrap / unwrapErr は条件付き戻り値型が解決される. + * unwrap / unwrapErr on a generic Result receiver resolve their conditional return types. * * @param Result $result */ @@ -256,7 +256,7 @@ function testUnwrapOnGenericReceiver(Result $result): void } /** - * expect / expectErr も unwrap / unwrapErr と同じ条件付き戻り値型が解決される. + * expect / expectErr resolve the same conditional return types as unwrap / unwrapErr. * * @param Result $result */ @@ -267,7 +267,7 @@ function testExpectOnGenericReceiver(Result $result): void } /** - * 具象レシーバでの unwrapOr / unwrapOrElse: 実行時に起こり得ない側の型を混ぜない. + * unwrapOr / unwrapOrElse on a concrete receiver: do not mix in the type of the branch that cannot occur at runtime. * * @param Ok $ok * @param Err $err @@ -283,7 +283,7 @@ function testConcreteUnwrapVariants(Ok $ok, Err $err, string $default, float $fa } /** - * ネストした Result の平坦化: andThen が内側の成功型と両エラー型の合成を推論できる. + * Flattening a nested Result: andThen can infer the inner success type and the combination of both error types. * * @param Result, LogicException> $nested */ @@ -294,39 +294,39 @@ function testNestedResultFlattening(Result $nested): void } /** - * 具象 Ok レシーバでは no-op 側のメソッドが実行時に起こり得ない型を混ぜない. + * On a concrete Ok receiver, the no-op-side methods do not mix in types that cannot occur at runtime. * * @param Ok $ok */ function testConcreteOkPrecision(Ok $ok): void { - // or/orElse は $this を返すため Ok のまま + // or/orElse return $this, so it stays Ok assertType('Valbeat\Result\Ok', $ok->orElse(static fn (never $e): Result => findNameById(0))); assertType('Valbeat\Result\Ok', $ok->or(findNameById(0))); - // mapErr は no-op + // mapErr is a no-op assertType('Valbeat\Result\Ok', $ok->mapErr(static fn (never $e): LogicException => $e)); - // map は Ok を返す + // map returns Ok assertType('Valbeat\Result\Ok', $ok->map(stringify(...))); - // mapOr/mapOrElse は常に $fn の結果（デフォルト値の型は混ざらない） + // mapOr/mapOrElse always yield the result of $fn (the default value's type is not mixed in) assertType('string', $ok->mapOr(0.5, stringify(...))); assertType('string', $ok->mapOrElse(static fn (): float => 0.5, stringify(...))); } /** - * 具象 Err レシーバでは no-op 側のメソッドが実行時に起こり得ない型を混ぜない. + * On a concrete Err receiver, the no-op-side methods do not mix in types that cannot occur at runtime. * * @param Err $err */ function testConcreteErrPrecision(Err $err, float $fallback): void { - // and/andThen は $this を返すため Err のまま + // and/andThen return $this, so it stays Err assertType('Valbeat\Result\Err', $err->andThen(static fn (never $v): Result => findNameById(0))); assertType('Valbeat\Result\Err', $err->and(findNameById(0))); - // map は no-op + // map is a no-op assertType('Valbeat\Result\Err', $err->map(static fn (never $v): int => $v)); - // mapErr は Err を返す + // mapErr returns Err assertType('Valbeat\Result\Err', $err->mapErr(static fn (RuntimeException $e): LogicException => new LogicException($e->getMessage()))); - // mapOr/mapOrElse は常にデフォルト側（$fn の戻り値型は混ざらない） + // mapOr/mapOrElse always yield the default side (the return type of $fn is not mixed in) assertType('float', $err->mapOr($fallback, static fn (never $v): string => $v)); assertType('float', $err->mapOrElse(static fn (): float => $fallback, static fn (never $v): string => $v)); } @@ -362,7 +362,7 @@ function testMap(Result $result): void } /** - * エラー側の網羅性テスト用フィクスチャ: native enum. + * Fixture for error-side exhaustiveness tests: native enum. */ enum HttpError { @@ -371,7 +371,7 @@ enum HttpError } /** - * エラー側の網羅性テスト用フィクスチャ: @phpstan-sealed なエラー union. + * Fixture for error-side exhaustiveness tests: a @phpstan-sealed error union. * * @phpstan-sealed ValidationFailure|NetworkFailure */ @@ -388,9 +388,9 @@ final class NetworkFailure implements AppError } /** - * エラー型が native enum の場合: isErr() 経由なら unwrapErr() が enum 型を保ち、 - * 全ケースを網羅する match は default なしで網羅と認識される. - * （いずれかのケースを落とすと phpstan analyse がエラーになるため、これ自体が網羅性のピン留めになる） + * When the error type is a native enum: via isErr(), unwrapErr() preserves the enum type, and + * a match covering all cases is recognized as exhaustive without a default. + * (Dropping any case makes phpstan analyse fail, so this itself pins down the exhaustiveness.) * * @param Result $result */ @@ -410,8 +410,8 @@ function testEnumErrorExhaustiveness(Result $result): string } /** - * エラー型が @phpstan-sealed union の場合: isErr() 経由で取り出した値に対する - * match(true)+instanceof が網羅と認識される（sealed 指定が前提。エラークラスは非ジェネリックなので型引数喪失は起きない）. + * When the error type is a @phpstan-sealed union: for a value extracted via isErr(), + * match(true)+instanceof is recognized as exhaustive (the sealed annotation is required; the error classes are non-generic, so no type-argument loss occurs). * * @param Result $result */ @@ -431,8 +431,8 @@ function testSealedErrorExhaustiveness(Result $result): string } /** - * 既知の落とし穴のピン留め（enum エラー）: instanceof Err では E が失われ、 - * enum であっても unwrapErr() は mixed になる。値を扱う分岐は isErr() を使う（上の2ケース参照）. + * Pinning down a known pitfall (enum error): with instanceof Err, E is lost, and even for an + * enum unwrapErr() becomes mixed. In branches that handle the value, use isErr() (see the two cases above). * * @param Result $result */ @@ -444,8 +444,8 @@ function testInstanceofErrLosesEnumErrorType(Result $result): void } /** - * 既知の落とし穴のピン留め（sealed エラー）: sealed union でも instanceof Err では - * E が失われ unwrapErr() は mixed になる. + * Pinning down a known pitfall (sealed error): even with a sealed union, instanceof Err + * loses E and unwrapErr() becomes mixed. * * @param Result $result */ @@ -457,7 +457,7 @@ function testInstanceofErrLosesSealedErrorType(Result $result): void } /** - * Results::try は戻り値の型を Ok 側に、送出されうる例外を Throwable として Err 側に推論する. + * Results::try infers the return type on the Ok side and the potentially thrown exception as Throwable on the Err side. */ function testTryInference(): void { @@ -465,7 +465,7 @@ function testTryInference(): void } /** - * Results::combine は iterable> から Result, E> を推論する. + * Results::combine infers Result, E> from iterable>. * * @param list> $results */ @@ -475,7 +475,7 @@ function testCombineInference(array $results): void } /** - * Results::flatten はネストした Result の内側の成功型と両エラー型の合成を推論する. + * Results::flatten infers the inner success type of a nested Result and the combination of both error types. * * @param Result, LogicException> $nested */