fix(FieldValidator): simplify tryValidate() and fix default/required interaction

- Fix critical bug where required() rejected null before default() could apply its fallback
- Simplify tryValidate() from 67-line multi-branch flow to 33-line linear pipeline
- Remove duplicated early returns, mid-loop default checks, and mid-loop required checks
- default() now applies in exactly one place: after the pipeline, as last-resort fallback
- required() now checks in exactly one place: at the very end, after default
- Update docs (CHANGELOG, README, core-concepts, basic-usage, llms.txt) to reflect new flow

Author: lemmon

CHANGELOG.md

@@ -8,6 +8,25 @@ All notable changes to this project will be documented in this file.
 
 - `uniqueField(string $fieldName, ?string $message = null)` on `ArrayValidator` for cross-item uniqueness validation of a nested field; convenience wrapper around `satisfies()` that produces field-level error paths by structuring errors as `[index => [fieldName => [message]]]`; all members of a duplicate group receive errors (e.g., both `symlinks.0.destination` and `symlinks.2.destination`); skips items where the field is null or missing; works with both associative arrays and objects; uses strict comparison via `serialize()` to distinguish types
 
+### Fixed
+
+- **CRITICAL BUG**: Fixed `default()` and `required()` interaction -- `required()` was rejecting null values before `default()` had a chance to provide a fallback
+  - **Issue**: Chaining `->default($value)->required()` always threw "Value is required" for null inputs because `required` checked for null before `default` was applied
+  - **Root Cause**: `tryValidate()` had a scattered, multi-branch architecture with `default` and `required` checks duplicated across 5+ locations (early returns, pre-pipeline, mid-loop, post-loop), making the interaction order unpredictable
+  - **Fix**: Simplified `tryValidate()` to a clean linear 4-step flow: coerce, type check, pipeline, then default-before-required at the end
+  - **Impact**: `default()` and `required()` now work cooperatively -- `default()` is the last-resort fallback for null, `required()` only fails if the value is still null after default
+  - **Real-World Benefit**: Enables patterns like `->pipe(fn($x) => null)->default($fallback)->required()` where a pipeline step intentionally nullifies a value and `default()` catches it before `required()` enforces presence
+
+### Changed
+
+- **Simplified `tryValidate()` pipeline architecture** -- reduced from 67 lines with 5+ branch points to 33 lines with a linear flow
+  - Removed 2 duplicated early returns for null + no-pipeline + not-required
+  - Removed mid-loop `default()` and `required()` checks (were duplicating post-loop logic)
+  - `default()` now applies in exactly one place: after the pipeline, as the last-resort fallback
+  - `required()` now checks in exactly one place: at the very end, after default has had its chance
+  - Pipeline always runs fully without mid-step bailouts
+  - Validation flow is now: **coerce -> type check -> pipeline -> default -> required**
+
 ## [0.13.0] - 2026-03-06
 
 ### Added

README.md

@@ -29,6 +29,7 @@ Rather than reimplementing every possible transformation or validation rule, Lem
 - **Smart Null Handling**: Validations skip `null` unless `required()`. `transform()` runs on `null`, while `pipe()` and `nullifyEmpty()` skip `null` for type safety.
 - **Form Safety First**: Empty strings coerce to `null` (not dangerous `0`/`false`) to prevent real-world issues like accidental zero bank balances
 - **Fluent API with Execution Order Guarantee**: Validation rules read like natural language and execute in the exact order written -- `Validator::isString()->pipe('trim')->nullifyEmpty()->required()`
+- **Last-Resort Default**: `default()` is a flag applied after the pipeline -- fills in null only as a last resort, before `required()` enforces presence
 - **Fail-Fast Per Field**: Each validator stops at the first failing rule, while schema validation still aggregates errors across fields
 - **API-Friendly Error Format**: Flattened errors with field paths (`'_root'` for root-level, dot notation for nested) perfect for frontend consumption
 - **Type-Aware Transformations**: Intelligent transformation system that maintains type context and handles coercion automatically

docs/getting-started/basic-usage.md

@@ -152,7 +152,7 @@ $result = $safeQuantity->validate('5'); // Returns: 5
 
 ### Execution Order Matters
 
