Merge pull request #1 from basarat/master

pull upstream

Author: spences10

README.md

@@ -27,6 +27,8 @@ I've been looking at the issues that turn up commonly when people start using Ty
 * Thank you for writing TypeScript Deep Dive. I have learned so much. [link](https://twitter.com/buctwbzs/status/857198618704355328?refsrc=email&s=11)
 * Loving @basarat's @typescriptlang online book basarat.gitbooks.io/typescript/# loaded with great recipes! [link](https://twitter.com/ericliprandi/status/857608837309677568)
 * Microsoft doc is great already, but if want to "dig deeper" into TypeScript I find this book of great value  [link](https://twitter.com/caludio/status/876729910550831104)
+* Thanks, this is a great book 🤓🤓 [link](https://twitter.com/jjwonmin/status/885666375548547073)
+* Deep dive to typescript is awesome in so many levels. i find it very insightful. Thanks [link](https://twitter.com/orenmizr/status/891083492787970053)
 
 ## Get Started
 If you are here to read the book online [get started](http://basarat.gitbooks.io/typescript/content/docs/getting-started.html).

SUMMARY.md

@@ -3,13 +3,16 @@
 * [Getting Started](docs/getting-started.md)
   * [Why TypeScript](docs/why-typescript.md)
 * [JavaScript](docs/javascript/recap.md)
-  * [Awful](docs/javascript/awful.md)
+  * [Equality](docs/javascript/equality.md)
+  * [References](docs/javascript/references.md)
+  * [Null vs. Undefined](docs/javascript/null-undefined.md)
+  * [this](docs/javascript/this.md)
   * [Closure](docs/javascript/closure.md)
+  * [Number](docs/javascript/number.md)
 * [Future JavaScript Now](docs/future-javascript.md)
   * [Classes](docs/classes.md)
     * [Classes Emit](docs/classes-emit.md)
     * [Classes Super](docs/classes-super.md)
-    * [Classes Extensibility](docs/classes-extensibility-wip.md)
   * [Arrow Functions](docs/arrow-functions.md)
   * [Rest Parameters](docs/rest-parameters.md)
   * [let](docs/let.md)
@@ -31,7 +34,8 @@
     * [File Module Details](docs/project/external-modules.md)
     * [globals.d.ts](docs/project/globals.md)
   * [Namespaces](docs/project/namespaces.md)
-* [NodeJS QuickStart](docs/quick/nodejs.md)
+  * [Dynamic Import Expressions](docs/project/dynamic-import-expressions.md)
+* [Node.js QuickStart](docs/quick/nodejs.md)
 * [Browser QuickStart](docs/quick/browser.md)
 * [TypeScript's Type System](docs/types/type-system.md)
   * [JS Migration Guide](docs/types/migrating.md)
@@ -43,6 +47,7 @@
   * [Enums](docs/enums.md)
   * [`lib.d.ts`](docs/types/lib.d.ts.md)
   * [Functions](docs/types/functions.md)
+  * [Callable](docs/types/callable.md)
   * [Type Assertion](docs/types/type-assertion.md)
   * [Freshness](docs/types/freshness.md)
   * [Type Guard](docs/types/typeGuard.md)
@@ -82,7 +87,7 @@
   * [Build Toggles](docs/tips/build-toggles.md)
   * [Barrel](docs/tips/barrel.md)
   * [Create Arrays](docs/tips/create-arrays.md)
-  * [Promise Safety](docs/tips/promise-safety.md)
+  * [Typesafe Event Emitter](docs/tips/typed-event.md)
 * [StyleGuide](docs/styleguide/styleguide.md)
 * [Common Errors](docs/errors/main.md)
 * [TypeScript Compiler Internals](docs/compiler/overview.md)

book.json

@@ -1,13 +1,25 @@
 {
-  "gitbook": ">=3.2.1",
-  "plugins": ["edit-link", "github"],
+  "plugins": ["edit-link", "github", "adsense","header"],
   "pluginsConfig": {
+    "layout": {
+      "headerPath" : "header.html"
+    },
+    "lunr": {
+      "ignoreSpecialCharacters": true
+    },
     "edit-link": {
       "base": "https://github.com/basarat/typescript-book/tree/master",
       "label": "Edit This Page"
     },
     "github": {
       "url": "https://github.com/basarat/typescript-book/"
+    },
+    "adsense": {
+      "client": "ca-pub-4656761253552116",
+      "slot": "2017468453",
+      "format": "auto",
+      "element": ".page-inner section",
+      "position": "bottom"
     }
   }
 }

code/async-await/es5/asyncAwaitES5.js

@@ -40,7 +40,7 @@ function delay(milliseconds, count) {
         }, milliseconds);
     });
 }
-// async function allways return a Promise
+// async function always return a Promise
 function dramaticWelcome() {
     return __awaiter(this, void 0, void 0, function () {
         var i, count;

code/async-await/es5/asyncAwaitES5.ts

@@ -6,7 +6,7 @@ function delay(milliseconds: number, count: number): Promise<number> {
         });
 }
 
-// async function allways return a Promise
+// async function always return a Promise
 async function dramaticWelcome(): Promise<void> {
     console.log("Hello");
 

code/async-await/es6/asyncAwaitES6.js

@@ -13,7 +13,7 @@ function delay(milliseconds, count) {
         }, milliseconds);
     });
 }
