Add eager and lazy evaluation strategies with pipeline architecture.

[gustavofreze]

No description provided.

[Copilot]

Pull request overview

This PR refactors the collection internals to support explicit eager vs. lazy evaluation through a pipeline architecture, updating operations, tests, and documentation accordingly.

Changes:

• Introduces Pipeline + EagerPipeline/LazyPipeline and refactors Collection to compose operations via pipeline stages.
• Replaces the previous operation set (LazyOperation/ImmediateOperation) with Transforming\* (pipeline stages) and Resolving\* (terminal helpers).
• Consolidates/rewrites tests and updates documentation to reflect the new API and extension patterns.

Reviewed changes

Copilot reviewed 80 out of 80 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/Models/Invoices.php	Adds domain-specific helpers (totalAmount, forCustomer) that exercise pipeline ops.
tests/Models/InvoiceSummaries.php	Updates reduce named-argument to accumulator to match new API.
tests/Models/Carriers.php	Adds a domain collection used for type-preservation tests.
tests/Internal/Operations/Write/CollectionRemoveOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Write/CollectionMergeOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Write/CollectionCreateOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Write/CollectionAddOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Transform/CollectionMapToJsonOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Transform/CollectionMapToArrayOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Transform/CollectionMapOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Transform/CollectionJoinToStringTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Transform/CollectionGroupByOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Transform/CollectionFlattenOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Transform/CollectionEachOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Retrieve/CollectionSliceOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Retrieve/CollectionLastOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Retrieve/CollectionGetOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Retrieve/CollectionFirstOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Retrieve/CollectionFindOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Order/CollectionSortOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Filter/CollectionFilterOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Compare/CollectionEqualsOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Compare/CollectionContainsOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Operations/Aggregate/CollectionReduceOperationTest.php	Removes per-operation test in favor of consolidated strategy-level coverage.
tests/Internal/Iterators/LazyIteratorTest.php	Removes old LazyIterator test after pipeline refactor.
tests/EagerCollectionTest.php	Adds comprehensive eager strategy coverage of core collection behavior.
tests/CollectionTest.php	Adds cross-strategy (lazy vs eager) equivalence tests and domain type-preservation checks.
tests/CollectionPerformanceTest.php	Removes performance/memory benchmarks from the test suite.
tests/CollectionIteratorTest.php	Removes iterator reuse tests that were tied to the previous iterator architecture.
src/Order.php	Updates enum docs to clarify key vs value sorting semantics.
src/Internal/Pipeline.php	Introduces pipeline abstraction for staged processing.
src/Internal/Operations/Write/Add.php	Removes legacy write operation (replaced by Transforming\Add).
src/Internal/Operations/Write/Create.php	Removes legacy create operation (pipelines now own sources).
src/Internal/Operations/Write/Merge.php	Removes legacy merge operation (replaced by Transforming\Merge).
src/Internal/Operations/Write/Remove.php	Removes legacy remove operation (replaced by Transforming\Remove).
src/Internal/Operations/Write/RemoveAll.php	Removes legacy removeAll operation (replaced by Transforming\RemoveAll).
src/Internal/Operations/Transforming/Add.php	New pipeline stage for appending elements.
src/Internal/Operations/Transforming/Filter.php	New pipeline stage for predicate filtering.
src/Internal/Operations/Transforming/FlatMap.php	New pipeline stage for one-level flattening.
src/Internal/Operations/Transforming/GroupInto.php	New pipeline stage for grouping into key=>list buckets.
src/Internal/Operations/Transforming/Map.php	Renames/relocates map operation and adapts it to Operation.
src/Internal/Operations/Transforming/Merge.php	New pipeline stage for concatenating another iterable.
src/Internal/Operations/Transforming/Rearrange.php	New pipeline stage that materializes + sorts based on Order.
src/Internal/Operations/Transforming/Remove.php	New pipeline stage for removing matching elements.
src/Internal/Operations/Transforming/RemoveAll.php	New pipeline stage for removing elements matching a predicate.
src/Internal/Operations/Transforming/Segment.php	New pipeline stage implementing slicing/segment semantics (including negative lengths).
src/Internal/Operations/Transform/Each.php	Removes legacy immediate each operation (replaced by Resolving\Each).
src/Internal/Operations/Transform/Flatten.php	Removes legacy flatten operation (replaced by Transforming\FlatMap).
src/Internal/Operations/Transform/GroupBy.php	Removes legacy groupBy operation (replaced by Transforming\GroupInto).
src/Internal/Operations/Transform/JoinToString.php	Removes legacy join operation (replaced by Resolving\Join).
src/Internal/Operations/Retrieve/Find.php	Removes legacy retrieve operation (replaced by Resolving\Find).
src/Internal/Operations/Retrieve/First.php	Removes legacy retrieve operation (replaced by Resolving\First).
src/Internal/Operations/Retrieve/Get.php	Removes legacy retrieve operation (replaced by Resolving\Get).
src/Internal/Operations/Retrieve/Last.php	Removes legacy retrieve operation (replaced by Resolving\Last).
src/Internal/Operations/Retrieve/Slice.php	Removes legacy slice operation (replaced by Transforming\Segment).
src/Internal/Operations/Resolving/Each.php	New terminal helper for side-effect execution.
src/Internal/Operations/Resolving/Equality.php	New helpers for contains/equals semantics.
src/Internal/Operations/Resolving/Find.php	New helper implementing predicate-based search.
src/Internal/Operations/Resolving/First.php	New helper implementing first/isEmpty semantics.
src/Internal/Operations/Resolving/Get.php	New helper implementing element lookup.
src/Internal/Operations/Resolving/Join.php	New helper implementing join-to-string.
src/Internal/Operations/Resolving/Last.php	New helper implementing last-element retrieval.
src/Internal/Operations/Resolving/Reduce.php	New helper implementing reduce accumulation.
src/Internal/Operations/Order/Sort.php	Removes legacy sort operation (replaced by Transforming\Rearrange).
src/Internal/Operations/Operation.php	Expands docs/typing to reflect pipeline-stage semantics.
src/Internal/Operations/LazyOperation.php	Removes legacy lazy-operation interface.
src/Internal/Operations/ImmediateOperation.php	Removes legacy immediate-operation interface.
src/Internal/Operations/Filter/Filter.php	Removes legacy filter operation (replaced by Transforming\Filter).
src/Internal/Operations/Compare/Contains.php	Removes legacy contains operation (replaced by Resolving\Equality::exists).
src/Internal/Operations/Compare/Equals.php	Removes legacy equals operation (replaced by Resolving\Equality::compareAll).
src/Internal/Operations/Aggregate/Reduce.php	Removes legacy reduce operation (replaced by Resolving\Reduce).
src/Internal/EagerPipeline.php	Adds eager strategy pipeline that materializes after each stage.
src/Internal/LazyPipeline.php	Adds lazy strategy pipeline that defers execution until consumption.
src/Internal/Iterators/LazyIterator.php	Removes legacy lazy iterator in favor of pipelines.
src/Internal/Iterators/LazyIteratorAggregate.php	Removes legacy iterator aggregate in favor of pipelines.
src/Collection.php	Refactors Collection to be pipeline-backed and adds lazy factory methods.
src/Collectible.php	Updates the public contract and docs for eager vs lazy evaluation.
phpstan.neon.dist	Adjusts PHPStan ignore patterns for new typing surface.
README.md	Updates examples and adds “Extending Collection” + eager/lazy explanation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 80 out of 80 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 79 out of 79 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.