JavaScript is cool

• Runs everywhere
• No special tooling
• Huge community
• Forwards compatible
• It just works (well, sort of)

…except when it isn’t

• Type mismatches
• Missing error hints (red squiggles)
• Code changes (internal/external)
• Difficult refactors

TypeScript is cool

• Typos & errors (red squigglies)
• Intellisense & autocomplete
• Onboarding & collaboration
• Maintenance
• Automated Documentation
• CI/CD quality checks

…except when it isn’t

• Requires Tooling
• Complexity
• Learning curve
• Doesn’t work everywhere

Provides great Intellisense

But doesn’t type-check by default

A JS example

const input = document.querySelector('input')

const someVal = 100 / input.value

Same code with TS

Enable Type Checking in JS files

// @ts-check

Helps catch errors

JSDocs provides more control

Also works with functions

It’s great:

• Still just JS (comments).
• Easy to start.
• Incrementally adoptable.

Could be better:

• Requires adding comments to each file.
• Adds noise to code reviews.

Enable TS check for whole project

// settings.json
{
  // ...
  "js/ts.implicitProjectConfig.checkJs": true,
}

It’s great:

• Less work to get type checking.

Could be better:

• Only works on your machine.

Enable TS check for whole team

// tsconfig.json
{
  "compilerOptions": {
    "checkJs": true,
  }
}

It’s great:

• Everyone can start catching bugs sooner.

Could be better:

• Only works in VS Code.

Run type checks with a CLI

npm install --save-dev typescript

// package.json
{
  "scripts": {
    "ts": "tsc"
  }
}

// tsconfig.json
{
  "files": ["./src/index.js"],
  "compilerOptions": {
    "checkJs": true,
    "allowJs": true,
    "noEmit": true,
  }
}

Now check types programmatically

npm run ts

It’s great:

• Runs on any machine
• Great for git hooks (pre-commit, pre-push)
• Great for CI/CD

Could be better:

• Some JSDocs syntax is awkward or not supported by TS

Opinions are based on experience

• Developer: can copy/paste code into browser/Node
• Writer: people can copy/paste code into their projects
• Teacher: students have a simpler setup and less to learn
• Maintainer: people can create codesandbox reproductions
• Team lead: want types without the learning overhead for new devs
• Reviewer: easier to read with separated types (highly subjective)

Create complex type definitions

Import type from different file

Import typedef from different file

Import type from a library

Define types in .d.ts files

export interface Dog {
  breed: string
  age: number
  name?: string
}

Disabling TS from checking code

• // @ts-ignore above line: Disable TS on that line.
• // @ts-nocheck top of file: Disable TS on whole file.
• exclude in tsconfig.json: Disable TS on groups of files.

Caveats

TypeScript mostly understands JSDocs, but not everything.

• Unsupported patterns
• Unsupported tags

Type Assertions

OK in TS

const canvas1 = 
  document.querySelector("canvas") as HTMLCanvasElement;

const canvas2 =
  <HTMLCanvasElement>document.querySelector("canvas");

Flat-out gross in JSDocs 🤮

const canvas1 = /** @type {HTMLCanvasElement} */ (
  document.querySelector("canvas")
);

• Type checking != TypeScript

• It’s not one or the other
• JSDocs is good BECAUSE TypeScript exists
• We still use .d.ts files and the CLI
• It’s mostly just syntactical difference in authoring
• For me, verbose comments + terse code is better than verbose code
• TS is an important testing ground for JS proposals & paves cow paths

Community Support for JSDocs

"My position is, types are fantastic, TypeScript is a bit of a pain … as soon as you use a .ts file, then you have to have the tooling to support that … there’s all of these points of friction when you use a non-standard language like TypeScript that I have come to believe makes it not worth it." - Rich Harris

"Like to keep the source I author the same as the source at runtime because debugging is way faster when it isn’t a murder mystery." - @brianleroux

"verbose comment - terse code" - @myfonj

Resources

• "Working with JavaScript" by VS Code
• "JSDoc Cheatsheet" by Devhints
• "JSDoc Cheatsheet and Type Safety Tricks" by Joshua Tzucker
• "Type Safe JavaScript with JSDoc" by Robert Biggs
• "JavaScript Type Linting" by Robert Biggs
• "TypeScript without TypeScript - JSDoc superpowers" by Stefan Baumgartner

Before

/**
 * @param {string}  p1 - String param.
 * @param {string=} p2 - Optional param (Closure syntax)
 * @param {string} [p3] - Optional param (JSDoc syntax).
 * @param {string} [p4="test"] - Param with default value.
 * @return {string} This is the result
 */
function stringsStringStrings(p1, p2, p3, p4="test") {
    // TODO
}

After

function stringsStringStrings(
  p1: string,
  p2? : string,
  p3?: string,
  p4 = "test"
): string {
    // TODO
}

Read the blog post: austingil.com/typescript-the-easy-way

Let’s connect

• austingil.com
• @heyAustinGil
• @mastodon.social/@Austingil
• @heyAustinGil
• @heyAustinGil
• @AustinGil

$100 for Akamai Connected Cloud

bit.ly/agilacc