-// async function allways return a Promise
+// async function always return a Promise
 function dramaticWelcome() {
     return __awaiter(this, void 0, void 0, function* () {
         console.log("Hello");

code/async-await/es6/asyncAwaitES6.ts

@@ -6,7 +6,7 @@ function delay(milliseconds: number, count: number): Promise<number> {
         });
 }
 
-// async function allways return a Promise
+// async function always return a Promise
 async function dramaticWelcome(): Promise<void> {
     console.log("Hello");
 

code/dynamic-import-expressions/dynamicImportExpression.js

@@ -0,0 +1,14 @@
+"use strict";
+function myApp() {
+    import(/* webpackChunkName: "momentjs" */ "moment")
+        .then(function (moment) {
+        // lazyModule has all of the proper types, autocomplete works,
+        // type checking works, code references work \o/
+        var time = moment().format();
+        console.log("TypeScript >= 2.4.0 Dynamic Import Expression:");
+        console.log(time);
+    })
+        .catch(function (err) {
+        console.log("Failed to load moment", err);
+    });
+}

code/dynamic-import-expressions/dynamicImportExpression.ts

@@ -0,0 +1,14 @@
+
+function myApp() {
+    import(/* webpackChunkName: "momentjs" */ "moment")
+        .then((moment) => {
+            // lazyModule has all of the proper types, autocomplete works,
+            // type checking works, code references work \o/
+            const time = moment().format();
+            console.log("TypeScript >= 2.4.0 Dynamic Import Expression:");
+            console.log(time);
+        })
+        .catch((err) => {
+            console.log("Failed to load moment", err);
+        });
+}

code/dynamic-import-expressions/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "dynamic-import-expressions",
+  "version": "1.0.0",
+  "description": "",
+  "main": "dynamicImportExpression.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Jose Quinto Zamora - https://blog.josequinto.com",
+  "license": "ISC",
+  "devDependencies": {
+    "typescript": "^2.4.1"
+  },
+  "dependencies": {
+    "moment": "^2.18.1"
+  }
+}

code/dynamic-import-expressions/tsconfig.json

@@ -0,0 +1,17 @@
+{
+    "compilerOptions": {
+        "target": "es5",                          
+        "module": "esnext",                     
+        "lib": [
+            "dom",
+            "es5",
+            "scripthost",
+            "es2015.promise"
+        ],                                        
+        "strict": true,                           
+        "moduleResolution": "node"            
+    },
+    "files": [
+      "./dynamicImportExpression.ts"
+  ]
+}

code/types/callable.ts

@@ -0,0 +1,46 @@
+export namespace asdfasdfasdfasdflkjasdflkjasdflkjasdflkjasdf {
+}
+
+namespace A {
+  interface ReturnString {
+    (): string
+  }
+  declare const foo: ReturnString;
+  const bar = foo(); // bar is inferred as a string
+}
+
+namespace Complex {
+  interface Complex {
+    (foo: string, bar?: number, ...others: boolean[]): number;
+  }
+
+  interface Overloaded {
+    (foo: string): string
+    (foo: number): number
+  }
+
+  // example implementation
+  const overloaded: Overloaded = (foo) => foo;
+
+  // example usage
+  const str = overloaded(''); // str is inferred string
+  const number = overloaded(123); // num is inferred number
+}
+
+namespace Direct {
+  const overloaded: {
+    (foo: string): string
+    (foo: number): number
+  } = (foo) => foo;
+
+  const simple: (foo: number) => string
+    = (foo) => foo.toString();
+
+  interface CallMeWithNewToGetString {
+    new(): string
+  }
+  // Usage 
+  declare const Foo: CallMeWithNewToGetString;
+  const bar = new Foo(); // bar is inferred to be of type string 
+}
+

code/types/freshness/index-signatures.ts

@@ -138,7 +138,7 @@ module jsland {
   }
 
   const failsSilently: NestedCSS = {
-    colour: 'red', // No error is `colour` is a valid string selector
+    colour: 'red', // No error as `colour` is a valid string selector
   }
 }
 

