Static compute stream API ~13

[justinbmeyer]

Related to #2, but only focusing on the static API exported from this module.

toStream use cases:

• take a compute's value and convert to event stream #1
• convert an observable property #2a (or nested property #2b) into an event stream
• convert an observable event #3a (or nested observable event #3b) into an event stream

  Proposal 1 - reduced, common patterns API

Pros:

• simple, 2 methods

Cons:

• ugly to listen to an object's events .toStream(map, ".", "closed");

  .toStream(compute)

computeStream.toStream(compute) //-> stream that emits with compute value #1

.toStream( * , propName, [eventName])

computeStream.toStream(map, "tasks") 
       //-> stream that emits with `tasks` property changes #2a + #3a

computeStream.toStream(map, "foo.bar") 
      //-> stream that emits when `bar` changes on 
      //     `foo` or `foo` changes with a different `bar`.
      //     #2b

computeStream.toStream(map, "tasks","add") 
      //-> stream that emits with `tasks`'s "add" event dispatches
      //     #3b

computeStream.toStream(map, ".", "closed"); 
    //-> stream that emits with `closed` event on `map` #3a

.toCompute(stream)

computeStream.toCompute(stream) //-> compute that changes with `stream.valueOf`

Proposal 2 - closer to event stream expectations

Pros:

• simple, 2 methods

Cons:

• ugly to do the most common case for CanJS (know when a property has changed).
• position of event argument changes

  .toStream(compute)

computeStream.toStream(compute) //-> stream that emits with compute value

.toStream( * , eventName )

computeStream.toStream(map, "tasks") 
         //-> stream that emits with `tasks` event.  
         //    This will commonly be when `tasks` changes.
         // #2a + #3a 

computeStream.toStream(map, "closed")  //#3a

computeStream.toStream( compute(map,"foo.bar"), "change" )
         //-> stream that emits when `foo` or `bar` changes. #2b by way of #1

.toStream( * , propertyName, eventName )

computeStream.toStream(map, "tasks","add") 
      //-> stream that emits with `tasks`'s "add" event dispatches
      //     #3b

Proposal 3 - spaces and dots

Pros:

• solves everything ... in a reasonable way

Cons:

• Have to know to use spaces.
• Only works because CanJS's conventions of dispatching event for the property change.

computeStream.toStream(compute)  //#1

computeStream.toStream(obj, "tasks") //#2a
computeStream.toStream(obj, "foo.bar") //#2b

computeStream.toStream( obj, "close") //#3a
computeStream.toStream(obj, "tasks add") //#3b
computeStream.toStream(obj, "person.tasks add") //#3b

Alternate, force people to use . for property reads.

computeStream.toStream(compute)  //#1

computeStream.toStream(obj, ".tasks") //#2a
computeStream.toStream(obj, ".foo.bar") //#2b

computeStream.toStream( obj, "close") //#3a
computeStream.toStream(obj, ".tasks add") //#3b
computeStream.toStream(obj, ".person.tasks add") //#3b

Proposal 4 - To each his/her own

.toStreamFromCompute

.toStreamFromPropery(obs, propName )

.toStreamFromEvent(obs, event)

.toStreamFromEvent(obs, propName, event)

[justinbmeyer]

computeStream.toStream(obj, ".fullName") //#2a
computeStream.toStream(obj, "fullName") //#3a

obj = {
  get fullName() {
    Observation.add(this, "first")
    Observation.add(this,"last")
    return this.first + " " + this.last;
  } 
}