feat(validators): introduce between() method for range validation

Added a new `between()` method to both StringValidator and NumericConstraintsTrait, allowing for concise validation of string lengths and numeric ranges. This enhancement simplifies the validation process by providing a shorthand for existing methods. Updated documentation and tests to reflect these changes.

Author: lemmon

CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 - `notEmpty()` convenience method for `StringValidator` and `ArrayValidator` to reject empty strings/arrays
+- `between()` shorthand for string length and numeric range constraints
 
 ### Documentation
 - Clarified fail-fast behavior per field and schema-level error aggregation in guides and examples

ROADMAP.md

@@ -309,8 +309,8 @@ $stringValidator = Validator::isString()
 ### Real-World Validation Gaps (For Consideration)
 - [x] **`notEmpty()` method** - Explicit validation that value is not empty string/array (clearer than custom validation)
 - [ ] **`in()` alias for `oneOf()`** - More intuitive method name (`->in(['active', 'inactive'])`)
-- [ ] **`between(min, max)` for strings** - Length validation shorthand (`->between(3, 50)` instead of `->minLength(3)->maxLength(50)`)
-- [ ] **`between(min, max)` for numerics** - Range validation shorthand (`->between(1, 100)` instead of `->min(1)->max(100)`)
+- [x] **`between(min, max)` for strings** - Length validation shorthand (`->between(3, 50)` instead of `->minLength(3)->maxLength(50)`)
+- [x] **`between(min, max)` for numerics** - Range validation shorthand (`->between(1, 100)` instead of `->min(1)->max(100)`)
 - [ ] **`filled()` method** - Requires non-null AND non-empty (stricter than required())
 - [ ] **`when()` conditional validation** - Apply validation only when condition is met (`->when($userRole === 'admin', fn($v) => $v->required())`)
 

TASKS.md

@@ -11,9 +11,6 @@ Public repo; keep this list short (about 7) and up to date. Rules: no numbering
 - `in()` alias for `oneOf()`
   - Add `in()` method as an alias for `oneOf()` for more intuitive API (`->in(['active', 'inactive'])` reads better than `->oneOf()`).
 
-- `between()` convenience methods
-  - Add `between(min, max)` shorthand for strings (length) and numerics (range) to reduce boilerplate (`->between(3, 50)` vs `->minLength(3)->maxLength(50)`).
-
 - Mutation testing pilot
   - Wire Infection (or similar) to the test suite, add baseline config, and document how to run it locally for enhanced test quality verification.
 

docs/guides/numeric-validation.md

@@ -107,6 +107,13 @@ $rangeValidator = Validator::isInt()->min(1)->max(10);
 $rating = $rangeValidator->validate(8); // Valid
 ```
 
+Use `between(min, max)` as a shorthand for the inclusive range:
+
+```php
+$rangeValidator = Validator::isInt()->between(1, 10);
+$rating = $rangeValidator->validate(8); // Valid
+```
+
 ### Sign Constraints
 
 ```php

docs/guides/string-validation.md

@@ -262,6 +262,17 @@ $result = $exactLengthValidator->validate('Hello'); // Valid (exactly 5 chars)
 // $exactLengthValidator->validate('Too Long'); // ❌ ValidationException (8 chars)
 ```
 
+### Length Between Bounds
+
+Use `between(min, max)` as a shorthand for `minLength()` + `maxLength()`:
+
+```php
+$validator = Validator::isString()->between(3, 8);
+$validator->validate('Hello'); // Valid
+// $validator->validate('Hi'); // ❌ ValidationException (too short)
+// $validator->validate('Too long'); // ❌ ValidationException (too long)
+```
+
 ### Non-Empty Strings
 
 Use `notEmpty()` as a clearer alternative to `minLength(1)` when you only want to reject empty strings.

llms.txt

@@ -82,6 +82,7 @@ date(string $format = 'Y-m-d', ?string $message = null): static
 minLength(int $min, ?string $message = null): static
 maxLength(int $max, ?string $message = null): static
 length(int $exact, ?string $message = null): static
+between(int $min, int $max, ?string $message = null): static
 notEmpty(?string $message = null): static
 oneOf(array $values, ?string $message = null): static
 ```
