feat(validator)!: return empty errors list from tryValidate on success

- Return [] instead of null so consumers can iterate without a null-guard
- Drop ?? [] guards in schema validators that consume nested tryValidate errors
- Update docs, CHANGELOG, and tests for the new tuple shape

BREAKING CHANGE: tryValidate() now returns an empty errors list on success instead of null. Check $valid or $errors === [] rather than $errors === null.

Author: lemmon

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Changed
+
+- **BREAKING:** the errors element of the `tryValidate()` tuple is now an empty list `[]` on success (previously `null`), so consumers can iterate or count the errors without a null-guard. Code that detected success via `$errors === null` should check `$valid` (or `$errors === []`) instead; `$valid` remains the canonical success signal
+
 ## [0.16.0] - 2026-07-06
 
 ### Added

docs/getting-started/basic-usage.md

@@ -62,8 +62,8 @@ try {
 
 ### `tryValidate()` - Tuple-based
 
-Returns a tuple `[bool $valid, mixed $data, ?array $errors]`, where `$errors` is a flat list of
-`ValidationError` objects (or `null` on success):
+Returns a tuple `[bool $valid, mixed $data, array $errors]`, where `$errors` is a flat list of
+`ValidationError` objects (empty on success):
 
 ```php
 $validator = Validator::isString()->email();

docs/getting-started/core-concepts.md

@@ -40,7 +40,7 @@ All validators extend `FieldValidator`, which provides:
 ### Core Validation Methods
 
 - `validate(mixed $value): mixed` - Throws exception on failure
-- `tryValidate(mixed $value): array` - Returns `[bool $valid, mixed $data, ?array $errors]`, where `$errors` is a list of `ValidationError` objects
+- `tryValidate(mixed $value): array` - Returns `[bool $valid, mixed $data, array $errors]`, where `$errors` is a list of `ValidationError` objects (empty on success)
 
 ### Common Configuration
 

docs/guides/error-handling.md

@@ -26,8 +26,8 @@ try {
 
 ### Tuple-Based: `tryValidate()`
 
-Returns a result tuple `[bool $valid, mixed $data, ?array $errors]`, where `$errors` is a flat
-list of `ValidationError` objects (or `null` on success):
+Returns a result tuple `[bool $valid, mixed $data, array $errors]`, where `$errors` is a flat
+list of `ValidationError` objects (empty on success):
 
 ```php
 $validator = Validator::isString()->email();

llms.txt

@@ -23,7 +23,7 @@
 - **Fluency:** Validators are mutable during configuration but used sequentially.
 - **Execution:**
   - `validate(mixed $value, string $key = '', mixed $input = null)` throws `ValidationException`.
-  - `tryValidate(mixed $value, string $key = '', mixed $input = null)` returns tuple `[bool $valid, mixed $data, ?array $errors]`, where `$errors` is a flat list of `ValidationError` objects (or `null` on success).
+  - `tryValidate(mixed $value, string $key = '', mixed $input = null)` returns tuple `[bool $valid, mixed $data, array $errors]`, where `$errors` is a flat list of `ValidationError` objects (empty on success, so it can be iterated without a null-guard).
 - **Fail-Fast:** Each validator chain stops at the first failing rule; schema validators aggregate errors across fields.
 - **Error Structure:** Validation errors are a flat list of `ValidationError` value objects, each with `getPath()` (dotted, `''` at root), `getCode()` (stable code, see `ValidationCode`), `getMessage()`, and `getParams()`. Access via `ValidationException::getErrors(?string $path = null)` or the `tryValidate` tuple. `getErrors()` (no arg) returns every error; `getErrors($path)` filters to a field and everything nested beneath it (`getErrors('')` returns only root-level errors; the trailing-dot match means `getErrors('name')` won't catch `name_full`). Match on codes, not message text. `satisfies()` accepts optional `(?string $code, array $params)`; params double as `{name}` message placeholders. `ValidationError` is `JsonSerializable` (`{path, code, message, params}`), so `json_encode($e->getErrors())` is API-ready; malformed UTF-8 param keys are normalized during serialization, and unencodable param values render as `"(complex value)"`.
 - **Null Handling:** Validators skip `null` values unless `required()` is called. `default()` fills in null as a last-resort fallback after the pipeline; `required()` enforces presence at the very end.

src/Lemmon/Validator/ArrayValidator.php

@@ -308,7 +308,7 @@ protected function validateType(mixed $value, string $key): mixed
                 );
 
                 if (!$valid) {
-                    foreach ($itemErrors ?? [] as $error) {
+                    foreach ($itemErrors as $error) {
                         $errors[] = $error->withPathPrefix((string) $index);
                     }
                     continue;

src/Lemmon/Validator/AssociativeValidator.php

@@ -70,7 +70,7 @@ protected function validateType(mixed $value, string $key): mixed
             );
 
             if (!$valid) {
-                foreach ($fieldErrors ?? [] as $error) {
+                foreach ($fieldErrors as $error) {
                     $errors[] = $error->withPathPrefix((string) $fieldKey);
                 }
                 continue;

src/Lemmon/Validator/FieldValidator.php

@@ -620,7 +620,7 @@ public function validate(mixed $value, string $key = '', mixed $input = null): m
         [$valid, $data, $errors] = $this->tryValidate($value, $key, $input);
         if (!$valid) {
             throw new ValidationException(
-                $errors ?? [new ValidationError('', ValidationCode::CUSTOM, 'Validation failed')],
+                $errors !== [] ? $errors : [new ValidationError('', ValidationCode::CUSTOM, 'Validation failed')],
             );
         }
         return $data;
@@ -632,10 +632,10 @@ public function validate(mixed $value, string $key = '', mixed $input = null): m
      * @param mixed $value The value to validate.
      * @param string $key The key of the field being validated.
      * @param mixed|null $input The entire input payload (array or object).
-     * @return array{bool, mixed, array<ValidationError>|null} A tuple containing:
+     * @return array{bool, mixed, array<ValidationError>} A tuple containing:
      *                                                 - bool: true if validation is successful, false otherwise.
      *                                                 - mixed: The validated and potentially coerced value on success, or the (possibly coerced) input value on failure.
-     *                                                 - array|null: A list of structured {@see ValidationError} objects on failure, or null on success.
+     *                                                 - array: A list of structured {@see ValidationError} objects on failure, or an empty list on success, so consumers can iterate it unconditionally.
      */
     public function tryValidate(mixed $value, string $key = '', mixed $input = null): array
     {
@@ -671,7 +671,7 @@ public function tryValidate(mixed $value, string $key = '', mixed $input = null)
                 ]);
             }
 
-            return [true, $processedValue, null];
+            return [true, $processedValue, []];
         } catch (ValidationException $e) {
             return [false, $value, $e->getErrors()];
         }

src/Lemmon/Validator/ObjectValidator.php

@@ -70,7 +70,7 @@ protected function validateType(mixed $value, string $key): mixed
             );
 
             if (!$valid) {
-                foreach ($fieldErrors ?? [] as $error) {
+                foreach ($fieldErrors as $error) {
                     $errors[] = $error->withPathPrefix((string) $fieldKey);
                 }
                 continue;

tests/ArrayValidatorTest.php

@@ -167,7 +167,7 @@
     [$valid, $data, $errors] = $validator->tryValidate(null);
     expect($valid)->toBe(true);
     expect($data)->toBe(null);
-    expect($errors)->toBe(null);
+    expect($errors)->toBe([]);
 });
 
 it('should coerce empty string to empty array', function () {