Final revision

orta · orta · commit 931eafa33660 · 2019-09-09T08:51:37.000-04:00
diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml
@@ -28,7 +28,7 @@ jobs:
     - run: gulp publish
 
     # Deploy if we can
-    - run: npx now site/ --token=$NOW_ACCESS_TOKEN --name=typescript-playbook-$PR_NUMBER
+    - run: npx now site/ --token=$NOW_ACCESS_TOKEN --name=typescript-site-$PR_NUMBER
       env:
         NOW_ACCESS_TOKEN: ${{ secrets.NOW_ACCESS_TOKEN }}
         PR_NUMBER: ${{ github.event.pull_request.number }}
diff --git a/Examples/en/JavaScript/External APIs/TypeScript + Node.js b/Examples/en/JavaScript/External APIs/TypeScript + Node.js
@@ -1,6 +1,6 @@
 //// { order: 3, isJavaScript: true }
 
-// Node is a very popular JavaScript runtime built on v8,
+// Node.js is a very popular JavaScript runtime built on v8,
 // the JavaScript engine which powers Chrome. You can use it
 // to build servers, front-end clients and anything in-between.
 
diff --git a/Examples/en/JavaScript/External APIs/TypeScript + React.tsx b/Examples/en/JavaScript/External APIs/TypeScript + React.tsx
@@ -17,7 +17,6 @@
 // First we'll look at how generic interfaces are used to map
 // React components. This is a faux-React functional component:
 
-
 type FauxactFunctionComponent<Props extends {}> =
   (props: Props, context?: any) => FauxactFunctionComponent<any> | null |  JSX.Element
 
diff --git a/Examples/en/JavaScript/External APIs/TypeScript + Web.js b/Examples/en/JavaScript/External APIs/TypeScript + Web.js
@@ -72,8 +72,8 @@ document.body.appendChild(popover);
 // on the x in the top right of the popup.
 
 // This example shows how you can work with the DOM API
-// in TypeScript - but it only shows a subset of working
-// with the browser's APIs which TypeScript supports
+// in JavaScript - but using TypeScript to provide great
+// tooling support.
 
-// There is an extended example for TypeScript with the
-// WebGL example available here: example:typescript---webgl
+// There is an extended example for TypeScript tooling with
+// WebGL available here: example:typescript---webgl
diff --git a/Examples/en/JavaScript/External APIs/TypeScript + WebGL.js b/Examples/en/JavaScript/External APIs/TypeScript + WebGL.js
@@ -1,7 +1,9 @@
 //// { order: 5 }
 
-// Create a HTML canvas which uses WebGL to render spinning
-// confetti, let's walk through the code to understand how it works
+// This example create a HTML canvas which uses WebGL to 
+// render spinning confetti using JavaScript. We're going 
+// to walk through the code to understand how it works, and
+// see how TypeScript's tooling provides useful insight.
 
 // This example builds off: example:working-with-the-dom
 
@@ -37,8 +39,7 @@ const gl = canvas.getContext("webgl")
 // array of vertices (numbers)
 
 // You can see the large set of attributes at the top of the shader,
-// these are passed in from 
-// 
+// these are passed into the compiled shader further down the example.
 
 // There's a great overview on how they work here:
 // https://webglfundamentals.org/webgl/lessons/webgl-how-it-works.html
@@ -117,9 +118,9 @@ gl.compileShader(vertexShader)
 // shader is another small program that runs through every
 // pixel in the canvas and set its color.
 
-// In this case, if you play around with the numers you can see how
+// In this case, if you play around with the numbers you can see how
 // this affects the lighting in the scene, as well as the border
