Add documentation

README.md

@@ -47,8 +47,8 @@ __Other features__
 * Supports the transducer protocol. You can for instance transduce streams with
   [Ramda](http://ramdajs.com/) and [transducers.js](https://github.com/jlongster/transducers.js).
 * Complies to the [fantasy land](https://github.com/fantasyland/fantasy-land)
-  applicative specification.
 * [Elegant support for promises](#using-promises-for-asynchronous-operations).
+  monad specification.
 * [Atomic updates](#atomic-updates).
 
 ## Examples
@@ -224,6 +224,17 @@ flyd.on(function(responses) {
 }, responses);
 ```
 
+__Note:__ this functionality has been deprecated in favour of `flyd.fromPromise`.
+The above example should idiomatically be written as:
+
+```javascript
+var urls = flyd.stream('/something.json');
+var responses = flyd.fromPromise(requestPromise(urls()));
+flyd.on(function(responses) {
+  console.log('Received response!');
+  console.log(responses());
+}, responses);
+```
 ### Mapping over a stream
 
 You've now seen most of the basic building block which Flyd provides. Let's see
@@ -426,6 +437,57 @@ __Example__
 var numbers = flyd.stream(0);
 var squaredNumbers = flyd.map(function(n) { return n*n; }, numbers);
 ```
+### flyd.chain(fn, s)
+Given a stream of streams, returns a single stream of merged values from the created streams.
+
+Ends when every created stream and the main stream ends
+
+__Signature__
+
+`(a -> Stream b) -> Stream a -> Stream b`
+
+__Example__
+```javascript
+var filter = flyd.stream('filter');
+var search_results = flyd.chain(function(filter){
+  return flyd.fromPromise(getResults(filter));
+}, filter);
+```
+
+### flyd.ap(valueStream, functionStream)
+
+Applies the value in `valueStream` to the function in `functionStream`
+
+__Signature__
+`Stream a -> Stream (a -> b) -> Stream b`
+
+__Example__
+```javascript
+function add3(x) { return x + 3; }
+flyd.ap(flyd.stream(5), flyd.stream(add3)) // stream(8);
+```
+
+while it can not seem useful immediately consider this example
+
+```javascript
+var get_results = function (filter, sortProperty, sortDirection) {
+  return flyd.fromPromise(fetch(`${base_url}/search?q=${filter}&sort=${sortProperty} ${sortDirection}`))
+};
+
+// this would eventually be linked to an input field
+var filter = flyd.stream('');
+var sortProperty = flyd.stream('name');
+var sortDirection = flyd.stream('descending');
+
+var results = flyd.stream(flyd.curryN(3, get_results))
+  .pipe(flyd.ap(filter))
+  .pipe(flyd.ap(sortProperty))
+  .pipe(flyd.ap(sortDirection))
+  .pipe(flyd.map(function(d){ return d; }));
+```
+
+In the above example you have a stream of results that triggers a call for get_results
+every time `filter`, `sortProperty`, or `sortDirection` is changed.
 
 ### flyd.on(fn, s)
 
@@ -503,6 +565,21 @@ s1(1)(1)(2)(3)(3)(3)(4);
 results; // [2, 4, 6, 8]
 ```
 
+### flyd.fromPromise(promise)
+
+Transforms a promise into a stream.
+
+__Signature__
+`Promise a -> Stream a`
+
+__Example__
+```javascript
+const urls = flyd.stream('./something.json');
+const requests = flyd.chain(function(url){
+  return flyd.fromPromise(requestPromise(url));
+}, urls);
+```
+
 ### flyd.curryN(n, fn)
 
 Returns `fn` curried to `n`. Use this function to curry functions exposed by
@@ -555,7 +632,36 @@ names(); // 'Bohr'
 A stream that emits `true` when the stream ends. If `true` is pushed down the
 stream the parent stream ends.
 
-### stream.map(f)
+### stream.pipe(fn)
+
+Returns the result of applying function `fn` to the stream.
+
+__Signature__
+Called bound to `Stream a`: `(Stream a -> Stream b) -> Stream b`
+
+__Example__
+```javascript
+// map a stream
+var numbers = flyd.stream(0);
+var squaredNumbers = numbers
+  .pipe(flyd.map(function(n) { return n*n; }));
+
+// Chain a stream
+var filter = flyd.stream('filter');
+var search_results = filter
+  .pipe(flyd.chain(function(filter){
+    return flyd.fromPromise(getResults(filter));
+  }));
+
+// use with a flyd module
+var filter = require('flyd/module/filter');
+var numbers = flyd.stream(0);
+var isEven = function(x){ return x % 2 === 0; };
+var evenNumbers = numbers
+  .pipe(filter(isEven));
+```
+
+### stream.map(f) __Deprecated__
 
 Returns a new stream identical to the original except every
 value will be passed through `f`.
@@ -574,7 +680,7 @@ var numbers = flyd.stream(0);
 var squaredNumbers = numbers.map(function(n) { return n*n; });
 ```
 
-### stream1.ap(stream2)
+### stream1.ap(stream2) __Deprecated__
 
 `stream1` must be a stream of functions.
 
@@ -624,7 +730,6 @@ Modules listed with names in the format `flyd/module/filter` are builtin to the
 | --- | --- |
 | [flyd/module/**filter**](module/filter) | Filter values from stream based on predicate. |
 | [flyd/module/**lift**](module/lift) | Maps a function taking _n_ parameters over _n_ streams. |
-| [flyd/module/**flatmap**](module/flatmap) | Maps a function over a stream of streams and flattens the result to a single stream. |
 | [flyd/module/**switchlatest**](module/switchlatest) | Flattens a stream of streams. The result stream reflects changes from the last stream only. |
 | [flyd/module/**keepwhen**](module/keepwhen) | Keep values from one stream only when another stream is true. |
 | [flyd/module/**obj**](module/obj) | Functions for working with stream in objects. |

lib/index.js

@@ -185,8 +185,53 @@ flyd.map = curryN(2, function(f, s) {
   return combine(function(s, self) { self(f(s.val)); }, [s]);
 })
 
+/**
+ * Chain a stream
+ *
+ * also known as flatMap
+ *
+ * Where `fn` returns a stream this function will flatten the resulting streams.
+ * Every time `fn` is called the context of the returned stream will "switch" to that stream.
+ *
+ * __Signature__: `(a -> Stream b) -> Stream a -> Stream b`
+ *
+ * @name flyd.chain
+ * @param {Function} fn - the function that produces the streams to be flattened
+ * @param {stream} stream - the stream to map
+ * @return {stream} a new stream with the mapped values
+ *
+ * @example
+ * var filter = flyd.stream('who');
+ * var items = flyd.chain(function(filter){
+ *   return flyd.fromPromise(findUseres(filter));
+ * }, filter);
+ */
 flyd.chain = curryN(2, chain);
 
+/**
+ * Apply a stream
+ *
+ * Applies the value in `s2` to the function in `s1`.
+ *
+ * __Signature__: `Stream (a -> b) -> Stream a -> Stream b`
+ *
+ * @name flyd.ap
+ * @param {stream} s1 - The value to be applied
+ * @param {stream} s2 - The function expecting the value
+ * @return {stream} a new stream with the mapped values
+ *
+ * @example
+ * var add = stream(a => b => a + b)
+ * var n1 = stream(1)
+ * var n2 = stream(2)
+ *
+ * var added = flyd.ap(n2, flyd.ap(n1, add)) // stream(3)
+ * // can also be written using pipe
+ * var added_pipe = add
+ *   .pipe(ap(n1))
+ *   .pipe(ap(n2));
+ * added_pipe() // 3
+ */
 flyd.ap = curryN(2, ap);
 
 /**
@@ -346,6 +391,19 @@ flyd.curryN = curryN
  */
 function boundMap(f) { return flyd.map(f, this); }
 
+/**
+ * Returns the result of applying function `fn` to this stream
+ *
+ * __Signature__: Called bound to `Stream a`: `(Stream a -> Stream b) -> Stream b`
+ *
+ * @name stream.pipe
+ * @param {Function} fn - the function to apply
+ * @return {stream} A new stream
+ *
+ * @example
+ * var numbers = flyd.stream(0);
+ * var squaredNumbers = numbers.pipe(flyd.map(function(n){ return n*n; }));
+ */
 function operator_pipe(f) { return f(this) }
 
 function boundChain(f) {

module/flatmap/index.js

@@ -1,5 +1,7 @@
 var flyd = require('../../lib');
 
+console.warn('flyd/module/flatmap has been deprecated in favour of flyd.chain');
+
 /**
  * Given a stream of streams, returns a single stream of merged values
  * from the created streams.