More work on examples

Examples/JavaScript/External APIs/TypeScript + Deno.ts

@@ -0,0 +1,33 @@
+//// { order: 3 }
+
+// Deno is a work-in-progress JavaScript and TypeScript 
+// runtime based on v8 with a focus on security. 
+
+// https://deno.land
+
+// Deno has a sandbox-based permissions system which reduces the 
+// access JavaScript has to the file-system or the network and uses
+// http based imports which are downloaded and cached locally.
+
+// Here is an example of using deno for scripting:
+
+import compose from "https://deno.land/x/denofun/lib/compose.ts";
+
+function greet(name: string) {
+    return `Hello, ${name}!`;
+}
+
+function makeLoud(x: string) {
+    return x.toUpperCase();
+}
+
+const greetLoudly = compose(makeLoud, greet);
+
+// Echos "HELLO, WORLD!."
+greetLoudly("world"); 
+
+
+import concat from "https://deno.land/x/denofun/lib/concat.ts";
+// Returns "helloworld"
+concat("hello", "world"); 
+

Examples/JavaScript/External APIs/TypeScript + Node.ts

@@ -0,0 +1,37 @@
+// Node 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.
+
+// https://nodejs.org/en/
+
+// Node comes with a set of core libraries which extend the
+// JavaScript runtime, they range from path handling:
+
+import {join} from "path"
+const myPath = join("~", "downloads", "todo_list.json")
+
+// To file manipulation:
+
+import {readFileSync} from "fs"
+const todoListText = readFileSync(myPath, "utf8")
+
+interface TODO {
+  title: string
+  description: string
+  done: boolean
+}
+
+const todoList = JSON.parse(todoListText) as TODO[]
+
+// And process handling:
+import {spawnSync} from "child_process"
+todoList.filter(todo => !todo.done)
+        .forEach(todo => {
+  // Use the ghi client to create an issue for every todo 
+  // list item which hasn't been completed yet
+  spawnSync(`ghi open --message "${todo.title}\n${todo.description}" `)
+});
+
+// TypeScript has up-to-date type definitions for all of the 
+// built in modules via DefinitelyTyped - which means you 
+// can write node programs with strong type coverage

Examples/JavaScript/External APIs/TypeScript + React.tsx

@@ -1,4 +1,4 @@
-//// { order: 0, compiler: { jsx: "react" } }
+//// { order: 2, compiler: { jsx: "react" } }
 
 // React is a popular library for creating user interfaces.
 // It provides a JavaScript abstraction for creating view 

Examples/JavaScript/External APIs/Working with the DOM.ts → Examples/JavaScript/External APIs/TypeScript + Web.ts

@@ -1,5 +1,8 @@
-// The DOM is the underlaying API for working with a webpage,
-// and TypeScript has great support for that API.
+//// { order: 0 }
+
+// The DOM (Document Object Model) is the underlying API for
+//  working with a webpage, and TypeScript has great support
+// for that API.
 
 // Let's create a popover to show when you press run in
 // the toolbar above.
@@ -62,8 +65,6 @@ popover.appendChild(message)
 popover.appendChild(closebutton)
 document.body.appendChild(popover)
 
-
-
 // If you hit "Run" above, then a popup should appear
 // in the bottom left, which you can close by clicking
 // on the x in the top right of the popup.

Examples/JavaScript/External APIs/TypeScript + WebGL.ts

@@ -1,3 +1,5 @@
+//// { order: 5 }
+
 // Create a HTML canvas which uses WebGL to render spinning
 // confetti, let's walk through the code to understand how it works
 

Examples/TypeScript/Advanced Meta-Types/Discriminate Types.ts

@@ -1,4 +1,3 @@
-//
 // A discriminated type union is where you use code flow
 // analysis to reduce a set of potential objects down to one
 // specific object.

Examples/TypeScript/Primitives/Type Widening:Narrowing.ts

