Time Zone Converter

Level: Beginner 15–30 min

Concepts: Edge CasesAlgorithms

Solutions: C# | TypeScript | Python

Implement a time zone converter that can convert times between different time zones, handle daylight saving time, and format dates according to various standards.

Requirements

  1. Convert times between different time zones
    • Support major time zones (UTC, EST, PST, etc.)
    • Handle daylight saving time transitions
    • Support custom time zone offsets
  2. Format dates and times
    • Support different date/time formats (ISO 8601, RFC 3339, etc.)
    • Handle different locale-specific formats
    • Support relative time formats (e.g., “2 hours ago”)
  3. Validate time zone inputs
    • Check for valid time zone names
    • Validate date/time strings
    • Handle invalid inputs gracefully

Hint

Start by implementing basic time zone conversions using fixed offsets, then add support for daylight saving time. Consider using a time zone database or library for accurate conversions. Think about edge cases like:

  • Times during daylight saving time transitions
  • Times near midnight that cross date boundaries
  • Invalid or ambiguous times
  • Non-integer time zone offsets (e.g., UTC+5:30)
  • Invalid or unknown time zone names
  • Conversions across the International Date Line

Bonus

  • Add support for historical time zone data
  • Implement time zone abbreviation resolution
  • Add support for recurring time conversions
  • Create a time zone database manager
  • Implement time zone-aware scheduling

Reference Walkthrough

Reference implementations in C#, TypeScript, and Python live at tddbuddy-reference-katas/time-zone-converter. The reference follows the kata hint’s “start by implementing basic time zone conversions using fixed offsets” and stays there — IANA zones, daylight saving rules, and ambiguous/skipped local times around DST transitions are explicitly out of scope. Widening the kata to full IANA handling swaps it from an F1 algorithmic exercise (one-line arithmetic) to an F3 domain-modelling one (injected clock, zone registry, disambiguation policy for the repeated hour in fall-back); the hint’s phrasing calls for the narrower first step. Twelve scenarios cover the identity case, westward / eastward shifts from UTC, a cross-zone conversion that doesn’t touch UTC, forward / backward midnight roll-overs, half-hour (+05:30) and quarter-hour (+05:45) offsets, month / year / leap-day boundaries, and a twenty-four-hour swing across the international date line.

  • C# (.NET 8, xUnit, FluentAssertions 6.12.0) — walkthrough — public static DateTime Convert(DateTime local, TimeSpan fromOffset, TimeSpan toOffset) with a one-expression body (local - fromOffset + toOffset); DateTime / TimeSpan arithmetic carries across minute / hour / day / month / year boundaries
  • TypeScript (Node 20, Vitest 1.6, TS 5 strict) — walkthrough — LocalDateTime / Offset shape-only interfaces; conversion normalises to a UTC millisecond instant via Date.UTC(...), shifts by the offset delta in milliseconds, and reads calendar components back via getUTC* for host-time-zone-independence
  • Python (3.11, pytest) — walkthrough — naive datetime plus timedelta offsets; convert is a single expression and the package __init__.py re-exports it so tests import from time_zone_converter import convert

This kata ships in Agent Full-Bake mode at high gear (F1 tier): the algorithm is small enough to land as one commit per language, with walkthroughs noting there are no builders because the date-time types come from the standard library and the inputs / outputs are the domain. See the repo’s Gears section for when high gear is the right call.

Related reading

  • Examples Pin Intent. Properties Pin the Invariants.
    Example-based tests anchor scenarios in the team's vocabulary. Property-based tests anchor invariants across the input space. The agent needs both axes, and most suites only carry one.
  • Katas Are Rehearsal, Not Performance
    You don't practice TDD on production code. You practice on katas and bring the muscle memory to production. The gap between knowing TDD and doing TDD is reps.
  • The Test Pyramid Was an Economic Argument
    The test pyramid was not a quality law. It was a cost structure: unit tests were cheap, integration tests were expensive, so you wrote many of the first and few of the second. Agents collapsed the cost of writing tests at every level, and the cheapest test that still tells the truth is the one that pins a seam the agent cannot fake.