feat(transform): skip null by default with configurable parameter

BREAKING CHANGE: transform() now skips null values by default (was executing on null)

- Add $skipNull parameter (default: true) to transform() method
- Most type conversions don't need null handling, making this safer and more efficient
- Use transform($fn, skipNull: false) when null processing is needed
- Update tests to reflect new default behavior and add explicit null handling test
- Update documentation (llms.txt, guides) with examples and migration notes
- Update CHANGELOG.md with breaking change details

Refs: Real-world feedback on null handling efficiency

Author: lemmon

CHANGELOG.md

@@ -4,16 +4,25 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Changed
+- **BREAKING**: `transform()` now skips `null` values by default (was executing on null)
+  - **Rationale**: Most type conversions don't need null handling, making this safer and more efficient by default
+  - **Migration**: Use `transform($fn, skipNull: false)` if you need to process null values (e.g., `transform(fn($v) => $v ?? 'fallback', skipNull: false)`)
+  - **Impact**: Existing code that relied on `transform()` executing on null will need to explicitly set `skipNull: false`
+  - **Real-World Benefit**: Prevents errors when null values reach type conversions like `DateTime::createFromFormat()`, `explode()`, `strlen()`, etc.
+
 ### Added
 - `notEmpty()` convenience method for `StringValidator` and `ArrayValidator` to reject empty strings/arrays
 - `between()` shorthand for string length and numeric range constraints with unified error messages
 - `in()` alias for `oneOf()` on primitive validators for clearer allowed-value validation
+- `transform()` method now accepts optional `$skipNull` parameter (default: `true`) to configure null handling
 
 ### Deprecated
 - `oneOf()` in favor of `in()` (alias retained for backward compatibility)
 
 ### Documentation
 - Clarified fail-fast behavior per field and schema-level error aggregation in guides and examples
+- Updated transformation documentation to reflect new null handling behavior
 
 ## [0.11.2] - 2026-01-05
 

docs/getting-started/basic-usage.md

@@ -305,7 +305,7 @@ $count = Validator::isString()
 
 - **Use `pipe()`** for same-type operations (string → string, array → array)
 - **Use `transform()`** for type changes (string → array, array → int)
-- **Null handling** - `pipe()` skips null values to avoid type errors, `transform()` runs on null so you can map it to a new value
+- **Null handling** - `pipe()` skips null values to avoid type errors, `transform()` skips null by default. Use `transform($fn, skipNull: false)` to process null values.
 
 ```php
 // Correct usage
@@ -314,6 +314,16 @@ $result = Validator::isArray()
     ->transform(fn($v) => implode(',', $v))    // Array → String (type change)
     ->pipe('trim', 'strtoupper')               // String operations (same type)
     ->validate(['a', 'b', 'a']); // Returns: "A,B"
+
+// Null handling: default behavior (skips null)
+$date = Validator::isString()
+    ->transform(fn($v) => DateTime::createFromFormat('Y-m-d', $v))
+    ->validate(null); // Returns: null (transform skipped, safe)
+
+// Null handling: explicit processing when needed
+$withFallback = Validator::isString()
+    ->transform(fn($v) => $v ?? 'Not provided', skipNull: false)
+    ->validate(null); // Returns: 'Not provided' (transform executed)
 ```
 
 ## Next Steps

docs/getting-started/core-concepts.md

@@ -141,7 +141,26 @@ $result = Validator::isString()
 - **Changes type context** - Updates internal type tracking
 - **No type coercion** - Returns exactly what the transformer produces
 - **Enables type switching** - Subsequent `pipe()` operations work with the new type