docs/async-await.md

@@ -63,7 +63,7 @@ function delay(milliseconds: number, count: number): Promise<number> {
         });
 }
 
-// async function allways return a Promise
+// async function always return a Promise
 async function dramaticWelcome(): Promise<void> {
     console.log("Hello");
 
@@ -96,7 +96,7 @@ function delay(milliseconds, count) {
         }, milliseconds);
     });
 }
-// async function allways return a Promise
+// async function always return a Promise
 function dramaticWelcome() {
     return __awaiter(this, void 0, void 0, function* () {
         console.log("Hello");
@@ -157,7 +157,7 @@ function delay(milliseconds, count) {
         }, milliseconds);
     });
 }
-// async function allways return a Promise
+// async function always return a Promise
 function dramaticWelcome() {
     return __awaiter(this, void 0, void 0, function () {
         var i, count;

docs/classes-emit.md

@@ -65,7 +65,7 @@ After having tutored many people about this I find the following explanation to
 1. effect of `new` on `this` inside the called function
 1. effect of `new` on `prototype` and `__proto__`
 
-All objects in JavaScript contain a `__proto__` member. This member is often not accessible in older browsers (sometimes documentation refers to this magical property as `[[prototype]]`). It has one objective: If a property is not found on an object during lookup (e.g. `obj.property`) then it is looked up at `obj.__proto__.property`. If it is still not found then `obj.__proto__.__proto__.property` till either: *it is found* or *the latest `.__proto__` itself is null*. This explains why JavaScript is said to support *prototypal inheritance* out of the box. This is shown in the following example, which you can run in the chrome console or nodejs:
+All objects in JavaScript contain a `__proto__` member. This member is often not accessible in older browsers (sometimes documentation refers to this magical property as `[[prototype]]`). It has one objective: If a property is not found on an object during lookup (e.g. `obj.property`) then it is looked up at `obj.__proto__.property`. If it is still not found then `obj.__proto__.__proto__.property` till either: *it is found* or *the latest `.__proto__` itself is null*. This explains why JavaScript is said to support *prototypal inheritance* out of the box. This is shown in the following example, which you can run in the chrome console or Node.js:
 
 ```ts
 var foo = {}

docs/classes-extensibility.md

@@ -118,7 +118,7 @@ As always these modifiers work for both member properties and member functions.
 ### Abstract
 `abstract` can be thought of as an access modifier. We present it separately because opposed to the previously mentioned modifiers it can be on a `class` as well as any member of the class. Having an `abstract` modifier primarily means that such functionality *cannot be directly invoked* and a child class must provide the functionality.
 
-* `abstract` **classes** cannot be directly instantiated. Instead the user must create some `class` that inherit from the `abstract class`.
+* `abstract` **classes** cannot be directly instantiated. Instead the user must create some `class` that inherits from the `abstract class`.
 * `abstract` **members** cannot be directly accessed and a child class must provide the functionality.
 
 ### Constructor is optional

docs/classes.md

@@ -12,8 +12,6 @@ For leading and ending comments in a file:
 * The first token in the source file gets all the initial trivia.
 * The last sequence of trivia in the file is tacked onto the end-of-file token, which otherwise has zero width.
 
-The first token in the source file gets all the initial trivia, and the last sequence of trivia in the file is tacked onto the end-of-file token, which otherwise has zero width.
-
 #### Trivia APIs
 For most basic uses, comments are the "interesting" trivia. The comments that belong to a Node can be fetched through the following functions:
 

docs/compiler/ast-trivia.md

@@ -8,7 +8,7 @@ Its interaction mechanism with the OE:
 
 `Program` *-uses->* `CompilerHost` *-uses->* `System`
 
-The reason for having a `CompilerHost` as a point of indirection is that it allows it's interface to be more finely tuned for `Program` needs and not bother with OE needs (e.g. the `Program` doesn't care about `fileExists` a function provided by `System`).
+The reason for having a `CompilerHost` as a point of indirection is that it allows its interface to be more finely tuned for `Program` needs and not bother with OE needs (e.g. the `Program` doesn't care about `fileExists` a function provided by `System`).
 
 There are other users of `System` as well (e.g. tests).
 

docs/compiler/program.md

@@ -62,4 +62,4 @@ foo.bar = 456; // Allowed!
 console.log(foo); // { bar: 456 }
 ```
 
-For this reason I recommend using `const` with literals or immutable data structures.
+For this reason I recommend using `const` with primitives or immutable data structures.

docs/const.md

@@ -19,6 +19,25 @@ Sample:
 
 Checkout the [section on modules][modules].
 
+## Catch clause variable cannot have a type annotation
+Sample: 
+```js
+try { something(); }
+catch (e: Error) { // Catch clause variable cannot have a type annotation
+}
+```
+TypeScript is protecting you from JavaScript code in the wild being wrong. Use a type guard instead: 
+```js
+try { something(); }
+catch (e) {
+  if (e instanceof Error){ 
+    // Here you go.
+  }
+}
+```
+
+
+
 ## For search indexing
 You can ignore reading this. This section is for search engine indexing.
 

docs/errors/main.md

@@ -1,4 +1,4 @@
 # Future JavaScript: Now
-One of the main selling points of TypeScript is that it allows you to use a bunch of features from ES6 and beyond in current (ES3 and 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.
+One of the main selling points of TypeScript is that it allows you to use a bunch of features from ES6 and beyond in current (ES3 and ES5 level) JavaScript engines (like current browsers and Node.js). Here we deep dive into why these features are useful followed by how these features are implemented in TypeScript.
 
 Note: Not all of these features are slated for immediate addition to JavaScript but provide great utility to your code organization and maintenance. Also note that you are free to ignore any of the constructs that don't make sense for your project, although you will end up using most of them eventually ;)

docs/future-javascript.md

@@ -2,7 +2,9 @@
 
 > NOTE: You cannot use generators in TypeScript in a meaningful way (the ES5 emitter is in progress). However that will change soon so we still have this chapter.
 
-`function *` is the syntax used to create a *generator function*. Calling a generator function returns a *generator object*. There are two key motivations behind generator functions. The generator object just follows the [iterator][iterator] interface (i.e. the `next`, `return` and `throw` functions).
+`function *` is the syntax used to create a *generator function*. Calling a generator function returns a *generator object*. The generator object just follows the [iterator][iterator] interface (i.e. the `next`, `return` and `throw` functions). 
+
+There are two key motivations behind generator functions: 
 
 ### Lazy Iterators