-**Critical**: Pipeline steps execute in the **exact order written**. This matters for `pipe()`, `transform()`, and `nullifyEmpty()`. `required()` is a flag, so its position does not change execution order.
+**Critical**: Pipeline steps execute in the **exact order written**. This matters for `pipe()`, `transform()`, and `nullifyEmpty()`. Both `required()` and `default()` are flags -- their position does not change execution order. `default()` fills in null after the pipeline as a last resort; `required()` enforces presence at the very end.
 
 ```php
 // Order matters for transformations

docs/getting-started/core-concepts.md

@@ -121,14 +121,13 @@ Validator::isObject($schema)            // stdClass object with schema
 
 Understanding the validation flow helps debug and optimize your validators:
 
-1. **Input Received** - Raw value passed to validator
-2. **Type Coercion** - If enabled, attempt type conversion
-3. **Required Check** - If required and value is null → error
-4. **Type Validation** - Check value type (skipped for null when the pipeline is present)
-5. **Pipeline Execution** - Validations and transformations run in the order written (fail-fast per field)
-6. **Required Re-Check** - If transformations produce null on a required field → error
-7. **Default Application** - If final result is null and a default exists → apply default
-8. **Return Result** - Return validated/coerced/transformed value or errors
+1. **Type Coercion** - If enabled, attempt type conversion (empty strings become `null` for primitives)
+2. **Type Validation** - Check value type (skipped for null -- lets the pipeline and default/required handle it)
+3. **Pipeline Execution** - Validations and transformations run in the order written (fail-fast per field)
+4. **Default** - Last-resort fallback: if the result is null and a default exists, apply it
+5. **Required** - Single check, always last: if the value is still null after default, fail
+
+`default()` and `required()` are both flags -- their position in the fluent chain does not change when they are evaluated. `default()` always applies after the pipeline as the last-resort fallback for null. `required()` always enforces presence at the very end, after default has had its chance.
 
 ## Data Transformations
 
@@ -257,7 +256,7 @@ $processed = Validator::isArray()
 
 ### Transformation Pipeline Order
 
-Pipeline methods (`pipe()`, `transform()`, `nullifyEmpty()`, `satisfies()`, etc.) execute in their written order. `required()` is a flag, so its position does not change execution order:
+Pipeline methods (`pipe()`, `transform()`, `nullifyEmpty()`, `satisfies()`, etc.) execute in their written order. `required()` and `default()` are flags -- their position does not change execution order:
 
 ```php
 // Execution order: trim → nullifyEmpty
