microsoft / typescript-new-handbook

Incubation repository for the new TypeScript handbook 🐣

Archived, because this now lives in the TypeScript website.

The New TypeScript Handbook

👶

This repo is still in early development.

You can read an early version starting from the Outline or read one enormous page

Pull Requests

We are currently not accepting pull requests from external contributors. PRs will be open once the initial round of writing is complete.

Authoring

See Authoring for how to contribute content.

typescript-new-handbook's Issues

Type Declarations Page

(If you would like me to separate these into different issues I can. Just wanted to keep all notes for the page together)

Execute Program's order of teaching TypeScript

Full thread: https://twitter.com/garybernhardt/status/1191799263396712448?s=20

Basic types
Operators
JavaScript built-ins
Inference
Syntax errors vs. type errors
Object types
Type unions
Literal types
Conditional narrowing
Discriminated unions
Error handling with unions

Typo: 'import' should be 'export'

Type in description of isolated modules here:

Exports of Non-Value Identifiers
In TypeScript, you can import a type and then subsequently import it:

Should be:
In TypeScript, you can import a type and then subsequently export it:

Feedback for Chapter "Basics"

Hi there 👋 Thank you so much for trying to improving the current docs. @DanielRosenwasser asked for feedback on Twitter and here are my 2 cents about the "Basic" chapter, which is the only one I could read so far.

Disclaimer: I don't know how this handbook is embedded in the new website, but I assume that it will be the very first touching point for everyone who wants to learn TypeScript.

Introduction

I needed to re-read some sentences in the current introduction. Maybe it was because I'm not a native english speaker or that in some sence the introduction was already deeper and more complex than I'd expected and I tried to figure out what is the goal of the introduction while reading it.

I think the goal of the introduction is summarized in the last two sentences:

JavaScript only truly provides dynamic typing - running the code to see what happens.
The alternative is to use a static type system to make predictions about what code is legal before it runs.

Maybe the whole introduction can be trimmed down to one example which illustrates this statement. I think the flip example would be sufficient already.

However there were other parts I missed in the introduction.

1. A small greeting: "Hello everyone!"
2. A small sentence about what TypeScript actually is. When I search the documentation for TypeScript it's first mentioned as "That's what a static type-checker like TypeScript does." I think this is already a good statement: Is TypeScript a type-checker? Is it a language? Is it both? If yes, is it even more? etc.
3. A statement about the goals of this handbook. Is is about learning the language? Is it about learning how to use the compiler? Something else?
4. A statement about how this handbook is structured. What previous experience is assumed? (e.g. knowledge about JavaScript, npm, the terminal) What are the chapters? Can they be read in any order?
5. Some meta information about how to get help. "Feeling lost? Click here.", "Found a typo? Report it here." and so on.

Goals

My personal goal of this handbook is to have the resource I can give to people who are new to TypeScript to learn the language.

If often saw people with previous programming knowledge, but without experience to TypeScript to either

1. come to an already existing TypeScript project or
2. start with people already familiar with TypeScript (and how to setup a TypeScript project) a new TypeScript project where they needed to use TypeScript, but wasn't in charge of setting up the project.

I personally would wish to not see any advice about how to download, configure and use tsc in the "Basics" chapter. Finding out about command line flags like --noEmitOnError would be something I'd cover in a later chapter. (Or maybe in a completely different handbook - the tsc handbook?) I'd love to see handbook which doesn't rely on additional tooling in the first chapters and would leverage embedded playgrounds for all examples, so someone who wants to learn TypeScript doesn't have to leave the browser.

I also assume that we still have something like "TypeScript in 5 minutes" (or maybe even "TypeScript in 5 minutes with tsc", "TypeScript in 5 minutes with babel", "TypeScript in 5 minutes with webpack", "TypeScript in 5 minutes with parcel", etc.). If we state our goals of the handbook in the introduction, we may also state non-goals (like introduction to specific tooling) and could navigate people who are interested in this topic to a different ressource.

I'd also introcude people to the general design vision of TypeScript here, so I can refer to them in later section. E.g. things which are currently listed at the end of the "Basic" chapter like "Type annotations never change the runtime behavior of your program."

Define common terms

