first cut at es6

Author: basarat

SUMMARY.md

@@ -2,3 +2,4 @@
 
 * [Gettting Started](docs/getting-started.md)
   * [Why TypeScript](docs/why-typescript.md)
+* [Future JavaScript Now](docs/future-javascript.md)

code/es6/test.ts

@@ -1,16 +1,13 @@
-var point2D = {
-    x: 0,
-    y: 10,
-};
-var point3D = {
-    x: 0,
-    y: 10,
-    z: 20
-};
-function iTakePoint2D(point) {
-}
-iTakePoint2D(point2D);
-iTakePoint2D(point3D);
-iTakePoint2D({
-    x: 0
-});
+var Point = (function () {
+    function Point(x, y) {
+        this.x = x;
+        this.y = y;
+    }
+    Point.prototype.add = function (point) {
+        return new Point(this.x + point.x, this.y + point.y);
+    };
+    return Point;
+})();
+var p1 = new Point(0, 10);
+var p2 = new Point(10, 20);
+var p3 = p1.add(p2);

code/testing.js

@@ -1,16 +1,11 @@
-interface Point2D {
-    x: number;
-    y: number;
+class Point {
+    constructor(public x: number, public y: number) {
+    }
+    add(point: Point) {
+        return new Point(this.x + point.x, this.y + point.y);
+    }
 }
-interface Point3D {
-    x: number;
-    y: number;
-    z: number;
-}
-var point2D: Point2D = { x: 0, y: 10, }
-var point3D: Point3D = { x: 0, y: 10, z: 20 }
-function iTakePoint2D(point: Point2D) { /* do something */ }
 
-iTakePoint2D(point2D); // exact match okay
-iTakePoint2D(point3D); // extra information okay
-iTakePoint2D({ x: 0 }); // Error: missing information `y`
+var p1 = new Point(0, 10);
+var p2 = new Point(10, 20);
+var p3 = p1.add(p2); // {x:10,y:30}

code/testing.ts

@@ -13,6 +13,7 @@
         "!./node_modules/**/*.ts"
     ],
     "files": [
+        "./es6/test.ts",
         "./testing.ts"
     ]
 }

code/tsconfig.json

