sync

OLD_parts/8-typing.md

@@ -0,0 +1,187 @@
+---
+title: Типизация
+---
+
+# Типизация
+
+## Общие правила типизации
+
+> Данный раздел определяет единые требования к типизации для всего проекта. Соблюдение этих правил обеспечивает читаемость, предсказуемость и безопасность кода.
+
+- Использовать только строгую типизацию TypeScript для всех файлов логики, компонентов, хуков, API, сторов и утилит.
+- Всегда явно указывать типы для:
+  - Пропсов компонентов
+  - Параметров функций и методов
+  - Возвращаемых значений функций и методов
+  - Всех переменных состояния (в том числе в store)
+  - Всех значимых переменных и констант, если их тип не очевиден из присваивания
+- Не использовать `any` и `unknown` без крайней необходимости. Если использование неизбежно — обязательно добавить комментарий с обоснованием.
+- Все интерфейсы, типы и enum всегда размещать в папке `types/` на своём уровне абстракции (например, `features/todo/types/`).
+- Для DTO всегда использовать отдельную папку `dto/` на уровне сущности или слоя.
+- Для сложных структур использовать отдельные интерфейсы или типы, размещая их в соответствующих файлах в папке `types/`.
+- Для DTO, enum, схем и других сущностей — всегда создавать отдельные типы/интерфейсы с осмысленными именами.
+- Ключи enum всегда писать ЗАГЛАВНЫМИ_БУКВАМИ (SCREAMING_SNAKE_CASE).
+- Не использовать неявное приведение типов и не полагаться на автоматический вывод, если это может снизить читаемость или безопасность.
+- Для массивов и объектов всегда указывать тип элементов/ключей.
+- Для возвращаемых значений асинхронных функций всегда указывать тип Promise.
+- Типизацию коллбеков и функций, передаваемых в пропсы, указывать инлайн, не выносить в отдельные типы.
+- Для типизации внешних библиотек использовать официальные типы или создавать собственные декларации при необходимости.
+- Не использовать устаревшие или не рекомендуемые паттерны типизации (например, `Function`, `Object`, `{}`).
+---
+
+### Примеры
+
+#### Интерфейс и типы для сущностей (всегда в папке types/)
+
+```ts
+// features/todo/types/todo-item.interface.ts
+
+/**
+ * Интерфейс задачи.
+ */
+export interface TodoItem {
+  /** Уникальный идентификатор задачи. */
+  id: string;
+  /** Текст задачи. */
+  text: string;
+  /** Статус выполнения задачи. */
+  completed: boolean;
+}
+```
+
+#### Типизация enum (всегда в папке types/)
+
+```ts
+// features/todo/types/todo-status.enum.ts
+
+/**
+ * Перечисление статусов задачи.
+ */
+export enum TodoStatus {
+  /** Активная задача. */
+  ACTIVE = 'active',
+  /** Выполненная задача. */
+  COMPLETED = 'completed',
+}
+```
+
+#### Типизация пропсов компонента
+
+```ts
+import { FC, memo } from 'react';
+import { TodoItem } from './types/todo-item.interface';
+
+/**
+ * Список задач.
+ */
+export interface TodoListProps {
+  /** Массив задач. */
+  items: TodoItem[];
+}
+
+export const TodoList: FC<TodoListProps> = memo(({ items }) => (
+  <ul>
+    {items.map((item) => (
+      <li key={item.id}>{item.text}</li>
+    ))}
+  </ul>
+));
+```
+
+#### Типизация функций и коллбеков (инлайн)
+
+```ts
+/**
+ * Функция фильтрации задач.
+ */
+export const getCompletedTodos = (items: TodoItem[]): TodoItem[] => {
+  return items.filter((t) => t.completed);
+};
+
+/**
+ * Колбэк для обработки клика (инлайн).
+ */
+const handleClick = (id: string): void => {
+  console.log('Clicked:', id);
+};
+```
+
+#### Типизация асинхронных функций
+
+```ts
+/**
+ * Получить задачи с сервера.
+ */
+export const fetchTodos = async (): Promise<TodoItem[]> => {
+  const response = await fetch('/api/todos');
+  return response.json();
+};
+```
+
+#### Типизация состояния в store (интерфейс в types/)
+
+```ts
+// features/todo/types/todo-store.interface.ts
+
+/**
+ * Состояние хранилища задач.
+ */
+export interface TodoStoreState {
+  /** Массив задач. */
+  items: TodoItem[];
+  /** Добавить задачу. */
+  addTodo: (item: TodoItem) => void;
+  /** Удалить задачу. */
+  removeTodo: (id: string) => void;
+}
+```
+
+#### Типизация DTO (всегда в папке dto/)
+
+```ts
+// features/todo/dto/create-todo.dto.ts
+
+/**
+ * DTO для создания задачи.
+ */
+export interface CreateTodoDto {
+  /** Текст задачи. */
+  text: string;
+}
+
+// features/todo/dto/todo-response.dto.ts
+
+/**
+ * DTO ответа сервера.
+ */
+export interface TodoResponseDto {
+  /** Созданная задача. */
+  todo: TodoItem;
+}
+```
+
+#### Типизация внешних библиотек
+
+```ts
+import type { AxiosResponse } from 'axios';
+
+export const getData = async (): Promise<AxiosResponse<TodoItem[]>> => {
+  // ...
+};
+```
+### Чек-лист проверки типизации
+
+- [ ] Все пропсы компонентов явно типизированы через интерфейс или тип в папке `types/`.
+- [ ] Все параметры и возвращаемые значения функций и методов явно типизированы.
+- [ ] Все переменные состояния (в том числе в store) имеют явные типы.
+- [ ] Все интерфейсы, типы и enum размещены в папке `types/` на своём уровне абстракции.
+- [ ] Ключи всех enum написаны ЗАГЛАВНЫМИ_БУКВАМИ (SCREAMING_SNAKE_CASE).
+- [ ] Все DTO размещены в папке `dto/` на своём уровне абстракции.
+- [ ] Не используется `any` и `unknown` без крайней необходимости и поясняющего комментария.
+- [ ] Для сложных структур используются отдельные интерфейсы или типы.
+- [ ] Для массивов и объектов указан тип элементов/ключей.
+- [ ] Для асинхронных функций указан тип Promise с конкретным типом результата.
+- [ ] Типы коллбеков и функций, передаваемых в пропсы, указаны инлайн.
+- [ ] Не используются устаревшие типы (`Function`, `Object`, `{}`).
+- [ ] Для внешних библиотек используются официальные типы или собственные декларации.
+- [ ] Нет неявного приведения типов, все типы читаемы и прозрачны.