Types for JavaScript: JSDoc & TypeScript

Find type mistakes before your users do

A type is the kind of a value: a number, a string, an object, a function, and so on. JavaScript checks types only while the code runs. That time is called runtime. A variable can hold a number now and a string later. This is flexible, but some mistakes stay hidden until runtime:

• a property name with a typo;
• a missing callback, which is a function you pass in so it can be called later;
• calling something that is not a function, which throws a TypeError.

If the mistake sits on a path that rarely runs, a user may be the first person to find it.

This lesson builds on data types, checking types, and type coercion. At runtime, JavaScript still uses the tools you know: typeof, Array.isArray, truthy checks, and if checks. The new tool in this lesson is a checker that can warn you before the code runs.

1const lesson = {2  title: "Types",3  onComplete: undefined,4};5 6lesson.onComplete();

Line 3 sets onComplete to undefined. Line 6 calls it anyway. JavaScript finds out only when it reaches line 6, so it throws a TypeError. A type checker could warn you about line 6 while you type.

A callback is optional when it may be missing. Your code must treat it that way: check that it is a function before you call it.

const lesson = { onComplete: undefined };
const finish = lesson.onComplete;
if (typeof finish === "function") finish();
console.log("Lesson saved");

Line 2 reads the callback, which may be missing. Line 3 calls it only if it is a function. Here it is undefined, so the call is skipped. Line 4 prints Lesson saved and nothing throws. This check also works for data that comes from outside your code.

A checker finds some mistakes early. It can't prove that your code does the right thing, for example that the lesson was really saved. Tests and runtime checks answer those questions.

The table compares three tools. Each row gives the tool, what it is good at, and what it can't do.

JSDoc is a way to write types inside comments. You keep your normal .js files. You add special comments that start with /**. Editors that use TypeScript can read them.

JavaScript skips comments when it runs, so these comments change nothing at runtime. To make the checker read them, put // @ts-check at the top of a file, or turn on checkJs for the whole project. The next section shows how.

// @ts-check
/** @param {number} price @returns {number} */
function withTax(price) {
  return price + 2;
}
console.log(withTax(3));

Line 2 tells the checker two things: price is a number, and the function returns a number. Line 4 adds a fee of 2, so the call on line 6 prints 5. The comment doesn't change how the code runs. If you call withTax("3"), JavaScript still joins the text and prints 32, unless your code checks the input.

Each row of the next table is one JSDoc tag: what you write, what it does, and an example.

Name an object shape, with optional and either-or types

The next example uses a few new tags and words:

• @typedef gives a name to an object shape. A shape is the list of properties an object has, with their types. Here the name is CourseCard.
• @property adds one property to that shape.
• Square brackets, like [status="draft"], mark a property as optional. The part after = is its default value.
• string | number is a union: the value can be a string or a number.

1// @ts-check2/**3 * @typedef {object} CourseCard4 * @property {string} title5 * @property {number} lessons6 * @property {"draft" | "published"} [status="draft"]7 */8 9/**10 * @param {CourseCard} course11 * @param {string | number} [prefix="Course"]12 * @returns {string}13 */14function summarize(course, prefix = "Course") {15  const label = typeof prefix === "number" ? "#" + prefix : prefix;16  return label + ": " + course.title + " (" + course.lessons + ")";17}18 19console.log(summarize({ title: "Types", lessons: 4, status: "published" }, 7));

Read it line by line:

• Lines 3 to 5 name the shape CourseCard: a string title and a number lessons.
• Line 6 adds an optional status. It can only be "draft" or "published".
• Line 10 says course must have the CourseCard shape.
• Line 11 says prefix is optional, and it can be a string or a number.
• Line 15 uses typeof to find out which one it got. A number such as 7 becomes "#7".
• Line 19 passes 7, so it prints #7: Types (4).

A union only lists what a value might be. Your code still has to check which one it is, as line 15 does.

Keep the item type with @template

A generic function works with many types and remembers which one it got. @template T makes a stand-in name, T, that means "whatever type the caller passes". Here, T is the type of the array's items. The function returns an item of that same type.

1// @ts-check2/**3 * @template T4 * @param {T[]} items5 * @returns {T | undefined}6 */7function first(items) {8  return items[0];9}10 11const firstName = first(["Ada", "Lin"]);12console.log(firstName);

Line 4 says items is an array of T. Line 11 passes an array of strings, so here T is string. The first item is Ada, so line 12 prints Ada.

Line 5 says the result is T | undefined. So the checker treats firstName as string | undefined. Why undefined? Because an array can be empty:

// @ts-check
/** @template T @param {T[]} items @returns {T | undefined} */
function first(items) {
  return items[0];
}
console.log(first([]) ?? "No items");

Line 6 calls first([]). Line 4 returns items[0], which is undefined for an empty array. The ?? operator gives a fallback value when the left side is undefined or null, so line 6 prints No items. The generic keeps the item type. It doesn't promise that an item exists.

Import a type without importing code

Sometimes a type is written in another file. TypeScript 5.5 added the JSDoc @import tag for this. It brings in a type name for your comments only. It loads no code at runtime.

An older way also works: write {import("./types").Course} inside the comment. @import is easier to read when several comments use the same type.

This example needs a second file, types.d.ts, where the type is written. The editor on this page can't check that file, so this block is for reading only.

1// @ts-check2/** @import {CourseFromTypes} from "./types" */3 4/** @type {CourseFromTypes} */5const importedCard = { title: "JSDoc", lessons: 2 };6 7console.log(importedCard.title);

Line 2 imports the type name CourseFromTypes. Line 4 uses it as the type of importedCard on line 5. Line 7 prints JSDoc.

You don't have to write every type. The checker can often work out a type by itself from the values. This is called inference. The panel below shows the types the real checker worked out for some of the examples in this lesson.

JSDoc comments help only when the checker is running. There are two ways to turn it on:

• For one file: put // @ts-check on the first line.
• For the whole project: set allowJs and checkJs to true in a jsconfig.json or tsconfig.json file.

Also set strict to true. It turns on extra checks for values that may be missing, such as undefined and null. It also makes the unknown type, which you'll meet later, much more useful.

Now the checker can catch withTax("3") before it prints 32. The JSDoc says price is a number, but that call gives it a string.

A warning in your editor is easy to miss. So also run tsc --noEmit in continuous integration (CI): the automatic checks that run on every change before it ships. tsc is the TypeScript checker, and --noEmit means "check only, don't write any files".

Avoid // @ts-nocheck. It turns off checking for the whole file. Use it only for a short time, while you fix the file.

1{2  "compilerOptions": {3    "allowJs": true,4    "checkJs": true,5    "strict": true,6    "noEmit": true7  },8  "include": ["src/**/*.js"]9}

Line 3 includes JavaScript files. Line 4 reports errors in them. Line 5 turns on the stricter checks.

An error message from the checker is called a diagnostic. Each one has a code such as TS2722, a line number, and a message. Pick an example below to see its real diagnostic.

1// @ts-check2/**3 * @typedef {{ title: string, onComplete?: () => void }} Lesson4 */5 6/** @param {Lesson} lesson */7function finishLesson(lesson) {8  lesson.onComplete();9}10 

The big change is when you find the mistake. Without a checker, the missing callback throws only at runtime. With a checker, TS2722 shows up in your editor before you open the browser. With a named object shape, the checker also catches a property name that looks right but doesn't exist, such as lessonCount.

TypeScript is JavaScript plus a way to write types in the code itself, plus a checker. Its files end in .ts. You write a type after a colon. This is called an annotation:

• const price: number = 3 gives a variable a type.
• function greet(user: User): string gives a parameter a type, and says the function returns a string.

You don't need to annotate everything. TypeScript works out many types from the values, as the checker did for JSDoc. There are two ways to give a type a name:

• A type alias can name any type: an object shape, or a union such as string | number.
• An interface names only an object shape. You can extend it later.

Many teams use both, and pick whichever reads more clearly.

type User = { name: string };
function greet(user: User): string {
  return "Hello, " + user.name;
}
console.log(greet({ name: "Asha" }));

Run this in a TypeScript project, not in this page's editor. Line 1 names the shape User: an object with a string name. Line 2 says greet takes a User and returns a string. Line 3 reads the name. Line 5 prints Hello, Asha.

Writing interface User { name: string } would name the same shape. But a union such as string | number needs a type alias.

The next example uses a union of three object shapes. Each shape has a status property with a different fixed value, so status tells the shapes apart. Narrowing means the checker learns more about a value from an if check. Inside the if, it knows which shape you have.

1type ApiState =2  | { status: "loading" }3  | { status: "ready"; user: { name: string } }4  | { status: "error"; message: string };5 6function label(state: ApiState) {7  if (state.status === "ready") {8    const readyState = state;9    return readyState.user.name.toUpperCase();10  }11  if ("message" in state) {12    return state.message;13  }14  return "Loading";15}16 17const result = label({ status: "ready", user: { name: "Ada" } });18console.log(result);