@@ -316,7 +315,7 @@ $nameValidator->validate('    ');     // ❌ "Name is required" (trimmed to empt
 ->pipe('trim')->nullifyEmpty()->required()
 ```
 
-You expect: trim → nullify → required check, and that's exactly what happens. `required()` is a flag and is enforced after the pipeline regardless of where it appears in the chain.
+You expect: trim → nullify → required check, and that's exactly what happens. Both `required()` and `default()` are flags evaluated after the pipeline, regardless of where they appear in the chain. `default()` fills in null as a last resort, then `required()` enforces presence.
 
 **Flexibility**: Different orders enable different behaviors for different use cases:
 

llms.txt

@@ -10,7 +10,7 @@
   - **Transformations**:
     - `pipe(callable)`: Skips `null` values (type-preserving, expects specific type).
     - `transform(callable, bool $skipNull = true)`: Skips `null` by default (most type conversions don't need null). Set `$skipNull = false` to process null values.
-- **Pipeline Order:** Pipeline steps execute in the exact order defined; `required()` is a flag enforced after the pipeline regardless of position.
+- **Pipeline Order:** Pipeline steps execute in the exact order defined. `default()` and `required()` are flags evaluated after the pipeline regardless of position: `default()` is the last-resort fallback for null, `required()` enforces presence after default has had its chance.
 - **Transformation Types:**
   - `pipe(callable)`: Intended for sanitization. Preserves type context and applies type-coercion to result.
   - `transform(callable)`: Intended for type conversion. Updates type context; no coercion.
@@ -25,8 +25,8 @@
   - `tryValidate(mixed $value, string $key = '', mixed $input = null)` returns tuple `[bool $valid, mixed $data, ?array $errors]`.
 - **Fail-Fast:** Each validator chain stops at the first failing rule; schema validators aggregate errors across fields.
 - **Error Structure:** `ValidationException` contains nested array of error messages. Use `getFlattenedErrors()` for API format `[{path: string, message: string}]`.
-- **Null Handling:** Validators skip `null` values unless `required()` is called.
-- **Pipeline:** Supports both validation (`satisfies`) and transformation (`transform`, `pipe`).
+- **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.
+- **Pipeline:** Supports both validation (`satisfies`) and transformation (`transform`, `pipe`). Flow: coerce -> type check -> pipeline -> default -> required.
 - **Coercion:** `coerce()` enables smart type conversion (e.g., "true" -> `true`). Non-coercible values pass through unchanged.
 - **Form Safety:** Empty strings `''` are treated as `null` for primitives if coerced.
 
@@ -183,7 +183,7 @@ oneOf(array $values, ?string $message = null): static // Deprecated alias for in
 Validator::isString()
     ->pipe('trim')  // Transformation: "  \n  " → "" (preserves string type, skips null)
     ->nullifyEmpty()  // Transformation: "" → null (converts empty string/array to null)
-    ->required()  // Validation flag: enforced after pipeline, throws if value is null
+    ->required()  // Flag: enforced after pipeline + default(); throws if value is still null
     ->date('Y-m-d')  // Validation: checks format Y-m-d (skips null, but required() ensures non-null)
     ->transform(fn($s) => DateTime::createFromFormat('Y-m-d', $s)); // Transformation: String → DateTime (receives validated string)
 // With valid input "2024-01-15": "2024-01-15" → trim → "2024-01-15" → nullifyEmpty (no-op) → date validation → transform receives "2024-01-15" → DateTime

src/Lemmon/Validator/FieldValidator.php

@@ -377,57 +377,33 @@ public function validate(mixed $value, string $key = '', array $input = []): mix
      */
     public function tryValidate(mixed $value, string $key = '', mixed $input = null): array
     {
-        // Handle initial null values - only return early if no pipeline, no default, and not required
-        if (is_null($value) && count($this->pipeline) === 0 && !$this->required) {
-            return $this->hasDefault ? [true, $this->default, null] : [true, null, null];
-        }
-
-        $value = $this->coerce ? $this->coerceValue($value) : $value;
-
-        // Handle null values after coercion - only return early if no pipeline, no default, and not required
-        if (is_null($value) && count($this->pipeline) === 0 && !$this->required) {
-            return $this->hasDefault ? [true, $this->default, null] : [true, null, null];
+        // Coerce input
+        if ($this->coerce) {
+            $value = $this->coerceValue($value);
         }
 
         try {
-            // Check required first for null values
-            if ($this->required && is_null($value)) {
-                throw new ValidationException([$this->requiredMessage]);
-            }
-
-            // Skip type validation for null values if we have pipeline (let pipeline handle it)
-            $processedValue = is_null($value) && count($this->pipeline) > 0
-                ? $value
-                : $this->validateType($value, $key);
+            // Type validation (skip null -- default/required will handle it)
+            $processedValue = is_null($value) ? $value : $this->validateType($value, $key);
 
-            // Execute the unified pipeline with smart null handling
+            // Execute pipeline
             foreach ($this->pipeline as $step) {
-                $operation = $step['operation'];
-                $type = $step['type'];
-                $skipNull = $step['skipNull'];
-
-                // Smart null handling: validations always skip null, transformations skip based on skipNull flag
-                // pipe() transformations skip null (type-preserving, expect specific type)
-                // transform() transformations execute on null (can handle null and change types)
-                if (is_null($processedValue)) {
-                    if ($type === PipelineType::VALIDATION || $skipNull) {
-                        continue;
-                    }
-                }
-
-                $processedValue = $operation($processedValue, $key, $input);
-
-                // Check required again if value became null during transformations
-                if ($this->required && is_null($processedValue)) {
-                    throw new ValidationException([$this->requiredMessage]);
+                if (is_null($processedValue) && ($step['type'] === PipelineType::VALIDATION || $step['skipNull'])) {
+                    continue;
                 }
+                $processedValue = $step['operation']($processedValue, $key, $input);
             }
 
-            // Apply default if final result is null
+            // Default -- last resort fallback for null
             if (is_null($processedValue) && $this->hasDefault) {
                 $processedValue = $this->default;
             }
 
+            // Required -- single check, always last
+            if ($this->required && is_null($processedValue)) {
+                throw new ValidationException([$this->requiredMessage]);
+            }
+
             return [true, $processedValue, null];
         } catch (ValidationException $e) {
             return [false, $value, $e->getErrors()];