Adding more docs for transducers for Issue #327

Author: mattpodwysocki

doc/gettingstarted/transducers.md

@@ -0,0 +1,99 @@
+# Transducers with Observable Sequences #
+
+Much like Language Integrated Query (LINQ), Transducers are composable algorithmic transformations. They, like LINQ, are independent from the context of their input and output sources and specify only the essence of the transformation in terms of an individual element. Because transducers are decoupled from input or output sources, they can be used in many different processes - collections, streams, observables, etc. Transducers compose directly, without awareness of input or creation of intermediate aggregates.  There are two major libraries currently out there, Cognitect's [`transduce.js`](https://github.com/cognitect-labs/transducers-js) and James Long's [`transduce-js`](https://github.com/jlongster/transducers.js) which are both great for getting high performance over large amounts of data.  Because it is collection type neutral, it is a perfect fit for RxJS to do transformations over large collections.
+
+The word `transduce` is just a combination of `transform` and `reduce`. The reduce function is the base transformation; any other transformation can be expressed in terms of it (`map`, `filter`, etc).
+```js
+var arr = [1, 2, 3, 4];
+
+arr.reduce(
+  function(result, x) { return result.concat(x + 1); }, []);
+
+// => [ 2, 3, 4, 5 ]
+```
+
+Using transducers, we can model the following behavior while breaking apart the map aspect of adding 1 to the concat operation, adding the seed and then the "collection" to transduce.
+
+```js
+var arr = [1, 2, 3, 4];
+
+function increment(x) { return x + 1; }
+function concatItem(acc, x) { return acc.concat(x); }
+
+transduce(map(increment), concatItem, [], arr);
+
+// => [ 2, 3, 4, 5 ]
+```
+
+Using Cognitect's [`transduce.js`](https://github.com/cognitect-labs/transducers-js) library, we can easily accomplish what we had above.  
+
+```js
+var t = transducers;
+
+var arr = [1, 2, 3, 4];
+
+function increment(x) { return x + 1; }
+
+into([], t.comp(t.map(increment)), arr);
+
+// => [ 2, 3, 4, 5 ]
+```
+
+We can go a step further and add filtering as well to get only even values.
+
+```js
+var t = transducers;
+
+var arr = [1, 2, 3, 4];
+
+function increment(x) { return x + 1; }
+function isEven(x) { return x % 2 === 0; }
+
+into([], t.comp(t.map(increment), t.filter(isEven)), arr);
+
+// => [ 2, 4 ]
+```
+
+Since it works so well using Arrays, there's no reason why it cannot work for Observable sequences as well.  To that end, we have introduced the [`transduce`](https://github.com/Reactive-Extensions/RxJS/tree/master/doc/api/core/operators/transduce.md) method which acts exactly like it does for Arrays, but for Observable sequences.  Once again, let's go over the above example, this time using an Observable sequence.
+
+```js
+var t = transducers;
+
+var source = Rx.Observable.range(1, 4);
+
+function increment(x) { return x + 1; }
+function isEven(x) { return x % 2 === 0; }
+
+var transduced = source.transduce(t.comp(t.map(increment), t.filter(isEven)));
+
+transduced.subscribe(
+  function (x) { console.log('Next: %s', x); },
+  function (e) { console.log('Error: %s', e); },
+  function ()  { console.log('Completed'); });
+
+// => Next: 2
+// => Next: 4
+// => Completed
+```
+
+Note that this above example also works the same with `transducers.js` as well with little to no modification.  This example will in fact work faster than the traditional LINQ style (as of now) which most use currently.
+
+```js
+var source = Rx.Observable.range(1, 4);
+
+function increment(x) { return x + 1; }
+function isEven(x) { return x % 2 === 0; }
+
+var transduced = source.map(increment).filter(isEven);
+
+transduced.subscribe(
+  function (x) { console.log('Next: %s', x); },
+  function (e) { console.log('Error: %s', e); },
+  function ()  { console.log('Completed'); });
+
+// => Next: 2
+// => Next: 4
+// => Completed
+```
+
+This opens up a wide new set of possibilities making RxJS even faster over large collections with no intermediate Observable sequences.

doc/readme.md

@@ -13,13 +13,13 @@ RxJS has no dependencies which complements and interoperates smoothly with both
    <th></th><th>Single return value</th><th>Mutiple return values</th>
    <tr>
       <td>Pull/Synchronous/Interactive</td>
-      <td>`Object`</td>
-      <td>Iterables (`Array` | `Set` | `Map`)</td>
+      <td><pre><code>Object</code></pre></td>
+      <td>Iterables(<pre><code>Array</code></pre> | <pre><code>Set</code></pre> | <pre><code>Map</code></pre>)</td>
    </tr>
    <tr>
       <td>Push/Asynchronous/Reactive</td>
-      <td>`Promise`</td>
-      <td>`Observable`</td>
+      <td><pre><code>Promise</code></pre></td>
+      <td><pre><code>Observable</code></pre></td>
    </tr>
 </table>
 </center>

src/core/linq/observable/concatmap.js

@@ -27,7 +27,7 @@
    * @returns {Observable} An observable sequence whose elements are the result of invoking the one-to-many transform function collectionSelector on each element of the input sequence and then mapping each of those sequence elements and their corresponding source element to a result element.
    */
   observableProto.selectConcat = observableProto.concatMap = function (selector, resultSelector, thisArg) {
-    if (resultSelector) {
+    if (typeof selector === 'function' && typeof resultSelector === 'function') {
       return this.concatMap(function (x, i) {
         var selectorResult = selector(x, i);
         isPromise(selectorResult) && (selectorResult = observableFromPromise(selectorResult));

src/core/linq/observable/selectmany.js

@@ -27,7 +27,7 @@
    * @returns {Observable} An observable sequence whose elements are the result of invoking the one-to-many transform function collectionSelector on each element of the input sequence and then mapping each of those sequence elements and their corresponding source element to a result element.
    */
   observableProto.selectMany = observableProto.flatMap = function (selector, resultSelector, thisArg) {
-    if (resultSelector) {
+    if (typeof selector === 'function' && typeof resultSelector === 'function') {
       return this.flatMap(function (x, i) {
         var selectorResult = selector(x, i);
         isPromise(selectorResult) && (selectorResult = observableFromPromise(selectorResult));