TypeScript in JavaScript Projects (JSDoc)

Getting Started

Enable checkJs or use

// @ts - check in individual files

Example: JSDoc for Type Safety

// @ts - check

* @param {number} a
* @param {number} b
* @returns {number}

function add(a, b) {
return a + b;
}

Objects and Interfaces

Inline Object Types

// @ts - check

function greet(person) {
return `Hello, ${person.firstName} ${person.lastName}`;
}
greet({ firstName: 'John', lastName: 'Doe' }); // OK
greet({ firstName: 'Jane' }); // Error: Property 'lastName' is missing

// @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 {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 Types

Function Declarations

// @ts - check

* @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

* @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

* @param {string} a
* @param {string} b
* @returns {string}

* @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

Advanced Types

Union and Intersection Types

// @ts - check

/** @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

* @typedef {[K in keyof T]: T[K] extends Function ? K : never}[keyof T] MethodNames

* @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

Type Imports

Importing Types from Other Files

// @ts - check

/** @typedef {import('./types').User} User */

/** @typedef {import('express').Request} ExpressRequest */

/** @typedef {import('./api').default as ApiClient} ApiClient */

Creating Declaration Files

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

Best Practices

Enable

// @ts - check at the top of files where you want type checking

Use

Document all function parameters and return types

Use

) for third - party libraries without types

Use

@ts - expect - error instead of
@ts - ignore when you expect an error

Common Pitfalls