Fight for Type Safety Stand with JavaScript

TypeScript 2.3 and later support type-checking JavaScript files with JSDoc types. And JSDoc's uses the Closure Compiler's type language, which in turn is originally based on the abandoned ES4 spec. Therefore, to some extent, TypeScript can check against ES4 type language!

 1/**
 2 * @template T, U
 3 * @typedef {U & { readonly __TYPE__: T}} Opaque */
 4
 5/** @typedef {Opaque<'age', number>} Age */
 6/** @type {function(number): Age} */
 7const newAge = (n) => {
 8  if (n < 0) {
 9    throw new Error("age must be positive")
10  } else {
11    return /** @type {Age} */(n)
12  }
13}

ES4 Type Language Overview

Take a glance at ES4 type language:

 1/** @type {null} */
 2const nil = null
 3
 4/** @type {string?} */
 5let nullable = null
 6
 7/** @type {function(number, number): number} */
 8const functionType = (x, y) => x + y
 9
10/**
11 * function.<T>(T): T
12 * @type {<T>(x: T) => T}
13 */
14const genericFunction = x => x
15
16/**
17 * @type { {k: string} }
18 */
19const objectType = { k: "structural" }
20
21/**
22 * (string, number)
23 * @type {string  | number}
24 */
25let unionType = 0
26
27/**
28 * [number]
29 * @type {number[]}
30 */
31const arrayType = [1, 2, 3]
32
33const immutableArray = /** @type {const} */ ([1, 2, 3])
34
35/**
36 * @type {[string, number]}
37 */
38const tupleType = ["one", 1]
39
40/** @type {*} */
41let dynamicType = null

Note that TypeScript syntax differs from ES4 for the following types:

0. dynamic type: any vs *
1. union type: A | B vs (A, B)
2. array: T[] vs [T]
3. function: (x: P) => R vs function(P): R

Since Closure Compiler also uses * and function(P): R, and TypeScript tries to be compatible with Closure type syntax, TypeScript also accepts * and function(P): R in JSDoc type annotation. However, some function type cannot be expressed in function(P): R form, e.g. type guard and assertion signature:

 1/** @typedef { {swim(): void;} } Fish */
 2/** @typedef { {fly(): void;} } Bird */
 3
 4/** @type {(p: Fish | Bird) => p is Fish} */
 5const isFish =  (p) => /** @type {Fish} */(p).swim !== undefined
 6
 7/** @type {(p: Fish | Bird) => asserts p is Fish} */
 8const assertIsFish = (p) => {
 9    if (/** @type {Fish} */(p).swim === undefined) {
10        throw new AssertionError("not a string");
11    }
12}

And there are other subtle differences, e.g. ES4 tuples should have at least two elements. But let's just ignore these details for now.

More Syntax Borrowed from Closure Compiler

Type Alias

Type aliases can be defined with the keyword @typedef:

1/** @typedef { {x: number, y: number} } Pointer */
2/** @type {Pointer} */
3const typeAlias = { x: 0, y: 0 }

Generic type parameters can be defined with the keyword template:

 1/**
 2 * @template T, U
 3 * @typedef {U & { readonly __TYPE__: T}} Opaque */
 4
 5/** @typedef {Opaque<'age', number>} Age */
 6/** @type {function(number): Age} */
 7const newAge = (n) => {
 8  if (n < 0) {
 9    throw new Error("age must be positive")
10  } else {
11    // Type cast requires parenthesized expression.
12    return /** @type {Age} */(n)
13  }
14}

Enum

@enum is also borrowed from Closure Compiler's type system, and is quite different from TypeScript's enum.

1/**
2 * @enum {function(number): number}
3 */
4const immutableObjectLiteral = {
5  /** @type {function(number)} */
6  succ: n => n + 1,
7  /** @type {function(number)} */
8  pred: n => n - 1
9}

Function Overloads

JSDoc's overloaded function comment syntax is not supported:

1/**
2 * @param {string} input
3 * @returns {string} result
4 *//**
5 * @param {number} input
6 * @returns {string} result
7 */
8function notSupported(input) { /* omit */ }

However, we can express function overloading type in TypeScript's form in a tricky way:

1/** @type { {
2            (): void;
3            (code: 0): void;
4            (code: 1, msg: string): void
5          } } */
6const f = (
7  /** @type {0 | 1} */ code = 0,
8  /** @type {string | undefined} */ msg = code === 0 ? undefined : ""
9) => { /* omit */ }

By default, TypeScript will infer parameters' type of overloaded function implementation as any, thus we need to specify specific types compatible with all overloads in parameter list of the function implementation.

Also, because here different overloads have different arity, we use default parameters to ensure the function implementation compatible with all overloads.

Import Types

Use import("module").Type to import types:

/** @type { import("m").T } */

This is often used in type aliases for brevity:

/** @typedef { import("module-name").LongTypeName } ShortName */

But if you have difficulties in expressing certain types in JSDoc comments, you can also declare the type in a separate TypeScript file, then import it in JSDoc comments.

Type Checking

Just create a jsconfig.json file under the root of the project.

It is possible to check JavaScript files without the jsconfig.json file with writing magic comment // @ts-check or setting a configuration option in vscode. But I prefer the jsconfig.json way, since I tend to set up some compiler options.

Why

Actually ES4 type system is quite different from TypeScript. For example, they have different subtype rules. Also, the JSDoc way of TypeScript type checking lacks some features, for example, there is no way to pass type parameter when invoking generic functions via JSDoc. The only thing we can do is let TypeScript infer the type parameter. If it fails to infer the type, we have to accept any as the type parameter. Another example is TypeScript cannot parse conditional types in JSDoc comments correctly. (#27424)

So why not code in TypeScript instead?

Possible reasons:

1. Get rid of the compilation step.
2. Avoid using TypeScript features unavailable in ECMAScript.
3. Secretly migrate a JavaScript project to TypeScript when other project developers do not want to switch to TypeScript.

Alternatives

An alternative approach for a secret migration from JavaScript is to rewrite them in ReScript, and use genType to generate TypeScript files.

1/* TypeScript file generated from index.res by genType. */
2/* eslint-disable import/first */
3
4// @ts-ignore: Implicit any on import
5import * as indexBS__Es6Import from './index.bs';
6const indexBS: any = indexBS__Es6Import;
7
8// tslint:disable-next-line:interface-over-type-literal
9export const h1: (line:string) => string = indexBS.h1;

This TypeScript files work, but the indexBS part is not perfectly human-readable. The TypeScript compiler can be used to generate corresponding .d.ts files.

export declare const htm: (text: string) => string;

This approach also brings in a sound type system.