Types for JavaScript: JSDoc & TypeScript

Catch type mistakes before users do

JavaScript is dynamically typed: values carry their type at runtime, and variables can hold different kinds of values over time. That flexibility is powerful, but it allows bugs such as a misspelled property, a missing callback, or undefined is not a function to wait until a user clicks the unlucky path.

This lesson connects back to data types, checking types, and type coercion. Runtime JavaScript still uses typeof, Array.isArray, truthiness, and guards. The new tool is a checker that can warn before the runtime has a chance to fail.

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

A dynamic typing recap matters because it tells you where static types fit. They are not a replacement for functions, objects, linting, development environment setup, or transpilers and polyfills. They are one more feedback loop: fast, local, and focused on shapes.

JSDoc is the gentlest path for a JavaScript codebase. You keep .js files and add comments that TypeScript-powered editors understand. The comments are ignored by the JavaScript runtime, but // @ts-check or project-wide checkJs lets the checker use them.

Object shapes, optional values, defaults, and unions

The next example declares a reusable CourseCard object shape with @typedef and @property. Square brackets make status optional and document its default. The prefix parameter accepts a string | number union, so the function narrows it with typeof.

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 the code line by line: the typedef names the object, each property adds a field, the function receives that named shape, and the body uses a normal runtime typeof check because unions describe possibilities, not decisions.

Generics with @template

Generic JSDoc lets one helper keep the type of the values it receives. Here @template T says “whatever item type the caller passes, use the same item type for the return.” The real inferred type displayed later is string | undefined, because arrays can be empty.

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);

Importing types without importing runtime code

TypeScript 5.5 added a JSDoc @import tag. It brings type names into comments without creating a runtime import. You can still use the older inline form {import("./types").Course}, but @import reads more like normal imports when several annotations share a type.

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

A JSDoc comment becomes a safety net only when the checker is running. Put // @ts-check at the top of one file for a local opt-in, or set allowJs and checkJs in a jsconfig.json or tsconfig.json for the project. strict makes optional values, unknown, and nullish flows much more useful.

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

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

The important shift is timing. Without checking, the optional callback example waits until runtime to throw. With checking, TS2722 is an editor squiggle before you open the browser. With object shapes, the checker can also catch a property that looks plausible but does not exist.

TypeScript is JavaScript plus type syntax and a compiler. You can annotate variables, parameters, returns, and object shapes; you also get inference, so many types are learned from values. A type alias can name any type expression, while an interface names an object shape and can be extended or merged. Teams often use both, choosing the clearer one for the job.

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);

The union says ApiState can be loading, ready, or error. The check state.status === "ready" narrows to the ready variant. The "message" in state branch narrows to the error variant. The lesson test asks TypeScript for the type of readyState and result, so the displayed inferred types are not guesses.

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

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

The TC39 Type Annotations proposal is currently Stage 1. Its goal is similar in spirit to type stripping: JavaScript engines would treat compatible annotations as comments while external tools check them. It is a proposal, not a browser feature you can rely on today.

Type checkers narrow values by reading your code. Runtime validators narrow values by actually inspecting data. You need both at trust boundaries: fetch, JSON.parse, localStorage, URLs, forms, and messages from another window.

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 ordinary JavaScript. In TypeScript you would annotate it as a type predicate, such as value is CoursePayload, so the checker learns from the same runtime branch that protects users.

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 intentionally small. Real TypeScript builds a full program, reads declarations, follows imports, understands control flow, and compares rich types. The toy version still makes the core idea concrete: it can report a bad call without running the function being called.

A declaration file, ending in .d.ts, describes types without providing the implementation. It is how TypeScript understands many JavaScript packages, browser APIs, Node APIs, globals, and legacy scripts.

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}

Packages can point at declarations with a top-level types field, or with exports entries that include a types path for each public export. If a package does not ship declarations, DefinitelyTyped may publish a matching @types package.

Generating declarations from JSDoc

JSDoc is not only for editors. TypeScript can read checked JavaScript and emit declaration files for library consumers. The test for this lesson asks TypeScript to emit the declaration below from the lesson’s JSDoc source and compares it to the stored text.

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

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 

In real teams, the answer is rarely “types only.” Use types for call shapes and object contracts, runtime validation for data you do not control, linting for consistency, and tests for behavior. Type systems are excellent at finding impossible operations; tests are excellent at proving important stories still work.

• Start with // @ts-check on a risky JavaScript file.
• Add JSDoc where inference cannot see enough, especially function boundaries.
• Move to .ts when type syntax is clearer than comments.
• Keep validators at API and user-input boundaries even after migration.

Common misconceptions

• “JSDoc always checks my JavaScript.” JSDoc is just comments until // @ts-check or checkJs asks TypeScript to read it.
• “TypeScript validates API data for me.” Types are erased. External data still needs runtime validation.
• “any is a convenient fix.” It is sometimes necessary at a boundary, but it also hides mistakes. Prefer unknown until you narrow.
• “A .d.ts file implements a module.” It only describes a module that must exist at runtime.
• “Node stripping TypeScript means TypeScript is checked.” Type stripping removes erasable syntax; it does not run the compiler’s type analysis.

Key takeaways

• Static type checking reads code before running it; it turns many runtime crashes into editor feedback.
• JSDoc plus checkJs brings types to JavaScript files without changing runtime syntax.
• TypeScript adds annotations, inference, unions, narrowing, generics, and strict checking, then erases types.
• unknown keeps external data honest; any turns checking off for that value.
• Declaration files describe JavaScript APIs, and runtime validation still protects untrusted data.

Up next: Runtimes.