Documentation for the policies for handling datetime.
Date vs Timestamp
When designing schemas, decide how to represent the date.
Date: store only date data. Should appear the same to everyone regardless of timezone. ex. 1/1/2024.
Timestamp/datetime: store an exact timestamp of date and time. ex. 1/1/2024 00:00 UTC. Does not store timezone info, e.g. 1/1/2024 03:00 UTC is identical to 12/31/2023 23:00 EDT.
The following fields should be date but are grandfathered in as timestamps.
Model | Field |
|---|---|
Activation_CR | startDate |
Reimbursement | dateCreated |
Reimbursement_Request | dateOfExpense |
Task | deadline |
Work_Package | startDate |
Front-End
If user has to input date/time manually, use MUI Date and Time Pickers. As a rule of thumb, including only a date picker should save date only, and including both should save timestamp.
Remember to document and indicate on the front-end whether a time picker is for ET or UTC (and make sure you convert when sending to backend if necessary)! By default it is a good idea to keep things in ET (America/New_York). Refer to the MUI documentation to set timezones.
When displaying a timestamp that includes a time, include the time in ET and append “ET” or “Eastern” after it. Don’t think there are examples of this currently, but if added you should make a new pipe for it.
Back-End
Endpoints dealing with timestamps should send as yyyy-mm-ddThh:mm:ss.sssZ. Axios and Express do this automatically with JS Date objects.
Endpoints dealing with dates only should send yyyy-mm-dd only to avoid confusion.
Auto-generated timestamps (e.g. work package created) should be generated on the backend, either with new Date() or, in the Prisma schema, @default(now()). This makes the timing more consistent and adds a layer of security also.
TICKET: Add validators and transformers in both frontend and backend to convert between Date objects and plain date strings.
Prisma
Prisma by default stores dates as timestamps without timezone info. We assume all timestamps in the database are in UTC.
For future schema additions, explicitly tag timestamps with @db.Timestamp(3) and dates with @db.Date.
For old data that is @db.Timestamp but should be a plain date, store it as yyyy-mm-ddT00:00:00Z (midnight UTC). Use the transformer mentioned above.
Testing
A good idea to include manual tests for dates and times that involve times within 4 hours of midnight in either direction to make sure the feature doesn’t mess up the time displayed. Remember that the default timezone is ET, so it should at least work as expected in this time zone.