// @ts-check in JS; JSDoc to get types

Intro

Enable checking

// calculator.js
// @ts-check

/**
 * Adds two numbers.
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
export function add(a, b) {
  return a + b
}

// Usage: type errors appear if you pass non-numbers
// add("2", 3) // TS will flag this in JS

Typedef & type

// models.js
// @ts-check

/** @typedef {{ id: string; name: string; age?: number }} User */

/** @type {User} */
export const currentUser = { id: "u1", name: "Ada" }

/**
 * Greets a user.
 * @param {User} u
 * @returns {string}
 */
export function greet(u) {
  return `Hello, ${u.name}!`
}

Template params

// helpers.js
// @ts-check

/**
 * Maps items with a function, preserving types.
 * @template T,U
 * @param {T[]} items
 * @param {(x: T) => U} f
 * @returns {U[]}
 */
export function map(items, f) {
  const out = []
  for (const x of items) out.push(f(x))
  return out
}

// Inference: T=number, U=string
// map([1,2], n => n.toFixed(2))

tsconfig for JS

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "checkJs": true,
    "allowJs": true,
    "strict": true,
    "noEmit": true
  },
  "include": ["./**/*.js"],
  "exclude": ["node_modules"]
}

Migration tips

ts-check check

Recap