-// radius on the confetti
+// radius on the confetti:
 
 const fragmentShader = gl.createShader(gl.FRAGMENT_SHADER)
 gl.shaderSource(
diff --git a/Examples/en/JavaScript/Functions with JavaScript/Function Chaining.ts b/Examples/en/JavaScript/Functions with JavaScript/Function Chaining.ts
@@ -4,15 +4,15 @@
 // Function chaining APIs are a common pattern in
 // JavaScript, which can make your code focused
 // with less intermediary values and easier to read
-// because of the spacing.
+// because of their nesting qualities.
 
 // A really common API which works via chaining
 // is jQuery. Here is an example of jQuery
 // being used with the types from DefinitelyTyped
 
 import $ from "jquery";
 
-// Here's an example use of the jQuery API
+// Here's an example use of the jQuery API:
 
 $("#navigation")
   .css("background", "red")
@@ -86,3 +86,4 @@ new AddNumbers(2).add(3).add(3);
 
 // For more examples on this:
 //
+//  - example:code-flow
diff --git a/Examples/en/JavaScript/Functions with JavaScript/Generic Functions.ts b/Examples/en/JavaScript/Functions with JavaScript/Generic Functions.ts
@@ -15,8 +15,9 @@ function wrapInArray<Type>(input: Type): Type[] {
 }
 
 // Note: it's common to see Type refereed to as T. This is
-// culturally like how people use i in a for loop to
-// represent index. We'll be using full names for clarity.
+// culturally similar to how people use i in a for loop to
+// represent index. T normally represents Types, so we'll 
+// be using the full name for clarity.
 
 // Our function will use inference to always keep the type
 // passed in the same as the type passed out (though
@@ -25,7 +26,9 @@ function wrapInArray<Type>(input: Type): Type[] {
 const stringArray = wrapInArray("hello generics");
 const numberArray = wrapInArray(123);
 
-// By providing types you can ensure code fails correctly
+// We can verify this works as expected by checking
+// if we can assign a string array to a function which
+// should be an object array
 const notStringArray: string[] = wrapInArray({});
 
 // You can also skip the generic inference by adding the
diff --git a/Examples/en/JavaScript/Functions with JavaScript/Typing Functions.ts b/Examples/en/JavaScript/Functions with JavaScript/Typing Functions.ts
@@ -129,4 +129,4 @@ const boolValue2 = boolOrNumberOrStringFunction("string")
 // variables in type definitions.
 
 // example:generic-functions
-
+// example:function-chaining
diff --git a/Examples/en/JavaScript/JavaScript Essentials/Code Flow.ts b/Examples/en/JavaScript/JavaScript Essentials/Code Flow.ts
@@ -53,7 +53,7 @@ if (typeof randomIdentifier === "number") {
 // code types will change in different locations.
 
 // To learn more about code flow analysis
-//  - [handbook]
+//  - example:type-guards
 
 // To continue reading through examples you could jump to a few different
 // places now.
diff --git a/Examples/en/JavaScript/JavaScript Essentials/Functions.ts b/Examples/en/JavaScript/JavaScript Essentials/Functions.ts
@@ -24,8 +24,8 @@ const addFunction = (x, y) => {
 // applies to all three formats.
 
 // TypeScript provides additional syntax which adds to a
-// function and offers hints on what the types are expected
-// by this function.
+// function definition and offers hints on what the 
+// types are expected by this function.
 //
 // Up next is the most open version of the add function, it
 // says that add takes two inputs of any type: this could
diff --git a/Examples/en/JavaScript/JavaScript Essentials/Hello World.ts b/Examples/en/JavaScript/JavaScript Essentials/Hello World.ts
@@ -4,7 +4,7 @@
 // like running a TypeScript project inside a web browser.
 
 // The playground makes it easy for you to safely experiment
-//  with ideas in TypeScript by making it trivial to share
+// with ideas in TypeScript by making it trivial to share
 // these projects. The URL for this page is everything 
 // required to load the project for someone else.
 
@@ -31,5 +31,5 @@ console.log(hello + " " + world)
 //
 // Click below to continue:
 //
-// example:arrays-and-objects
+// example:objects-and-arrays
 
diff --git a/Examples/en/TypeScript/Language/Soundness.ts b/Examples/en/TypeScript/Language/Soundness.ts
@@ -28,7 +28,10 @@ const usersAge = ("23" as any) as number;
 // type assertions is a way of telling TypeScript you know
 // best, and TypeScript will try to let you get on with it.
 
-// TODO: Most type systems actually have some sort of runtiem checks
+// Languages which are sound would occasionally use runtime checks
+// to ensure that the data matches what your types say - but
+// TypeScript aims to have no type-aware runtime impact on 
+// your transpiled code.
 
 // Function Parameter Bi-variance
 
diff --git a/Examples/en/TypeScript/Language/Structural Typing.ts b/Examples/en/TypeScript/Language/Structural Typing.ts
@@ -1,5 +1,3 @@
-// TODO: Members feels a bit too set-theory-y - can property work instead?
-
 // TypeScript is a Structural Type System. A structural type
 // system means that when comparing types, TypeScript only
 // takes into account the members on the type.
@@ -9,7 +7,7 @@
 // other. See example:nominal-typing
 
 // For example, these two interfaces are completely
-// transferrable:
+// transferrable in a structural type system:
 
 interface Ball { diameter: number; }
 interface Sphere { diameter: number; }
diff --git a/Examples/en/TypeScript/Language/Type Guards.ts b/Examples/en/TypeScript/Language/Type Guards.ts
@@ -1,12 +1,10 @@
-// Type Guards allow you to customize the code flow analysis.
-// This language feature lets you create functions which 
-// tell TypeScript the type of an argument passed to it.
+// Type Guarding is the term where you influence the code 
+// flow analysis via code. TypeScript uses existing JavaScript
+// behavior which validates your objects at runtime to influence
+// the code flow. This example assumes you've read example:code-flow
 
-// You create a function where the return type offers 
-// information to the code flow analysis when the function
-// returns true
-
-// We'll create a system for handling internet or mail orders.
+// To run through these examples, we'll create some classes, 
+// here's a system for handling internet or telephone orders.
 
 interface Order { address: string }
 interface TelephoneOrder extends Order { callerNumber: string }
@@ -15,11 +13,50 @@ interface InternetOrder extends Order { email: string }
 // Then a type which could be one of the two Order subtypes or undefined
 type PossibleOrders = TelephoneOrder | InternetOrder | undefined
 
+// And a function which returns a Possible order
 declare function getOrder(): PossibleOrders
-
 const possibleOrder = getOrder()
 
-// Now we have a possible order, we can use two type guards
+// We can use the "in" operator to check whether a particular
+// key is on the object to narrow the union. "in" is a JavaScript
+// operator for objects.
+
+if ("email" in possibleOrder) {
+  const mustBeInternetOrder = possibleOrder
+}
+
+// You can use the JavaScript "instanceof" operator if you 
+// have a class which conforms to the interface:
+
+class TelephoneOrderClass {
+  address: string
+  callerNumber: string
+}
+
+if (possibleOrder instanceof TelephoneOrderClass) {
+  possibleOrder
+}
+
+// You can use the JavaScript "typeof" operator to 
+// narrow your union, this only works with primitives
+// inside JavaScript (like strings, objects, numbers)
+
+if (typeof possibleOrder === "undefined") {
+  const definitelyNotAnOder = possibleOrder
+}
+
+// You can see a full list of possible typeof values
+// here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof
+
+// Using JavaScript operators can only get you so far, when
+// you want to check your own object types you can use
+// type predicate functions.
+
+// A type predicate function is a function where the return
+// type offers information to the code flow analysis when 
+// the function returns true
+
+// Using the possible order, we can use two type guards
 // to declare which type the possibleOrder is:
 
 function isAnInternetOrder(order: PossibleOrders): order is InternetOrder {
@@ -42,4 +79,7 @@ if (isATelephoneOrder(possibleOrder)) {
 }
 
 // You can read more on how code flow analysis here:
-// example:code-flow
+//
+//  - example:code-flow
+//  - example:type-guards
+//  - example:discriminate-types
diff --git a/Examples/en/TypeScript/Language/Type Widening:Narrowing.ts b/Examples/en/TypeScript/Language/Type Widening:Narrowing.ts
@@ -57,5 +57,11 @@ if (quantumString) {
 // In strict mode the type quantumString has two representations.
 // Inside the if, the type was narrowed to just string.
 
+// You can see more examples of narrowing in 
+//
+// example:union-and-intersection-types
+// example:discriminate-types
+
+// And even more resources on the web:
 // https://mariusschulz.com/blog/literal-type-widening-in-typescript
 // https://sandersn.github.io/manual/Widening-and-Narrowing-in-Typescript.html
diff --git a/Examples/en/TypeScript/Meta-Types/Conditional Types.ts b/Examples/en/TypeScript/Meta-Types/Conditional Types.ts
@@ -27,18 +27,18 @@ type ExtractDogish<A> = A extends { barks: true } ? A : never;
 
 // A cat doesn't bark, so it will return never
 type NeverCat = ExtractDogish<Cat>;
-// A wolf will bark, so it returns the wolf
+// A wolf will bark, so it returns the wolf shape
 type Wolfish = ExtractDogish<Wolf>;
 
 // This becomes useful when you want to work with a
 // union of many types and reduce the number of potential
-// options in a union,
+// options in a union:
 
 type Animals = Cat | Dog | Cheetah | Wolf;
 
 // When you apply ExtractDogish to a union type, it is the
 // same as running the conditional against each member of
-// the type
+// the type:
 
 type Dogish = ExtractDogish<Animals>;
 
@@ -55,19 +55,19 @@ type Dogish = ExtractDogish<Animals>;
 // Deferred Conditional Types
 
 // Conditional types can be used to tighten your APIs which
-// can return different types depending on the inputs.
+// can return different types depending on the inputs. 
 
 // For example this function which could return either a
 // string or number depending on the boolean passed in.
 
-declare function getUserID<T extends boolean>(user: {}, oldSystem: T): T extends true ? string : number;
+declare function getAdoptionID<T extends boolean>(user: {}, oldSystem: T): T extends true ? string : number;
 
 // Then depending on how much the type-system knows about
 // the boolean, you will get different return types:
 
-let stringReturnValue = getUserID({}, /* oldSystem */ true);
-let numberReturnValue = getUserID({}, /* oldSystem */ false);
-let stringOrID = getUserID({}, /* oldSystem */ Math.random() < 0.5);
+let stringReturnValue = getAdoptionID({}, /* oldSystem */ true);
+let numberReturnValue = getAdoptionID({}, /* oldSystem */ false);
+let stringOrID = getAdoptionID({}, /* oldSystem */ Math.random() < 0.5);
 
 // In this case above TypeScript can know the return value
 // instantly. However, you can use conditional types in functions
@@ -77,25 +77,31 @@ let stringOrID = getUserID({}, /* oldSystem */ Math.random() < 0.5);
 // Same as our Dogish above, but as a function instead
 declare function isCatish<T>(x: T): T extends { meows: true } ? T : undefined;
 
-// In this Generic function there are no constraints on the
-// generic parameter U, and so it could be any type.
+// There is an extra useful tool within conditional types, which
+// is being able to specifically tell TypeScript that it should
+// infer the type when deferring. That is the 'infer' keyword.
 
-// This means using Catish would need to wait to know what
-// the actual type of U is before it can be applied.
+// infer is typically used to create meta-types which inspect
+// the existing types in your code, think of it as creating 
+// a new variable inside the type
 
-function findOtherAnimalsOfType<U>(animal: U) {
-  let maybeCat = isCatish(animal);
+type GetReturnValue<Type> = Type extends (...args: any[]) => infer Return ? Return : Type
 
-  // You can use assignment to short-circuit the process
-  // if you' have a good idea about the types during
-  // implementation
-  let b: Cat | Cheetah | undefined = maybeCat;
-  return maybeCat;
-}
-
-const a = findOtherAnimalsOfType<Animals>({ meow: true, fast: true });
-const b = findOtherAnimalsOfType<Cat>({ meows: true });
+// Roughly:
+//
+//  - this is a conditional generic type called GetReturnValue 
+//    which takes a type in it's first parameter
+//
+//  - the conditional checks if the type is a function, and 
+//    if so create a new type called Return based on the return
+//    value for that function
+//
+//  - If the pass checks, the type value is the inferred
+//    return value, otherwise it is the original Type
+//
 
-// TODO: This example needs work!
+type getAdoptionIDReturn = GetReturnValue<typeof getAdoptionID>
 
-// typeof process("foo")
+// This fails the check for being a function, and would 
+// just return the type passed into it.
+type getCat = GetReturnValue<Cat>
diff --git a/Examples/en/TypeScript/Primitives/Any.ts b/Examples/en/TypeScript/Primitives/Any.ts
diff --git a/Examples/en/TypeScript/Primitives/Union and Intersection Types.ts b/Examples/en/TypeScript/Primitives/Union and Intersection Types.ts
diff --git a/dangerfile.ts b/dangerfile.ts
diff --git a/src/_docs/home.md b/src/_docs/home.md