-- **Null handling** - `transform()` runs even when the current value is null so you can map null to a new value or type
+- **Null handling** - `transform()` skips null by default (most type conversions don't need null). Use `transform($fn, skipNull: false)` to process null values.
+
+**Null Handling Examples:**
+
+```php
+// Default behavior: skips null (most common case)
+$result = Validator::isString()
+    ->transform(fn($v) => DateTime::createFromFormat('Y-m-d', $v))
+    ->validate(null); // Returns: null (transform skipped, no error)
+
+// Explicit null processing: when you need to handle null
+$result = Validator::isString()
+    ->transform(fn($v) => $v ?? 'N/A', skipNull: false)
+    ->validate(null); // Returns: 'N/A' (transform executed on null)
+
+// Converting null to empty array
+$result = Validator::isArray()
+    ->transform(fn($v) => $v === null ? [] : $v, skipNull: false)
+    ->validate(null); // Returns: [] (null converted to empty array)
+```
 
 #### `pipe()` - Type-Preserving Transformations
 

llms.txt

@@ -8,7 +8,7 @@
   - **Validations** (`satisfies`, `min`, `email`): Skip `null` values.
   - **Transformations**:
     - `pipe(callable)`: Skips `null` values (type-preserving, expects specific type).
-    - `transform(callable)`: Executes on `null` (can handle null and change types).
+    - `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.
 - **Transformation Types:**
   - `pipe(callable)`: Intended for sanitization. Preserves type context and applies type-coercion to result.
@@ -60,7 +60,7 @@ satisfiesAll(array<callable|FieldValidator> $rules, ?string $message = null): st
 satisfiesNone(array<callable|FieldValidator> $rules, ?string $message = null): static
 
 // Transformation
-transform(callable $fn): static (can change type)
+transform(callable $fn, bool $skipNull = true): static (can change type, skips null by default)
 pipe(callable ...$fns): static (preserves type, skips null)
 ```
 

src/Lemmon/Validator/AllowedValuesTrait.php

@@ -25,7 +25,7 @@ trait AllowedValuesTrait
      * @param ?string $message Optional custom error message.
      * @return $this
      */
-    public function in(array $values, null|string $message = null): self
+    public function in(array $values, ?string $message = null): self
     {
         return $this->satisfies(
             static fn ($value) => in_array($value, $values, true),
@@ -43,7 +43,7 @@ public function in(array $values, null|string $message = null): self
      *
      * @deprecated Use in() instead.
      */
-    public function oneOf(array $values, null|string $message = null): self
+    public function oneOf(array $values, ?string $message = null): self
     {
         return $this->in($values, $message);
     }

src/Lemmon/Validator/ArrayValidator.php

@@ -6,7 +6,7 @@
 
 class ArrayValidator extends FieldValidator
 {
-    private null|FieldValidator $itemValidator = null;
+    private ?FieldValidator $itemValidator = null;
     private bool $filterEmpty = false;
 
     /**
@@ -47,7 +47,7 @@ public function filterEmpty(): self
      * @param null|string $message Custom error message
      * @return $this
      */
-    public function notEmpty(null|string $message = null): static
+    public function notEmpty(?string $message = null): static
     {
         return $this->minItems(1, $message ?? 'Value must not be empty');
     }
@@ -59,7 +59,7 @@ public function notEmpty(null|string $message = null): static
      * @param null|string $message Custom error message
      * @return $this
      */
-    public function minItems(int $min, null|string $message = null): static
+    public function minItems(int $min, ?string $message = null): static
     {
         return $this->satisfies(
             static fn ($value, $key = null, $input = null) => count($value) >= $min,
@@ -74,7 +74,7 @@ public function minItems(int $min, null|string $message = null): static
      * @param null|string $message Custom error message
      * @return $this
      */
-    public function maxItems(int $max, null|string $message = null): static
+    public function maxItems(int $max, ?string $message = null): static
     {
         return $this->satisfies(
             static fn ($value, $key = null, $input = null) => count($value) <= $max,
@@ -89,7 +89,7 @@ public function maxItems(int $max, null|string $message = null): static
      * @param null|string $message Custom error message
      * @return $this
      */
-    public function contains(mixed $valueOrValidator, null|string $message = null): static
+    public function contains(mixed $valueOrValidator, ?string $message = null): static
     {
         return $this->satisfies(
             static function ($value, $key = null, $input = null) use ($valueOrValidator) {

src/Lemmon/Validator/FieldValidator.php

@@ -10,7 +10,7 @@ abstract class FieldValidator
     protected bool $hasDefault = false;
     protected bool $coerce = false;
     protected bool $required = false;
-    protected null|string $requiredMessage = null;
+    protected ?string $requiredMessage = null;
 
     /**
      * Creates a deep copy of the validator, including pipeline closures bound to the clone.
@@ -29,15 +29,15 @@ public function clone(): static
     /**
      * Current type context for transformations (null = original validator type)
      */
-    protected null|string $currentType = null;
+    protected ?string $currentType = null;
 
     /**
      * Marks the field as required.
      *
      * @param string|null $message Custom error message for required validation
      * @return $this
      */
-    public function required(null|string $message = null): self
+    public function required(?string $message = null): self
     {
         $this->required = true;
         $this->requiredMessage = $message ?? 'Value is required';
@@ -92,10 +92,8 @@ public function nullifyEmpty(): self
      * @param ?string $message Optional custom error message. If not provided, a generic message is used.
      * @return $this
      */
-    public function satisfies(
-        callable|FieldValidator $validation,
-        null|string $message = null,
-    ): self {
+    public function satisfies(callable|FieldValidator $validation, ?string $message = null): self
+    {
         $rule = $validation instanceof FieldValidator
             // Convert FieldValidator to callable
             ? static function ($value, $key = null, $input = null) use ($validation) {
@@ -135,7 +133,7 @@ public function addValidation(callable $validation, string $message): self
      * @param ?string $message Custom error message.
      * @return $this
      */
-    public function satisfiesAll(array $validations, null|string $message = null): self
+    public function satisfiesAll(array $validations, ?string $message = null): self
     {
         return $this->satisfies(static function ($value, $key = null, $input = null) use (
             $validations,
@@ -161,7 +159,7 @@ public function satisfiesAll(array $validations, null|string $message = null): s
      * @deprecated Use satisfiesAll() instead. Will be removed in v1.0.0.
      * @param array<FieldValidator|callable> $validators
      */
-    public function allOf(array $validators, null|string $message = null): self
+    public function allOf(array $validators, ?string $message = null): self
     {
         return $this->satisfiesAll($validators, $message);
     }
@@ -173,7 +171,7 @@ public function allOf(array $validators, null|string $message = null): self
      * @param ?string $message Custom error message.
      * @return $this
      */
-    public function satisfiesAny(array $validations, null|string $message = null): self
+    public function satisfiesAny(array $validations, ?string $message = null): self
     {
         return $this->satisfies(static function ($value, $key = null, $input = null) use (
             $validations,
@@ -199,7 +197,7 @@ public function satisfiesAny(array $validations, null|string $message = null): s
      * @deprecated Use satisfiesAny() instead. Will be removed in v1.0.0.
      * @param array<FieldValidator|callable> $validators
      */
-    public function anyOf(array $validators, null|string $message = null): self
+    public function anyOf(array $validators, ?string $message = null): self
     {
         return $this->satisfiesAny($validators, $message);
     }
@@ -211,7 +209,7 @@ public function anyOf(array $validators, null|string $message = null): self
      * @param ?string $message Custom error message.
      * @return $this
      */
-    public function satisfiesNone(array $validations, null|string $message = null): self
+    public function satisfiesNone(array $validations, ?string $message = null): self
     {
         return $this->satisfies(
             static function ($value, $key = null, $input = null) use ($validations) {
@@ -237,7 +235,7 @@ static function ($value, $key = null, $input = null) use ($validations) {
     /**
      * @deprecated Use satisfiesNone() instead. Will be removed in v1.0.0.
      */
-    public function not(FieldValidator $validator, null|string $message = null): self
+    public function not(FieldValidator $validator, ?string $message = null): self
     {
         return $this->satisfiesNone(
             [$validator],
@@ -250,9 +248,10 @@ public function not(FieldValidator $validator, null|string $message = null): sel
      * Can change the type - subsequent operations work with the new type.
      *
      * @param callable $transformer The transformation function that receives the validated value.
+     * @param bool $skipNull Whether to skip null values (default: true). Set to false to process null values.
      * @return $this
      */
-    public function transform(callable $transformer): self
+    public function transform(callable $transformer, bool $skipNull = true): self
     {
         $this->pipeline[] = [
             'type' => PipelineType::TRANSFORMATION,
@@ -264,7 +263,7 @@ public function transform(callable $transformer): self
 
                 return $result; // No coercion - transform can change type
             },
-            'skipNull' => false, // transform() should execute on null (can handle null and change types)
+            'skipNull' => $skipNull,
         ];
         return $this;
     }

src/Lemmon/Validator/IntValidator.php

@@ -45,7 +45,7 @@ protected function validateType(mixed $value, string $key): mixed
      * @param ?string $message Custom error message.
      * @return static
      */
-    public function port(null|string $message = null): static
+    public function port(?string $message = null): static
     {
         return $this->satisfies(
             static fn ($value, $key = null, $input = null) => (

src/Lemmon/Validator/NumericConstraintsTrait.php

@@ -19,7 +19,7 @@ trait NumericConstraintsTrait
      * @param ?string $message Custom error message.
      * @return static
      */
-    public function min(int|float $min, null|string $message = null): static
+    public function min(int|float $min, ?string $message = null): static
     {
         return $this->satisfies(
             static fn ($value, $key = null, $input = null) => $value >= $min,
@@ -34,7 +34,7 @@ public function min(int|float $min, null|string $message = null): static
      * @param ?string $message Custom error message.
      * @return static
      */
-    public function max(int|float $max, null|string $message = null): static
+    public function max(int|float $max, ?string $message = null): static
     {
         return $this->satisfies(
             static fn ($value, $key = null, $input = null) => $value <= $max,
@@ -50,7 +50,7 @@ public function max(int|float $max, null|string $message = null): static
      * @param ?string $message Custom error message.
      * @return static
      */
-    public function between(int|float $min, int|float $max, null|string $message = null): static
+    public function between(int|float $min, int|float $max, ?string $message = null): static
     {
         return $this->satisfies(
             static fn ($value, $key = null, $input = null) => $value >= $min && $value <= $max,
@@ -65,7 +65,7 @@ public function between(int|float $min, int|float $max, null|string $message = n
      * @param ?string $message Custom error message.
      * @return static
      */
-    public function gt(int|float $threshold, null|string $message = null): static
+    public function gt(int|float $threshold, ?string $message = null): static
     {
         return $this->satisfies(
             static fn ($value, $key = null, $input = null) => $value > $threshold,
@@ -80,7 +80,7 @@ public function gt(int|float $threshold, null|string $message = null): static
      * @param ?string $message Custom error message.
      * @return static
      */
-    public function gte(int|float $threshold, null|string $message = null): static
+    public function gte(int|float $threshold, ?string $message = null): static
     {
         return $this->satisfies(
             static fn ($value, $key = null, $input = null) => $value >= $threshold,
@@ -95,7 +95,7 @@ public function gte(int|float $threshold, null|string $message = null): static
      * @param ?string $message Custom error message.
      * @return static
      */
-    public function lt(int|float $threshold, null|string $message = null): static
+    public function lt(int|float $threshold, ?string $message = null): static
     {
         return $this->satisfies(
             static fn ($value, $key = null, $input = null) => $value < $threshold,
@@ -110,7 +110,7 @@ public function lt(int|float $threshold, null|string $message = null): static
      * @param ?string $message Custom error message.
      * @return static
      */
-    public function lte(int|float $threshold, null|string $message = null): static
+    public function lte(int|float $threshold, ?string $message = null): static
     {
         return $this->satisfies(
             static fn ($value, $key = null, $input = null) => $value <= $threshold,
@@ -125,7 +125,7 @@ public function lte(int|float $threshold, null|string $message = null): static
      * @param ?string $message Custom error message.
      * @return static
      */
-    public function multipleOf(int|float $divisor, null|string $message = null): static
+    public function multipleOf(int|float $divisor, ?string $message = null): static
     {
         return $this->satisfies(
             static function ($value, $key = null, $input = null) use ($divisor) {
@@ -148,7 +148,7 @@ static function ($value, $key = null, $input = null) use ($divisor) {
      * @param ?string $message Custom error message.
      * @return static
      */
-    public function positive(null|string $message = null): static
+    public function positive(?string $message = null): static
     {
         return $this->satisfies(
             static fn ($value, $key = null, $input = null) => $value > 0,
@@ -162,7 +162,7 @@ public function positive(null|string $message = null): static
      * @param ?string $message Custom error message.
      * @return static
      */
-    public function negative(null|string $message = null): static
+    public function negative(?string $message = null): static
     {
         return $this->satisfies(
             static fn ($value, $key = null, $input = null) => $value < 0,
@@ -176,7 +176,7 @@ public function negative(null|string $message = null): static
      * @param ?string $message Custom error message.
      * @return static
      */
-    public function nonNegative(null|string $message = null): static
+    public function nonNegative(?string $message = null): static
     {
         return $this->gte(0, $message ?? 'Value must be non-negative');
     }
@@ -187,7 +187,7 @@ public function nonNegative(null|string $message = null): static
      * @param ?string $message Custom error message.
      * @return static
      */
-    public function nonPositive(null|string $message = null): static
+    public function nonPositive(?string $message = null): static
     {
         return $this->lte(0, $message ?? 'Value must be non-positive');
     }