Merge pull request #4 from microsoft/v2

Pull across forks

Author: 0length

packages/documentation/copy/en/handbook-v2/Basics.md

@@ -69,7 +69,7 @@ The alternative is to use a _static_ type system to make predictions about what
 
 ## Static type-checking
 
-Think back to that `TypeError` we got earlier from calling a `string`.
+Think back to that `TypeError` we got earlier from trying to call a `string` as a function.
 _Most people_ don't like to get any sorts of errors when running their code - those are considered bugs!
 And when we write new code, we try our best to avoid introducing new bugs.
 
@@ -163,8 +163,6 @@ if (value !== "a") {
 
 ## Types for Tooling
 
-<!-- TODO: this section's title sucks -->
-
 TypeScript can catch bugs when we make mistakes in our code.
 That's great, but TypeScript can _also_ prevent us from making those mistakes in the first place.
 
@@ -174,14 +172,25 @@ Once it has that information, it can also start _suggesting_ which properties yo
 That means TypeScript can be leveraged for editing code too, and the core type-checker can provide error messages and code completion as you type in the editor.
 That's part of what people often refer to when they talk about tooling in TypeScript.
 
-<!-- TODO: insert GIF of completions here -->
+<!-- prettier-ignore -->
+```ts twoslash
+// @noErrors
+// @esModuleInterop
+import express from "express";
+const app = express();
+
+app.get("/", function (req, res) {
+  res.sen
+//       ^|
+});
+
+app.listen(3000);
+```
 
 TypeScript takes tooling seriously, and that goes beyond completions and errors as you type.
 An editor that supports TypeScript can deliver "quick fixes" to automatically fix errors, refactorings to easily re-organize code, and useful navigation features for jumping to definitions of a variable, or finding all references to a given variable.
 All of this is built on top of the type-checker and fully cross-platform, so it's likely that [your favorite editor has TypeScript support available](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Editor-Support).
 
-<!-- TODO: validate that link -->
-
 ## `tsc`, the TypeScript compiler
 
 We've been talking about type-checking, but we haven't yet used our type-_checker_.

packages/documentation/copy/en/handbook-v2/Everyday Types.md

@@ -17,9 +17,9 @@ As we learn about the types themselves, we'll also learn about the places where
 We'll start by reviewing the most basic and common types you might encounter when writing JavaScript or TypeScript code.
 These will later form the core "building blocks" of more complex types.
 
-## Primitives `string`, `number`, and `boolean`
+## The primitives: `string`, `number`, and `boolean`
 
-JavaScript has three main [primitive](https://developer.mozilla.org/en-US/docs/Glossary/Primitive) kinds of values: `string`, `number`, and `boolean`.
+JavaScript has three very commonly used [primitive](https://developer.mozilla.org/en-US/docs/Glossary/Primitive) kinds of values: `string`, `number`, and `boolean`.
 Each has a corresponding type in TypeScript.
 As you might expect, these are the same names you'd see if you used the JavaScript `typeof` operator on a value of those types:
 
@@ -367,7 +367,7 @@ Here are the most relevant differences between the two that you should be aware
 You'll learn more about these concepts in later chapters, so don't worry if you don't understand all of these right away.
 
 - Type aliases may not participate [in declaration merging, but interfaces can](/play?#code/PTAEEEDtQS0gXApgJwGYEMDGjSfdAIx2UQFoB7AB0UkQBMAoEUfO0Wgd1ADd0AbAK6IAzizp16ALgYM4SNFhwBZdAFtV-UAG8GoPaADmNAcMmhh8ZHAMMAvjLkoM2UCvWad+0ARL0A-GYWVpA29gyY5JAWLJAwGnxmbvGgALzauvpGkCZmAEQAjABMAMwALLkANBl6zABi6DB8okR4Jjg+iPSgABboovDk3jjo5pbW1d6+dGb5djLwAJ7UoABKiJTwjThpnpnGpqPBoTLMAJrkArj4kOTwYmycPOhW6AR8IrDQ8N04wmo4HHQCwYi2Waw2W1S6S8HX8gTGITsQA).
-- Interfaces may only be used to [declare object types, not primitives](/play?#code/PTAEAkFMCdIcgM6gC4HcD2pIA8CGBbABwBtIl0AzUAKBFAFcEBLAOwHMUBPQs0XFgCahWyGBVwBjMrTDJMAshOhMARpD4tQ6FQCtIE5DWoixk9QEEWAeV37kARlABvaqDegAbrmL1IALlAEZGV2agBfampkbgtrWwMAJlAAXmdXdy8ff0Dg1jZwyLoAVWZ2Lh5QVHUJflAlSFxROsY5fFAWAmk6CnRoLGwmILzQQmV8JmQmDzI-SOiKgGV+CaYAL0gBBdyy1KCQ-Pn1AFFplgA5enw1PtSWS+vCsAAVAAtB4QQWOEMKBuYVUiVCYvYQsUTQcRSBDGMGmKSgAAa-VEgiQe2GLgKQA).
+- Interfaces may only be used to [declare the shapes of object, not re-name primitives](/play?#code/PTAEAkFMCdIcgM6gC4HcD2pIA8CGBbABwBtIl0AzUAKBFAFcEBLAOwHMUBPQs0XFgCahWyGBVwBjMrTDJMAshOhMARpD4tQ6FQCtIE5DWoixk9QEEWAeV37kARlABvaqDegAbrmL1IALlAEZGV2agBfampkbgtrWwMAJlAAXmdXdy8ff0Dg1jZwyLoAVWZ2Lh5QVHUJflAlSFxROsY5fFAWAmk6CnRoLGwmILzQQmV8JmQmDzI-SOiKgGV+CaYAL0gBBdyy1KCQ-Pn1AFFplgA5enw1PtSWS+vCsAAVAAtB4QQWOEMKBuYVUiVCYvYQsUTQcRSBDGMGmKSgAAa-VEgiQe2GLgKQA).
 - Interface names will [_always_ appear in their original form](/play?#code/PTAEGEHsFsAcEsA2BTATqNrLusgzngIYDm+oA7koqIYuYQJ56gCueyoAUCKAC4AWHAHaFcoSADMaQ0PCG80EwgGNkALk6c5C1EtWgAsqOi1QAb06groEbjWg8vVHOKcAvpokshy3vEgyyMr8kEbQJogAFND2YREAlOaW1soBeJAoAHSIkMTRmbbI8e6aPMiZxJmgACqCGKhY6ABGyDnkFFQ0dIzMbBwCwqIccabcYLyQoKjIEmh8kwN8DLAc5PzwwbLMyAAeK77IACYaQSEjUWY2Q-YAjABMAMwALA+gbsVjNXW8yxySoAADaAA0CCaZbPh1XYqXgOIY0ZgmcK0AA0nyaLFhhGY8F4AHJmEJILCWsgZId4NNfIgGFdcIcUTVfgBlZTOWC8T7kAJ42G4eT+GS42QyRaYbCgXAEEguTzeXyCjDBSAAQSE8Ai0Xsl0K9kcziExDeiQs1lAqSE6SyOTy0AKQ2KHk4p1V6s1OuuoHuzwArMagA) in error messages, but _only_ when they are used by name.
 - Type alias names [_may_ appear in error messages](/play?#code/PTAEGEHsFsAcEsA2BTATqNrLusgzngIYDm+oA7koqIYuYQJ56gCueyoAUCKAC4AWHAHaFcoSADMaQ0PCG80EwgGNkALk6c5C1EtWgAsqOi1QAb06groEbjWg8vVHOKcAvpokshy3vEgyyMr8kEbQJogAFND2YREAlOaW1soBeJAoAHSIkMTRmbbI8e6aPMiZxJmgACqCGKhY6ABGyDnkFFQ0dIzMbBwCwqIccabcYLyQoKjIEmh8kwN8DLAc5PzwwbLMyAAeK77IACYaQSEjUWZWhfYAjABMAMwALA+gbsVjoADqgjKESytQPxCHghAByXigYgBfr8LAsYj8aQMUASbDQcRSExCeCwFiIQh+AKfAYyBiQFgOPyIaikSGLQo0Zj-aazaY+dSaXjLDgAGXgAC9CKhDqAALxJaw2Ib2RzOISuDycLw+ImBYKQflCkWRRD2LXCw6JCxS1JCdJZHJ5RAFIbFJU8ADKC3WzEcnVZaGYE1ABpFnFOmsFhsil2uoHuzwArO9SmAAEIsSFrZB-GgAjjA5gtVN8VCEc1o1C4Q4AGlR2AwO1EsBQoAAbvB-gJ4HhPgB5aDwem-Ph1TCV3AEEirTp4ELtRbTPD4vwKjOfAuioSQHuDXBcnmgACC+eCONFEs73YAPGGZVT5cRyyhiHh7AAON7lsG3vBggB8XGV3l8-nVISOgghxoLq9i7io-AHsayRWGaFrlFauq2rg9qaIGQHwCBqChtKdgRo8TxRjeyB3o+7xAA), sometimes in place of the equivalent anonymous type (which may or may not be desirable).
 
@@ -516,7 +516,7 @@ The second change means "I know for other reasons that `req.method` has the valu
 
 ## `null` and `undefined`
 
-JavaScript has two primitive values, `null` and `undefined`, both of which are used to signal absent or uninitialized values.
+JavaScript has two primitive values used to signal absent or uninitialized value: `null` and `undefined`.
 
 TypeScript has two corresponding _types_ by the same names. How these types behave depends on whether you have the `strictNullChecks` option on.
 
@@ -554,3 +554,38 @@ function liveDangerously(x?: number | null) {
 ```
 
 Just like other type assertions, this doesn't change the runtime behavior of your code, so it's important to only use `!` when you know that the value _can't_ be `null` or `undefined`.
+
+### Less Common Primitives
+
+It's worth mentioning the rest of the primitives in JavaScript which are represented in the type system.
+Though we will not go into depth here.
+
+##### `bigint`
+
+There is a primitive in JavaScript used for very large integers, `BitInt`:
+
+```ts
+// Creating a bigint via the BigInt function
+let foo: bigint = BigInt(100);
+
+// Creating a BigInt via the literal syntax
+let bar: bigint = 100n;
+```
+
+You can learn more about BitInt in [the TypeScript 3.2 release notes](/docs/handbook/release-notes/typescript-3-2.html#bigint).
+
+##### `symbol`
+
+There is a primitive in JavaScript used to create a globally unique reference via the function `Symbol()`:
+
+```ts twoslash
+// @errors: 2367
+const firstName = Symbol("name");
+const secondName = Symbol("name");
+
+if (firstName === secondName) {
+  // Can't ever happen
+}
+```
+
+You can learn more about them in [Symbols handbook reference page](/docs/handbook/symbols.html).

packages/documentation/copy/en/handbook-v2/More on Functions.md

@@ -726,3 +726,73 @@ function sum({ a, b, c }: ABC) {
 ```
 
 ## Assignability of Functions
+
+### Return type `void`
+
+The `void` return type for functions can produce some unusual, but expected behavior.
+
+Contextual typing with a return type of `void` does **not** force functions to **not** return something. Another way to say this is a contextual function type with a `void` return type (`type vf = () => void`), when implemented, can return _any_ other value, but it will be ignored.
+
+Thus, the following implementations of the type `() => void` are valid:
+```ts twoslash
+type voidFunc = () => void
+
+const f1: voidFunc = () => {
+  return true
+}
+
+const f2: voidFunc = () => true
+
+const f3: voidFunc = function () {
+  return true
+}
+```
+
+And when the return value of one of these functions is assigned to another variable, it will retain the type of `void`:
+
+```ts twoslash
+type voidFunc = () => void
+
+const f1: voidFunc = () => {
+  return true
+}
+
+const f2: voidFunc = () => true
+
+const f3: voidFunc = function () {
+  return true
+}
+// ---cut---
+const v1 = f1()
+
+const v2 = f2()
+
+const v3 = f3()
+```
+
+This behavior exists so that the following code is valid even though `Array.prototype.push` returns a number and the `Array.prototype.forEach` method expects a function with a return type of `void`.
+```ts twoslash
+const src = [1, 2, 3]
+const dst = [0]
+
+src.forEach(el => dst.push(el))
+```
+
+There is one other special case to be aware of, when a literal function definition has a `void` return type, that function must **not** return anything.
+
+```ts twoslash
+function f2 (): void {
+  // @ts-expect-error
+  return true 
+}
+
+const f3 = function (): void {
+  // @ts-expect-error
+  return true 
+}
+```
+
+For more on `void` please refer to these other documentation entries:
+- [v1 handbook](https://www.typescriptlang.org/docs/handbook/basic-types.html#void)
+- [v2 handbook](https://www.typescriptlang.org/docs/handbook/2/functions.html#void)
+- [FAQ - "Why are functions returning non-void assignable to function returning void?"](https://github.com/Microsoft/TypeScript/wiki/FAQ#why-are-functions-returning-non-void-assignable-to-function-returning-void)

packages/documentation/copy/en/handbook-v2/Narrowing.md

@@ -240,7 +240,7 @@ function printAll(strs: string | string[] | null) {
   if (strs !== null) {
     if (typeof strs === "object") {
       for (const s of strs) {
-        //           ^?
+        //            ^?
         console.log(s);
       }
     } else if (typeof strs === "string") {

packages/documentation/copy/en/handbook-v2/Types from Transformation.md renamed to packages/documentation/copy/en/handbook-v2/Type Manipulation/Conditional Types.md

@@ -1,18 +1,11 @@
 ---
-title: Types from Transformation
+title: Conditional Types
 layout: docs
-permalink: /docs/handbook/2/types-from-transformation.html
+permalink: /docs/handbook/2/conditional-types.html
 oneline: "Step one in learning TypeScript: The basics types."
 beta: true
 ---
 
-There are certain patterns that are very commonplace in JavaScript, like iterating over the keys of objects to create new ones, and returning different values based on the inputs given to us.
-This idea of creating new values and types on the fly is somewhat untraditional in typed languages, but TypeScript provides some useful base constructs in the type system to accurately model that behavior, much in the same way that `keyof` can be used to discuss the property names of objects, and indexed access types can be used to fetch values of a certain property name.
-
-We'll quickly see that combined, these smaller constructs can be surprisingly powerful and can express many patterns in the JavaScript ecosystem.
-
-## Conditional Types
-
 At the heart of most useful programs, we have to make decisions based on input.
 JavaScript programs are no different, but given the fact that values can be easily introspected, those decisions are also based on the types of the inputs.
 _Conditional types_ help describe the relation between the types of inputs and outputs.

packages/documentation/copy/en/handbook-v2/Type Manipulation/Indexed Access Types.md

@@ -0,0 +1,54 @@
+---
+title: Indexed Access Types
+layout: docs
+permalink: /docs/handbook/2/indexed-access-types.html
+oneline: "Step one in learning TypeScript: The basics types."
+beta: true
+---
+
+We can use an _indexed access type_ to look up a specific property on another type:
+
+```ts twoslash
+type Person = { age: number; name: string; alive: boolean };
+type A = Person["age"];
+//   ^?
+```
+
+The indexing type is itself a type, so we can use unions, `keyof`, or other types entirely:
+
+```ts twoslash
+type Person = { age: number; name: string; alive: boolean };
+// ---cut---
+type I1 = Person["age" | "name"];
+//   ^?
+
+type I2 = Person[keyof Person];
+//   ^?
+
+type AliveOrName = "alive" | "name";
+type I3 = Person[AliveOrName];
+//   ^?
+```
+
+You'll even see an error if you try to index a property that doesn't exist:
+
+```ts twoslash
+// @errors: 2339
+type Person = { age: number; name: string; alive: boolean };
+// ---cut---
+type I1 = Person["alve"];
+```
+
+Another example of indexing with an arbitrary type is using `number` to get the type of an array's elements.
+We can combine this with `typeof` to conveniently capture the element type of an array literal:
+
+```ts twoslash
+const MyArray = [
+  { name: "Alice", age: 15 },
+  { name: "Bob", age: 23 },
+  { name: "Eve", age: 38 },
+];
+
+type T = typeof MyArray[number];
+//   ^?
+```

packages/documentation/copy/en/handbook-v2/Type Manipulation/Keyof Type Operator.md

@@ -0,0 +1,33 @@
+---
+title: Keyof Type Operator
+layout: docs
+permalink: /docs/handbook/2/indexed-access-types.html
+oneline: "Step one in learning TypeScript: The basics types."
+beta: true
+---
+
+## The `keyof` type operator
+
+The `keyof` operator takes an object type and produces a string or numeric literal union of its keys:
+
+```ts twoslash
+type Point = { x: number; y: number };
+type P = keyof Point;
+//   ^?
+```
+
+If the type has a `string` or `number` index signature, `keyof` will return those types instead:
+
+```ts twoslash
+type Arrayish = { [n: number]: unknown };
+type A = keyof Arrayish;
+//   ^?
+
+type Mapish = { [k: string]: boolean };
+type M = keyof Mapish;
+//   ^?
+```
+
+Note that in this example, `M` is `string | number` -- this is because JavaScript object keys are always coerced to a string, so `obj[0]` is always the same as `obj["0"]`.
+
+`keyof` types become especially useful when combined with mapped types, which we'll learn more about later.

packages/documentation/copy/en/handbook-v2/Type Manipulation/Typeof Type Operator.md

@@ -0,0 +1,71 @@
+---
+title: Typeof Type Operator
+layout: docs
+permalink: /docs/handbook/2/typeof-types.html
+oneline: "Step one in learning TypeScript: The basics types."
+beta: true
+---
+
+## The `typeof` type operator
+
+JavaScript already has a `typeof` operator you can use in an _expression_ context:
+
+```ts twoslash
+// Prints "string"
+console.log(typeof "Hello world");
+```
+
+TypeScript adds a `typeof` operator you can use in a _type_ context to refer to the _type_ of a variable or property:
+
+```ts twoslash
+let s = "hello";
+let n: typeof s;
+//  ^?
+```
+
+This isn't very useful for basic types, but combined with other type operators, you can use `typeof` to conveniently express many patterns.
+For an example, let's start by looking at the predefined type `ReturnType<T>`.
+It takes a _function type_ and produces its return type:
+
+```ts twoslash
+type Predicate = (x: unknown) => boolean;
+type K = ReturnType<Predicate>;
+//   ^?
+```
+
+If we try to use `ReturnType` on a function name, we see an instructive error:
+
+```ts twoslash
+// @errors: 2749
+function f() {
+  return { x: 10, y: 3 };
+}
+type P = ReturnType<f>;
+```
+
+Remember that _values_ and _types_ aren't the same thing.
+To refer to the _type_ that the _value `f`_ has, we use `typeof`:
+
+```ts twoslash
+function f() {
+  return { x: 10, y: 3 };
+}
+type P = ReturnType<typeof f>;
+//   ^?
+```
+
+### Limitations
+
+TypeScript intentionally limits the sorts of expressions you can use `typeof` on.
+
+Specifically, it's only legal to use `typeof` on identifiers (i.e. variable names) or their properties.
+This helps avoid the confusing trap of writing code you think is executing, but isn't:
+
+```ts twoslash
+// @errors: 1005
+declare const msgbox: () => boolean;
+// type msgbox = any;
+// ---cut---
+// Meant to use =
+let shouldContinue: typeof msgbox("Are you sure you want to continue?");
+```

packages/documentation/copy/en/handbook-v2/Type Manipulation/_Creating Types from Types.md

@@ -0,0 +1,14 @@
+---
+title: Creating Types from Types
+layout: docs
+permalink: /docs/handbook/2/types-from-types.html
+oneline: "Step one in learning TypeScript: The basics types."
+beta: true
+---
+
+TypeScript's type system is very powerful because it allows expressing types _in terms of other types_.
+Although the simplest form of this is generics, we actually have a wide variety of _type operators_ available to us.
+It's also possible to express types in terms of _values_ that we already have.
+
+By combining various type operators, we can express complex operations and values in a succinct, maintainable way.
+In this section we'll cover ways to express a type in terms of an existing type or value.