Extract localeDateFormat helper from timeago utils
What does this MR do and why?
Extract localeDateFormat helper from timeago utils
The timeago utils are currently housing some wrappers around
Intl.DateTimeFormat
which are used if the user opts to see absolute
Dates everywhere.
This MR extracts the logic into a new singleton, which has not a single, but a ton of features:
- It respects the users locale preference
- It respects the users preference for
hourCycle
(AM/PM vs 24h) - All the formatters are lazy-loaded upon first use, because it is rather expensive to create a formatter, but fast to use one.
- It exposes a well-documented, limited set of formatters, so that developers have an easier time to choose the correct formatter.
- If needbe the lazy-loaded getters can be reset (tests, or maybe on the User preference page, where we could show a live preview how the dates look.
- All available formatters are also exposed as string constants, so that we have an easier time if certain Vue components want to pass a format as a prop.
- Each formatter exposes a
format
and aformatRange
function to format single dates and date ranges, respectively. - Both those functions accept "Dateish" values, so anything which could
be used to create a date. This is mainly for backwards compatibility
with the existing
dateFormat
function
Currently only two date formatters are available:
-
localDateFormat.asDateTime
. Prints a medium sized date and time with minute precision. -
localDateFormat.asDate
. Prints a medium sized date.
It's deliberate that only these formatters are available now, more are going to follow, as we slowly migrate from other APIs to this one.
Other features that aren't available yet:
- formatting dates as iso-like dates (
yyyy-mm-dd
) - formatting dates in different timezones from the user or UTC
The reason these aren't available: We have to look how to expose these options while also keeping the API surface reasonable.
In the end, this new API is meant to replace:
-
formatDate
, as this function is not locale aware -
Date.prototype.toLocaleDateString
andDate.prototype.toLocaleString
, as those APIs are about 22x slower. - Custom instantiations of
Intl.DateTimeFormat
. As this might be slower, but also result in sub-optimal User experience, because the formats chosen could be conflicting with the user expectations, by e.g. forcing 12h/24h formats.
See also: gitlab-org/frontend/rfcs#90
Screenshots or screen recordings
N/A – No user visible changes, but for developers the JSDoc have a nice preview:
What | JetBrains IDE (RubyMine) | VSCode |
---|---|---|
Auto Complete | ||
Docs on localDateFormat
|
||
Docs on localDateFormat.asDateTime
|
||
Docs on localDateFormat.asDate
|
How to set up and validate locally
- Start the GDK
- Set your time settings to "absolute".
- Go to any page (eg. repo, commits) with a lot of dates. The absolute rendered dates should still be there.
MR acceptance checklist
This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.
-
I have evaluated the MR acceptance checklist for this MR.