Investigate library for dates

[sareh]

Is your feature request related to a problem? Please describe. Investigate library for dates and timestamps, for the Persian article.

moment https://momentjs.com, with moment Jalali plugin, for the Persian calendar https://github.com/jalaali/moment-jalaali date-fns https://date-fns.org/

Example of Persian timestamps/dates:

Here is a codepen showing absolute and relative timestamps https://codepen.io/sareh/pen/rrvaqE

Describe the solution you'd like As a result of this investigation, we need to have an understanding of the pros and cons of these libraries and a recommendation for which to use (or neither) with sufficient reasoning. We should write issues for implementing the recommended implementation.

Write an ADR, writing up our decision.

[pjlee11]

The following is a brain dump from the group investigation performed by those assigned to the PR.

Brief Comparison of libraries

Name	Size (gzip)	Methods richness	Pattern	Timezone Support	Locale	Relative timestamps
Moment.js	329K(69.6K)	High	OO	Good (moment-timezone)	123	Yes
date-fns	78.4k(13.4k)	High	Functional	Not yet	32	Yes
dayjs	6.5k(2.6k)	Medium	OO	Not yet	23	Yes (as a plug-in)

More detailed comparrison of the libraries - https://github.com/you-dont-need/You-Dont-Need-Momentjs

Moment.js

Pros

