datasynth_core/distributions/
timezone.rs

1//! Timezone handling for multi-region synthetic data generation.
2//!
3//! This module provides timezone-aware datetime handling for:
4//! - Entity-specific timezone assignments (by company code pattern)
5//! - UTC to local time conversions
6//! - Consolidation timezone for group reporting
7
8use chrono::{DateTime, NaiveDateTime, Offset, TimeZone, Utc};
9use chrono_tz::Tz;
10use serde::{Deserialize, Serialize};
11use std::collections::HashMap;
12
13/// Timezone configuration for multi-region entities.
14#[derive(Debug, Clone, Serialize, Deserialize)]
15pub struct TimezoneConfig {
16    /// Default timezone for entities without a specific mapping.
17    pub default_timezone: String,
18    /// Entity-to-timezone mappings (supports patterns like "EU_*" -> "Europe/London").
19    pub entity_timezones: HashMap<String, String>,
20    /// Consolidation timezone for group reporting.
21    pub consolidation_timezone: String,
22}
23
24impl Default for TimezoneConfig {
25    fn default() -> Self {
26        Self {
27            default_timezone: "America/New_York".to_string(),
28            entity_timezones: HashMap::new(),
29            consolidation_timezone: "UTC".to_string(),
30        }
31    }
32}
33
34impl TimezoneConfig {
35    /// Creates a new timezone config with the specified default timezone.
36    pub fn new(default_tz: &str) -> Self {
37        Self {
38            default_timezone: default_tz.to_string(),
39            entity_timezones: HashMap::new(),
40            consolidation_timezone: "UTC".to_string(),
41        }
42    }
43
44    /// Sets the consolidation timezone.
45    pub fn with_consolidation(mut self, tz: &str) -> Self {
46        self.consolidation_timezone = tz.to_string();
47        self
48    }
49
50    /// Adds an entity-to-timezone mapping.
51    ///
52    /// Supports pattern matching:
53    /// - Exact match: "1000" -> "America/New_York"
54    /// - Prefix match: "EU_*" -> "Europe/London"
55    /// - Suffix match: "*_APAC" -> "Asia/Singapore"
56    pub fn add_mapping(mut self, entity_pattern: &str, timezone: &str) -> Self {
57        self.entity_timezones
58            .insert(entity_pattern.to_string(), timezone.to_string());
59        self
60    }
61}
62
63/// Handler for timezone operations.
64#[derive(Debug, Clone)]
65pub struct TimezoneHandler {
66    config: TimezoneConfig,
67    /// Parsed default timezone.
68    default_tz: Tz,
69    /// Parsed consolidation timezone.
70    consolidation_tz: Tz,
71    /// Cached parsed entity timezones.
72    entity_tz_cache: HashMap<String, Tz>,
73}
74
75impl TimezoneHandler {
76    /// Creates a new timezone handler from configuration.
77    pub fn new(config: TimezoneConfig) -> Result<Self, TimezoneError> {
78        let default_tz: Tz = config
79            .default_timezone
80            .parse()
81            .map_err(|_| TimezoneError::InvalidTimezone(config.default_timezone.clone()))?;
82
83        let consolidation_tz: Tz = config
84            .consolidation_timezone
85            .parse()
86            .map_err(|_| TimezoneError::InvalidTimezone(config.consolidation_timezone.clone()))?;
87
88        // Pre-parse all entity timezone mappings
89        let mut entity_tz_cache = HashMap::new();
90        for (pattern, tz_name) in &config.entity_timezones {
91            let tz: Tz = tz_name
92                .parse()
93                .map_err(|_| TimezoneError::InvalidTimezone(tz_name.clone()))?;
94            entity_tz_cache.insert(pattern.clone(), tz);
95        }
96
97        Ok(Self {
98            config,
99            default_tz,
100            consolidation_tz,
101            entity_tz_cache,
102        })
103    }
104
105    /// Creates a handler with default US Eastern timezone.
106    pub fn us_eastern() -> Self {
107        Self::new(TimezoneConfig::default()).expect("Default timezone config should be valid")
108    }
109
110    /// Gets the timezone for a specific entity code.
111    ///
112    /// Matches entity code against patterns in this order:
113    /// 1. Exact match
114    /// 2. Prefix patterns (e.g., "EU_*")
115    /// 3. Suffix patterns (e.g., "*_APAC")
116    /// 4. Default timezone
117    pub fn get_entity_timezone(&self, entity_code: &str) -> Tz {
118        // Check exact match first
119        if let Some(tz) = self.entity_tz_cache.get(entity_code) {
120            return *tz;
121        }
122
123        // Check patterns
124        for (pattern, tz) in &self.entity_tz_cache {
125            if let Some(prefix) = pattern.strip_suffix('*') {
126                // Prefix pattern (e.g., "EU_*")
127                if entity_code.starts_with(prefix) {
128                    return *tz;
129                }
130            } else if let Some(suffix) = pattern.strip_prefix('*') {
131                // Suffix pattern (e.g., "*_APAC")
132                if entity_code.ends_with(suffix) {
133                    return *tz;
134                }
135            }
136        }
137
138        self.default_tz
139    }
140
141    /// Converts a local datetime to UTC for a specific entity.
142    pub fn to_utc(&self, local: NaiveDateTime, entity_code: &str) -> DateTime<Utc> {
143        let tz = self.get_entity_timezone(entity_code);
144        tz.from_local_datetime(&local)
145            .single()
146            .unwrap_or_else(|| {
147                tz.from_local_datetime(&local)
148                    .earliest()
149                    .expect("valid time components")
150            })
151            .with_timezone(&Utc)
152    }
153
154    /// Converts a UTC datetime to local time for a specific entity.
155    pub fn to_local(&self, utc: DateTime<Utc>, entity_code: &str) -> NaiveDateTime {
156        let tz = self.get_entity_timezone(entity_code);
157        utc.with_timezone(&tz).naive_local()
158    }
159
160    /// Converts a local datetime to the consolidation timezone.
161    pub fn to_consolidation(&self, local: NaiveDateTime, entity_code: &str) -> DateTime<Tz> {
162        let utc = self.to_utc(local, entity_code);
163        utc.with_timezone(&self.consolidation_tz)
164    }
165
166    /// Returns the consolidation timezone.
167    pub fn consolidation_timezone(&self) -> Tz {
168        self.consolidation_tz
169    }
170
171    /// Returns the default timezone.
172    pub fn default_timezone(&self) -> Tz {
173        self.default_tz
174    }
175
176    /// Returns the timezone name for an entity.
177    pub fn get_timezone_name(&self, entity_code: &str) -> String {
178        self.get_entity_timezone(entity_code).name().to_string()
179    }
180
181    /// Calculates the UTC offset in hours for an entity at a given time.
182    pub fn get_utc_offset_hours(&self, entity_code: &str, at: NaiveDateTime) -> f64 {
183        let tz = self.get_entity_timezone(entity_code);
184        let offset = tz.offset_from_local_datetime(&at).single();
185        match offset {
186            Some(o) => o.fix().local_minus_utc() as f64 / 3600.0,
187            None => 0.0,
188        }
189    }
190
191    /// Returns a reference to the underlying configuration.
192    pub fn config(&self) -> &TimezoneConfig {
193        &self.config
194    }
195}
196
197/// Errors that can occur during timezone operations.
198#[derive(Debug, Clone)]
199pub enum TimezoneError {
200    /// Invalid timezone name.
201    InvalidTimezone(String),
202    /// Ambiguous local time (e.g., during DST transition).
203    AmbiguousTime(NaiveDateTime),
204}
205
206impl std::fmt::Display for TimezoneError {
207    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
208        match self {
209            TimezoneError::InvalidTimezone(tz) => {
210                write!(f, "Invalid timezone: '{tz}'. Use IANA timezone names.")
211            }
212            TimezoneError::AmbiguousTime(dt) => {
213                write!(f, "Ambiguous local time: {dt}")
214            }
215        }
216    }
217}
218
219impl std::error::Error for TimezoneError {}
220
221/// Common timezone presets for different regions.
222pub struct TimezonePresets;
223
224impl TimezonePresets {
225    /// US-centric configuration with NY as default.
226    pub fn us_centric() -> TimezoneConfig {
227        TimezoneConfig::new("America/New_York")
228            .with_consolidation("America/New_York")
229            .add_mapping("*_WEST", "America/Los_Angeles")
230            .add_mapping("*_CENTRAL", "America/Chicago")
231            .add_mapping("*_MOUNTAIN", "America/Denver")
232    }
233
234    /// Europe-centric configuration with London as default.
235    pub fn eu_centric() -> TimezoneConfig {
236        TimezoneConfig::new("Europe/London")
237            .with_consolidation("Europe/London")
238            .add_mapping("DE_*", "Europe/Berlin")
239            .add_mapping("FR_*", "Europe/Paris")
240            .add_mapping("CH_*", "Europe/Zurich")
241    }
242
243    /// Asia-Pacific configuration with Singapore as default.
244    pub fn apac_centric() -> TimezoneConfig {
245        TimezoneConfig::new("Asia/Singapore")
246            .with_consolidation("Asia/Singapore")
247            .add_mapping("JP_*", "Asia/Tokyo")
248            .add_mapping("CN_*", "Asia/Shanghai")
249            .add_mapping("IN_*", "Asia/Kolkata")
250            .add_mapping("AU_*", "Australia/Sydney")
251    }
252
253    /// Global configuration with UTC as consolidation.
254    pub fn global_utc() -> TimezoneConfig {
255        TimezoneConfig::new("America/New_York")
256            .with_consolidation("UTC")
257            .add_mapping("US_*", "America/New_York")
258            .add_mapping("EU_*", "Europe/London")
259            .add_mapping("APAC_*", "Asia/Singapore")
260    }
261}
262
263#[cfg(test)]
264mod tests {
265    use super::*;
266    use chrono::Timelike;
267
268    #[test]
269    fn test_default_timezone() {
270        let handler = TimezoneHandler::us_eastern();
271        let tz = handler.get_entity_timezone("UNKNOWN_COMPANY");
272        assert_eq!(tz.name(), "America/New_York");
273    }
274
275    #[test]
276    fn test_exact_match() {
277        let config = TimezoneConfig::new("America/New_York").add_mapping("1000", "Europe/London");
278        let handler = TimezoneHandler::new(config).unwrap();
279
280        assert_eq!(handler.get_entity_timezone("1000").name(), "Europe/London");
281        assert_eq!(
282            handler.get_entity_timezone("2000").name(),
283            "America/New_York"
284        );
285    }
286
287    #[test]
288    fn test_prefix_pattern() {
289        let config = TimezoneConfig::new("America/New_York").add_mapping("EU_*", "Europe/Berlin");
290        let handler = TimezoneHandler::new(config).unwrap();
291
292        assert_eq!(
293            handler.get_entity_timezone("EU_1000").name(),
294            "Europe/Berlin"
295        );
296        assert_eq!(
297            handler.get_entity_timezone("EU_SUBSIDIARY").name(),
298            "Europe/Berlin"
299        );
300        assert_eq!(
301            handler.get_entity_timezone("US_1000").name(),
302            "America/New_York"
303        );
304    }
305
306    #[test]
307    fn test_suffix_pattern() {
308        let config = TimezoneConfig::new("America/New_York").add_mapping("*_APAC", "Asia/Tokyo");
309        let handler = TimezoneHandler::new(config).unwrap();
310
311        assert_eq!(
312            handler.get_entity_timezone("1000_APAC").name(),
313            "Asia/Tokyo"
314        );
315        assert_eq!(
316            handler.get_entity_timezone("CORP_APAC").name(),
317            "Asia/Tokyo"
318        );
319        assert_eq!(
320            handler.get_entity_timezone("1000_US").name(),
321            "America/New_York"
322        );
323    }
324
325    #[test]
326    fn test_to_utc() {
327        let handler = TimezoneHandler::new(TimezoneConfig::new("America/New_York")).unwrap();
328
329        // 10 AM New York time
330        let local =
331            NaiveDateTime::parse_from_str("2024-06-15 10:00:00", "%Y-%m-%d %H:%M:%S").unwrap();
332        let utc = handler.to_utc(local, "US_1000");
333
334        // In June, NY is UTC-4 (EDT)
335        assert_eq!(utc.hour(), 14);
336    }
337
338    #[test]
339    fn test_to_local() {
340        let config = TimezoneConfig::new("America/New_York").add_mapping("EU_*", "Europe/London");
341        let handler = TimezoneHandler::new(config).unwrap();
342
343        // 12:00 UTC
344        let utc = DateTime::parse_from_rfc3339("2024-06-15T12:00:00Z")
345            .unwrap()
346            .with_timezone(&Utc);
347
348        // London in June is UTC+1 (BST)
349        let london_local = handler.to_local(utc, "EU_1000");
350        assert_eq!(london_local.hour(), 13);
351
352        // New York in June is UTC-4 (EDT)
353        let ny_local = handler.to_local(utc, "US_1000");
354        assert_eq!(ny_local.hour(), 8);
355    }
356
357    #[test]
358    fn test_presets() {
359        // Test that presets can be created without errors
360        let _ = TimezoneHandler::new(TimezonePresets::us_centric()).unwrap();
361        let _ = TimezoneHandler::new(TimezonePresets::eu_centric()).unwrap();
362        let _ = TimezoneHandler::new(TimezonePresets::apac_centric()).unwrap();
363        let _ = TimezoneHandler::new(TimezonePresets::global_utc()).unwrap();
364    }
365
366    #[test]
367    fn test_invalid_timezone() {
368        let config = TimezoneConfig::new("Invalid/Timezone");
369        let result = TimezoneHandler::new(config);
370        assert!(result.is_err());
371    }
372}
datasynth_core/distributions/timezone.rs

datasynth_core/distributions/
timezone.rs
