Add some example apps

[scriby]

Show an example Express application using asyncblock

[Animadei]

Also

1. add an example to show users that every function body requires another call to asyncblock before calling any async functions and that passing the flow object to callee functions should not be allowed;
2. add documentation that asyncblock.enableTransform() causes Node.js Tools debugger for Visual Studio 2015 to be unable to place breakpoints or single step because the final code is transformed and executed somewhere else. A workaround for the enableTransform() and .sync() convenience transform API is to not use it and use the comparable flow.sync() API instead.

By the way, Asyncblock is one of the most useful modules in Node.js and the best Fiber wrapper libraries out there. It's amazing why Node.js hasn't added Asyncblock and Fiber as part of its core deliverable. Writing asynchronous code couldn't be more easier and cleaner. Thank you.

[Animadei]

On the surface async/await looks like it could replace asyncblock, but it cannot until JavaScript also exposes a parent async context like asyncblock. There's no way to call await from a callback because of this. Here is a non-working async/await JavaScript ES7 example:

`
// An example showing how async/await cannot be used from a callback context.
//
// Using experimental Node.js v7.0.0:
// node --harmony test_asyncawait_bad.js
//
// Depends on:
// npm install request-promise
// npm install request
// npm install cheerio
//

"use strict";

let request = require("request-promise");
let cheerio = require("cheerio");

async function main () {
try {
let firstPage = await request.get("http://www.example.com");
let $ = cheerio.load(firstPage);
let hrefNodes = $("a");

hrefNodes.each((i, e) => {
  let linkFound = $(e).attr("href");
  let secondPage = await request.get(linkFound);
  console.log("Contents of link found: " + secondPage);
});

} catch (e) {
console.log("ERROR: " + e.stack);
}
}

main();

/*
OUTPUT:

  let secondPage = await request.get(linkFound);
                         ^^^^^^^

SyntaxError: Unexpected identifier
at Object.exports.runInThisContext (vm.js:76:16)
at Module._compile (module.js:545:28)
at Object.Module._extensions..js (module.js:582:10)
at Module.load (module.js:490:32)
at tryModuleLoad (module.js:449:12)
at Function.Module._load (module.js:441:3)
at Module.runMain (module.js:607:10)
at run (bootstrap_node.js:382:7)
at startup (bootstrap_node.js:137:9)
at bootstrap_node.js:497:3
*/
`

Here is a working asyncblock example that does what the async/await could not do:

`
// An example showing how Asyncblock can be used from a callback context.
//
// Using Node.js v6.9.1:
// node --harmony test_asyncblock_good.js
//
// Depends on:
// npm install asyncblock
// npm install request
// npm install cheerio
//

"use strict";

let asyncblock = require("asyncblock");
let request = require("request");
let cheerio = require("cheerio");

asyncblock(flow => {
try {
let firstPage = flow.sync(["response"], request, "http://www.example.com");
let $ = cheerio.load(firstPage.response.body);
let hrefNodes = $("a");

hrefNodes.each((i, e) => {
  let linkFound = $(e).attr("href");
  let secondPage = flow.sync(["response"], request, linkFound);
  console.log("Contents of link found: " + secondPage.response.body);
});

} catch (e) {
console.log("ERROR: " + e.stack);
}
});
`

As a bonus here is a working asyncblock example showing that the asynchronous context can be re-used and it makes code look real nice. This is what I wanted from JavaScript ES7 but that seems to remain a limitation.

`
// An example showing how to use Asyncblock's get current flow context from
// another function.
//
// Using Node.js v6.9.1:
// node --harmony test_asyncblock_good2.js
//
// Depends on:
// npm install asyncblock
// npm install request
// npm install cheerio
//

"use strict";

let asyncblock = require("asyncblock");
let request = require("request");
let cheerio = require("cheerio");

asyncblock(flow => {
try {
let $ = cheerio.load(fetchPage("http://www.example.com"));
let hrefNodes = $("a");

hrefNodes.each((i, e) => {
  let linkFound = $(e).attr("href");
  console.log("Contents of link found: " + fetchPage(linkFound));
});

} catch (e) {
console.log("ERROR: " + e.stack);
}
});

function fetchPage (url) {
let flow = asyncblock.getCurrentFlow();
let result = flow.sync(["response"], request, url);
return (typeof result.response !== "undefined" && result.response !== null) ? result.response.body : "";
}
`

There is just no replacement for asyncblock to date. It is so handy.