feat: introduce mapEach() method

[nikophil]

I'm bringing back this mapEach() method.

On the project I'm working on, we have tons of factories with "withers" which prevents to use sequences and fluent usage of the factories when collections are involved.

I'm opened to any better api, or naming 😅

[smnandre]

withEach ? Or maybe even eachWith ?

[kbond]

Would you mind adding the docs for this with a real example? It'd help me understand the feature more I think.

[aegypius]

withEach ? Or maybe even eachWith ?

I agree mapEach seem to be a little redundant why not a simple map(callable callback): self like our beloved PHP\Ds Sequence::map(...)

[silasjoisten]

Suggested change

	public function mapEach(callable $callback, array $values): self // @phpstan-ignore missingType.callable (cannot properly type the callable)
	public function map(callable $callback, array $values): self // @phpstan-ignore missingType.callable (cannot properly type the callable)

[smnandre]

Maybe then it would be better to use the same signature as array_map (the variadic values) ?

*
 * @return self<T, TFactory>
 */
function map(callable $callback, array... $arguments): self

Instead of calling map($callable, [[1, 2, 3], [a, b, c]]) , one could do map(callable, [1,2,3], [4,5,6])

[nikophil]

yeah this could be a good idea... I still need to work on this one and think of a good real life example to convince @kbond 😆

I'm not really sure map() is a good name, the main difference is that this method effectively applies a callback on each element of a FactoryCollection, but it will actually pass a different item as a parameter of the callback on each iteration.

It's a mix between a "map()" and the new distribute() method recently introduced.

BTW, I'm still not 100% convince of the API of this method. But I really would like something to call so-called "state method" on each element of a FactoryCollection