waves.io basic design concept

gistfile1.txt

- Wave[T]
  - not reusable stream of Ts
- Drain[T]
  - not reusable stream sink for Ts
- Source[T]
  - has `def newWave(): Wave[T]`, i.e. is creator for Wave[T] instances
  - has implicit conversion to Wave[T], i.e. can be used whereever a Wave[T] is expected
- Sink[T]
  - has `def newDrain(): Drain[T]`, i.e. is creator for Drain[T] instances
  - has implicit conversion to Drain[T], i.e. can be used whereever a Drain[T] is expected
- Operation[A, B]
  - reuseable wave transformation from A to B
  - Wave[A] + Operation[A, B] = Wave[B]
  - Operation[A, B] + Drain[B] = Drain[A]
  - Source[T] + Operation[A, B] = Source[B]
  - Operation[A, B] + Sink[B] = Sink[A]
- Combining Waves/Sources with Drain/Sinks:
  - Wave[T] + Drain[T] = Unit
    - materializes and immediately starts the stream
    - afterwards the wave and the drain are consumed and cannot be reused
  - Source[T] + Sink[T] = FlowCreator
    - FlowCreator::startNew() = source.newWave + sink.newDrain = Unit

- Complex stream graphs (potentially several waves, several drains)
  - Can be assembled using operations (e.g. `split` or `merge`)
  - Always have a "main line" which eventually triggers materialization/starting
  - Examples:
    - Wave[A]::tee(Drain[A]) = Wave[A]
    - Wave[A]::merge(Wave[A]) = Wave[A]
  - Substreams (e.g. arg to `tee` or `merge`) are materialized/started
    when the main line is materialized/started
  - Graphs with a single main line can be optimized/materialized as one single entity,
    i.e. without (required) inner async boundaries
  - Multiple main lines require async boundaries in between
    - Example (`proxy` implements async boundary):
      val proxy = new DrainWave[A]
      wave1.tee(proxy).produceTo(sink1) // materializes and starts stream 1
      wave2.merge(proxy).produceTo(sink2) // materializes and starts stream 2
  - No "WaveGraph", "FlowGraph" or any other graph abstraction

- Deep, a priori, optimization possible for:
  - Operation[A, B]
  - Source[T]
  - Sink[T]
  - FlowCreator
  - including (single main line) graph setups like, e.g.,
    - Source[A]::tee(Sink[A]) = Source[A]
    - Source[A]::merge(Source[A]) = Source[A]

- Open Questions
  - Is there a good reason for separating Wave + Drain combination from materialization/starting?
    I.e. should `Wave[T] + Drain[T]` return a Startable rather than Unit?