Add TypeScript 2.1 release notes #440

mhegazy · 2016-11-24T01:35:47Z

Some parts copied verbatim from @DanielRosenwasser's blog.

This includes the content already in https://github.com/Microsoft/TypeScript/wiki/What%27s-new-in-TypeScript.

DanielRosenwasser · 2016-11-30T01:41:11Z

pages/release notes/TypeScript 2.1.md

+
+```ts
+// From T pick a set of properties K
+function pick<T, K extends keyof T>(obj: T, ...keys: K[]): Pick<T, K>;


declare function

DanielRosenwasser · 2016-11-30T01:42:06Z

pages/release notes/TypeScript 2.1.md

+# Support for external helpers library (`tslib`)
+
+TypeScript injects a handful of helper functions such as `__extends` for inheritance, `__assign` for spread operator in JSX, and `__awaiter` for async functions.
+Previously there were two options either 1. inject helpers in *every* file that needs them or 2. no helpers at all with `--noEmitHelpers`.


Turn these into an ordered list

Mention that this was a painpoint if users wanted to keep their bundle size low.

done and done.

DanielRosenwasser · 2016-11-30T01:42:21Z

pages/release notes/TypeScript 2.1.md

+
+# Support for external helpers library (`tslib`)
+
+TypeScript injects a handful of helper functions such as `__extends` for inheritance, `__assign` for spread operator in JSX, and `__awaiter` for async functions.


Assign is also used beyond JSX

DanielRosenwasser · 2016-11-30T01:43:07Z

pages/release notes/TypeScript 2.1.md

+
+TypeScript 2.1 allows for including these files in your project once in a separate module, and the compiler will emit imports to them as needed.
+
+First, install the [`tslib`](https://github.com/Microsoft/tslib):


the tslib utility library

DanielRosenwasser · 2016-11-30T01:43:44Z

pages/release notes/TypeScript 2.1.md

+tsc --module commonjs --importHelpers a.ts
+```
+
+##### Example


You don't need this heading.

DanielRosenwasser · 2016-11-30T01:48:02Z

pages/release notes/TypeScript 2.1.md

+
+```ts
+
+const c1 = 1;  // Type 1


Surround each type with a single quote

that is confusing.. it is not type '1' it is type 1

DanielRosenwasser · 2016-11-30T01:49:00Z

pages/release notes/TypeScript 2.1.md

+
+# Use returned values from super calls as 'this'
+
+In ES2015, constructors which return a value (which is an object) implicitly substitute the value of `this` for any callers of `super()`.


"constructors which return an object" might be shorter

DanielRosenwasser · 2016-11-30T01:49:57Z

pages/release notes/TypeScript 2.1.md

+TypeScript 2.1 supports inheriting configuration using `extends`, where:
+
+* `extends` is a new top-level property in `tsconfig.json` (alongside `compilerOptions`, `files`, `include`, and `exclude`).
+* `extends`' value is a string containing a path to another configuration file to inherit from.


The value of extends must be a string...

DanielRosenwasser · 2016-11-30T01:50:22Z

pages/release notes/TypeScript 2.1.md

+* `extends` is a new top-level property in `tsconfig.json` (alongside `compilerOptions`, `files`, `include`, and `exclude`).
+* `extends`' value is a string containing a path to another configuration file to inherit from.
+* The configuration from the base file are loaded first, then overridden by those in the inheriting config file.
+* If a circularity is encountered, we report an error.


circularity between configuration files is encountered

changed to Circularity between configuration files is not allowed.

DanielRosenwasser · 2016-11-30T01:51:42Z

pages/release notes/TypeScript 2.1.md

+Modules are parsed automatically in strict mode.
+The new flag is recommended for non-module code.
+
+# Support for `--target ES2016`, `--target ES2017` and `--target ESNext`


Move this higher up - probably before implicit any inference.

sandersn

Here are my comments for now. I need to compare the presentation of mapped types with the one in the Handbook PR I made. I'll comment more at that time.

sandersn · 2016-11-30T17:28:54Z

pages/release notes/TypeScript 2.1.md

+let propName: keyof Person;
+```
+
+The above is equivalent to having written out


keyof Person is equivalent to ...

sandersn · 2016-11-30T17:29:41Z