• Lines 1 to 4 say an ApiState is loading, ready, or error.
• Line 7 checks state.status === "ready". Inside this if, the checker knows it has the ready shape, so user exists.
• Line 11 checks "message" in state. The in operator asks: "does this object have a property with this name?" Only the error shape has message, so inside this if the checker knows it has the error shape.
• Line 17 passes a ready object, so line 18 prints ADA.

In the panel in the JSDoc section, press Add the TypeScript example. It shows the types the checker found for readyState and result. This lesson's test gets them from the real TypeScript checker, so they are not guesses.

Here is unknown in action. Line 2 reads payload.name without checking what payload is first, so the checker reports an error.

1function readName(payload: unknown) {2  return payload.name;3}4 

Here is a very common TypeScript error. Line 1 says lessons must be a number. Line 2 gives it the string "four", so the checker reports TS2322.

1type Course = { title: string; lessons: number };2const course: Course = { title: "Types", lessons: "four" };3 

A type assertion, written with as, tells the checker "trust me, this is a number". It doesn't change the value. In the next example the value stays a string at runtime.

const price = "3" as unknown as number;
console.log(price + 1);

In a TypeScript project, line 1 claims "3" is a number, but it stays the string "3". Line 2 joins text, so it prints 31, not 4. To really turn text into a number, use Number(price) and check that the result is a real number.

For example, Node 22.18+ can run the next .ts file directly. It removes : number from line 1. Then line 2 prints 4. Run it in Node, not in this page's editor.

const price: number = 3;
console.log(price + 1);

There is also a plan to add type syntax to JavaScript itself. TC39 is the group that designs JavaScript. Its Type Annotations proposal is at Stage 1, the earliest stage. The idea is like type stripping: JavaScript engines would skip type annotations as if they were comments, and separate tools would check them.

It would not support every TypeScript feature; enums, for example, are left out. It is only a proposal. You can't use it in browsers today.

The checker narrows types by reading your code. A runtime check, also called a validator, looks at the real data while the code runs. You need both where data comes into your code from outside:

• responses from fetch;
• text you read with JSON.parse;
• values saved in localStorage;
• URLs and form fields;
• messages from another window.

An API's documentation may promise a field, and the real data may still be missing it. So check the real value before you show a price:

const data = JSON.parse('{"title":"Tea"}');
const isOrder = typeof data === "object" && data !== null &&
  typeof data.title === "string" && typeof data.price === "number";
console.log(isOrder ? data.price : "Invalid order");

Line 1 reads data that has no price. Lines 2 and 3 check three things: data is an object, title is a string, and price is a number. The price is missing, so isOrder is false. Line 4 prints Invalid order.

Checking only that data is an object would not be enough. The price would still be missing when you show it.

Now step through a bigger validator. Pick good or broken data, and watch which branch runs.

1function isCourse(value) {Run2  return typeof value === "object" &&3    value !== null &&4    typeof value.title === "string" &&5    Array.isArray(value.lessons) &&6    value.lessons.every((lesson) => typeof lesson === "string");7}8 9const payload = JSON.parse('{"title":"Types for JS","lessons":["JSDoc","TypeScript"]}');10if (isCourse(payload)) {11  console.log(payload.title.toUpperCase());12} else {13  console.log("Invalid course data");14}

The guard is plain JavaScript. In TypeScript you can give it a special return type, value is CoursePayload. This is called a type predicate. It tells the checker: "if this function returns true, the value has the CoursePayload shape". So the same if protects users at runtime and teaches the checker.

How can a checker find a mistake without running the code? The toy checker below shows the idea. It reads the parameters a function expects and the arguments a call passes, then compares them.

1const signature = {Run2  name: "enroll",3  params: [4    { name: "student", type: "string" },5    { name: "lessons", type: "number" },6  ],7};8 9function checkCall(signature, args) {10  const errors = [];11  if (args.length !== signature.params.length) {12    errors.push(`Expected ${signature.params.length} arguments, got ${args.length}.`);13  }14  signature.params.forEach((param, index) => {15    if (index < args.length && typeof args[index] !== param.type) {16      errors.push(`${param.name} should be ${param.type}, got ${typeof args[index]}.`);17    }18  });19  return errors;20}21 22const report = checkCall(signature, ["Ada", "4"]);23console.log(report.join("\\n") || "Call matches the signature.");

The toy checker is tiny on purpose. It only counts arguments and compares typeof results. Real TypeScript does much more:

• it reads every file in the project;
• it reads .d.ts files;
• it follows imports;
• it follows if checks and early returns;
• it compares complex types.

