feature: variadic arguments ADR (#2241)

Author: norberttech

documentation/adrs.md

@@ -3,17 +3,23 @@
 [TOC]
 
 # What are ADRs?
-Architecture Decision Records (ADRs) are structured documents that capture significant architectural decisions made during the development of this project. 
+
+Architecture Decision Records (ADRs) are structured documents that capture significant architectural decisions made
+during the development of this project.
 
 Each ADR explains:
-- **The context**: Why the decision was necessary.  
-- **The decision**: What was decided and why.  
-- **The consequences**: The impact of the decision, both positive and negative.  
 
-ADRs act as a single source of truth for important design and architectural choices, ensuring that everyone involved in the project has a shared understanding of why things are the way they are.
+- **The context**: Why the decision was necessary.
+- **The decision**: What was decided and why.
+- **The consequences**: The impact of the decision, both positive and negative.
+
+ADRs act as a single source of truth for important design and architectural choices, ensuring that everyone involved in
+the project has a shared understanding of why things are the way they are.
 
 ## How to Use ADRs in This Project
-**Follow Existing ADRs**: ADRs are mandatory to follow unless explicitly overridden by a new ADR. This ensures consistency in decision-making across the project.
+
+**Follow Existing ADRs**: ADRs are mandatory to follow unless explicitly overridden by a new ADR. This ensures
+consistency in decision-making across the project.
 
 > Whenever ADR is merged into the main branch, it is considered accepted and must be followed by all contributors.
 
@@ -22,13 +28,16 @@ ADRs act as a single source of truth for important design and architectural choi
 - If you encounter a situation that requires a significant architectural or design change, you must create a new ADR.
 - Use the provided [ADR Template](/documentation/adrs/template.md) to create your proposal.
 - Submit the ADR via a pull request and engage in a discussion with maintainers and contributors.
-- **Document Decisions Transparently**: All significant decisions must be documented. This includes not only what was decided but also the alternatives that were considered and why they were rejected.
+- **Document Decisions Transparently**: All significant decisions must be documented. This includes not only what was
+  decided but also the alternatives that were considered and why they were rejected.
 
 ## Index of ADRs
 
 ### [Accepted AD](https://github.com/flow-php/flow/pulls?q=is%3Apr+is%3Aclosed+is%3Amerged+label%3AAD+)
+
 - [2025-01-07: Static Analysis Baseline](/documentation/adrs/static-analysis-baseline.md)
 - [2025-01-09: Extension Points](/documentation/adrs/extension-points.md)
+- [2026-03-02: Variadic Arguments Pattern for Required Parameters](/documentation/adrs/variadic-arguments-pattern.md)
 
 ### [Proposed AD](https://github.com/flow-php/flow/pulls?q=is%3Apr+is%3Aopen+label%3AAD+)
 

documentation/adrs/variadic-arguments-pattern.md

@@ -0,0 +1,101 @@
+# Variadic Arguments Pattern for Required Parameters
+
+[TOC]
+
+Proposed by: @norberttech
+Date: 2026-03-02
+
+## Context
+---
+
+Several Flow PHP methods accept multiple arguments where at least one is required. Examples include:
+- `DataFrame::partitionBy()`
+- `Rows::partitionBy()`
+- `Window::partitionBy()`
+- Type comparison methods
+
+A proposal was made to simplify the API signatures from:
+
+```php
+public function partitionBy(string|Reference $entry, string|Reference ...$entries) : self
+```
+
+To:
+
+```php
+public function partitionBy(string|Reference ...$entries) : self
+```
+
+The rationale for the proposal was to reduce array operations like `array_unshift()` used internally to merge the first required argument with the variadic rest.
+
+## Decision
+---
+
+**Keep the explicit first argument pattern**
+
+Methods that require at least one argument should use the signature pattern:
+
+```php
+public function method(Type $first, Type ...$rest) : ReturnType
+```
+
+Rather than:
+
+```php
+public function method(Type ...$args) : ReturnType
+```
+
+## Pros & Cons
+---
+
+**Advantages of the chosen pattern:**
+
+- **Compile-time enforcement**: PHP enforces at least one argument at the language level
+- **Static analysis support**: PHPStan, Psalm, and IDEs immediately understand the constraint
+- **Better developer experience**: The method signature clearly communicates the requirement without needing to read documentation or encounter runtime exceptions
+- **Fail-fast principle**: Errors are caught before execution, not during
+
+**Disadvantages:**
+
+- Internal implementation requires merging arguments: `array_unshift($rest, $first)`
+- Slightly more verbose method signatures
+- Minor performance overhead from array operations (negligible in practice)
+
+## Alternatives Considered
+---
+
+### 1. Pure variadic with runtime validation
+
+```php
+public function partitionBy(string|Reference ...$entries) : self
+{
+    if ([] === $entries) {
+        throw new InvalidArgumentException('At least one entry is required.');
+    }
+    // ...
+}
+```
+
+**Rejected because:** Developers only discover the constraint at runtime, leading to worse developer experience.
+
+### 2. Validation in the References class
+
+```php
+final class References
+{
+    public function __construct(string|Reference ...$references)
+    {
+        if ([] === $references) {
+            throw new InvalidArgumentException('References cannot be empty.');
+        }
+        // ...
+    }
+}
+```
+
+**Rejected because:** While this centralizes validation, it still defers the error to runtime. The explicit first argument pattern catches errors earlier in the development cycle.
+
+## Links and References
+---
+
+- [GitHub Issue #2236](https://github.com/flow-php/flow/issues/2236) - Original proposal discussion