Feat: Batch transform support (BatchTransformerInterface)

[bpolaszek]

Summary

• Add BatchTransformerInterface — a new interface (separate from TransformerInterface) for transforming items in batches instead of one-by-one
• Add CallableBatchTransformer — callable-based implementation
• Add batchSize option to EtlConfiguration to control chunk size
• Modify IterableProcessor to chunk extracted items via iterable_chunk() when a batch transformer is detected
• Add processItemBatch() to EtlExecutor for batch processing orchestration
• Move bentools/iterable-functions from require-dev to require

Use case

Transformers that make HTTP calls can now send N requests concurrently instead of waiting for each response sequentially:

$executor = (new EtlExecutor())
    ->transformWith(new CallableBatchTransformer(
        function (array $items, EtlState $state): array {
            return $httpClient->sendConcurrent(
                array_map(fn ($item) => new Request('GET', $item['url']), $items)
            );
        }
    ))
    ->withOptions(new EtlConfiguration(batchSize: 10))
    ->process($source);

Design decisions

• BatchTransformerInterface does not extend TransformerInterface (PHP prevents parameter type narrowing mixed → array)
• Batch mode activates when transformer implements BatchTransformerInterface (regardless of batchSize)
• nextTick callbacks are consumed between batches, not between items within a batch
• SkipRequest during extraction removes the item from the batch; StopRequest processes collected items then stops
• When transformer is not BatchTransformerInterface, batchSize is ignored (zero behavioral change)

Test plan

• Happy path: N items, batch size M, all transformed correctly
• Partial last batch (7 items, batchSize=3 → batches of 3, 3, 1)
• Empty input
• SkipRequest during ExtractEvent → item removed from batch
• StopRequest during ExtractEvent → processes collected items, then stops
• SkipRequest during TransformEvent → result skipped
• Fan-out in batch mode (transformer yields more results than inputs)
• batchSize=1 with BatchTransformerInterface → works with chunks of 1
• Non-batch transformer with batchSize > 1 → gracefully ignored
• Integration with flushFrequency
• ExtractEvent fires per item, TransformEvent fires per result
• batchSize larger than total items → single batch
• EtlConfiguration validation (batchSize < 1 throws)
• All 147 tests pass, PHPStan clean, 99.3% coverage

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (26fdf50) to head (c92c636).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff             @@
##              master       #60   +/-   ##
===========================================
  Coverage     100.00%   100.00%           
- Complexity       352       372   +20     
===========================================
  Files             61        62    +1     
  Lines            916       966   +50     
===========================================
+ Hits             916       966   +50     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.