pages/release notes/TypeScript 2.1.md

+let propName: "name" | "age" | "location";
+```
+
+This `keyof` operator is actually called an *index type query*.


delete 'actually'

sandersn · 2016-11-30T17:35:52Z

pages/release notes/TypeScript 2.1.md

+let nameOrAge: Person["name" | "age"];
+```
+
+This pattern can be used with other parts of the type system to get type-safe lookups, serving users of libraries like Ember.


The last part is pretty formal. I'd rewrite to: ", which is great if you use Ember or something like it."

Actually, might as well reword the beginning too: "You can use this pattern with ..."

sandersn · 2016-11-30T17:37:15Z

pages/release notes/TypeScript 2.1.md

+}
+```
+
+Or we might want to create a related type where all the properties are `Promise`s.


The example is wrong. It should be Promise, or else the sentence should talk about booleans.

Probably the sentence should talk about booleans, given the extended example below.

sandersn · 2016-11-30T17:53:57Z

pages/release notes/TypeScript 2.1.md

+};
+```
+
+Mapped types are produced by taking a union of literal types, and compute a set of properties for a new object type.


sandersn · 2016-11-30T17:57:58Z

pages/release notes/TypeScript 2.1.md

+## Implicit any errors
+
+One great benefit of this is that you'll see *way fewer* implicit `any` errors when running with `--noImplicitAny`.
+Implicit `any` errors are only reported when the compiler is unable to know the type of a available without a type annotation.


typo: available → variable

sandersn

Some more comments, on mapped types mostly.

sandersn · 2016-11-30T18:41:25Z

pages/release notes/TypeScript 2.1.md

+}
+```
+
+Much of the time, we want to take an existing type and make each of its properties entirely optional.


I would rewrite as "One common task is to take an existing type ..."

sandersn · 2016-11-30T18:42:35Z

pages/release notes/TypeScript 2.1.md

+}
+```
+
+Or we might want to create a related type where all the properties are `Promise`s.


Probably the sentence should talk about booleans, given the extended example below.

sandersn · 2016-11-30T21:46:52Z

pages/release notes/TypeScript 2.1.md

+# `keyof` and Lookup Types
+
+Many libraries take advantage of the fact that objects are (for the most part) just a map of strings to values.
+Given what TypeScript knows about each value's properties, there's a set of known strings (or keys) that you can use for lookups.


This is feature-oriented, which is fine for a release notes format. In the handbook, I put a cool example of usage up front and afterward explain how it works. I think that's better for blog and instructional formats.

sandersn · 2016-11-30T21:48:10Z

pages/release notes/TypeScript 2.1.md

+let a: Person["age"];
+```
+
+This is the same as saying that `n` gets the type of the `name` property in `Person`.


a not n

sandersn · 2016-11-30T21:48:48Z

pages/release notes/TypeScript 2.1.md

+let nameOrAge: Person["name" | "age"];
+```
+
+This pattern can be used with other parts of the type system to get type-safe lookups, serving users of libraries like Ember.


Actually, might as well reword the beginning too: "You can use this pattern with ..."

sandersn · 2016-11-30T23:46:11Z

pages/release notes/TypeScript 2.1.md

+function freeze<T>(obj: T): Readonly<T>;
+```
+
+For that, they are now included by default in the standard library.


For → because of

sandersn · 2016-11-30T23:46:46Z

pages/release notes/TypeScript 2.1.md

+};
+
+// Same property names, but make the value a promise instead of a concreate one
+type Defered<T> = {


isn't Deferred the correct spelling? I'm not sure anymore

sandersn · 2016-11-30T23:46:54Z

pages/release notes/TypeScript 2.1.md

+    readonly [P in keyof T]: T[P];
+};
+
+// Same property names, but make the value a promise instead of a concreate one


typo:concrete

sandersn · 2016-11-30T23:47:33Z

pages/release notes/TypeScript 2.1.md

+let copy = { ...original };
+```
+
+Similarly, you can merge several different objects so that in the following example, `merged` will have properties from `foo`, `bar`, and `baz`.


I would break this into two sentences: "Similarly, you can merge several different objects. In the following example, ..."

sandersn · 2016-11-30T23:47:58Z

pages/release notes/TypeScript 2.1.md

