TypeScript Server

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ

Разработчику Архитектору

Дальше: Компиляция · Экосистема · JS-курс: TypeScript Server

---

TypeScript Server (tsserver) — фоновый процесс, который питает языковые возможности редактора: подсветка ошибок, автодополнение, переход к определению, рефакторинг. Вы пользуетесь им каждый день в Cursor / VS Code, даже если редко запускаете tsc вручную.

Маршрут: Компиляция → tsserver → Экосистема.

Краткий указатель в JS-курсе — JS-курс: TypeScript Server. CLI tsc — 15.md.

---

tsc и tsserver: две роли одного компилятора

	tsc	tsserver
Запуск	терминал, CI	IDE в фоне
Цель	emit .js, проверка	подсказки, навигация
Когда	сборка, typecheck	при каждом изменении файла
Протокол	CLI	LSP / собственный TS-протокол

Оба используют один движок анализа TypeScript — расхождения версий между IDE и CI ломают доверие к подсветке.

---

Языковые службы (Language Services)

Под языковыми службами понимают API, через которые редактор получает completion, diagnostics, rename и рефакторинг. В экосистеме TypeScript это реализует tsserver (и обёртки вроде typescript-language-server поверх LSP). Ниже — что именно доступно из IDE.

---

Что делает tsserver

  Редактор (Cursor / VS Code)
        │  запросы: completion, definition, diagnostics
        ▼
   tsserver (фоновый процесс)
        │  читает tsconfig, строит граф проекта
        ▼
   Модель типов + AST в памяти

Возможность	Польза
Diagnostics	ошибки типов до tsc в терминале
Completion	поля и методы по типу
Go to Definition	переход к объявлению
Find All References	все использования символа
Rename Symbol	безопасное переименование
Quick Fix	предложения исправлений
Signature Help	параметры функции при вводе

Разбор:

• Сервер кэширует проект и инкрементально обновляет файлы при сохранении.
• В больших репозиториях нагрузка на CPU/RAM — нормальна; помогают project references — 3.md.

---

Language Server Protocol (LSP)

Современные редакторы общаются с языком через LSP: единый протокол для TypeScript, Rust, Go и др.

  Extension (TypeScript language features)
        ↔  LSP messages
  tsserver / typescript-language-server

Разбор:

• VS Code/Cursor поставляют расширение TypeScript and JavaScript Language Features.
• Альтернативы (typescript-language-server) тоже оборачивают тот же компилятор.

---

Версия TypeScript в workspace

В проекте должна использоваться локальная версия из node_modules:

1. Command Palette → TypeScript: Select TypeScript Version.
2. Выберите Use Workspace Version.

Разбор:

• Глобальный TS 5.8 в IDE и 5.4 в package.json дадут разные ошибки на CI.
• В package.json фиксируйте "typescript": "~5.7.0" (пример) и обновляйте осознанно.

---

Как tsserver видит проект

Сервер читает tsconfig.json (или jsconfig.json для JS):

{
  "compilerOptions": {
    "strict": true,
    "module": "NodeNext"
  },
  "include": ["src/**/*"],
  "exclude": ["dist", "node_modules"]
}

Ситуация	Поведение
Файл вне include	слабая проверка или isolated-режим
Несколько tsconfig	отдельные проекты в монорепо
references	загрузка зависимых пакетов по графу

Подробнее — 9.md, 3.md.

---

Inferred type и подсказки

Наведите курсор на переменную — IDE показывает inferred type:

const config = {
  retries: 3,
  timeoutMs: 5000,
};
// inferred: { retries: number; timeoutMs: number }

Подсказка строится тем же анализом, что и проверка присваиваний. Запись as const сузит вывод — см. 10.md.

---

Рефакторинг через IDE

Действие	Что проверяет TS
Rename Symbol	все ссылки в проекте
Organize Imports	неиспользуемые и порядок
Extract function	типы параметров и возврата

Перед массовым rename в git убедитесь, что нет несохранённых файлов и tsc --noEmit зелёный.

---

Ограничения и расхождения с CI

Ситуация	Почему
IDE молчит, CI падает	другая версия TS, другой tsconfig
Ошибка только в IDE	файл не в include CI
Медленные подсказки	весь монорепо без references
any в .js	checkJs: false

Рекомендация: в CI всегда tsc --noEmit или tsc -b — 6.md, 3.md.

---

tsserver и JavaScript

В .js файлах при allowJs / checkJs сервер тоже анализирует типы (JSDoc или вывод). Это помогает постепенной миграции — 6.md.

---

Отладка проблем с языковым сервисом

1. Перезапуск TS server: TypeScript: Restart TS Server.
2. Проверить workspace version.
3. Открыть Output → TypeScript — лог запросов.
4. Убедиться, что один корневой tsconfig (или solution-style references).

---

Частые ошибки

Ошибка	Причина	Что делать
Подсказки устарели	кэш tsserver	Restart TS Server
Разные ошибки IDE и CI	версия TS	workspace version + lockfile
Файл не в проекте	нет в include	поправить tsconfig
Rename сломал сборку	символ из .d.ts	искать re-exports
Тормоза в монорепо	один огромный project	composite + references

---

Расширение TypeScript (для авторов инструментов)

Обычной разработке достаточно tsc и IDE. Расширение языка — когда пишут линтеры, кодогенераторы, плагины сборки или кастомные IDE-фичи поверх того же движка, что и tsserver.

API	Назначение
Compiler API (typescript npm)	AST, проверка, emit, кастомные трансформеры
Language Service API	completion, rename, find references — основа tsserver
Transformer plugins	изменение AST при компиляции (осторожно с поддержкой)

import * as ts from "typescript";

const source = `const x: number = "oops";`;
const file = ts.createSourceFile(
  "tmp.ts",
  source,
  ts.ScriptTarget.Latest,
  true,
);
const program = ts.createProgram({ rootNames: ["tmp.ts"], options: {} });
// далее — getSemanticDiagnostics(program) и т.д.

Типичные потребители:

• @typescript-eslint — правила поверх AST/типов;
• ts-morph, typescript-eslint — обход и правки кода;
• Angular compiler, Nest CLI — доменные трансформации;
• обёртки Babel / SWC с TS-синтаксисом (без полного typecheck).

Для прикладного backend/frontend этот уровень не обязателен — достаточно 15.md и workspace tsserver. Таблицы и ссылки — Справочник — расширение TypeScript.

---

Практика

1. Откройте 4.md проект и посмотрите inferred type у greet.
2. Выполните Rename Symbol для функции — проверьте импорты.
3. Намеренно сломайте тип и примените Quick Fix, если доступен.
4. Переключите TS version на workspace и сравните диагностику.
5. Добавьте tsc --noEmit в CI и сравните с подсветкой IDE.

---

Смежные статьи

• Компиляция — emit, source maps
• Экосистема — monorepo, CI
• Подключение — tsconfig
• Рекомендации — strict, миграция
• Справочник — 30, Справочник — инструменты и CLI