mirror of
https://github.com/twentyhq/twenty.git
synced 2026-04-19 06:19:39 -04:00
afeb505eed
This PR implements the necessary tools to have `react-datepicker` calendar and our date picker components work reliably no matter the timezone difference between the user execution environment and the user application timezone. Fixes https://github.com/twentyhq/core-team-issues/issues/1781 This PR won't cover everything needed to have Twenty handle timezone properly, here is the follow-up issue : https://github.com/twentyhq/core-team-issues/issues/1807 # Features in this PR This PR brings a lot of features that have to be merged together. - DATE field type is now handled as string only, because it shouldn't involve timezone nor the JS Date object at all, since it is a day like a birthday date, and not an absolute point in time. - DATE_TIME field wasn't properly handled when the user settings timezone was different from the system one - A timezone abbreviation suffix has been added to most DATE_TIME display component, only when the timezone is different from the system one in the settings. - A lot of bugs, small features and improvements have been made here : https://github.com/twentyhq/core-team-issues/issues/1781 # Handling of timezones ## Essential concepts This topic is so complex and easy to misunderstand that it is necessary to define the precise terms and concepts first. It resembles character encoding and should be treated with the same care. - Wall-clock time : the time expressed in the timezone of a user, it is distinct from the absolute point in time it points to, much like a pointer being a different value than the value that it points to. - Absolute time : a point in time, regardless of the timezone, it is an objective point in time, of course it has to be expressed in a given timezone, because we have to talk about when it is located in time between humans, but it is in fact distinct from any wall clock time, it exists in itself without any clock running on earth. However, by convention the low-level way to store an absolute point in time is in UTC, which is a timezone, because there is no way to store an absolute point in time without a referential, much like a point in space cannot be stored without a referential. - DST : Daylight Save Time, makes the timezone shift in a specific period every year in a given timezone, to make better use of longer days for various reasons, not all timezones have DST. DST can be 1 hour or 30 min, 45 min, which makes computation difficult. - UTC : It is NOT an “absolute timezone”, it is the wall-clock time at 0° longitude without DST, which is an arbitrary and shared human convention. UTC is often used as the standard reference wall-clock time for talking about absolute point in time without having to do timezone and DST arithmetic. PostgreSQL stores everything in UTC by convention, but outputs everything in the server’s SESSION TIMEZONE. ## How should an absolute point in time be stored ? Since an absolute point in time is essentially distinct from its timezone it could be stored in an absolute way, but in practice it is impossible to store an absolute point in time without a referential. We have to say that a rocket launched at X given time, in UTC, EST, CET, etc. And of course, someone in China will say that it launched at 10:30, while in San Francisco it will have launched at 19:30, but it is THE SAME absolute point in time. Let’s take a related example in computer science with character encoding. If a text is stored without the associated encoding table, the correct meaning associated to the bits stored in memory can be lost forever. It can become impossible for a program to guess what encoding table should be used for a given text stored as bits, thus the glitches that appeared a lot back in the early days of internet and document processing. The same can happen with date time storing, if we don’t have the timezone associated with the absolute point in time, the information of when it absolutely happened is lost. It is NOT necessary to store an absolute point in time in UTC, it is more of a standard and practical wall-clock time to be associated with an absolute point in time. But an absolute point in time MUST be store with a timezone, with its time referential, otherwise the information of when it absolutely happened is lost. For example, it is easier to pass around a date as a string in UTC, like `2024-01-02T00:00:00Z` because it allows front-end and back-end code to “talk” in the same standard and DST-free wall-clock time, BUT it is not necessary. Because we have date libraries that operate on the standard ISO timezone tables, we can talk in different timezone and let the libraries handle the conversion internally. It is false to say that UTC is an absolute timezone or an absolute point in time, it is just the standard, conventional time referential, because one can perfectly store every absolute points in time in UTC+10 with a complex DST table and have the exactly correct absolute points in time, without any loss of information, without having any UTC+0 dates involved. Thus storing an absolute point in time without a timezone associated, for example with `timestamp` PostgreSQL data type, is equivalent to storing a wall-clock time and then throwing away voluntarily the information that allows to know when it absolutely happened, which is a voluntary data-loss if the code that stores and retrieves those wall-clock points in time don’t store the associated timezone somewhere. This is why we use `timestamptz` type in PostgreSQL, so that we make sure that the correct absolute point in time is stored at the exact time we send it to PostgreSQL server, no matter the front-end, back-end and SQL server's timezone differences. ## The JavaScript Date object The native JavaScript Date object is now officially considered legacy ([source](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)), the Date object stores an absolute point in time BUT it forces the storage to use its execution environment timezone, and one CANNOT modify this timezone, this is a legacy behavior. To obtain the desired result and store an absolute point in time with an arbitrary timezone there are several options : - The new Temporal API that is the successor of the legacy Date object. - Moment / Luxon / @date-fns/tz that expose objects that allow to use any timezone to store an absolute point in time. ## How PostgreSQL stores absolute point in times PostgreSQL stores absolute points in time internally in UTC ([source](https://www.postgresql.org/docs/current/datatype-datetime.html#DATATYPE-DATETIME-INPUT-TIME-STAMPS)), but the output date is expressed in the server’s session timezone ([source](https://www.postgresql.org/docs/current/sql-set.html)) which can be different from UTC. Example with the object companies in Twenty seed database, on a local instance, with a new “datetime” custom column : <img width="374" height="554" alt="image" src="https://github.com/user-attachments/assets/4394cb43-d97e-4479-801d-ca068f800e39" /> <img width="516" height="524" alt="image" src="https://github.com/user-attachments/assets/b652f36a-d2e2-47a4-8950-647ca688cbbd" /> ## Why can’t I just use the JavaScript native Date object with some manual logic ? Because the JavaScript Date object does not allow to change its internal timezone, the libraries that are based on it will behave on the execution environment timezone, thus leading to bugs that appear only on the computers of users in a timezone but not for other in another timezone. In our case the `react-datepicker` library forces to use the `Date` object, thus forcing the calendar to behave in the execution environment system timezone, which causes a lot of problems when we decide to display the Twenty application DATE_TIME values in another timezone than the user system one, the bugs that appear will be of the off-by-one date class, for example clicking on 23 will select 24, thus creating an unreliable feature for some system / application timezone combinations. A solution could be to manually compute the difference of minutes between the application user and the system timezones, but that’s not reliable because of DST which makes this computation unreliable when DST are applied at different period of the year for the two timezones. ## Why can’t I compute the timezone difference manually ? Because of DST, the work to compute the timezone difference reliably, not just for the usual happy path, is equivalent to developing the internal mechanism of a date timezone library, which is equivalent to use a library that handles timezones. ## Using `@date-fns/tz` to solve this problem We could have used `luxon` but it has a heavy bundle size, so instead we rely here on `@date-fns/tz` (~1kB) which gives us a `TZDate` object that allows to use any given timezone to store an absolute point-in-time. The solution here is to trick `react-datepicker` by shifting a Date object by the difference of timezone between the user application timezone and the system timezone. Let’s take a concerte example. System timezone : Midway, ⇒ UTC-11:00, has no DST. User application timezone : Auckland, NZ ⇒ UTC+13:00, has a DST. We’ll take the NZ daylight time, so that will make a timezone difference of 24 hours ! Let’s take an error-prone date : `2025-01-01T00:00:00` . This date is usually a good test-case because it can generate three classes of bugs : off-by-one day bugs, off-by-one month bugs and off-by-one year bugs, at the same time. Here is the absolute point in time we take expressed in the different wall-clock time points we manipulate Case | In system timezone ⇒ UTC-11 | In UTC | In user application timezone ⇒ UTC+13 -- | -- | -- | -- Original date | `2024-12-31T00:00:00-11:00` | `2024-12-31T11:00:00Z` | `2025-01-01T00:00:00+13:00` Date shifted for react-datepicker | `2025-01-01T00:00:00-11:00` | `2025-01-01T11:00:00Z` | `2025-01-02T00:00:00+13:00` We can see with this table that we have the number part of the date that is the same (`2025-01-01T00:00:00`) but with a different timezone to “trick” `react-datepicker` and have it display the correct day in its calendar. You can find the code in the hooks `useTurnPointInTimeIntoReactDatePickerShiftedDate` and `useTurnReactDatePickerShiftedDateBackIntoPointInTime` that contain the logic that produces the above table internally. ## Miscellaneous Removed FormDateFieldInput and FormDateTimeFieldInput stories as they do not behave the same depending of the execution environment and it would be easier to put them back after having refactored FormDateFieldInput and FormDateTimeFieldInput --------- Co-authored-by: Charles Bochet <charles@twenty.com>
The #1 Open-Source CRM
🌐 Website · 📚 Documentation · 
Roadmap · 
Discord · 
Figma
Installation
See: 🚀 Self-hosting 🖥️ Local Setup
Does the world need another CRM?
We built Twenty for three reasons:
CRMs are too expensive, and users are trapped. Companies use locked-in customer data to hike prices. It shouldn't be that way.
A fresh start is required to build a better experience. We can learn from past mistakes and craft a cohesive experience inspired by new UX patterns from tools like Notion, Airtable or Linear.
We believe in Open-source and community. Hundreds of developers are already building Twenty together. Once we have plugin capabilities, a whole ecosystem will grow around it.
What You Can Do With Twenty
Please feel free to flag any specific needs you have by creating an issue.
Below are a few features we have implemented to date:
- Personalize layouts with filters, sort, group by, kanban and table views
- Customize your objects and fields
- Create and manage permissions with custom roles
- Automate workflow with triggers and actions
- Emails, calendar events, files, and more
Personalize layouts with filters, sort, group by, kanban and table views
Customize your objects and fields
Create and manage permissions with custom roles
Automate workflow with triggers and actions
Emails, calendar events, files, and more
Stack
- TypeScript
- Nx
- NestJS, with BullMQ, PostgreSQL, Redis
- React, with Recoil, Emotion and Lingui
Thanks
Thanks to these amazing services that we use and recommend for UI testing (Chromatic), code review (Greptile), catching bugs (Sentry) and translating (Crowdin).
Join the Community
- Star the repo
- Subscribe to releases (watch -> custom -> releases)
- Follow us on Twitter or LinkedIn
- Join our Discord
- Improve translations on Crowdin
- Contributions are, of course, most welcome!