+var newObj = {...obj, z: 3, y: 4}; // { x: number, y:number, x: number }
+```
+
+The order of specifying spread operations decides what properties end up in the resulting object;


decides → determines

mhegazy · 2016-12-01T21:56:17Z

@DanielRosenwasser and @sandersn, I have simplified the notes for keyof and mapped type, less chatty now.

sandersn

Few small typos left to fix, otherwise looks good.

sandersn · 2016-12-05T18:44:37Z

pages/release notes/TypeScript 2.1.md

+In JavaScript it is fairly common to have APIs that expect property names as parameters, but so far it hasn't been possible to express the type relationships that occur in those APIs.

-That's where the `keyof` operator comes in.
+Enter Index Type Query or `keysof`;


typo: keyof

sandersn · 2016-12-05T18:49:56Z

pages/release notes/TypeScript 2.1.md


-Much of the time, we want to take an existing type and make each of its properties entirely optional.
-With `Person`, we might write the following:
+A partial verion of it can would be:


delete 'can'

sandersn · 2016-12-05T18:51:49Z

pages/release notes/TypeScript 2.1.md

+They're like [list comprehensions in Python](https://docs.python.org/2/tutorial/datastructures.html#nested-list-comprehensions), but instead of producing new elements in a list, they produce new properties in a type.

-With mapped types, we no longer have to create new partial or readonly variants of existing types either.
+In addition to `Partial`, Mapped Types can enable expressing many usueful transfomrations on types:


"enable expressing" → express

typo: useful

typo: transformations

sandersn · 2016-12-05T18:53:12Z

pages/release notes/TypeScript 2.1.md

-Previously there were two options either 1. inject helpers in *every* file that needs them or 2. no helpers at all with `--noEmitHelpers`.
+TypeScript injects a handful of helper functions such as `__extends` for inheritance, `__assign` for spread operator in object literals and JSX elements, and `__awaiter` for async functions.
+
+Previously there were two options either:


I would just delete 'either'. Or say "Previously there were two options; either:"

sandersn · 2016-12-05T19:00:20Z

pages/release notes/TypeScript 2.1.md

+}
+```
+
+A partial verion of it can would be:


mhegazy · 2016-12-05T21:37:53Z

@DanielRosenwasser let me know if you have more comments and i will get them done in a separate PR.

mhegazy and others added 4 commits November 23, 2016 17:33

Add TypeScript 2.1 release notes

5a52756

Reorder

b91dd42

Merge branch 'master' into 2.1ReleaseNotes

03182cd

Merge branch 'master' into 2.1ReleaseNotes

ee8de09

DanielRosenwasser suggested changes Nov 30, 2016

View reviewed changes

sandersn reviewed Nov 30, 2016

View reviewed changes

sandersn suggested changes Nov 30, 2016

View reviewed changes

mhegazy added 3 commits December 1, 2016 13:06

Merge branch 'master' into 2.1ReleaseNotes

06ed494

Review comments

9f11f3f

Simplify keyof

7a619a3

sandersn approved these changes Dec 5, 2016

View reviewed changes

sandersn reviewed Dec 5, 2016

View reviewed changes

pages/release notes/TypeScript 2.1.md Outdated

}

```

A partial verion of it can would be:

Copy link

Member

sandersn Dec 5, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

version

Fix typos

fb781a9

mhegazy merged commit 3b7f2f9 into master Dec 5, 2016

mhegazy deleted the 2.1ReleaseNotes branch December 5, 2016 21:37


		# Support for external helpers library (`tslib`)

		TypeScript injects a handful of helper functions such as `__extends` for inheritance, `__assign` for spread operator in JSX, and `__awaiter` for async functions.


		TypeScript 2.1 allows for including these files in your project once in a separate module, and the compiler will emit imports to them as needed.

		First, install the [`tslib`](https://github.com/Microsoft/tslib):


		# Use returned values from super calls as 'this'

		In ES2015, constructors which return a value (which is an object) implicitly substitute the value of `this` for any callers of `super()`.


		```ts

		const c1 = 1; // Type 1

Add TypeScript 2.1 release notes #440

Add TypeScript 2.1 release notes #440

Uh oh!

Conversation

mhegazy commented Nov 24, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sandersn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sandersn left a comment