Switch Observable signature to Generator in Generator out

[benlesh]

Per #28, we need to match observable spec defined at http://github.com/zenparsing/es-observable

After discussion with @jhusain, it's been determined that the signature should be "generator in generator out", and that Generator should have an additional dispose method on it.

Here's the basics for purposes of this issue (the @zenparsing repo will be the "official" version of the spec though, it's just not updated as of the time of this issue creation):

// rough interface (could be more "genericky", I suppose)
interface Generator {
  next(value:any):IteratorResult<any>
  return(value:any):IteratorResult<any>
  throw(value:any):IteratorResult<any>
  dispose():void
}

let subscription:Generator = myObservable.subscribe(observer:Generator);

With this there will be three methods of unsubscribing:

1. subscription.return(x) - signal success to the consumer, then clean up.
2. subscription.throw(err) - signal an error to the consumer, then clean up.
3. subscription.dispose() - just clean up

Why?

This enables the support of generator functions as observers:

myObservable.subscribe(prime(function* () {
  try {
    while(true) {
      var value = yield; // nexted value
      doSomething(value);
    }
  } catch(err) {
    someErrorHappened(err)
  } finally {
    // clean up
  }
}));

which would be (roughly) synonymous with:

myObservable.subscribe({
  next(value) { doSomething(value); },
  throw(err) { someErrorHappened(err); },
  dispose() { completedSuccessfully(); }
});

Both will work, the latter is preferred in most cases, but the primed generator pattern can prove useful for things like parsers or other state machines that may built up values to clean up as it processes incoming values.

* Note: prime is a function that pumps one "next" value at the generator to get it started, since generators are initialized lazily with the first next call to their returned iterators.

/cc @jhusain

ref:

• Strawman: New subscription interface (cancel, return, throw) tc39/proposal-observable#32
• Don't use the generator interface tc39/proposal-observable#33

[benlesh]

FYI: The subscription shorthand method will still be supported, and will just get an extra handler:

myObservable.subscribe(nextHandler, throwHandler, returnHandler, disposeHandler);

[benlesh]

I no longer think this is the appropriate direction for this library or the observable spec. Closing for now. See discussion here: tc39/proposal-observable#35 (comment)

[benlesh]

FWIW: This subscription returned by the subscriber methods will remain as-is for now. I believe the behavior of disposal will change to be more on-par with current RxJS, however. And I'd like to add a subscribeWithGenerator method (or some such named thing) that primes the generator function passed, and returns a generator as a subscription object.