TypeScript in JavaScript Projects (JSDoc)

Example: JSDoc for Type Safety

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

Inline Object Types

// @ts-check /** * @param {{ firstName: string, lastName: string, age?: number }} person */
function greet(person) {
  return `Hello, ${person.firstName} ${person.lastName}`;
}
greet({ firstName: 'John', lastName: 'Doe' }); // OK
greet({ firstName: 'Jane' }); // Error: Property 'lastName' is missing

Using @typedef for Complex Types

// @ts-check /** * @typedef {Object} User * @property {number} id - The user ID * @property {string} username - The username * @property {string} [email] - Optional email address * @property {('admin'|'user'|'guest')} role - User role * @property {() => string} getFullName - Method that returns full name */
/** @type {User} */
const currentUser = {
  id: 1, username: 'johndoe', role: 'admin', getFullName() {
    return 'John Doe';
  }
};
// TypeScript will provide autocomplete for User properties console.log(currentUser.role);

Extending Types

// @ts-check /** @typedef {{ x: number, y: number }} Point */
/** * @typedef {Point & { z: number }} Point3D
*/
/** @type {Point3D} */
const point3d = { x: 1, y: 2, z: 3 };
// @ts-expect-error - missing z property
const point2d = { x: 1, y: 2 };

Function Declarations

// @ts-check /** * Calculates the area of a rectangle * @param {number} width - The width of the rectangle * @param {number} height - The height of the rectangle * @returns {number} The calculated area */
function calculateArea(width, height) {
  return width * height;
}
// TypeScript knows the parameter and return types
const area = calculateArea(10, 20);

Function Expressions and Callbacks

// @ts-check /** * @callback StringProcessor * @param {string} input * @returns {string} */
/** * @type {StringProcessor}
*/
const toUpperCase = (str) => str.toUpperCase();
/** * @param {string[]} strings
* @param {StringProcessor} processor
* @returns {string[]}
*/
function processStrings(strings, processor) {
  return strings.map(processor);
}
const result = processStrings(['hello', 'world'], toUpperCase);
// result will be ['HELLO', 'WORLD']

Function Overloads

// @ts-check /** * @overload * @param {string} a * @param {string} b * @returns {string} */
/** * @overload
* @param {number} a
* @param {number} b
* @returns {number}
*/
/** * @param {string | number} a
* @param {string | number} b
* @returns {string | number}
*/
function add(a, b) {
  if (typeof a === 'string' || typeof b === 'string') {
    return String(a) + String(b);
  }
return a + b;
}
const strResult = add('Hello, ', 'World!'); // string
const numResult = add(10, 20);             // number

Union and Intersection Types

// @ts-check /** @typedef {{ name: string, age: number }} Person */
/** @typedef {Person & { employeeId: string }} Employee */
/** @typedef {Person | { guestId: string, visitDate: Date }} Visitor */
/** @type {Employee} */
const employee = {
  name: 'Alice', age: 30, employeeId: 'E123'
};
/** @type {Visitor} */
const guest = {
  guestId: 'G456', visitDate: new Date()
};
/** * @param {Visitor} visitor
* @returns {string}
*/
function getVisitorId(visitor) {
  if ('guestId' in visitor) {
    return visitor.guestId;  // TypeScript knows this is a guest
  }
return visitor.name;      // TypeScript knows this is a Person
}

Mapped and Conditional Types

// @ts-check /** * @template T * @typedef {[K in keyof T]: T[K] extends Function ? K : never}[keyof T] MethodNames */
/** * @template T
* @typedef {{
    *   [K in keyof T as `get${'<' }Capitalize<string & K>{'>'}`]: () => T[K]
    * }} Getters
*/
/** @type {Getters<{ name: string, age: number }> } */
const userGetters = {
  getName: () => 'John', getAge: () => 30
};
// TypeScript enforces the return types
const name = userGetters.getName(); // string
const age = userGetters.getAge();   // number

// @ts-check
// Importing types from TypeScript files
/** @typedef {import('./types').User} User */
// Importing types from node_modules
/** @typedef {import('express').Request} ExpressRequest */
// Importing with renaming
/** @typedef {import('./api').default as ApiClient} ApiClient */

// types.d.ts
declare module 'my-module' {
 export interface Config {
 apiKey: string;
 timeout?: number;
 retries?: number;
 }
 export function initialize(config: Config): void;
 export function fetchData<T = any>(url: string): Promise<T>;
}

// @ts-check
/** @type {import('my-module').Config} */
const config = {
 apiKey: '12345',
 timeout: 5000
};
// TypeScript will provide autocomplete and type checking
import { initialize } from 'my-module';
initialize(config);