Simple dates, brutal time zones. You think Date just works? Cute. Treat the server as the clock, store UTC instants, demand ISO‑8601 with offsets, and stop guessing. Convert only at the edges with Intl and real IANA zones. DST will ambush you twice a year; have a policy. Log offsets. Test the weird days. Temporal’s coming. Want fewer 3 a.m. outages and angry users—prove it.
Key Takeaways
- Store timestamps in UTC as epoch milliseconds; keep IANA zone name separately for round-trip fidelity.
- Accept only ISO 8601 with explicit Z or offset; validate inputs with Temporal or a robust parser module.
- Normalize to UTC on the server; log original offset and source; make the server the authoritative clock.
- Convert to local time only at presentation using Intl.DateTimeFormat with user locale and validated IANA timeZone.
- Handle DST gaps and duplicates explicitly; define disambiguation policies and test edge cases with fixed clocks.
Store and Normalize Times in UTC
Because time zones love chaos, you shut them down at the source: store everything in UTC. You pick one clock. The only clock. Dates go in as UTC, normalized, boring, reliable. Need display? Convert at the edge, never in the core. You want audits, ordering, reproducible math. UTC delivers. Local offsets sulk. Leap seconds whine. You ignore them. Use epoch storage when you can; integers don’t lie. Milliseconds if needed, nanoseconds when life gets loud—hello precision retention. Arithmetic stays sane. Sorting stays sane. Caches stop melting. Reports stop gaslighting you at midnight. You save weekends. You save dignity. Still tempted by “user local everywhere”? Cute. Also wrong. Centralize UTC, then expose time politely at the boundary. Be ruthless. Time deserves fear. Ship it now.
Safe Parsing From User Input and APIS
UTC in the core is non‑negotiable; now you face the mess at the gates: human strings and flaky APIs. Stop guessing. You parse on your terms. Use format whitelisting, not vibes. Accept ISO 8601 only: 2025-03-10T14:32:00Z or with an explicit offset. Reject everything else. No timezone names. No slashes. No “maybe it means local.” It doesn’t. Do input validation first, then parse. Prefer a real parser: Temporal if you have it, otherwise a battle‑tested library. Never trust Date.parse roulette across browsers. Normalize to Instant, keep the offset, log the source. APIs lie. Servers drift. Phones travel. When data lacks offset, force the user to pick one, or default to a server‑controlled zone and mark it “assumed.” Then store UTC. Every time. No exceptions, ever.
Formatting and Display With Intl.Datetimeformat
You want time that actually speaks your user’s language and zone, not some ghost UTC stamp—so you use Intl.DateTimeFormat with locale‑aware time zones, or you confuse everyone. Pick dateStyle and timeStyle like a boss—short for speed, long for ceremony—and watch 3/4/25 stop being a joke. Set the locale, set the timeZone, set the tone, because if you won’t, your app will lie to people and they’ll blame you, not the clock.
Locale-Aware Time Zones
Why let your app mumble 2025-12-01T15:00:00Z when it can speak human? Use Intl.DateTimeFormat with a real locale and a real timeZone. You pick ‘en-US’ or ‘fr-FR’. You pass { timeZone: ‘Asia/Kolkata’ }. Boom. Local flavor, correct zone. You respect users, not servers.
Stop guessing abbreviations. Let the engine pick scripts, calendars, and numbering when needed. It handles locale fallback so odd tags don’t crash. It does territory mapping so ‘en’ in GB doesn’t look like ‘en’ in US. You want Monday, not some mystery.
Detect the locale. Honor user settings. Normalize IANA names. Validate them too. Then format once, show everywhere. No brittle hacks. No fake math. Just dates that read right, feel right, and never argue back. Ship confidence. Ban confusion. Be bold.
Datestyle and Timestyle
How clean do you want your dates to look? Use Intl.DateTimeFormat with dateStyle and timeStyle. You pick short, medium, long, or full. You control tone. No messy strings, no awkward hacks. You want crisp? dateStyle: ‘short’. You want ceremony? ‘full’. And yes, time zones still matter, so pass timeZone or get burned.
Now be bold. Lock design consistency across screens. Don’t let one widget whisper while another screams. Same locale, same styles, same energy. Users notice. They judge fast.
Accessibility considerations aren’t optional. Screen readers need predictable phrasing, not random DIY formats. So stop reinventing calendars. Use numeric options when clarity wins. Prefer 24‑hour when ambiguity kills. Label UTC when it’s UTC. Add weekday when context saves time. Decide. Format. Ship. Do it today.
Daylight Saving Time and Ambiguous Local Times
You think time is linear; JavaScript laughs when the clock jumps forward and your 2:30 vanishes, so you must handle that hole. Then the clock falls back and 1:30 hits twice, so detect the duplicate or watch your logs gaslight you. You test edges, pick explicit zones, and stamp UTC like a boss—or you ship bugs today, not tomorrow.
Handling Spring-Forward Gaps
While the clock jumps forward, your code face‑plants. You schedule 2:30 AM in March and boom the hour vanishes. JavaScript will roll it to 3:30 AM or lie, depending on the API. That gap burns. Users blame you not physics. So you confront it.
Define appointment policies. Don’t dodge. For missing intervals say exactly what happens: skip, shift to 3:00, or reject. Make it loud. Validate input against the zone’s rules before saving. Use Temporal.ZonedDateTime or a library that flags nonexistent local times. Convert to UTC at the edge then reason in local time only for display. Show warnings in forms. Offer a picker that grays out the gap. Log every auto‑shift. Test the jump with fixtures. And own it, because clock won’t apologize.
Detecting Fall-Back Duplicates
Because the clock repeats an hour, your precious 1:30 AM happens twice—and yes, both are “right.” That’s the trap. You try to log bedtime. You get two. Which one wins? Not magic. You perform conflict detection. You anchor times to an offset. You store UTC, always. Then you reconstruct with zone rules. In JavaScript, use Temporal.ZonedDateTime or format with Intl, not naive Date math. Need duplicate flagging? Compare local wall time plus zone to its UTC instant; if two distinct instants share identical hh:mm, tag them. Ask the offset. If it increases after 1:59, you’re in the repeat window. Require a choice. First 1:30 or second 1:30. Prompt the user. Or add a disambiguation policy: earlier, later, or reject. Stop guessing. Be bold now.
Serialization, Transport, and Database Considerations
From the wire to the disk, time gets mangled. You think JSON saves you? Cute. Serialize UTC with an explicit Z, or enjoy mysteries at 3 a.m. Include offset when you must, but never mix guessed zones with stored instants. Use RFC 3339, full precision, and no sloppy local strings. Milliseconds matter. So do leap seconds? Not here. Document that. Schema versioning isn’t optional; it’s survival. Add fields, don’t mutate meaning, keep Binary compatibility for old consumers that still choke on surprises. In transport, compress after you normalize, not before. In databases, store instants as UTC, store zones as separate text, and index both. Round trips should be lossless. Prove it with tests. Fail loud. Fix upstream. Repeat. No excuses. Own your temporal data.
Server–Client Responsibilities and Boundaries
You nailed the wire and the disk. Now own the boundary. The server holds Clock Authority, not your jittery browser. It stamps UTC, validates offsets, and rejects cute client guesses. The client displays. Period. It asks for data, not truth. You enforce API Contracts: inputs are ISO 8601 with timezone or explicit UTC; outputs are clear, consistent, documented. No mystery fields. No timezone roulette. The server converts on rules it controls. The client formats for humans: locale, calendar, snarky labels if you must. If the client sends a local time, it must send the zone. Miss it? You bounce it. Hard. Cache server time drift, sync often, distrust tabs that nap. Log both received and normalized times. And when clocks fight, the server wins.
Preparing for the Temporal API and Future-Proofing
While the old Date limps along, Temporal is rolling in like a freight train, and you either get ready or get run over. You want safety. You want sane time zones. Good. Stop dithering. Start with a Polyfill strategy now. Feature‑detect Temporal. If absent, load the polyfill and keep shipping. No heroics. Just discipline.
Next, commit to Migration planning. Map current Date uses. Replace fuzzy math with Temporal.Instant, ZonedDateTime, and PlainDate. Use adapters so old code survives while new code breathes. Write tests with fixed clocks. Store ISO strings. Round‑trip time zones. Ban midnight hacks. Wrap parsing in one module. Expose pure functions. Log offsets. Document DST rules. Then cut dead branches weekly. Small merges. Ruthless focus. You’re not waiting. You’re arriving early. Clock mistakes cost money.
