В каких случаях оправдано использование JSDoc вместо полноценного TypeScript?

JSDoc — это способ описывать типы прямо в комментариях к JavaScript-коду. TypeScript умеет читать эти комментарии и проверять типы без переименования файлов в .ts. Это делает JSDoc удобным компромиссом, когда полноценная миграция на TypeScript невозможна или нецелесообразна.

Когда JSDoc оправдан

• Проект на чистом JavaScript, который нельзя быстро перевести на TypeScript (legacy, ограничения сборки, команда без опыта).
• Небольшие библиотеки и утилиты, где важна совместимость с JS-потребителями без шага компиляции.
• Скрипты, конфиги, инструменты сборки, где TypeScript избыточен.
• Постепенная миграция: сначала JSDoc, потом плавный переход на .ts.

Как это работает

Достаточно включить allowJs и checkJs в tsconfig.json, и TypeScript начнёт проверять JS-файлы, используя JSDoc-аннотации.

// tsconfig.json
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "noEmit": true
  }
}

// utils.js
/**
 * @param {string} name
 * @param {number} age
 * @returns {string}
 */
export function greet(name, age) {
  return `${name} is ${age}`;
}

greet(42, 'Bob'); // ошибка типов

Ограничения

JSDoc не покрывает все возможности TypeScript: сложные дженерики, условные типы, mapped types, декораторы описываются громоздко или не описываются вовсе. Синтаксис комментариев многословнее, а рефакторинг и автодополнение слабее, чем в .ts-файлах.

Итог: JSDoc стоит применять как лёгкий способ типизации в JS-проектах, для скриптов и при постепенной миграции; для крупной активной кодовой базы полноценный TypeScript обычно даёт больше выгоды.