@@ -0,0 +1,77 @@
+### Arrow Functions
+
+Lovingly called the *fat arrow* (becuase `->` is a thin arrow and `=>` is a fat arrow) and also called a *lambda function* (because of other languages). Another commonly used feature is the fat arrow function `()=>something`. The motivation for a *fat arrow* is: 
+1. You don't need to keep typing `function`
+1. I lexically captures the meaning of `this`
+
+For a language that claims to be functional, in JavaScript you tend to be typing `function` quite a lot. The fat arrow makes it simple for you to create a function 
+```ts
+var inc = (x)=>x+1;
+```
+`this` has traditionally been a pain point in JavaScript. As a wise man once said "I hate JavaScript as it tends to lose the meaning of `this` all too easily". Fat arrows fix it by capturing the meaning of `this` from the surrounding context. Consider this pure JavaScript class: 
+
+```ts
+function Person(age) {
+    this.age = age
+    this.growOld = function(){
+        this.age++;
+    }
+}
+var person = new Person(1); 
+setTimeout(person.growOld,1000);
+
+setTimeout(function(){ console.log(person.age); },2000); // 1, should have been 2
+```
+If you run this code in the browser `this` within the function is going to point to `window` because `window` is going to be what executes the `growOld` function. Fix is to use an arrow function: 
+```ts
+function Person(age) {
+    this.age = age
+    this.growOld = () => {
+        this.age++;
+    }
+}
+var person = new Person(1); 
+setTimeout(person.growOld,1000);
+
+setTimeout(function(){ console.log(person.age); },2000); // 2
+```
+The reason why this works is the reference to `this` is captured by the arrow function from outside the function body. This is equivalent to the following JavaScript code (which is what you would write yourself if you didn't have TypeScript): 
+```ts
+function Person(age) {
+    this.age = age
+    var _this = this;  // capture this
+    this.growOld = function() {
+        _this.age++;   // use the captured this
+    }
+}
+var person = new Person(1); 
+setTimeout(person.growOld,1000);
+
+setTimeout(function(){ console.log(person.age); },2000); // 2
+```
+Note that since you are using TypeScript you can be even sweeter in syntax and combine arrows with classes: 
+```ts
+class Person {
+    constructor(public age:number){}    
+    growOld = () => {
+        this.age++;
+    }
+}
+var person = new Person(1); 
+setTimeout(person.growOld,1000);
+
+setTimeout(function(){ console.log(person.age); },2000); // 2
+```
+
+#### Tip on Arrow Functions
+Beyond the terse syntax, you only *need* to use the fat arrow if you are going to give the function to someone else to call. Effectively: 
+```ts
+var growOld = person.growOld; 
+// Then later someone else calls it:
+growOld();
+```
+If you are going to call it yourself, i.e. 
+```ts
+person.growOld();
+```
+then `this` is going to be the correct calling context (in this example `person`).

docs/arrow-functions.md

@@ -0,0 +1,23 @@
+### Classes
+The reason why its important to have classes in JavaScript as a first class item is that: 
+1. People like to use classes
+1. Provides a consistent way for developers to use classes instead of every framework (emberjs,reactjs etc) coming up with their own version.
+
+```ts
+class Point {
+    constructor(public x: number, public y: number) {
+    }
+    add(point: Point) {
+        return new Point(this.x + point.x, this.y + point.y);
+    }
+}
+
+var p1 = new Point(0, 10);
+var p2 = new Point(10, 20);
+var p3 = p1.add(p2); // {x:10,y:30}
+```
+
+Finally JavaScript developers can *have class* :bowtie:. 
+
+[](Classes support inheritance)
+[](modifiers : public, private, protected)

docs/classes.md

@@ -0,0 +1,11 @@
+# Future JavaScript: Now
+One of the main selling points of TypeScript is that it allows you to use a bunch of features from ES6 in current (ES5 level) JavaScript engines (like current browsers and NodeJS). Here we deep dive into why these features are useful followed by how these features are implemented in TypeScript.
+
+1. Classes
+2. Arrow Functions
+
+## Classes
+{% include "./classes.md" %}
+
+## Arrow Functions
+{% include "./arrow-functions.md" %}            

docs/future-javascript.md

@@ -0,0 +1,16 @@
+{
+    "version": "1.4.1",
+    "compilerOptions": {
+        "target": "es5",
+        "module": "commonjs",
+        "declaration": false,
+        "noImplicitAny": false,
+        "removeComments": true,
+        "noLib": false
+    },
+    "filesGlob": [
+        "./**/*.ts",
+        "!./node_modules/**/*.ts"
+    ],
+    "files": []
+}

docs/tsconfig.json

@@ -14,7 +14,7 @@ We find it best to explain these in separation in first go.
 ### Your JavaScript is TypeScript
 TypeScript provides compile time Type safety for your JavaScript code. This is no surprise given its name. The great thing is that the types are completely optional. Your JavaScript code `.js` file can be renamed to a `.ts` file and TypeScript will still give you back valid `.js` equivalent to the original JavaScript file. TypeScript is *intentionally* and strictly a superset of JavaScript with optional Type checking.
 
-### Types are Inferred
+### Types can be Implicit
 In order to give you type safety with minimal cost of productivity during new code development. E.g. TypeScript will know that foo is of type `number` below and will give an error on the second line as shown:
 
 ```ts
@@ -25,7 +25,7 @@ foo = '456'; // Error: cannot assign `string` to `number`
 ```
 The motivation is that if you do stuff like this, in the rest of your code you cannot be certain that `foo` is a `number` or a `string`. Such issues turn up often in large multi-file code bases. We will deep dive into the type inference rules later.
 
-### Types can be specified
+### Types can be Explicit
 As we've mentioned before, TypeScript will infer as much as it can safely, however you can use annotations to:
 1. Help along the compiler, and more importantly the next developer who has to read your code (that might be future you!).
 1. Enforce that what the compiler sees is, what you thought it should see. That is your understanding of the code matches an algorithmic analysis of the code (done by the compiler).
@@ -65,9 +65,79 @@ iTakePoint2D(point3D); // extra information okay
 iTakePoint2D({ x: 0 }); // Error: missing information `y`
 ```
 
+### Type errors do not prevent JavaScript emit
+To make it easy for you to migrate your JavaScript code to TypeScript, even if there are compilation errors, by default TypeScript *will emit valid JavaScript* the best that it can. e.g.
+
+```ts
+var foo = 123;
+foo = '456'; // Error: cannot assign a `string` to a `number`
+```
+
+will emit the following js: 
+
+```ts
+var foo = 123;
+foo = '456';
+```
+
+So you can incrementally upgrade your JavaScript code to TypeScript. This is very different from how many other language compilers work and is there for your ease.
+
+### Types can be ambient
+A major design goal of TypeScript was to make it possible for you to safely and easily use existing JavaScript libraries in TypeScript. TypeScript does this by means of *declaration*. TypeScript provides you with a sliding scale of how much or how little effort you want to put in your declarations, the more effort you put the more type safety + code intelligence you get. Note that definitions for most of the popular libraries have already been written for you by the [DefinitelyTyped community](https://github.com/borisyankov/DefinitelyTyped) so for the most purposes: 
+
+1. The definition already exists 
+1. You have a vast list of well reviewed TypeScript declaration templates already available.
+
+As a quick example consider a trivial example of [jquery](https://jquery.com/). By default (as expect in good JS code) TypeScript expects you to declare (i.e. use `var` somewhere) before you use a variable
+```ts
+$('.awesome').show(); // Error: cannot find name `$`
+```
+As a quick fix *you can tell TypeScript* that there is indeed something called `$`: 
+```ts
+declare var $:any;
+$('.awesome').show(); // Okay! 
+```
+If you want you can build on this basic definition and provide more information to help protect you from errors: 
+```ts
+declare var $:{
+    (selector:string)=>any;
+};
+$('.awesome').show(); // Okay! 
+$(123).show(); // Error: selector needs to be a string
+```
+
+We will discuss the details of creating TypeScript definitions for existing JavaScript in detail later once you know more about TypeScript (e.g. stuff like `interface` and the `any`).
+
+## Future JavaScript Now
+TypeScript provides a number of features that are planned in ES6 for current JavaScript engines (that only support ES5 etc). The typescript team is actively adding these features and this list is only going to get bigger over time and we will cover this in its own section. But just as a specimen here is an example of a class: 
+
+```ts
+class Point {
+    constructor(public x: number, public y: number) {
+    }
+    add(point: Point) {
+        return new Point(this.x + point.x, this.y + point.y);
+    }
+}
+
+var p1 = new Point(0, 10);
+var p2 = new Point(10, 20);
+var p3 = p1.add(p2); // {x:10,y:30}
+```
+
+and the lovely fat arrow function: 
+
+```ts
+var inc = (x)=>x+1;
+```
+
+### Summary
+In this section we have provided you with the motivation and design goals of TypeScript. With this out of the way we can dig into the nitty gritty details of TypeScript.
 
 [](Interfaces are open ended)
 [](Type Inferernce rules)
 [](Cover all the annotations)
+[](Cover all ambients : also that there are no runtime enforcement)
+
 
 {% include "footer.md" %}

docs/why-typescript.md

@@ -0,0 +1,6 @@
+'.source.gfm':
+    'include':
+        'prefix': 'include'
+        'body': """
+            {% include "${1:./path}.md" %}            
+        """