• Handles all our use cases
• Clever webpack bundling and utilising a vendor bundle should allow moment to only be loaded once until a version change or cache clear (as per the trainline's usage of moment - https://engineering.thetrainline.com/optimising-js-bundles-for-internationalisation-378cb28b835e)

Cons

• Pulls in all of the moment library (66KB gzipped with locales, and that's not including the additional locales we require)
• Currently can't be loaded with just a single locale

date-fns

Pros

• Functional "like lodash for dates", meaning only the required methods are imported
• Actively want people to contribute new locales - https://date-fns.org/docs/I18n#adding-new-language

Cons

• Limited amount of locales currently
• No timezone support (has issue open regarding this that are a year old - https://github.com/date-fns/date-fns/issues/180#issuecomment-330789750)

Day.js

Pros

• Day.js seems much more modular, claims to only build the dependencies for the locale used, should POC this to ensure it's true
• Good amount of locales

Cons

• Relative timestamps are a seperate plug-in
• Not sure how comprehensive the supported locales are though: https://github.com/iamkun/dayjs/blob/master/src/locale/fa.js
• No current timezone support (https://github.com/iamkun/dayjs/pull/325)

Build our own

This would be similar to how we did timestamps for AMP.

Pros

Would be built to our use case and optimised for size

Cons

• We'd need to build this from scratch and therefore need support for timezones and locales
• Would it be open source?
• Do we have capacity to maintain it?
• Long time to get started

Summary of libraries

• No libaries support dual timestamps out the box

Around the BBC

• iPlayer currently use their own library and moment timezone, however their library only handles english locale
• Childrens Web sunk a week of dev time into this problem in January, sounds like they had some similar requirements (https://jira.dev.bbc.co.uk/browse/CHILDREN-4332?focusedCommentId=3708866&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-3708866) & didn’t reach a satisfactory alt https://jira.dev.bbc.co.uk/browse/CHILDREN-4332 (edited)
• WS / News AMP: built their own due to lack of support libraries in ruby
• Sport web uses date-fns

Outcome

Each of the following should be evaluated in terms of size (gzipped and webpack bundled) and user pros / cons

• POC: Moment.js with locales and timezone
• POC: Date-fns - Findings
• ~POC: Date-fns with moment timezone~ (From the above findings we don't think date-fns supports our use case)
• POC: Day.js Findings
• POC: Day.js with moment timezone
• SPIKE: Make moment more granular and locked into a single locale, could be raised as an issue/question in moment's github repo

[pjlee11]

For each POC we should install the library and attempt to create the following timestamps:

• English absolute timestamp EG: 7 July 2018
• English relative timestamp EG: 4 hours ago
• Persian absolute timestamp (Jalali - Georgian) - see codepen
• Persian relative timestamp - see codepen

The markup should be

<time datetime="YYYY-MM-DD HH:MM:SS{+Timezone}">{formattedTimestamp}</span>

We should then detail the weight the library (including plugins) adds to the application, which should be possible to see following a npm run build and opening the following file in a browser simorgh/reports/webpackBundleReport.html. Also detail any other thoughts/findings

[pjlee11]

As part of the knowledge sharing day, together we created the branch timestamp-investigation which creates a new component LocalisedTimestamp and adds tests for /news and /persian expecting absolute and relative timestamps for both. This should be used as a base for the proof of concepts in a red green refactor methodology.

[pjlee11]

Sareh, Alison, Marcos and Brian are performing a POC using date-fns. Myself, Ben, Che and Alex are performing a POC using dayjs.

[sareh]

Date-fns

Pros

• It is easy to get an absolute Gregorian date. dateFns.format(unixTimestamp * 1000, 'D MMMM YYYY');
• dateFns.format() can take a JS Date or a Unix timestamp as its first argument.

Cons

• There are few locales. No fa locale currently existing, so we would need to contribute these to the library.
• The API is not consistent between locales. e.g. for en you shouldn't pass in a locale, for non-en, you need to pass in a locale:

//en
dateFns.format(timestamp * 1000, 'd MMMM yyyy');
//fa
dateFns.format(timestamp * 1000, 'd MMMM yyyy', {locale: fa});

• There is no documentation for dateFns.formatRelative() on the default version of the documentation (https://date-fns.org/docs/Getting-Started), even though there are examples on the main page (https://date-fns.org/) The formatRelative function is available at npm i -S date-fns@next and documentation is https://date-fns.org/v2.0.0-alpha.23/docs/formatRelative

• Relative formatting is suitable for calendars, as in 'last Tuesday', not for '4 hours ago' items. We would have to add a new method for relative times to this library.

[bcmn]

dayjs

Pros

• It is easy to get an absolute Gregorian date. dayjs(unixTimestamp * 1000).format('D MMMM YYYY');
• Desired relative formatting easily through use of RelativeTime plug-in -- & works in such a way that internationalisation is easy. dayjs(publishedTimestamp).from(dayjs(currentTimestamp));
• fa & a range of other locales already existing (albeit in some cases with only basic month/day translations), & easily expandable, with a clear template.
• Gzipped size in bundle report as 3.1kb with both timestamps working

Cons (or areas that would need to be explored, at the very least...)

• Non-arabic numerals (i.e. non-0 1 2 3 4 5 6 7 8 9) are not currently possible -- the Persian (& Pashto?) service would be expected to use Eastern Arabic Numerals (i.e. ۰۱۲۳۴۵۶۷۸۹).
• Non-gregorian calendars are not currently possible -- the Persian & Pashto services currently utilise the Jalali calendar, so this would be needed to maintain the same functionality.
• Similar to date-fns, the API is not consistent between locales -- defaulting to en. In the code, this anglocentrism is even more pervasive, as en does not even have a locale file like other languages, but is defaulted inline throughout the codebase.
• No timezone support (this needs to be explored further in a different POC, we are assuming we should be able to use in parallel with moment-timezone.)
• The implementation of plugins, & how they might be conditionally pulled in, seems unclear -- relativeTime, for example, exists within the dayjs files -- it's unclear whether it would only be pulled in when needed, or if it is bundled alongside any request that includes DayJS. import relativeTime from 'dayjs/plugin/relativeTime';

---

The proof of concept is on the branch dayjs.

If I get a chance, I might have a quick look into using moment-timezone alongside dayjs to verify our current assumption that it would be possible to use the two together.

[pjlee11]

Following the 2 POC's we have the following questions: 1) Which non-Gregorian calendars do we need to support? Jim to ask WS product and WS editorial 2) How much work is it to override numerals for a given locale in dayjs? 3) In the short term could we implement the math for a conversion to the Jalali calendar locally before attempting to get changes made in dayjs? 4) Is a dual calendar a useful real world thing or is it very BBC specific and therefore should we use a library to create a Gregorian calendar, a Jalali calendar and combine them within our codebase?

Answers 2) We should POC locally overriding the latin numerals

[jimjohnsonrollings]

• Pashto also uses both Jalali and Gregorian
• Arabic uses two different names for each month
• Amharic would like to use the Ethiopian calendar - it may also be the case for Oromo and Tigrinya (answer to be continued...)

[bcmn]

• POC: Moment.js with locales and timezone
• POC: Date-fns - Findings
• ~POC: Date-fns with moment timezone~ (From the above findings we don't think date-fns supports our use case)
• POC: Day.js Findings
• POC: Day.js with moment timezone
• SPIKE: Make moment more granular and locked into a single locale, could be raised as an issue/question in moment's github repo

Following up on this, from their docs, it does not appear it is possible to use moment-timezone with non-moment libraries:

To use moment-timezone, you will need moment@2.9.0+, moment-timezone.js, and the moment-timezone data.

[bcmn]

Just to quickly show how big an impact Moment & Moment-timezone has on the webpack bundle report, following a very quick look into it this morning:

With DayJS

With Moment

[bcmn]

Just to document all these thoughts somewhere: I recently tried to make a proof of concept of the numeral switching we'd discussed adding to DayJS. While a basic implementation was possible, it raised some interesting issues:

• It's possible to easily add the behaviour to DayJS' default format function. It's easy to add to any format function.
• Realistically, it would likely want to be an optional behaviour. This might be achieved by a parameter, but a way of achieving it that's more consistent with DayJS' structure would seem to be a plugin.
• However, this starts raising the issue of how we handle the different functions that return text containing numerals.
• DayJS' .format, the advancedFormat plugin, & the relativeTime format plugin should all be affected by the numeral switching. I couldn't see an obvious way of achieving this in one fell swoop. It doesn't feel like something that each plugin should have to consider before returning.
• It might be possible to achieve using some strange binding solution, similar to how advancedFormat already works? But I'm not sure it feels great.

I plan to open an issue/talk it over with the DayJS devs to see if they have a preferred solution I'm missing.

[bcmn]

Delayed because I was on holiday/accidentally deleted a draft, but here is the DayJS issue on non-arabic numerals.

[ChrisBAshton]

We tackled this recently in VJ: https://github.com/bbc/cmu-timeline/pull/21

TLDR; opted for toLocaleString, falling back to a simple dd/mm/YY format for browsers that don't support it. Wanted to avoid the bloat of a library.

[amywalkerdev]

• we decided to stay with Momentjs for now
• we are first going to look into bundle splitting and how it works for News + the new WS services we’re introducing
• currently the idea is to look at splitting per service and optimising that since it’s very unlikely we will get people going to multiple services, e.g. Russian service user going to Mundo and then Thai
• the reason why we decided to stay with Moment for now is because it already contains logic for dealing with timezones and dealing with timezones is difficult enough
• we already have to figure out bundle splitting for all the services so by doing this work we’re kind of killing two birds with one stone
• each bundle will most likely contain information like service config, translations, locales, typography

  1602