@ahoy-jon good point, although do you know why the parameter is call-by-name? I don't really see the point. I notice that in Pending.scala handle is an inline method. Should Stream#handle also be inline? @fwbrasil do you have some guidance here?

I don't have the logic behind this call-by-name, but there might be something to do with inlining and allocations.

a potential signature could be:

 def handle[V1 >: V, S1](
        f:  (=> Unit < S) => (Unit < (Emit[Chunk[V1]] & S1))
    )(using Frame, Tag[Emit[Chunk[V1]]], Tag[Emit[Chunk[V]]]): Stream[V1, S1]

I have a case for a Stream[Int, IO & Abort] (for Stream.fromIteratorCatching), that could be done like that:

stream.handle(
 _.fold(
   onSuccess = () => Chunk.empty, 
   onFail = _ => Chunk(-1), 
   onPanic = _ => Chunk(-2)
 ), 
  _.map(chunk => Emit.value(chunk))
)

@ahoy-jon good point, although do you know why the parameter is call-by-name? I don't really see the point. I notice that in Pending.scala handle is an inline method. Should Stream#handle also be inline? @fwbrasil do you have some guidance here?

The by-name param was introduced to allow Abort to handle the case when the computation panics without ever suspending. For example, ((throw ex): Int < Any).handle(Abort.run) produces Result.Panic(ex) instead of just throwing. Ideally, users should ensure code that may fail is suspended but we try to provide some built-in safety in APIs where possible. I think we should do the same for stream.handle.

Regarding inline, I don't think we need it. Streams are typically built once and reused multiple times so the potential improvement is limited.

I have a case for a Stream[Int, IO & Abort] (for Stream.fromIteratorCatching), that could be done like that:

We recommend handle only for effect handling, not regular transformations. I think it's important to avoid confusion and reduce the ways of doing the same thing.

I updated Stream#handle to accept functions with call-by-name inputs