@@ -91,6 +92,7 @@ oneOf(array $values, ?string $message = null): static
 ```php
 min(int|float $min, ?string $message = null): static
 max(int|float $max, ?string $message = null): static
+between(int|float $min, int|float $max, ?string $message = null): static
 gt(int|float $threshold, ?string $message = null): static
 gte(int|float $threshold, ?string $message = null): static
 lt(int|float $threshold, ?string $message = null): static

src/Lemmon/Validator/NumericConstraintsTrait.php

@@ -42,6 +42,23 @@ public function max(int|float $max, null|string $message = null): static
         );
     }
 
+    /**
+     * Validates that the value falls within the provided inclusive range.
+     *
+     * @param int|float $min The minimum value.
+     * @param int|float $max The maximum value.
+     * @param ?string $message Custom error message.
+     * @return static
+     */
+    public function between(int|float $min, int|float $max, null|string $message = null): static
+    {
+        if ($message === null) {
+            return $this->min($min)->max($max);
+        }
+
+        return $this->min($min, $message)->max($max, $message);
+    }
+
     /**
      * Validates that the value is greater than the given threshold.
      *

src/Lemmon/Validator/StringValidator.php

@@ -144,6 +144,15 @@ public function length(int $exact, null|string $message = null): static
         );
     }
 
+    public function between(int $min, int $max, null|string $message = null): static
+    {
+        if ($message === null) {
+            return $this->minLength($min)->maxLength($max);
+        }
+
+        return $this->minLength($min, $message)->maxLength($max, $message);
+    }
+
     public function notEmpty(null|string $message = null): static
     {
         return $this->minLength(1, $message ?? 'Value must not be empty');

tests/FloatValidatorTest.php

@@ -46,6 +46,26 @@
     $rangeValidator->validate(5);
 })->throws(ValidationException::class);
 
+it('should validate floats between bounds', function () {
+    $validator = Validator::isFloat()->between(1.5, 2.5);
+
+    expect($validator->validate(1.5))->toBe(1.5);
+    expect($validator->validate(2.0))->toBe(2.0);
+    expect($validator->validate(2.5))->toBe(2.5);
+
+    $validator->validate(1.4);
+})->throws(ValidationException::class, 'Value must be at least 1.5');
+
+it('should reject floats above the between range', function () {
+    $validator = Validator::isFloat()->between(1.5, 2.5);
+    $validator->validate(2.6);
+})->throws(ValidationException::class, 'Value must be at most 2.5');
+
+it('should use custom error message for float between validation', function () {
+    $validator = Validator::isFloat()->between(1.5, 2.5, 'Out of range');
+    $validator->validate(3.0);
+})->throws(ValidationException::class, 'Out of range');
+
 it('should validate float multiples', function () {
     $multipleValidator = Validator::isFloat()->multipleOf(5);
 

tests/IntValidatorTest.php

@@ -35,6 +35,26 @@
     $rangeValidator->validate(5);
 })->throws(ValidationException::class, 'Value must be at least 10');
 
+it('should validate integers between bounds', function () {
+    $validator = Validator::isInt()->between(10, 20);
+
+    expect($validator->validate(10))->toBe(10);
+    expect($validator->validate(15))->toBe(15);
+    expect($validator->validate(20))->toBe(20);
+
+    $validator->validate(9);
+})->throws(ValidationException::class, 'Value must be at least 10');
+
+it('should reject integers above the between range', function () {
+    $validator = Validator::isInt()->between(10, 20);
+    $validator->validate(21);
+})->throws(ValidationException::class, 'Value must be at most 20');
+
+it('should use custom error message for integer between validation', function () {
+    $validator = Validator::isInt()->between(1, 5, 'Out of range');
+    $validator->validate(0);
+})->throws(ValidationException::class, 'Out of range');
+
 it('should validate integer multiples', function () {
     $multipleValidator = Validator::isInt()->multipleOf(5);