Enable fluent interface for streams

[joshdifabio]

The stream functions suffer from the same problems as PHP's array functions; they're awkward to chain.

$output = filter(map(filter($input, $filterFn), $mapFn), $otherFilterFn);

This would be preferable imo:

$output = $input
    ->apply(filter($filterFn))
    ->apply(map($mapFn))
    ->apply(filter($otherFilterFn));

Edit: Inspired by apache beam.

[kelunik]

Another solution is to just write:

$stream = Stream\filter($stream, $filterFunctor);
$stream = Stream\map($stream, $mapFunctor);
$stream = Stream\filter($stream, $otherFilterFunctor);

But I agree, chaining can be a bit nicer to read. Unfortunately such functionality can only be implemented by adding the to be chained methods to each and every implementation, mixing responsibilities.

[kelunik]

What could be done is using a wrapper, e.g.

$output = transform($stream)
    ->filter(...)
    ->map(...);

where transform wraps the stream in another stream that provides these methods.

[joshdifabio]

Unfortunately such functionality can only be implemented by adding the to be chained methods to each and every implementation, mixing responsibilities.

My suggestion is to only add a single apply() method to the implementations, not map(), filter(), flatMap() etc.

apply() would take a Transform object as an argument; map(), filter(), etc. would return Transform objects.

[kelunik]

How would the API of a Transform object and the implementation of apply look like?

[joshdifabio]

That's the tricky part!

[kelunik]

@joshdifabio Your comment was right, but without the leading \: https://github.com/amphp/amp/blob/3665df6e96c2fa603b66becccb4e3379570566eb/lib/Iterator.php

[joshdifabio]

Ah, you already have an async iterator!

interface Transform
{
    function apply($value): Iterator;
}

So the Stream::apply() function wouldn't be too difficult to implement I suppose.

[kelunik]

@joshdifabio We have the following options:

$stream = $stream->apply($a)->apply($b);

$stream = transform($stream)->apply($a)->apply($b);

$stream = transform($stream)->filter($a)->map($b);

The first one requires an additional method and violates single responsibility. The second one allows custom transforms, the third one is more expressive, but doesn't allow custom transforms.

[joshdifabio]

I like the first option the most. The second is okay too but it hides the functionality from users since the Stream interface wouldn't expose it. I think the third option is a bit too opinionated about which transform functions are worthy of being included in whatever object transform() returns.

One of the nice things about the apply($transform) pattern is that you can do things like composite transforms, and domain-specific objects can return domain-specific transforms to clients, for example:

$stream = $stream->apply(chunkStream())
                 ->apply($gzipAlgo->compressStream())
                 ->apply($cryptAlgo->encryptStream());

[kelunik]

I guess we should move this issue to amphp/byte-stream.

[kelunik]

This applies to both Amp\Iterator and amphp/byte-stream.

[kelunik]

Closing for now, we might revisit it at a later time. It can always be added, as the feature is self-contained. See #136.