Стиль кодирования

Назначение

Этот гайд фиксирует соглашения по кодированию, которые последовательно используются в кодовой базе Nrgy.js.

Общая информация

Репозиторий представляет собой строгий TypeScript-монорепозиторий с небольшими сфокусированными модулями, colocated-тестами и явными runtime-контрактами. Стиль намеренно консервативный: простые функции, явные типы там, где это важно, и минимум лишних слоев абстракции.

Язык и типизация

• Используйте TypeScript в режиме strict.
• Для публичного API предпочитайте именованные экспорты.
• Держите generic-типы рядом с экспортируемым контрактом и избегайте лишней типовой косвенности.
• Используйте overload'ы, когда у runtime API есть явно разные сигнатуры вызова.
• Для повторно используемых контрактов публикуйте явные типы: контексты, атомы, опции.

Структура модулей

• Делайте модули сфокусированными на одной основной ответственности.
• Размещайте документацию модуля рядом с исходным файлом.
• Не создавайте отдельную документацию для index.ts; используйте пакетный README.md.
• Держите тесты рядом с реализацией в файлах *.test.ts или *.test.tsx.

Стиль runtime-кода

• Предпочитайте небольшие чистые helper-функции крупным изменяемым классам, если lifecycle-state не является основной задачей.
• Используйте комментарии редко и только там, где реализация иначе плохо читается.
• Старайтесь делать очистку ресурсов предсказуемой через destroy(), unsubscribe() и Scope.
• Сохраняйте framework-agnostic границы в @nrgyjs/core.

Форматирование

• Следуйте .editorconfig и текущей конфигурации форматирования.
• Используйте отступ в два пробела.
• Сохраняйте точки с запятой и trailing commas.
• В TypeScript предпочитайте одинарные кавычки.
• В Markdown переносите длинный текст на читаемую ширину строки.

Тестирование

• Используйте Vitest для unit-тестов.
• Формулируйте тесты вокруг наблюдаемого поведения, а не деталей реализации.
• Покрывайте lifecycle-границы, уничтожение ресурсов и распространение ошибок, если это релевантно.

Документация

• Поддерживайте английские .md и русские .ru.md версии исходной документации.
• Держите README-ссылки синхронизированными с реальным расположением файлов.
• Следите, чтобы примеры концептуально соответствовали текущему публичному API.