JSDoc to Typescript Cheatsheet

Arguments and return type

/**
 * @param {number} a
 * @param {number} b
 *
 * @returns {number}
 */
function sum(a, b) {
  return a + b
}

function sum(a: number, b: number): number

Async function with return value

/**
 * @param {number} a
 * @param {number} b
 *
 * @returns {Promise<number>}
 */
async function sum(a, b) {
  return a + b
}

function sum(
  a: number,
  b: number,
): Promise<number>

Async function with no return value

/**
 * @param {String} environment
 *
 * @returns {Promise}
 */
async function startLogger(environment) {
  if (environment === "production") {
    await startProductionLogger()
  } else {
    await startDevelopmentLogger()
  }
}

function startLogger(
  environment: string,
): Promise<any>

String union argument

/**
 * @param {'production' | 'development'} environment
 *
 * @returns {Promise}
 */
async function startLogger(environment) {
  if (environment === "production") {
    await startProductionLogger()
  } else {
    await startDevelopmentLogger()
  }
}

function startLogger(
  environment: "production" | "development",
): Promise<any>

Destructured argument

/**
 * @param {Object} obj
 * @param {number} obj.a
 * @param {number} obj.b
 *
 * @returns {number}
 */
function sum({ a, b }) {
  return a + b
}

function sum({
  a,
  b,
}: {
  a: number
  b: number
}): number

Declaring a typedef for reusable types

/**
 * @typedef Pair
 * @property {number} a
 * @property {number} b
 */
 
/**
 * @param {Pair} obj
 *
 * @returns {number}
 */
function sum({ a, b }) {
  return a + b
}

type Pair = {
  a: number
  b: number
}
 
function sum({ a, b }: Pair): number

Typedefs in argument and return type

/**
 * @typedef Auth
 * @property {string} username
 * @property {string} password
 */
 
/**
 * @typedef Token
 * @property {String} access_token
 */
 
/**
 * @param {Auth} auth
 *
 * @returns {Promise<Token>}
 */
function login(auth) {
  return authenticateWithThirdPartyService(auth)
}

type Auth = {
  username: string
  password: string
}
 
type Token = {
  access_token: string
}
 
function login(auth: Auth): Promise<Token>

Importing type from external TS file

export type Auth = {
  username: string
  password: string
}

Aliased for reusability

/**
 * @typedef { import('@/app/login').Auth } Auth
 */
 
/**
 * @param {Auth} auth
 *
 * @returns {Promise<Token>}
 */
function login(auth) {
  return authenticateWithThirdPartyService(auth)
}

Inline for single use

/**
 * @param {import('@/app/login').Auth} auth
 *
 * @returns {Promise<Token>}
 */
function login(auth) {
  return authenticateWithThirdPartyService(auth)
}

Type parameters

/**
 * @template T
 * @template U
 *
 * @param {Record<T, U>} input
 * @returns {Record<U, T>}
 */
function reverseRecord(input) {
  const entries = Object.entries(input).map(
    ([key, value]) => [value, key],
  )
 
  return Object.fromEntries(entries)
}

function reverseRecord<T, U>(
  input: Record<T, U>,
): Record<U, T>

Type parameters with constraints

/**
 * @template {PropertyKey} T
 * @template {PropertyKey} U
 *
 * @param {Record<T, U>} input
 * @returns {Record<U, T>}
 */
function reverseRecord(input) {
  const entries = Object.entries(input).map(
    ([key, value]) => [value, key],
  )
 
  return Object.fromEntries(entries)
}

function reverseRecord<
  T extends PropertyKey,
  U extends PropertyKey,
>(input: Record<T, U>): Record<U, T>