"""Shared types and constants used across multiple model modules.

This module defines types and constants that are used by multiple
model modules, ensuring a single source of truth for cross-model types.
"""

import math
from typing import Literal

#: The four supported time-range presets for the dashboard views.
TimeRange = Literal["24h", "7d", "30d", "365d"]

#: Number of seconds represented by each preset.
TIME_RANGE_SECONDS: dict[str, int] = {
    "24h": 24 * 3600,
    "7d": 7 * 24 * 3600,
    "30d": 30 * 24 * 3600,
    "365d": 365 * 24 * 3600,
}

#: Bucket size in seconds for each time-range preset.
BUCKET_SECONDS: dict[str, int] = {
    "24h": 3_600,          # 1 hour  → 24 buckets
    "7d": 6 * 3_600,       # 6 hours → 28 buckets
    "30d": 86_400,         # 1 day   → 30 buckets
    "365d": 7 * 86_400,    # 7 days  → ~53 buckets
}

#: Human-readable bucket size label for each time-range preset.
BUCKET_SIZE_LABEL: dict[str, str] = {
    "24h": "1h",
    "7d": "6h",
    "30d": "1d",
    "365d": "7d",
}


def bucket_count(range_: TimeRange) -> int:
    """Return the number of buckets needed to cover *range_* completely.

    Args:
        range_: One of the supported time-range presets.

    Returns:
        Ceiling division of the range duration by the bucket size so that
        the last bucket is included even when the window is not an exact
        multiple of the bucket size.
    """
    return math.ceil(TIME_RANGE_SECONDS[range_] / BUCKET_SECONDS[range_])