baconjs/bacon.js — pull request #428 by skozin (2014-09-11 22:17:32+00:00)
Title: Bacon.sampledBy #2

Here is another take on `Bacon.sampledBy(props, samplers, combinator)` (the first is #387). It is a generalization of `Property.sampledBy`, and is based on `Bacon.when` as well.

Allows both props and samplers be either properties or streams. When all samplers are properties, the resulting stream is a Property, otherwise is an EventStream.

When a combinator function is provided, the resulting values are generated by applying the combinator to the sampled values of all props and samplers on each event from any sampler. Skips all samplings that occur before all props and samplers get their first events/values.

When no combinator is provided, the resulting values are generated by combining the sampled values of all props (but not samplers) into an array on each event from any sampler. Skips samplings that occur before all props, but not necessarily samplers, get their first values.

Preserves laziness when no combinator is provided, works with sync sources.

All in all, `Bacon.sampledBy` behaves as close as possible to `Property.sampledBy`, which now shares most of it's code with the former. The behavior of `Property.sampledBy` is unchanged as arguments to the internal call of `Bacon.when` remain the same.

The thing I'm not sure about is `unstable` markers in the specification. Why they're needed in the `"skips samplings that occur before the property gets its first value"` and `"works with synchronous sampler stream"` tests of `Property.sampledBy`? I added this marker to the similar tests of `Bacon.sampledBy`, but I have no idea whether it is necessary. Tests run successfully without them.