Merge branch 'prescriptive-react' of https://github.com/Microsoft/TypeScript-Handbook into prescriptive-react

DanielRosenwasser · DanielRosenwasser · commit 05b63d779188 · 2017-03-27T14:48:33.000-07:00
diff --git a/pages/Advanced Types.md b/pages/Advanced Types.md
@@ -857,7 +857,7 @@ function proxify<T>(o: T): Proxify<T> {
 let proxyProps = proxify(props);
 ```
 
-Note that `Readonly<T>` and `Partial<T>` are so useful, they are included in TypeScript's standard libarary along with `Pick` and `Record`:
+Note that `Readonly<T>` and `Partial<T>` are so useful, they are included in TypeScript's standard library along with `Pick` and `Record`:
 
 ```ts
 type Pick<T, K extends keyof T> = {
diff --git a/pages/Compiler Options.md b/pages/Compiler Options.md
@@ -22,7 +22,7 @@ Option                                         | Type      | Default
 `--inlineSourceMap`                            | `boolean` | `false`                        | Emit a single file with source maps instead of having a separate file.
 `--inlineSources`                              | `boolean` | `false`                        | Emit the source alongside the sourcemaps within a single file; requires `--inlineSourceMap` or `--sourceMap` to be set.
 `--init`                                       |           |                                | Initializes a TypeScript project and creates a `tsconfig.json` file.
-`--isolatedModules`                            | `boolean` | `false`                        | Unconditionally emit imports for unresolved files.
+`--isolatedModules`                            | `boolean` | `false`                        | Transpile each file as a separate module (similar to "ts.transpileModule").
 `--jsx`                                        | `string`  | `"Preserve"`                   | Support JSX in `.tsx` files: `"React"` or `"Preserve"`. See [JSX](./JSX.md).
 `--jsxFactory`                                 | `string`  | `"React.createElement"`        | Specify the JSX factory function to use when targeting react JSX emit, e.g. `React.createElement` or `h`.
 `--lib`                                        | `string[]`|                                | List of library files to be included in the compilation.<br/>Possible values are:  <br/>► `ES5` <br/>► `ES6` <br/>► `ES2015` <br/>► `ES7` <br/>► `ES2016` <br/>► `ES2017` <br/>► `DOM` <br/>► `DOM.Iterable` <br/>► `WebWorker` <br/>► `ScriptHost` <br/>► `ES2015.Core` <br/>► `ES2015.Collection` <br/>► `ES2015.Generator` <br/>► `ES2015.Iterable` <br/>► `ES2015.Promise` <br/>► `ES2015.Proxy` <br/>► `ES2015.Reflect` <br/>► `ES2015.Symbol` <br/>► `ES2015.Symbol.WellKnown` <br/>► `ES2016.Array.Include` <br/>► `ES2017.object` <br/>► `ES2017.SharedMemory` <br/><br/> Note: If `--lib` is not specified a default library is injected. The default library injected is:  <br/> ► For `--target ES5`: `DOM,ES5,ScriptHost`<br/>  ► For `--target ES6`: `DOM,ES6,DOM.Iterable,ScriptHost`
@@ -31,7 +31,7 @@ Option                                         | Type      | Default
 `--locale`                                     | `string`  | *(platform specific)*          | The locale to use to show error messages, e.g. en-us.
 `--mapRoot`                                    | `string`  |                                | Specifies the location where debugger should locate map files instead of generated locations. Use this flag if the .map files will be located at run-time in a different location than the .js files. The location specified will be embedded in the sourceMap to direct the debugger where the map files will be located.
 `--maxNodeModuleJsDepth`                       | `number`  | `0`                            | The maximum dependency depth to search under node_modules and load JavaScript files. Only applicable with `--allowJs`.
-`--module`<br/>`-m`                            | `string`  | `target === "ES6" ? "ES6" : "CommonJS"`   | Specify module code generation: `"None"`, `"CommonJS"`, `"AMD"`, `"System"`, `"UMD"`, `"ES6"`, or `"ES2015"`.<br/>► Only `"AMD"` and `"System"` can be used in conjunction with `--outFile`.<br/>► `"ES6"` and `"ES2015"` values may not be used when targeting `"ES5"` or lower.
+`--module`<br/>`-m`                            | `string`  | `target === "ES6" ? "ES6" : "CommonJS"`   | Specify module code generation: `"None"`, `"CommonJS"`, `"AMD"`, `"System"`, `"UMD"`, `"ES6"`, or `"ES2015"`.<br/>► Only `"AMD"` and `"System"` can be used in conjunction with `--outFile`.<br/>► `"ES6"` and `"ES2015"` values may be used when targeting `"ES5"` or lower.
 `--moduleResolution`                           | `string`  | `module === "AMD" | "System" | "ES6" ?  "Classic" : "Node"`                    | Determine how modules get resolved. Either `"Node"` for Node.js/io.js style resolution, or `"Classic"`. See [Module Resolution documentation](./Module Resolution.md) for more details.
 `--newLine`                                    | `string`  | *(platform specific)*          | Use the specified end of line sequence to be used when emitting files: `"crlf"` (windows) or `"lf"` (unix)."
 `--noEmit`                                     | `boolean` | `false`                        | Do not emit outputs.
diff --git a/pages/Decorators.md b/pages/Decorators.md
@@ -2,7 +2,7 @@
 
 With the introduction of Classes in TypeScript and ES6, there now exist certain scenarios that require additional features to support annotating or modifying classes and class members.
 Decorators provide a way to add both annotations and a meta-programming syntax for class declarations and members.
-Decorators are a [stage 1 proposal](https://github.com/wycats/javascript-decorators/blob/master/README.md) for JavaScript and are available as an experimental feature of TypeScript.
+Decorators are a [stage 2 proposal](https://github.com/tc39/proposal-decorators) for JavaScript and are available as an experimental feature of TypeScript.
 
 > NOTE&emsp; Decorators are an experimental feature that may change in future releases.
 
@@ -163,6 +163,28 @@ function sealed(constructor: Function) {
 
 When `@sealed` is executed, it will seal both the constructor and its prototype.
 
+Next we have a example how to override the constructor.
+
+```ts
+function classDecorator<T extends {new(...args:any[]):{}}>(constructor:T) {
+    return class extends constructor {
+        newProperty = "new property";
+        hello = "override";
+    }
+}
+
+@classDecorator
+class Greeter {
+    property = "property";
+    hello: string;
+    constructor(m: string) {
+        this.hello = m;
+    }
+}
+
+console.log(new Greeter("world"));
+```
+
 ## Method Decorators
 
 A *Method Decorator* is declared just before a method declaration.
diff --git a/pages/Interfaces.md b/pages/Interfaces.md
@@ -143,7 +143,7 @@ Variables use `const` whereas properties use `readonly`.
 
 # Excess Property Checks
 
-In our first example using interfaces, TypeScript let us pass `{ size: number; label: string; }` to something that only expected a `{ label: string; }`.
+In our first example using interfaces, TypeScript lets us pass `{ size: number; label: string; }` to something that only expected a `{ label: string; }`.
 We also just learned about optional properties, and how they're useful when describing so-called "option bags".
 
 However, combining the two naively would let you to shoot yourself in the foot the same way you might in JavaScript.
diff --git a/pages/JSX.md b/pages/JSX.md
@@ -12,16 +12,18 @@ In order to use JSX you must do two things.
 1. Name your files with a `.tsx` extension
 2. Enable the `jsx` option
 
-TypeScript ships with two JSX modes: `preserve` and `react`.
+TypeScript ships with three JSX modes: `preserve`, `react`, and `react-native`.
 These modes only affect the emit stage - type checking is unaffected.
 The `preserve` mode will keep the JSX as part of the output to be further consumed by another transform step (e.g. [Babel](https://babeljs.io/)).
 Additionally the output will have a `.jsx` file extension.
 The `react` mode will emit `React.createElement`, does not need to go through a JSX transformation before use, and the output will have a `.js` file extension.
+The `react-native` mode is the equivalent of `preserve` in that it keeps all JSX, but the output will instead have a `.js` file extension.
 
-Mode       | Input     | Output                       | Output File Extension
------------|-----------|------------------------------|----------------------
-`preserve` | `<div />` | `<div />`                    | `.jsx`
-`react`    | `<div />` | `React.createElement("div")` | `.js`
+Mode           | Input     | Output                       | Output File Extension
+---------------|-----------|------------------------------|----------------------
+`preserve`     | `<div />` | `<div />`                    | `.jsx`
+`react`        | `<div />` | `React.createElement("div")` | `.js`
+`react-native` | `<div />` | `<div />`                    | `.js`
 
 You can specify this mode using either the `--jsx` command line flag or the corresponding option in your [tsconfig.json](./tsconfig.json.md) file.
 
diff --git a/pages/Module Resolution.md b/pages/Module Resolution.md
@@ -33,7 +33,7 @@ Any other import is considered **non-relative**.
 Some examples include:
 
 * `import * as $ from "jquery";`
-* `import { Component } from "angular2/core";`
+* `import { Component } from "@angular/core";`
 
 A relative import is resolved relative to the importing file and *cannot* resolve to an ambient module declaration.
 You should use relative imports for your own modules that are guaranteed to maintain their relative location at runtime.
@@ -199,13 +199,13 @@ Value of *baseUrl* is determined as either:
 
 Note that relative module imports are not impacted by setting the baseUrl, as they are always resolved relative to their importing files.
 
-You can find more documentation on baseUrl in [RequireJS](http://requirejs.org/docs/api.html#config-baseUrl) and [SystemJS](https://github.com/systemjs/systemjs/blob/master/docs/overview.md#baseurl) documentation.
+You can find more documentation on baseUrl in [RequireJS](http://requirejs.org/docs/api.html#config-baseUrl) and [SystemJS](https://github.com/systemjs/systemjs/blob/master/docs/config-api.md#baseurl) documentation.
 
 ### Path mapping
 
 Sometimes modules are not directly located under *baseUrl*.
 For instance, an import to a module `"jquery"` would be translated at runtime to `"node_modules\jquery\dist\jquery.slim.min.js"`.
-Loaders use a mapping configuration to map module names to files at run-time, see [RequireJs documentation](http://requirejs.org/docs/api.html#config-paths) and [SystemJS documentation](https://github.com/systemjs/systemjs/blob/master/docs/overview.md#map-config).
+Loaders use a mapping configuration to map module names to files at run-time, see [RequireJs documentation](http://requirejs.org/docs/api.html#config-paths) and [SystemJS documentation](https://github.com/systemjs/systemjs/blob/master/docs/config-api.md#paths).
 
 The TypeScript compiler supports the declaration of such mappings using `"paths"` property in `tsconfig.json` files.
 Here is an example for how to specify the `"paths"` property for `jquery`.
diff --git a/pages/Modules.md b/pages/Modules.md
@@ -628,7 +628,7 @@ export class SomeType { /* ... */ }
 export function someFunc() { /* ... */ }
 ```
 
-Conversly when importing:
+Conversely when importing:
 
 ### Explicitly list imported names
 
diff --git a/pages/Variable Declarations.md b/pages/Variable Declarations.md
@@ -472,7 +472,7 @@ function f([first, second]: [number, number]) {
     console.log(first);
     console.log(second);
 }
-f(input);
+f([1, 2]);
 ```
 
 You can create a variable for the remaining items in a list using the syntax `...`:
diff --git a/pages/declaration files/Do's and Don'ts.md b/pages/declaration files/Do's and Don'ts.md
@@ -17,9 +17,7 @@ function reverse(s: String): String;
 function reverse(s: string): string;
 ```
 
-If you're tempted to use the type `Object`, consider using `any` instead.
-There is currently no way in TypeScript to specify an object that is "not a primitive".
-<!--(Revisit if/when #1809 is implemented)-->
+Instead of `Object`, use the non-primitive `object` type ([added in TypeScript 2.2](../release notes/TypeScript 2.2.md#object-type)).
 
 ## Generics
 
diff --git a/pages/release notes/TypeScript 2.1.md b/pages/release notes/TypeScript 2.1.md
@@ -452,7 +452,7 @@ var Derived = (function (_super) {
 }(Base));
 ```
 
-> This change entails a break in the behavior of extending built-in classes like `Error`, `Array`, `Map`, etc.. Please see the [extending built-ins breaking change documnetation](https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work) for more details.
+> This change entails a break in the behavior of extending built-in classes like `Error`, `Array`, `Map`, etc.. Please see the [extending built-ins breaking change documentation](https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work) for more details.
 
 # Configuration inheritance
 
diff --git a/pages/release notes/TypeScript 2.2.md b/pages/release notes/TypeScript 2.2.md
@@ -0,0 +1,202 @@
+# Support for Mix-in classes
+
+TypeScript 2.2 adds support for the ECMAScript 2015 mixin class pattern (see [MDN Mixin description](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#Mix-ins) and ["Real" Mixins with JavaScript Classes](http://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/) for more details) as well as rules for combining mixin construct signatures with regular construct signatures in intersection types.
+
+##### First some terminology
+
+A **mixin constructor type** refers to a type that has a single construct signature with a single rest argument of type `any[]` and an object-like return type. For example, given an object-like type `X`, `new (...args: any[]) => X` is a mixin constructor type with an instance type `X`.
+
+A **mixin class** is a class declaration or expression that `extends` an expression of a type parameter type. The following rules apply to mixin class declarations:
+
+* The type parameter type of the `extends` expression must be constrained to a mixin constructor type.
+* The constructor of a mixin class (if any) must have a single rest parameter of type `any[]` and must use the spread operator to pass those parameters as arguments in a `super(...args)` call.
+
+Given an expression `Base` of a parametric type `T` with a constraint `X`, a mixin class `class C extends Base {...}` is processed as if `Base` had type `X` and the resulting type is the intersection `typeof C & T`.
+In other words, a mixin class is represented as an intersection between the mixin class constructor type and the parametric base class constructor type.
+
+When obtaining the construct signatures of an intersection type that contains mixin constructor types, the mixin construct signatures are discarded and their instance types are mixed into the return types of the other construct signatures in the intersection type.
+For example, the intersection type `{ new(...args: any[]) => A } & { new(s: string) => B }` has a single construct signature `new(s: string) => A & B`.
+
+##### Putting all of the above rules together in an example
+
+```ts
+class Point {
+    constructor(public x: number, public y: number) {}
+}
+
+class Person {
+    constructor(public name: string) {}
+}
+
+type Constructor<T> = new(...args: any[]) => T;
+
+function Tagged<T extends Constructor<{}>>(Base: T) {
+    return class extends Base {
+        _tag: string;
+        constructor(...args: any[]) {
+            super(...args);
+            this._tag = "";
+        }
+    }
+}
+
+const TaggedPoint = Tagged(Point);
+
+let point = new TaggedPoint(10, 20);
+point._tag = "hello";
+
+class Customer extends Tagged(Person) {
+    accountBalance: number;
+}
+
+let customer = new Customer("Joe");
+customer._tag = "test";
+customer.accountBalance = 0;
+```
+
+Mixin classes can constrain the types of classes they can mix into by specifying a construct signature return type in the constraint for the type parameter.
+For example, the following `WithLocation` function implements a subclass factory that adds a `getLocation` method to any class that satisfies the `Point` interface (i.e. that has `x` and `y` properties of type `number`).
+
+```ts
+interface Point {
+    x: number;
+    y: number;
+}
+
+const WithLocation = <T extends Constructor<Point>>(Base: T) =>
+    class extends Base {
+        getLocation(): [number, number] {
+            return [this.x, this.y];
+        }
+    }
+```
+
+# `object` type
+
+TypeScript did not have a type that represents the non-primitive type, i.e. any thing that is not `number`, `string`, `boolean`, `symbol`, `null`, or `undefined`. Enter the new `object` type.
+
+With `object` type, APIs like `Object.create` can be better represented. For example:
+
+```ts
+declare function create(o: object | null): void;
+
+create({ prop: 0 }); // OK
+create(null); // OK
+
+create(42); // Error
+create("string"); // Error
+create(false); // Error
+create(undefined); // Error
+```
+
+# Support for `new.target`
+
+The `new.target` meta-property is new syntax introduced in ES2015.
+When an instance of a constructor is created via `new`, the value of `new.target` is set to be a reference to the constructor function initially used to allocate the instance.
+If a function is called rather than constructed via `new`, `new.target` is set to `undefined`.
+
+`new.target` comes in handy when `Object.setPrototypeOf` or `__proto__` needs to be set in a class constructor. One such use case is inheriting from `Error` in NodeJS v4 and higher.
+
+##### Example
+
+```ts
+class CustomError extends Error {
+    constructor(message?: string) {
+        super(message); // 'Error' breaks prototype chain here
+        Object.setPrototypeOf(this, new.target.prototype); // restore prototype chain
+    }
+}
+```
+
+This results in the generated JS
+
+```js
+var CustomError = (function (_super) {
+  __extends(CustomError, _super);
+  function CustomError() {
+    var _newTarget = this.constructor;
+    var _this = _super.apply(this, arguments);  // 'Error' breaks prototype chain here
+    _this.__proto__ = _newTarget.prototype; // restore prototype chain
+    return _this;
+  }
+  return CustomError;
+})(Error);
+```
+
+`new.target` also comes in handy for writing constructable functions, for example:
+
+```ts
+function f() {
+  if (new.target) { /* called via 'new' */ }
+}
+```
+
+Which translates to:
+
+```js
+function f() {
+  var _newTarget = this && this instanceof f ? this.constructor : void 0;
+  if (_newTarget) { /* called via 'new' */ }
+}
+```
+
+# Better checking for `null`/`undefined` in operands of expressions
+
+TypeScript 2.2 improves checking of nullable operands in expressions. Specifically, these are now flagged as errors:
+
+* If either operand of a `+` operator is nullable, and neither operand is of type `any` or `string`.
+* If either operand of a `-`, `*`, `**`, `/`, `%`, `<<`, `>>`, `>>>`, `&`, `|`, or `^` operator is nullable.
+* If either operand of a `<`, `>`, `<=`, `>=`, or `in` operator is nullable.
+* If the right operand of an `instanceof` operator is nullable.
+* If the operand of a `+`, `-`, `~`, `++`, or `--` unary operator is nullable.
+
+An operand is considered nullable if the type of the operand is `null` or `undefined` or a union type that includes `null` or `undefined`.
+Note that the union type case only only occurs in `--strictNullChecks` mode because `null` and `undefined` disappear from unions in classic type checking mode.
+
+# Dotted property for types with string index signatures
+
+Types with a string index signature can be indexed using the `[]` notation, but were not allowed to use the `.`.
+Starting with TypeScript 2.2 using either should be allowed.
+
+```ts
+interface StringMap<T> {
+    [x: string]: T;
+}
+
+const map: StringMap<number>;
+
+map["prop1"] = 1;
+map.prop2 = 2;
+
+```
+
+This only apply to types with an *explicit* string index signature.
+It is still an error to access unknown properties on a type using `.` notation.
+
+# Support for spread operator on JSX element children
+
+TypeScript 2.2 adds support for using spread on a JSX element children.
+Please see [facebook/jsx#57](https://github.com/facebook/jsx/issues/57) for more details.
+
+##### Example
+
+```ts
+function Todo(prop: { key: number, todo: string }) {
+    return <div>{prop.key.toString() + prop.todo}</div>;
+}
+
+function TodoList({ todos }: TodoListProps) {
+    return <div>
+        {...todos.map(todo => <Todo key={todo.id} todo={todo.todo} />)}
+    </div>;
+}
+
+let x: TodoListProps;
+
+<TodoList {...x} />
+```
+
+# New `jsx: react-native`
+
+React-native build pipeline expects all files to have a `.js` extensions even if the file contains JSX syntax.
+The new `--jsx` value `react-native` will persevere the JSX syntax in the output file, but give it a `.js` extension.
diff --git a/pages/tutorials/React & Webpack.md b/pages/tutorials/React & Webpack.md

Original file line number	Diff line number	Diff line change
`@@ -472,7 +472,7 @@ function f([first, second]: [number, number]) {`
`472`	`472`	`console.log(first);`
`473`	`473`	`console.log(second);`
`474`	`474`	`}`
`475`		`-f(input);`
	`475`	`+f([1, 2]);`
`476`	`476`	```
`477`	`477`
`478`	`478`	You can create a variable for the remaining items in a list using the syntax `...`: