Addition of non-trivial examples.

[dmaevac]

Maybe add some non-trivial examples to the docs, as to many folks it will not be immediatley aparent what a powerful concept streams are.

Something like fetching data from one or more sources (xhr, json file?) then forking, parsing, combining, maybe generating some html elements.

I add this issue partially as a note, hopefully I will get some time to contribute some examples.

Related to https://github.com/caolan/highland/issues/28

[brian-gates]

Seconded! :+1:

[markstos]

A specific bit of docs that could use improvement: wrapCallback() seems to imply it works with callbacks that have more than two arguments, but it's not clear now this works. For example the request library returns (err,response,body).

[riston]

The 'body' should be also included in the response object. The possible solution would be something this:

// Edit well I have strange behavior, when using the request stream mode it does not pass anything forward, the issue is now reported https://github.com/caolan/highland/pull/42

var _       = require('highland'),
    fs      = require('fs'),
    request = require('request');

// This works but not using the stream approach
// function get(path) {

//     return _(function (push, next) {

//         request(path, function (error, response, body) {
//             // The response itself also contains the body
//             push(error, response);
//             push(null, _.nil);
//         });
//     });
// }

var google = _(request.get('http://www.google.com'));

// google
// _(fs.createReadStream('./highland.js', { encoding: 'utf-8' }))
// _(fs.createReadStream('./highland.js', { encoding: 'utf-8' }))

google
// res is empty array
.map(function (res) {
    // console.log(res);
    return res;
})
// res is empty array
.toArray(function (res) {

    console.log(res);
});