@@ -0,0 +1,61 @@
+// It might be easiest to start of the discussion of
+// widening and narrowing with an example:
+
+const welcomeString = "Hello There"
+let replyString = "Hey"
+
+// Aside from the text differences of the strings, welcomeString
+// is a const (which  means the value will never change)
+// and replyString is a let (which means it can change)
+
+// If you hover over both variables, you get very different
+// type information from TypeScript:
+//
+//   const welcomeString: "Hello There"
+//
+//   let replyString: string
+//
+
+// TypeScript has inferred the type of welcomeString to be 
+// the literal string "Hello There" whereas replyString
+// is general string.
+
+// This is because a let needs to have a wider type, you 
+// could set replyString to be any other string - which means
+// it has a wider set of possibilities.
+
+replyString = "Hi :wave:"
+
+// If replyString had the string literal type "Hey" - then 
+// you could never change the value because it could only
+// change to "Hey" again.
+
+// Widening and Narrowing types is about expanding and reducing
+// the possibilities which a type could represent.
+
+// An example of type narrowing is working with unions, the
+// example on code flow analysis is almost entirely based on
+// narrowing: example:code-flow
+
+// Type narrowing is what powers the strict mode of TypeScript
+// via the nullability checks. With strict mode turned off, 
+// markers for nullability like undefined and null are ignored
+// in a union.
+
+declare const quantumString: string | undefined
+// This will fail in strict mode only
+quantumString.length
+
+// In strict mode the onus is on the code author to ensure
+// that the type has been narrowed to the non-null type.
+// Usually this is as simple as an if check
+
+if (quantumString) {
+  quantumString.length
+}
+
+// In strict mode the type quantumString has two representations.
+// Inside the if, the type was narrowed to just string.
+
+// https://mariusschulz.com/blog/literal-type-widening-in-typescript
+// https://sandersn.github.io/manual/Widening-and-Narrowing-in-Typescript.html

Examples/scripts/generateTOC.js

@@ -4,6 +4,7 @@ const {join} = require("path")
 const { writeFileSync } = require("fs")
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 
 /** Retrieve file paths from a given folder and its subfolders. */
 // https://gist.github.com/kethinov/6658166#gistcomment-2936675
@@ -19,31 +20,14 @@ const getFilePaths = (folderPath) => {
 /**
  * @typedef {Object} Item - an item in the TOC
  * @property {string[]} path - the path to get to this file
+ * @property {string} id - an id for the slug
  * @property {string} title - name
  * @property {string} body - the text for the example
  * @property {number} sortIndex - when listing the objects
+ * @property {string} hash - the md5 of the content
  * @property {any} compilerSettings - name
  */
 
-
- /** @type Item */
-const example1 = {
-  path: ["JavaScript", "Functions with JavaScript", "Function Chaining.ts"],
-  title: "Function Chaining",
-  body: "",
-  sortIndex: 0,
-  compilerSettings: {}
-}
-
- /** @type Item */
-const example2 = {
-  path: ["JavaScript", "Modern JavaScript", "JSDoc Support.ts"],
-  title: "JSDoc support",
-  body: "",
-  sortIndex: 3,
-  compilerSettings: { isJavaScript: true }
-}
-
 const root = join(__dirname, "..")
 const allJS = getFilePaths(join(root, "JavaScript"))
 const allTS = getFilePaths(join(root, "JavaScript"))
@@ -77,14 +61,18 @@ const toc = all.map(m => {
       throw err
     }
   }
-  return {
+   /** @type Item */
+  const item = {
     path: relative.split("/"),
     title: title,
     id: title.toLowerCase().replace(/[^\x00-\x7F]/g, "-").replace(/ /g, "-").replace(/\//g, "-").replace(/\+/g, "-"),
     body: contents,
     sortIndex: index,
+    hash: crypto.createHash('md5').update(contents).digest("hex"),
     compilerSettings: compiler
-  }  
+  }
+
+  return item
 }) 
 
 const tableOfContentsFile = join("site/examplesTableOfContents.json")