Rename Core\Reducer to Composite and expose it as a public validator

The term "Reducer" is widely used in functional programming to describe
a specific pattern: a function that takes an accumulator and a value,
returning a new accumulator (e.g., array_reduce, Redux reducers). This
class does not perform that operation. Instead, it consolidates multiple
validators into a single one, which is the definition of composition.

The new name "Composite" accurately reflects what this validator does:
it composes zero or more validators into a unified validation unit. This
aligns with the Composite design pattern terminology and avoids semantic
confusion with functional programming concepts.

The class has also been moved from the internal Core namespace to the
public Validators namespace. This change acknowledges that composing
validators dynamically is a legitimate use case for library consumers,
not just an internal implementation detail. The library itself uses this
pattern in Attributes and KeySet validators, demonstrating its practical
value.

The signature has been extended to accept zero or more validators:

- Zero validators: Returns AlwaysValid (useful for conditional chains)
- One validator: Pass-through without wrapping (avoids unnecessary nesting)
- Multiple validators: Combines using AllOf (all must pass)

This flexibility is particularly useful when building validation chains
dynamically, where the number of validators may vary at runtime based on
configuration or user input.

Assisted-by: Claude Code (Claude Opus 4.5)

Author: henriquemoody

docs/validators.md

@@ -69,6 +69,7 @@ In this page you will find a list of validators by their category.
 - [AllOf](validators/AllOf.md)
 - [AnyOf](validators/AnyOf.md)
 - [Circuit](validators/Circuit.md)
+- [Composite](validators/Composite.md)
 - [NoneOf](validators/NoneOf.md)
 - [OneOf](validators/OneOf.md)
 
@@ -179,6 +180,7 @@ In this page you will find a list of validators by their category.
 - [AnyOf](validators/AnyOf.md)
 - [Call](validators/Call.md)
 - [Circuit](validators/Circuit.md)
+- [Composite](validators/Composite.md)
 - [Each](validators/Each.md)
 - [Key](validators/Key.md)
 - [KeySet](validators/KeySet.md)
@@ -335,6 +337,7 @@ In this page you will find a list of validators by their category.
 - [Circuit](validators/Circuit.md)
 - [Cnh](validators/Cnh.md)
 - [Cnpj](validators/Cnpj.md)
+- [Composite](validators/Composite.md)
 - [Consonant](validators/Consonant.md)
 - [Contains](validators/Contains.md)
 - [ContainsAny](validators/ContainsAny.md)

docs/validators/Composite.md

@@ -0,0 +1,64 @@
+<!--
+SPDX-FileCopyrightText: (c) Respect Project Contributors
+SPDX-License-Identifier: MIT
+-->
+
+# Composite
+
+- `Composite()`
+- `Composite(Validator ...$validators)`
+
+Consolidates zero or more validators into a single validator.
+
+- When no validators are provided, it acts as [AlwaysValid](AlwaysValid.md).
+- When a single validator is provided, it acts as a pass-through.
+- When multiple validators are provided, they are combined using [AllOf](AllOf.md), meaning all validators must pass for the input to be considered valid.
+
+```php
+v::composite()->assert('anything');
+// Validation passes successfully
+
+v::composite(v::intType())->assert(42);
+// Validation passes successfully
+
+v::composite(v::intType(), v::positive(), v::lessThan(100))->assert(42);
+// Validation passes successfully
+
+v::composite(v::intType(), v::positive())->assert(-5);
+// → -5 must be a positive number
+```
+
+## Use cases
+
+This validator is useful for dynamically building validation chains or when you
+have a variable number of validators that need to be applied together.
+
+```php
+$validators = [v::stringType(), v::notSpaced()];
+
+if (true) { // some condition
+    $validators[] = v::email();
+}
+
+v::composite(...$validators)->assert('respectpanda#example.com');
+// → "respectpanda#example.com" must be a valid email address
+```
+
+## Categorization
+
+- Composite
+- Nesting
+
+## Changelog
+
+| Version | Description |
+| ------: | :---------- |
+|   3.0.0 | Created     |
+
+## See Also
+
+- [AllOf](AllOf.md)
+- [AlwaysValid](AlwaysValid.md)
+- [AnyOf](AnyOf.md)
+- [NoneOf](NoneOf.md)
+- [OneOf](OneOf.md)

src/Mixins/AllBuilder.php

@@ -62,6 +62,8 @@ public static function allCnh(): Chain;
 
     public static function allCnpj(): Chain;
 
+    public static function allComposite(Validator ...$validators): Chain;
+
     public static function allConsonant(string ...$additionalChars): Chain;
 
     public static function allContains(mixed $containsValue, bool $identical = false): Chain;

src/Mixins/AllChain.php

@@ -62,6 +62,8 @@ public function allCnh(): Chain;
 
     public function allCnpj(): Chain;
 
+    public function allComposite(Validator ...$validators): Chain;
+
     public function allConsonant(string ...$additionalChars): Chain;
 
     public function allContains(mixed $containsValue, bool $identical = false): Chain;

src/Mixins/Builder.php

@@ -67,6 +67,8 @@ public static function cnh(): Chain;
 
     public static function cnpj(): Chain;
 
+    public static function composite(Validator ...$validators): Chain;
+
     public static function consonant(string ...$additionalChars): Chain;
 
     public static function contains(mixed $containsValue, bool $identical = false): Chain;

src/Mixins/Chain.php

@@ -69,6 +69,8 @@ public function cnh(): Chain;
 
     public function cnpj(): Chain;
 
+    public function composite(Validator ...$validators): Chain;
+
     public function consonant(string ...$additionalChars): Chain;
 
     public function contains(mixed $containsValue, bool $identical = false): Chain;

src/Mixins/KeyBuilder.php

@@ -64,6 +64,8 @@ public static function keyCnh(int|string $key): Chain;
 
     public static function keyCnpj(int|string $key): Chain;
 
+    public static function keyComposite(int|string $key, Validator ...$validators): Chain;
+
     public static function keyConsonant(int|string $key, string ...$additionalChars): Chain;
 
     public static function keyContains(int|string $key, mixed $containsValue, bool $identical = false): Chain;

src/Mixins/KeyChain.php

@@ -64,6 +64,8 @@ public function keyCnh(int|string $key): Chain;
 
     public function keyCnpj(int|string $key): Chain;
 
+    public function keyComposite(int|string $key, Validator ...$validators): Chain;
+
     public function keyConsonant(int|string $key, string ...$additionalChars): Chain;
 
     public function keyContains(int|string $key, mixed $containsValue, bool $identical = false): Chain;

src/Mixins/NotBuilder.php

@@ -64,6 +64,8 @@ public static function notCnh(): Chain;
 
     public static function notCnpj(): Chain;
 
+    public static function notComposite(Validator ...$validators): Chain;
+
     public static function notConsonant(string ...$additionalChars): Chain;
 
     public static function notContains(mixed $containsValue, bool $identical = false): Chain;

src/Mixins/NotChain.php

@@ -64,6 +64,8 @@ public function notCnh(): Chain;
 
     public function notCnpj(): Chain;
 
+    public function notComposite(Validator ...$validators): Chain;
+
     public function notConsonant(string ...$additionalChars): Chain;
 
     public function notContains(mixed $containsValue, bool $identical = false): Chain;