Similar to how the introduction should define the term TypeScript I'd also explictly try to define certain terms which may are unknown, but used a lot. A good example is ECMAScript. The first time its used its just called "the ECMAScript specification" with a link to the spec, but not a concrete explanation. Later it's used in "Type annotations aren't part of JavaScript (or ECMAScript to be pedantic)" - maybe it would be good to explicitly explain when what term is used beforehand. The next oocurence is this:

Template strings are a feature from a version of ECMAScript called ECMAScript 2015 (a.k.a. ECMAScript 6, ES2015, ES6, etc. - don't ask). TypeScript has the ability to rewrite code from newer versions of ECMAScript to older ones such as ECMAScript 3 or ECMAScript 5 (a.k.a. ES3 and ES5).

I'd try to simplify this a little bit and be more straightforward. Something like this:

The language JavaScript as we commonly call it has a formal specification which is called ECMAScript. You can find the complete specification here. Most of the times both terms are interchangeable and thoughout this guide we'll use JavaScript, with one exception: As the language evolves and new features are added also new versions of the ECMAScript specification are created. These versions original used a major version number )like ECMAScript 3 or ECMAScript 5) and later switched to a version scheme using the current year (like ECMAScript 2015). In general we abbreviate these versions as ES3, ES2015 and so on.

But mabye this can be even dropped in the "Basics" chapter completely, when we move tsc and the downleveling section to a later chapter.

Avoid noise and use a neutral tone

Things like:

Tada! Wait, "tada" what exactly?
...to be pedantic
a.k.a. ECMAScript 6, ES2015, ES6, etc. - don't ask
By default TypeScript targets ES3, an extremely old version of ECMAScript.

A friendly casual tone is nice, but some filler make it harder to read the documentation. Some of these examples could be dropped completely (imho) and others can be rewritten like the last one.

By default TypeScript targets ES3, which is the oldest version of ECMAScript which TypeScript supports.

Be as opinionated as possible

In some cases that is already done quite well ("it's best not to add annotations when the type system would end up inferring the same type anyway"), but maybe it can be taken even further.

E.g. if we would embed playground examples and would not introduce tsc so early, we could also build every example in a way that they use --strict by default. In that case I wouldn't even explain that there is a hidden --strict setting in the background, but I'd write the complete handbook using this best practice and I'd just in a later advanced chapter tell the reader, that there are actually looser and more dangerous configurations possible.

That makes reading the introduction leaner (less explanation about configurations) and you automatically teach good practices.

Avoid uncertainties

For that I think I just found one example:

In this case, there was very little for TypeScript to transform, so it looks identical to what we wrote.

What's very little and looks identical in that case? I stumbled over this question and couldn't read further, because I first had to answer it in my head. Was there something transformed I couldn't see/find or are they identical (even though just for this particular example)?

A different approach how to explain a type checker

Currently the type checker is explained like this:

1. "We've been talking about type-checking, but we haven't yet used our type-checker. Let's get acquainted with our new friend tsc..."
2. "writing our first TypeScript program"
3. "now let's type-check it"
4. "there were no type errors"
5. "But check again - we got some file output instead."
6. Then somethind about transforming files...
7. Then we introduce a type-checking error and try it again.

Maybe we can find a more straightforward explanation which doesn't touch tranforming files in the middle of the explanation. That would probably be easier with embedded playgrounds as well.

---

I hope the feedback is valuable and doesn't sound too negative. Thank you very much for trying to improve the documentation. Feel free to close the issue immediately 🙃

Introduction to Handbook

(If you would like me to separate these into different issues I can. Just wanted to keep all notes for the page together)

More on Functions Page

(If you would like me to separate these into different issues I can. Just wanted to keep all notes for the page together)

Do you want this? (Half finished 'reference' article)

I started writing this a while back https://github.com/jack-williams/ts-spec/blob/master/conditional-types.md

It's incomplete, out-of-date, and probably wrong in places -- but it's a starting point. I'm still planning to finish it up but there are PR's outstanding that might change a few things.

Anyway, I'm just offering it up as a resource to cannibalised.

Types of Extraction Page

(If you would like me to separate these into different issues I can. Just wanted to keep all notes for the page together)

Narrowing Page

I noticed most pages have a mini table of contents and an introduction at the top. Narrowing has subtopics in the outline but it is not present at the top of its page, nor is an introduction.

Subtopics:

Also the never type and Exhaustiveness checking subsections are empty: is this correct?

(If you would like me to separate these into different issues I can. Just wanted to keep all notes for the page together)

Making the Content Searchable

Is it possible to make the Handbook searchable?

The Outline can be a bit overwhelming and hard to find specific topics especially with longer pages like the More on Functions and Classes page.

Other suggestions on making the handbook less busy:

• Possibly remove all subtopics and maybe add a description. But allow subtopics to be seen when main pages are open
• Or make the subtopics dropdowns (I'm not sure if this is the idea once the handbook is ported to the TypeScript website)

Command Line/Flag Appendix

Many command line examples and command line flags are mentioned.

Is it possible to add an appendix with all those mentioned?

Error on isolatedModules option description

TypeScript-New-Handbook/reference/Compiler Options.md

Lines 652 to 656 in cfd1d9d

	#### Exports of Non-Value Identifiers
	In TypeScript, you can import a *type* and then subsequently import it:
	```ts
	// @noErrors

I think that line 654 should be (bold to mark the change):

In TypeScript, you can import a type and then subsequently export it:

// CC @RyanCavanaugh because you added that text.

Typo in Inference example comment

Here: https://microsoft.github.io/TypeScript-New-Handbook/everything/#inference
the comment reads:

// Parameter 'n' is of type 'number'
// 'parsed' is of type 'string[]'

should be the other way around:

// Parameter 'n' is of type 'string'
// 'parsed' is of type 'number[]'

Narrowing page seems unfinished

https://microsoft.github.io/TypeScript-New-Handbook/chapters/narrowing/#the-never-type

Running Code Samples

When selecting the 'Try' button and opening TypeScript playground (or simply copy and pasting the code locally), running some of the code samples does not allow users to see the results of the code (thinking in terms of beginners or those trying to get more of an understanding).

Suggestion: Update TS code samples to actually call functions created in code samples:

function printAll(strs: string | string[] | null) {
    if (typeof strs === "object") {
        for (const s of strs) {
            console.log(s)
        }
    }
    else if (typeof strs === "string") {
        console.log(strs)
    }
    else {
        // do nothing
    }
}

to

function printAll(strs: string | string[] | null) {
    if (typeof strs === "object") {
        for (const s of strs) {
            console.log(s)
        }
    }
    else if (typeof strs === "string") {
        console.log(strs)
    }
    else {
        // do nothing
    }
}

printAll("just wanna see something")

Entire page flashes every reload when using light theme

https://microsoft.github.io/TypeScript-New-Handbook/everything/

1. Select light theme+light code in top right corner
2. Reload page
3. It flashes dark theme, after that returns to the light

Error text not wrapped

https://microsoft.github.io/TypeScript-New-Handbook/everything/#type-assertions

`in` Operator for Narrowing Section

Hi, thanks for this awesome new handbook, I like the new way that you're presenting TypeScript here!

Type guards with the in operator are not mentioned in the Narrowing section.

They are mentioned in the current handbook on the Advanced Types page under the Using the in Operator section:

---

Using the in operator

The in operator now acts as a narrowing expression for types.

For a n in x expression, where n is a string literal or string literal type and x is a union type, the “true” branch narrows to types which have an optional or required property n, and the “false” branch narrows to types which have an optional or missing property n.

function move(pet: Fish | Bird) {
    if ("swim" in pet) {
        return pet.swim();
    }
    return pet.fly();
}

---

Potentially related to #9 by @gcrev93

Code Box Rendering Issue

For some reason, the code and errors do not wrap around but rather continue outside of the code box causing it to look like this:

Please note: I am using a MacBook. I checked this on Chrome and Safari and it has the text outside of the code box. When testing in Edge this does not occur. The text adjusts to fit into the box.

noImplicitUseStrict not honored in @showEmit

Not obvious why; other emit flags work

TypeScript Basics Page

(If you would like me to separate these into different issues I can. Just wanted to keep all notes for the page together)

Information on Modules

Will we be adding information on importing/exporting modules and etc?

The current Handbook in the TypeScript has a Modules page that is very helpful, so just wanted to inquire.