Skip to content

TIME_HANDLING.md

Latest commit

 

History

History
121 lines (91 loc) · 4.16 KB

TIME_HANDLING.md

File metadata and controls

121 lines (91 loc) · 4.16 KB

Time Handling in mailcli

Overview

mailcli uses a layered approach to time handling that balances user-friendliness with machine-readability.

Architecture

┌─────────────────────────────────────────────────────┐
│  User Input Layer                                    │
│  • Input: 2026-03-19 (local timezone)               │
│  • Parsed in local timezone for user convenience    │
│  • Example: --since 2026-03-19                       │
└─────────────────┬───────────────────────────────────┘
                  │ Converted to UTC
                  ▼
┌─────────────────────────────────────────────────────┐
│  Internal Storage Layer                              │
│  • All times stored as UTC                           │
│  • Consistent timezone for comparisons              │
│  • Example: 2026-03-18T16:00:00Z                     │
└─────────────────┬───────────────────────────────────┘
                  │ Converted for display
                  ▼
┌─────────────────────────────────────────────────────┐
│  Output Layer                                         │
│  • JSON: ISO 8601 (RFC3339) with timezone           │
│  • Text: Local timezone with offset info            │
└─────────────────────────────────────────────────────┘

Examples

1. User Input (Local Timezone)

# User inputs date in local timezone
$ mailcli mail search --since 2026-03-19

# Internally converted to UTC
# If user is in UTC+8: 2026-03-19 00:00:00 → 2026-03-18T16:00:00Z

2. JSON Output (ISO 8601)

{
  "uid": 12345,
  "subject": "Test Email",
  "date": "2026-03-19T15:30:45+08:00"
}
  • Format: RFC3339 (ISO 8601 subset)
  • Includes: Timezone offset
  • Purpose: Machine-readable, API-friendly

3. Text Output (User-Friendly)

Date: 2026-03-19 15:30:45 (UTC+08:00)
  • Format: Local timezone with offset
  • Includes: Human-readable offset information
  • Purpose: Easy to read for humans

Implementation Details

Package: pkg/timeutil

Functions

  • ParseDateInLocalTZ(dateStr string): Parse user input in local timezone, return UTC
  • FormatInLocalTZ(t time.Time): Format time in local timezone
  • FormatInLocalTZWithOffset(t time.Time): Format with offset information
  • FormatRFC3339(t time.Time): Format as ISO 8601 (RFC3339)
  • ToUTC(t time.Time): Convert time to UTC
  • NowUTC(): Get current time in UTC

Usage Example

import "github.com/keepmind9/mailcli/pkg/timeutil"

// Parse user input (local timezone)
sinceDate, err := timeutil.ParseDateInLocalTZ("2026-03-19")
// Result: 2026-03-18T16:00:00Z (assuming UTC+8)

// Format for JSON output
jsonDate := timeutil.FormatRFC3339(sinceDate)
// Result: "2026-03-18T16:00:00Z"

// Format for text output
textDate := timeutil.FormatInLocalTZWithOffset(sinceDate)
// Result: "2026-03-19 00:00:00 (UTC+08:00)"

Benefits

✅ User-Friendly: Users input dates in their local timezone ✅ Consistent: All internal operations use UTC ✅ Machine-Readable: JSON output uses standard ISO 8601 format ✅ Clear: Text output shows timezone offset explicitly ✅ Compatible: Works with any timezone worldwide

Timezone Handling

  • Input: Interpreted in user's local timezone
  • Storage: Always UTC (consistent)
  • Display: Converted back to local timezone
  • JSON: RFC3339 with timezone offset (no ambiguity)

Testing

See pkg/timeutil/timeutil_test.go for comprehensive tests.

go test ./pkg/timeutil/...