Merge pull request #2 from basarat/master

update from upstream

Author: spences10

.gitignore

@@ -1,6 +1,11 @@
-.alm
+# Mac 
 *.DS_Store
 
+# IDEs
+.alm
+.vscode
+
+
 # Node rules:
 ## Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
 .grunt

README.md

@@ -1,7 +1,7 @@
 TypeScript Deep Dive
 =======
 
-I've been looking at the issues that turn up commonly when people start using TypeScript. This is based on the lessons from [StackOverflow](http://stackoverflow.com/tags/typescript/topusers) / [DefinitelyTyped](https://github.com/DefinitelyTyped/) and general engagement with the [TypeScript community](https://github.com/TypeStrong/). You can [follow for updates](https://twitter.com/basarat) and [don't forget to ★ on Github](https://github.com/basarat/typescript-book) 🌹
+I've been looking at the issues that turn up commonly when people start using TypeScript. This is based on the lessons from [Stack Overflow](http://stackoverflow.com/tags/typescript/topusers) / [DefinitelyTyped](https://github.com/DefinitelyTyped/) and general engagement with the [TypeScript community](https://github.com/TypeStrong/). You can [follow for updates](https://twitter.com/basarat) and [don't forget to ★ on GitHub](https://github.com/basarat/typescript-book) 🌹
 
 ## Reviews
 
@@ -22,20 +22,27 @@ I've been looking at the issues that turn up commonly when people start using Ty
 * Guyz excellent book on Typescript(@typescriptlang) by @basarat ([link](https://twitter.com/deeinlove/status/813245965507260417))
 * Leaning on the legendary @basarat's "TypeScript Deep Dive" book heavily at the moment ([link](https://twitter.com/sitapati/status/814379404956532737))
 * numTimesPointedPeopleToBasaratsTypeScriptBook++; ([link](https://twitter.com/brocco/status/814227741696462848))
-* A book not only for typescript, a good one for deeper javascript knowledge as well. [link](https://www.gitbook.com/book/basarat/typescript/discussions/59)
+* A book not only for typescript, a good one for deeper JavaScript knowledge as well. [link](https://www.gitbook.com/book/basarat/typescript/discussions/59)
 * In my new job, we're using @typescriptlang, which I am new to. This is insanely helpful huge thanks, @basarat! [link](https://twitter.com/netchkin/status/855339390566096896)
 * 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)
+* @basarat's intro to @typescriptlang is still one of the best going (if not THE best) [link](https://twitter.com/stevealee/status/953953255968698368)
+* This is sweet! So many #typescript goodies! [link](https://twitter.com/pauliescanlon/status/989898852474998784)
 
 ## Get Started
 If you are here to read the book online [get started](http://basarat.gitbooks.io/typescript/content/docs/getting-started.html).
 
+## Translations 
+Book is completely free so you can copy paste whatever you want without requiring permission. If you have a translation you want me to link here. [Send a PR](https://github.com/basarat/typescript-book/edit/master/README.md).
+* [Filipino](https://github.com/themarshann/typescript-book-fil)
+* [Italian](https://github.com/TizioFittizio/typescript-book)
+
 ## Other Options
 You can also download one of the following:
-* [EPUB for iPad,iPhone,Mac](https://www.gitbook.com/download/epub/book/basarat/typescript)
+* [EPUB for iPad, iPhone, Mac](https://www.gitbook.com/download/epub/book/basarat/typescript)
 * [PDF for Windows and others](https://www.gitbook.com/download/pdf/book/basarat/typescript)
 * [MOBI for Kindle](https://www.gitbook.com/download/mobi/book/basarat/typescript)
 

SUMMARY.md

@@ -12,7 +12,6 @@
 * [Future JavaScript Now](docs/future-javascript.md)
   * [Classes](docs/classes.md)
     * [Classes Emit](docs/classes-emit.md)
-    * [Classes Super](docs/classes-super.md)
   * [Arrow Functions](docs/arrow-functions.md)
   * [Rest Parameters](docs/rest-parameters.md)
   * [let](docs/let.md)
@@ -61,12 +60,24 @@
   * [Index Signatures](docs/types/index-signatures.md)
   * [Moving Types](docs/types/moving-types.md)
   * [Exception Handling](docs/types/exceptions.md)
+  * [Mixins](docs/types/mixins.md)
 * [JSX](docs/jsx/tsx.md)
+  * [React](docs/jsx/react.md)
+  * [Non React JSX](docs/jsx/others.md)
 * [Options](docs/options/intro.md)
   * [noImplicitAny](docs/options/noImplicitAny.md)
   * [strictNullChecks](docs/options/strictNullChecks.md)
+* [Errors in TypeScript](docs/errors/main.md)
+  * [Interpreting Errors](docs/errors/interpreting-errors.md)
+  * [Common Errors](docs/errors/common-errors.md)
+* [Testing](docs/testing/intro.md)
+  * [Jest](docs/testing/jest.md)
+  * [Cypress](docs/testing/cypress.md)
+* [Tools](docs/tools/intro.md)
+  * [Prettier](docs/tools/prettier.md)
+  * [Husky](docs/tools/husky.md)
+  * [Changelog](docs/tools/changelog.md)
 * [TIPs](docs/tips/main.md)
-  * [Quick Object Return](docs/tips/quickObjectReturn.md)
   * [String Based Enums](docs/tips/stringEnums.md)
   * [Nominal Typing](docs/tips/nominalTyping.md)
   * [Stateful Functions](docs/tips/statefulFunctions.md)
@@ -77,7 +88,6 @@
   * [Classes are Useful](docs/tips/classesAreUseful.md)
   * [Avoid Export Default](docs/tips/defaultIsBad.md)
   * [Limit Property Setters](docs/tips/propertySetters.md)
-  * [`null` is bad](docs/tips/null.md)
   * [`outFile` caution](docs/tips/outFile.md)
   * [JQuery tips](docs/tips/jquery.md)
   * [static constructors](docs/tips/staticConstructor.md)
@@ -89,7 +99,6 @@
   * [Create Arrays](docs/tips/create-arrays.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)
   * [Program](docs/compiler/program.md)
   * [AST](docs/compiler/ast.md)

book.json

@@ -1,4 +1,7 @@
 {
+  "language": "en",
+  "author": "Basarat Ali Syed",
+  "title": "TypeScript Deep Dive",
   "plugins": ["edit-link", "github", "adsense","header"],
   "pluginsConfig": {
     "layout": {

code/errors/errors.ts renamed to code/errors/common-errors.ts

@@ -0,0 +1,21 @@
+export const module = 123;
+
+type SomethingComplex = {
+  foo: number,
+  bar: string
+}
+function takeSomethingComplex(arg: SomethingComplex) {
+}
+function getBar(): string {
+  return 'some bar';
+}
+
+//////////////////////////////////
+// Example error production
+//////////////////////////////////
+const fail = {
+  foo: 123,
+  bar: getBar
+};
+
+takeSomethingComplex(fail); // TS ERROR HAPPENS HERE 

code/errors/errors.js

@@ -1 +1,5 @@
-{}
+{
+  "compilerOptions": {
+    "noEmit": true
+  }
+}

code/errors/interpreting-errors.ts

@@ -7,7 +7,7 @@ module aaa {
 
   const queue = new Queue();
   queue.push(0);
-  queue.push("1"); // Ops a mistake
+  queue.push("1"); // Oops a mistake
 
   // a developer walks into a bar
   console.log(queue.pop().toPrecision(1));
@@ -68,4 +68,4 @@ namespace ddd {
   function loadUsers() {
     return getJSON<LoadUsersResponse>({ url: 'https://example.com/users' });
   }
-}
+}

code/errors/tsconfig.json

@@ -3,6 +3,7 @@
 * [Tip: Arrow Function Danger](#tip-arrow-function-danger)
 * [Tip: Libraries that use `this`](#tip-arrow-functions-with-libraries-that-use-this)
 * [Tip: Arrow Function inheritance](#tip-arrow-functions-and-inheritance)
+* [Tip: Quick object return](#tip-quick-object-return)
 
 ### Arrow Functions
 
@@ -90,7 +91,7 @@ then `this` is going to be the correct calling context (in this example `person`
 In fact if you want `this` *to be the calling context* you should *not use the arrow function*. This is the case with callbacks used by libraries like jquery, underscore, mocha and others. If the documentation mentions functions on `this` then you should probably just use a `function` instead of a fat arrow. Similarly if you plan to use `arguments` don't use an arrow function.
 
 #### Tip: Arrow functions with libraries that use `this`
-Many libraries do this e.g. `jQuery` iterables (one example http://api.jquery.com/jquery.each/) will use `this` to pass you the object that it is currently iterating over. In this case if you want to access the library passed `this` as well as the surrounding context just use a temp variable like `_self` like you would in the absence of arrow functions.
+Many libraries do this e.g. `jQuery` iterables (one example https://api.jquery.com/jquery.each/) will use `this` to pass you the object that it is currently iterating over. In this case if you want to access the library passed `this` as well as the surrounding context just use a temp variable like `_self` like you would in the absence of arrow functions.
 
 ```ts
 let _self = this;
@@ -101,8 +102,26 @@ something.each(function() {
 ```
 
 #### Tip: Arrow functions and inheritance
+Arrow functions as properties on classes work fine with inheritance: 
 
-If you have an instance method as an arrow function then it goes on `this`. Since there is only one `this` such functions cannot participate in a call to `super` (`super` only works on prototype members). You can easily get around it by creating a copy of the method before overriding it in the child.
+```ts
+class Adder {
+    constructor(public a: number) {}
+    add = (b: number): number => {
+        return this.a + b;
+    }
+}
+class Child extends Adder {
+    callAdd(b: number) {
+        return this.add(b);
+    }
+}
+// Demo to show it works
+const child = new Child(123);
+console.log(child.callAdd(123)); // 246
+```
+
+However, they do not work with the `super` keyword when you try to override the function in a child class. Properties go on `this`. Since there is only one `this` such functions cannot participate in a call to `super` (`super` only works on prototype members). You can easily get around it by creating a copy of the method before overriding it in the child.
 
 ```ts
 class Adder {
@@ -122,3 +141,26 @@ class ExtendedAdder extends Adder {
     }
 }
 ```
+
+### Tip: Quick object return
+
+Sometimes you need a function that just returns a simple object literal. However, something like
+
+```ts
+// WRONG WAY TO DO IT
+var foo = () => {
+    bar: 123
+};
+```
+is parsed as a *block* containing a *JavaScript Label* by JavaScript runtimes (cause of the JavaScript specification).
+
+>  If that doesn't make sense, don't worry, as you get a nice compiler error from TypeScript saying "unused label" anyways. Labels are an old (and mostly unused) JavaScript feature that you can ignore as a modern GOTO (considered bad by experienced developers 🌹)
+
+You can fix it by surrounding the object literal with `()`:
+
+```ts
+// Correct 🌹
+var foo = () => ({
+    bar: 123
+});
+```

code/types/generics.ts

@@ -1,5 +1,7 @@
 ## Async Await
 
+> [A PRO egghead video course that covers the same material](https://egghead.io/courses/async-await-using-typescript)
+
 As a thought experiment imagine the following: a way to tell the JavaScript runtime to pause the executing of code on the `await` keyword when used on a promise and resume *only* once (and if) the promise returned from the function is settled:
 
 ```ts
@@ -63,7 +65,7 @@ function delay(milliseconds: number, count: number): Promise<number> {
         });
 }
 
-// async function always return a Promise
+// async function always returns a Promise
 async function dramaticWelcome(): Promise<void> {
     console.log("Hello");
 
@@ -96,7 +98,7 @@ function delay(milliseconds, count) {
         }, milliseconds);
     });
 }
-// async function always return a Promise
+// async function always returns a Promise
 function dramaticWelcome() {
     return __awaiter(this, void 0, void 0, function* () {
         console.log("Hello");
@@ -157,7 +159,7 @@ function delay(milliseconds, count) {
         }, milliseconds);
     });
 }
-// async function always return a Promise
+// async function always returns a Promise
 function dramaticWelcome() {
     return __awaiter(this, void 0, void 0, function () {
         var i, count;
@@ -189,9 +191,9 @@ dramaticWelcome();
 You can see full example [here][asyncawaites5code].
 
 
-**Note**: for both target scenarios, we need to make sure our run-time has an ECMAScript-compliant Promise available globally. That might involve grabbing a polyfill for Promise. We also need to make sure that TypeScript knows Promise exists by setting your lib flag to something like "dom", "es2015" or "dom", "es2015.promise", "es5". 
+**Note**: for both target scenarios, we need to make sure our run-time has an ECMAScript-compliant Promise available globally. That might involve grabbing a polyfill for Promise. We also need to make sure that TypeScript knows Promise exists by setting our lib flag to something like "dom", "es2015" or "dom", "es2015.promise", "es5". 
 **We can see what browsers DO have Promise support (native and polyfilled) [here](https://kangax.github.io/compat-table/es6/#test-Promise).**
 
 [generators]:./generators.md
-[asyncawaites5code]:../code/async-await/es5/asyncAwaitES5.js
-[asyncawaites6code]:../code/async-await/es6/asyncAwaitES6.js
+[asyncawaites5code]:https://cdn.rawgit.com/basarat/typescript-book/705e4496/code/async-await/es5/asyncAwaitES5.js
+[asyncawaites6code]:https://cdn.rawgit.com/basarat/typescript-book/705e4496/code/async-await/es6/asyncAwaitES6.js

docs/arrow-functions.md

@@ -10,7 +10,7 @@ Point.prototype.add = function (point) {
 };
 ```
 
-The reason its wrapped in an Immediately-Invoked Function Expression (IIFE) i.e.
+The reason it's wrapped in an Immediately-Invoked Function Expression (IIFE) i.e.
 
 ```ts
 (function () {
@@ -81,7 +81,7 @@ delete foo.__proto__.bar; // remove from foo.__proto__
 console.log(foo.bar); // undefined
 ```
 
-Cool so you understand `__proto__`. Another useful information is that all `function`s in JavaScript have a property called `prototype` and that it has a member `constructor` pointing back to the function. This is shown below:
+Cool so you understand `__proto__`. Another useful fact is that all `function`s in JavaScript have a property called `prototype` and that it has a member `constructor` pointing back to the function. This is shown below:
 
 ```ts
 function Foo() { }
@@ -121,7 +121,7 @@ That's it. Now look at the following straight out of `__extends`. I've taken the
 
 Reading this function in reverse the `d.prototype = new __()` on line 3 effectively means `d.prototype = {__proto__ : __.prototype}` (because of the effect of `new` on `prototype` and `__proto__`), combining it with the previous line (i.e. line 2 `__.prototype = b.prototype;`) you get `d.prototype = {__proto__ : b.prototype}`.
 
-But wait, we wanted `d.prototype.__proto__` i.e. just the proto changed and maintain the old `d.prototype.constructor`. This is where the significance of the first line (i.e. `function __() { this.constructor = d; }`) comes in. Here we will effectively have `d.prototype = {__proto__ : __.prototype, d.constructor = d}` (because of the effect of `new` on `this` inside the called function). So, since we restore `d.prototype.constructor`, the only thing we have truly mutated is the `__proto__` hence `d.prototype.__proto__ = b.prototype`.
+But wait, we wanted `d.prototype.__proto__` i.e. just the proto changed and maintain the old `d.prototype.constructor`. This is where the significance of the first line (i.e. `function __() { this.constructor = d; }`) comes in. Here we will effectively have `d.prototype = {__proto__ : __.prototype, constructor : d}` (because of the effect of `new` on `this` inside the called function). So, since we restore `d.prototype.constructor`, the only thing we have truly mutated is the `__proto__` hence `d.prototype.__proto__ = b.prototype`.
 
 #### `d.prototype.__proto__ = b.prototype` significance
 

docs/async-await.md

@@ -23,7 +23,7 @@ export function forEachChild<T>(node: Node, cbNode: (node: Node) => T, cbNodeArr
             // .... lots more
 ```
 
-Basically it checks `node.kind` and based on that assumes an interface offered by the `node` and calls the `cbNode` on the children. Note, however that this function doesn't call `visitNode` for *all* children (e.g. SyntaxKind.SemicolonToken). If you want *all* the children of a node in the AST just call `.getChildren` member function of the `Node`.
+Basically, it checks `node.kind` and based on that assumes an interface offered by the `node` and calls the `cbNode` on the children. However, note that this function doesn't call `visitNode` for *all* children (e.g. SyntaxKind.SemicolonToken). If you want *all* the children of a node in the AST just call `.getChildren` member function of the `Node`.
 
 E.g. here is a function that prints the verbose `AST` of a node:
 

docs/classes-emit.md

@@ -10,7 +10,7 @@ export const enum SyntaxKind {
     // ... LOTS more
 ```
 
-It's a `const enum` (a concept [we covered previously](../enums.md)) so that it gets *inlined* (e.g. `ts.SyntaxKind.EndOfFileToken` becomes `1`) and we don't get a dereferencing cost when working with the AST. However the compiler is compiled with `--preserveConstEnums` compiler flag so that the enum *is still available at runtime*. So in JavaScript you can use `ts.SyntaxKind.EndOfFileToken` if you want. Additionally you can convert these enum members to display strings using the following function:
+It's a `const enum` (a concept [we covered previously](../enums.md)) so that it gets *inlined* (e.g. `ts.SyntaxKind.EndOfFileToken` becomes `1`) and we don't get a dereferencing cost when working with the AST. However, the compiler is compiled with `--preserveConstEnums` compiler flag so that the enum *is still available at runtime*. So in JavaScript you can use `ts.SyntaxKind.EndOfFileToken` if you want. Additionally you can convert these enum members to display strings using the following function:
 
 ```ts
 export function syntaxKindToName(kind: ts.SyntaxKind) {

docs/classes-super.md

@@ -1,5 +1,5 @@
 ### Trivia
-Trivia (called that because it's `trivial`) represent the parts of the source text that are largely insignificant for normal understanding of the code. For example; whitespace, comments, and even conflict markers. Trivia is *not stored* in the AST (to keep it lightweight). However it can be fetched *on demand* using a few `ts.*` APIs. 
+Trivia (called that because it's `trivial`) represent the parts of the source text that are largely insignificant for normal understanding of the code. For example; whitespace, comments, and even conflict markers. Trivia is *not stored* in the AST (to keep it lightweight). However, it can be fetched *on demand* using a few `ts.*` APIs. 
 
 Before we show them you need to understand the following: