# DefaultState

Универсальный класс-обертка для стандартизированного представления состояния операций в приложениях. Реализует паттерн "состояние результата" с автоматическим отслеживанием временных меток и гибкой типизацией данных.

## Особенности

- **Генерализованный ответ**: Единый формат для успешных и ошибочных результатов операций
- **Автоматическое временное отслеживание**: Мета-информация о создании и обновлении состояния
- **Гибкая типизация**: Поддержка generic-типов для строгой типизации поля `data`
- **Булева семантика**: Возможность использования в условных выражениях через `__bool__`
- **Несколько способов инициализации**: Из словаря, ключевых аргументов или пустая инициализация
- **Цепочка вызовов**: Методы обновления возвращают `self` для fluent-интерфейса

## Быстрый старт

```python
from datetime import datetime
from typing import Optional
from your_module import DefaultState

# Создание пустого состояния
state = DefaultState()
print(state.result)  # False
print(state.status)  # INIT

# Обновление состояния
state.update(result=True, status="SUCCESS", detail="Operation completed")
print(bool(state))  # True

# Использование с типизированными данными
user_data = {"id": 1, "name": "John"}
user_state = DefaultState[dict]()
user_state.success(data=user_data, status="USER_FOUND")

# Проверка результата
if user_state:
    print(f"User: {user_state.data['name']}")
    print(f"Created: {user_state.created_dt}")
```

## API Reference

### `DefaultState` Class

Универсальный контейнер состояния операции.

#### `__init__(init_data: Optional[dict] = None, **kwargs) -> None`

Инициализирует объект состояния. Поддерживает три способа инициализации:

**Параметры:**
- `init_data` (Optional[dict]): Словарь с начальными значениями полей
- `**kwargs`: Ключевые аргументы для прямого присвоения полям

**Примеры:**
```python
# Из словаря
state1 = DefaultState({'result': True, 'status': 'OK'})

# Из ключевых аргументов  
state2 = DefaultState(result=False, status='ERROR', detail='Not found')

# Пустая инициализация
state3 = DefaultState()
```

## `update(result: bool = False, status: Optional[AllowedTypes] = None, detail: Optional[AllowedTypes] = None, data: Optional[T] = None) -> DefaultState[T]`

Обновляет указанные поля состояния и временную метку.

**Параметры:**
- `result` (bool): Результат операции (по умолчанию False)
- `status` (Optional[AllowedTypes]): Статус операции
- `detail` (Optional[AllowedTypes]): Детальное описание
- `data` (Optional[T]): Произвольные данные

**Возвращает:**
- `DefaultState[T]`: self для цепочки вызовов

**Пример:**
```python
state.update(result=True, status="PROCESSING", data={"progress": 50})
```

## `success(status: Optional[AllowedTypes] = None, detail: Optional[AllowedTypes] = None, data: Optional[T] = None) -> DefaultState[T]`

Специализированный метод для установки успешного результата.

**Параметры:**
- `status` (Optional[AllowedTypes]): Статус успешной операции
- `detail` (Optional[AllowedTypes]): Детальное описание
- `data` (Optional[T]): Произвольные данные

**Возвращает:**
- `DefaultState[T]`: self для цепочки вызовов

**Пример:**
```python
state.success(status="COMPLETED", detail="User created", data=user_id)
```

## `insert(data: dict) -> DefaultState[T]`

Алиас для `update()` с передачей словаря (обратная совместимость).

**Параметры:**
- `data` (dict): Словарь с данными для обновления

**Возвращает:**
- `DefaultState[T]`: self для цепочки вызовов

**Пример:**
```python
state.insert({"result": True, "status": "UPDATED"})
```

## `__bool__() -> bool`

Реализует булев контекст. Возвращает значение `result`.

**Возвращает:**
- `bool`: True если операция успешна

**Пример:**
```python
if state:
    # Действия при успешном результате
    process_data(state.data)
```

### Свойства

#### `result: Optional[bool]`
Основной результат операции (True/False).

#### `status: Optional[AllowedTypes]`
Краткий статус операции.

#### `detail: Optional[AllowedTypes]`  
Детальное описание результата или ошибки.

#### `data: Optional[T]`
Произвольные данные, возвращаемые операцией.

#### `created_at: int`
Тimestamp создания состояния (короткий доступ к `meta.created_at`).

#### `updated_at: int`
Timestamp последнего обновления (короткий доступ к `meta.updated_at`).

#### `created_dt: datetime`
Объект datetime создания состояния.

#### `updated_dt: datetime`
Объект datetime последнего обновления.

### `MetaState` Class

Вспомогательный класс для хранения мета-информации.

#### `created_at: int`
Timestamp создания состояния.

#### `updated_at: int`  
Timestamp последнего обновления.

## Конфигурация

Класс не требует внешней конфигурации. Все настройки задаются через параметры инициализации или методы обновления.


### Рекомендации

- Используйте `success()` для положительных сценариев.
- Не используйте `data` для передачи метаданных — лучше вынести в отдельные поля.
- При работе с JSON — убедитесь, что `data` сериализуемо.

---

💡 **Совет:** Этот класс отлично подходит для шаблонизации ответов в микросервисах, ETL-процессах, AI-обработчиках и CLI-утилитах.

---