The main idea is the same: it reports a bad call without running the function.

A declaration file ends in .d.ts. It describes types, but it holds no working code. TypeScript uses declaration files to understand:

• JavaScript packages;
• browser APIs, such as document;
• Node APIs;
• global variables;
• older scripts.

A declaration file only describes. If it is out of date, it can say something exists when it doesn't:

const widget = {};
console.log(typeof widget.mount);

Line 1 makes an empty widget. Line 2 prints undefined, even if a .d.ts file says mount exists. Keep declaration files in step with the package you installed. Test the real code too; don't trust a description that may be old.

Here is a small declaration file for an older widget module. The word declare means "this exists at runtime; I'm only describing it".

1declare module "legacy-widget" {2  export type WidgetOptions = {3    theme?: "light" | "dark";4    onClose?: () => void;5  };6 7  export function mount(target: Element, options?: WidgetOptions): void;8}

Line 1 describes a module named legacy-widget. Line 2 names the shape of its options. Line 7 describes the mount function. None of these lines make anything at runtime.

Each row of the next table is one word you'll meet around declaration files: the word, what it means, and where you see it.

A package can tell TypeScript where its declaration files are in two ways:

• a top-level types field in its package.json;
• a types path inside each entry of its exports field.

Some packages include no declaration files. Then a community project called DefinitelyTyped may publish them as a separate package whose name starts with @types/.

Make declaration files from JSDoc

TypeScript can also read JSDoc-typed JavaScript and write .d.ts files for you. Then people who use your JavaScript library get types too. This lesson's test does exactly that with the lesson's JSDoc code. It checks that the result matches the file shown below.

1{2  "compilerOptions": {3    "allowJs": true,4    "checkJs": true,5    "declaration": true,6    "emitDeclarationOnly": true,7    "outDir": "types"8  },9  "include": ["src/**/*.js"]10}

Line 4 checks the JavaScript files. Line 5 turns on declaration files. Line 6 writes only declaration files, with no JavaScript. Line 7 puts them in a folder named types.

1/**2 * @typedef {object} CourseSummary3 * @property {string} title4 * @property {number} lessons5 */6/**7 * @param {CourseSummary} course8 * @returns {string}9 */10export function formatCourse(course: CourseSummary): string;11export type CourseSummary = {12    title: string;13    lessons: number;14};15 

Line 10 is the function's type: it takes a CourseSummary and returns a string. Lines 11 to 14 turn the JSDoc @typedef into a TypeScript type. The JSDoc comments are kept above them.

Real teams rarely use types alone. Each tool has its own job:

• Types check calls and object shapes.
• Runtime checks protect data you don't control.
• A linter, a tool that checks code style and common slips, keeps the code tidy.
• Tests check that the program does the right thing.

Types are great at finding operations that can never work. Tests are great at showing that important features still work.

const data = JSON.parse('{"price":"3"}');
console.log(typeof data.price);

Line 1 reads data where the price is in quotes, so it is a string. Line 2 prints string, not number. Writing a type such as { price: number } for this data, or using as, can't change the data.

So check or convert the data where it enters your code. After that check, normal TypeScript types keep the rest of the app consistent.

A gentle way to add types to a JavaScript project:

• Start with // @ts-check in one risky JavaScript file.
• Add JSDoc where the checker can't work out a type, especially for function parameters.
• Move to .ts files when type syntax is easier to read than comments.
• Keep runtime checks for API data and user input, even after you move to TypeScript.

Common misconceptions

• “JSDoc always checks my JavaScript.” JSDoc is only comments until // @ts-check or checkJs tells TypeScript to read it.
• “TypeScript checks API data for me.” Types are removed before the code runs. Data from outside still needs a runtime check.
• “any is a quick fix.” Sometimes you need it where outside data comes in, but it also hides mistakes. Use unknown until you have checked the value.
• “A .d.ts file holds the module's code.” It only describes a module. The real code must exist at runtime.
• “If Node can run my TypeScript, my types are checked.” Node only removes the types. It doesn't check them.

The next table compares three kinds of tools. Each row asks the same question about all three.

Key takeaways

• Static type checking reads code before it runs. It turns many runtime crashes into warnings in your editor.
• JSDoc plus checkJs adds types to .js files without changing how they run.
• TypeScript adds annotations, inference, unions, narrowing, generics, and strict checks. Then the types are removed before the code runs.
• unknown makes you check outside data before you use it. any turns checking off for that value.
• Declaration files describe JavaScript that exists somewhere else. Runtime checks still protect data you don't control.

Up next: Runtimes, the places where JavaScript runs.