document closure. Closes basarat#139

Author: Basarat Ali Syed

SUMMARY.md

@@ -4,6 +4,7 @@
   * [Why TypeScript](docs/why-typescript.md)
 * [JavaScript](docs/javascript/recap.md)
   * [Awful](docs/javascript/awful.md)
+  * [Closure](docs/javascript/closure.md)
 * [Future JavaScript Now](docs/future-javascript.md)
   * [Classes](docs/classes.md)
     * [Classes Emit](docs/classes-emit.md)

code/javascript/closure.js

@@ -0,0 +1,41 @@
+"use strict";
+function outerFunction(arg) {
+    var variableInOuterFunction = arg;
+    function bar() {
+        console.log(variableInOuterFunction);
+    }
+    bar();
+}
+outerFunction("hello closure");
+var another;
+(function (another) {
+    function outerFunction(arg) {
+        var variableInOuterFunction = arg;
+        return function () {
+            console.log(variableInOuterFunction);
+        };
+    }
+    var innerFunction = outerFunction("hello closure!");
+    innerFunction();
+})(another = exports.another || (exports.another = {}));
+var revealing;
+(function (revealing) {
+    function createCounter() {
+        var val = 0;
+        return {
+            increment: function () { val++; },
+            getVal: function () { return val; }
+        };
+    }
+    var counter = createCounter();
+    counter.increment();
+    console.log(counter.getVal());
+})(revealing = exports.revealing || (exports.revealing = {}));
+var server;
+(function (server) {
+    server.on(function handler(req, res) {
+        loadData(req.id).then(function (data) {
+            res.send(data);
+        });
+    });
+})(server = exports.server || (exports.server = {}));

code/javascript/closure.ts

@@ -0,0 +1,51 @@
+function outerFunction(arg) {
+    var variableInOuterFunction = arg;
+
+    function bar() {
+        console.log(variableInOuterFunction); // Access a variable from the outer scope
+    }
+
+    // Call the local function to demonstrate that it has access to arg
+    bar();
+}
+
+outerFunction("hello closure"); // logs hello closure!
+
+
+export namespace another {
+    function outerFunction(arg) {
+        var variableInOuterFunction = arg;
+        return function() {
+            console.log(variableInOuterFunction);
+        }
+    }
+
+    var innerFunction = outerFunction("hello closure!");
+
+    // Note the outerFunction has returned
+    innerFunction(); // logs hello closure!
+}
+
+
+export namespace revealing {
+    function createCounter() {
+        let val = 0;
+        return {
+            increment() { val++ },
+            getVal() { return val }
+        }
+    }
+
+    let counter = createCounter();
+    counter.increment();
+    console.log(counter.getVal()); // 1
+}
+
+export namespace server {
+    server.on(function handler(req, res) {
+        loadData(req.id).then(function(data) {
+            // the `res` has been closed over and is available
+            res.send(data);
+        })
+    });
+}

code/javascript/tsconfig.json

@@ -0,0 +1,28 @@
+{
+    "compilerOptions": {
+        "target": "es5",
+        "module": "commonjs",
+        "moduleResolution": "node",
+        "isolatedModules": false,
+        "jsx": "react",
+        "experimentalDecorators": true,
+        "emitDecoratorMetadata": true,
+        "declaration": false,
+        "noImplicitAny": false,
+        "noImplicitUseStrict": false,
+        "removeComments": true,
+        "noLib": false,
+        "preserveConstEnums": true,
+        "suppressImplicitAnyIndexErrors": true
+    },
+    "exclude": [
+        "node_modules",
+        "typings/browser",
+        "typings/browser.d.ts"
+    ],
+    "compileOnSave": true,
+    "buildOnSave": false,
+    "atom": {
+        "rewriteTsconfig": false
+    }
+}

docs/javascript/closure.md

@@ -1,3 +1,67 @@
 ## Closure
 
-The best thing that JavaScript ever got was closures. 
+The best thing that JavaScript ever got was closures. A function in JavaScript has access to any variables defined in the outer scope. Closures are best explained with examples:
+
+```ts
+function outerFunction(arg) {
+    var variableInOuterFunction = arg;
+
+    function bar() {
+        console.log(variableInOuterFunction); // Access a variable from the outer scope
+    }
+
+    // Call the local function to demonstrate that it has access to arg
+    bar();
+}
+
+outerFunction("hello closure"); // logs hello closure!
+```
+
+You can see that the inner function has access to a variable (variableInOuterFunction) from the outer scope. The variables in the outer function have been closed by (or bound in) the inner function. Hence the term **closure**. The concept in itself is simple enough and pretty intuitive.
+
+Now the awesome part: The inner function can access the variables from the outer scope *even after the outer function has returned*. This is because the variables are still bound in the inner function and not dependent on the outer function. Again let's look at an example:
+
+```ts
+function outerFunction(arg) {
+    var variableInOuterFunction = arg;
+    return function() {
+        console.log(variableInOuterFunction);
+    }
+}
+
+var innerFunction = outerFunction("hello closure!");
+
+// Note the outerFunction has returned
+innerFunction(); // logs hello closure!
+```
+
+### Reason why its awesome
+It allows you to compose objects easily e.g. the revealing module pattern:
+
+```ts
+function createCounter() {
+    let val = 0;
+    return {
+        increment() { val++ },
+        getVal() { return val }
+    }
+}
+
+let counter = createCounter();
+counter.increment();
+console.log(counter.getVal()); // 1
+counter.increment();
+console.log(counter.getVal()); // 2
+```
+
+At a high level it is also what makes something like nodejs possible (don't worry if it doesn't click in your brain right now. It will eventually 🌹):
+
+```ts
+// Pseudo code to explain the concept
+server.on(function handler(req, res) {
+    loadData(req.id).then(function(data) {
+        // the `res` has been closed over and is available
+        res.send(data);
+    })
+});
+```