tsconfig.tsbuildinfo

Обзор

Файл tsconfig.tsbuildinfo представляет собой промежуточный (информационный) файл, который генерируется компилятором TypeScript при использовании опции Incremental Compilation. Его основная задача — хранить метаданные о предыдущей компиляции проекта, чтобы ускорить следующие сборки путём инкрементального пересчёта только изменённых файлов.

Данный файл содержит сериализованные данные в формате JSON, в частности список файлов проекта с их версиями и идентификаторами, а также информацию о зависимостях и состоянии компиляции.

Детальное описание содержимого

Файл не содержит классов, функций или методов в традиционном понимании исходного кода, так как это не исполняемый модуль, а скорее технический артефакт сборочного процесса TypeScript. Однако можно выделить основные структурные элементы данных:

• fileNames — массив строк, содержащий пути к исходным файлам TypeScript и декларациям .d.ts, которые были включены в текущий проект.

• fileIdsList — массив массивов чисел, где каждый вложенный массив соответствует списку идентификаторов файлов, используемых в различных частях проекта.

• fileInfos — массив объектов, каждый из которых содержит информацию о состоянии конкретного файла:

  • version — хэш-сумма или версия файла, отражающая текущее состояние содержимого.

  • affectsGlobalScope — булево значение, показывающее влияет ли файл на глобальную область видимости.

  • impliedFormat — числовой код, обозначающий формат файла (например, TS, JS, JSON).

• referencedMap — массив связей между файлами, показывающий какие файлы ссылаются на какие.

• semanticDiagnosticsPerFile — информация о диагностике ошибок по отдельным файлам.

• affectedFilesPendingEmit — список файлов, которые подлежат повторной эмиссии при следующей компиляции.

• version — версия компилятора TypeScript, которая создала данный файл.

Важные особенности и алгоритмы

• Инкрементальная компиляция: благодаря сохранению информации о версиях файлов и связях между ними компилятор может эффективно определять, какие части проекта нужно пересобирать, а какие нет, что значительно ускоряет процесс сборки крупных проектов.

• Кэширование состояния: файл выступает в роли кэша, позволяя избежать полной повторной компиляции без необходимости анализировать весь исходный код.

• Диагностика и отслеживание ошибок: часть данных используется для хранения диагностической информации, что помогает в отслеживании ошибок и предупреждений в процессе разработки.

Взаимодействие с системой

• Генерируется и обновляется компилятором TypeScript (tsc) при настройке параметра incremental в tsconfig.json.

• Используется самим компилятором для оптимизации последующих сборок.

• Не предназначен для ручного редактирования или чтения пользователем.

• Обычно хранится в рабочей директории проекта рядом с tsconfig.json.

• Может влиять на работу систем сборки, CI/CD и IDE, которые опираются на инкрементальную компиляцию TypeScript.

Пример использования (пояснительный)

В tsconfig.json проекта может быть включена опция:

{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": "./buildcache/tsconfig.tsbuildinfo"
  }
}

После первой компиляции TypeScript создаст файл tsconfig.tsbuildinfo в указанной папке buildcache. При последующих сборках компилятор будет использовать этот файл для быстрого определения изменённых модулей и минимизации времени компиляции.

Визуальное представление структуры файла

Файл является структурой данных, где основными элементами являются списки файлов и взаимосвязей. Ниже приведена схема в формате Mermaid flowchart, иллюстрирующая ключевые части файла и их взаимосвязи:

flowchart TD
    TSBuildInfo["tsconfig.tsbuildinfo (JSON)"]
    FileNames["fileNames: список путей к файлам"]
    FileInfos["fileInfos: версии и метаданные файлов"]
    FileIds["fileIdsList: идентификаторы файлов"]
    RefMap["referencedMap: зависимости между файлами"]
    Diagnostics["semanticDiagnosticsPerFile: диагностика"]
    PendingEmit["affectedFilesPendingEmit: файлы для компиляции"]
    Version["version: версия компилятора"]

    TSBuildInfo --> FileNames
    TSBuildInfo --> FileIds
    TSBuildInfo --> FileInfos
    TSBuildInfo --> RefMap
    TSBuildInfo --> Diagnostics
    TSBuildInfo --> PendingEmit
    TSBuildInfo --> Version

Резюме

• tsconfig.tsbuildinfo — служебный файл TypeScript для инкрементальной компиляции.

• Хранит метаданные о файлах проекта, их версиях и зависимостях.

• Позволяет ускорить повторные сборки, анализируя только изменённые части.

• Не является исходным кодом и не содержит классов или функций.

• Генерируется и используется исключительно TypeScript-компилятором.

Данное понимание важно для разработчиков и инженеров сборки, желающих оптимизировать процесс сборки своих TypeScript-проектов.