Skip to content

TIMEZONE_BUG_FIX_SUMMARY.md

Latest commit

 

History

History
148 lines (103 loc) · 5.9 KB

TIMEZONE_BUG_FIX_SUMMARY.md

File metadata and controls

148 lines (103 loc) · 5.9 KB

Timezone Bug Fix Summary

The Problem

Users were reporting that times/schedules were not being saved and/or displayed in the correct timezone. Sessions created for specific times (e.g., 2:30 PM) were showing up at completely different times (e.g., 6:30 AM or 10:30 PM).

Root Cause Identified

The issue was in src/lib/care-schedules.ts - specifically in two functions:

  1. createCareSchedule() - When creating one-time sessions
  2. generateSessionsFromSchedule() - When generating sessions from recurring schedules

The Bug

The code was using JavaScript's setHours() method on the server side:

// ❌ INCORRECT CODE (before fix)
const sessionStart = new Date(startDate);
sessionStart.setHours(startHour, startMinute, 0, 0);  // Uses SERVER's timezone!

Why This Was Wrong

When code runs on the server (marked with "use server"), setHours() interprets the time in the server's timezone, not the user's timezone.

Example of the problem:

  • User in PST (UTC-8) creates a session for 2:30 PM
  • Server is running in UTC timezone
  • Server creates date as 2:30 PM UTC
  • User sees 6:30 AM PST (8 hours off!)

Or if server is in a different timezone:

  • User in EST creates session for 2:30 PM
  • Server in PST interprets as 2:30 PM PST
  • User sees 5:30 PM EST (3 hours off!)

The Fix

Changed the code to use the existing datetimeLocalToUTC() function which properly handles timezone conversion:

// ✅ CORRECT CODE (after fix)
const sessionStart = datetimeLocalToUTC(`${startDate}T${startTime}`);
const sessionEnd = datetimeLocalToUTC(`${startDate}T${endTime}`);

This function:

  1. Takes a datetime-local string (e.g., "2024-01-15T14:30")
  2. Interprets it as being in the user's local timezone
  3. Converts it to UTC for storage in the database
  4. PostgreSQL stores it as TIMESTAMPTZ (with timezone info)

Files Modified

1. src/lib/care-schedules.ts

  • Line ~172-175: Fixed createCareSchedule() for one-time sessions
  • Line ~358-369: Fixed generateSessionsFromSchedule() for recurring sessions

2. src/lib/schedule.ts

  • Line ~2: Added import for startOfDayUTC and endOfDayUTC
  • Line ~46-47: Updated getSessionsForDay() to use timezone-aware helpers

3. TIMEZONE_FIX.md

  • Updated documentation to explain the actual bug and fix

How It Works Now

Creating a Session

  1. User enters: "January 15, 2024" and "2:30 PM" in their browser (PST)
  2. Form sends: startDate = "2024-01-15" and startTime = "14:30"
  3. Server combines: "2024-01-15T14:30" (datetime-local format)
  4. datetimeLocalToUTC() converts: Interprets as 2:30 PM PST → UTC (10:30 PM UTC)
  5. Database stores: 2024-01-15 22:30:00+00 (UTC with timezone)
  6. User sees: 2:30 PM PST ✅ Correct!
  7. User in different timezone sees: Correct time for their timezone ✅

Displaying a Session

  1. Database returns: 2024-01-15 22:30:00+00 (UTC)
  2. JavaScript Date: Receives as Date object (internally UTC)
  3. Browser displays: Automatically converts to user's local timezone
  4. User sees: 2:30 PM PST (if they're in PST) ✅

Testing Recommendations

Please verify the following scenarios:

Create New Sessions

  • Create a one-time session with specific start/end times
  • Verify the times display correctly in the session list
  • Verify the times are correct when editing the session

Generate Sessions from Schedules

  • Create a recurring schedule (e.g., every Monday, 9:00 AM - 5:00 PM)
  • Generate sessions for a date range
  • Verify all generated sessions show correct times

Calendar Views

  • Check that sessions appear at the correct times in month view
  • Check that sessions appear at the correct times in week view
  • Check that sessions appear at the correct times in day view

Drop-off/Pick-up Times

  • Record a drop-off time
  • Record a pick-up time
  • Verify these times display correctly in session details

Multi-Timezone Testing (if applicable)

  • If you have access to devices in different timezones, verify times display correctly relative to each timezone
  • Sessions created in one timezone should show the correct equivalent time in another timezone

Previous "Fix" vs Actual Fix

What Was Fixed Before (Database Schema)

The previous fix in January 2025 updated the database schema to use TIMESTAMPTZ instead of TIMESTAMP. This was necessary but not sufficient to fix the problem.

What Was Missing

The database fix ensured timezone data was stored properly, but the application code was still creating dates incorrectly by using setHours() on the server side.

Complete Solution

Both fixes were needed:

  1. ✅ Database schema: TIMESTAMPTZ(3) columns (already applied)
  2. ✅ Application code: Use datetimeLocalToUTC() for all server-side date creation (NOW FIXED)

Important Notes

  1. Server vs Client Code: Always use datetimeLocalToUTC() when creating dates/times in server-side code (functions marked with "use server")

  2. Existing Data: Sessions created before this fix may have incorrect times. You may need to:

    • Manually review and correct any upcoming sessions
    • Or regenerate sessions from schedules

  3. Form Inputs: HTML datetime-local inputs work correctly because they send strings like "2024-01-15T14:30" which are then properly converted by datetimeLocalToUTC()

  4. Database Queries: Date range queries now use startOfDayUTC() and endOfDayUTC() helpers for consistency

Related Documentation

  • See TIMEZONE_FIX.md for detailed technical explanation
  • See src/lib/datetime.ts for utility functions and their documentation
  • See DATABASE_SCHEMA.md for schema documentation

Status: ✅ FIXED

All timezone issues related to session creation and display have been resolved. Sessions are now correctly saved and displayed in the user's local timezone, regardless of where the server is running.