feat: add timezone support to datetime parsing (#2099)

Author: MartinCupela

docusaurus/docs/React/guides/theming/translations.mdx

@@ -286,6 +286,28 @@ const i18n = new Streami18n({
 
 If you would like to stick with english language for dates and times in Stream components, you can set `disableDateTimeTranslations` to true.
 
+### Timezone location
+
+To display date and time in different than machine's local timezone, provide the `timezone` parameter to the `Streami18n` constructor. The `timezone` value has to be a [valid timezone identifier string](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). If no `timezone` parameter is provided, then the machine's local timezone is applied.
+
+```ts
+import { Streami18n } from 'stream-chat-react';
+
+const streamI18n = new Streami18n({ timezone: 'Europe/Prague'});
+```
+
+If you are using `moment` as your datetime parser engine and want to start using timezone-located datetime strings, then we recommend to use `moment-timezone` instead of `moment` package. Moment Timezone will automatically load and extend the moment module, then return the modified instance. This will also prevent multiple versions of `moment` being installed in a project.
+
+```ts
+import type momentTimezone from 'moment-timezone';
+import { Streami18n } from 'stream-chat-react';
+
+const i18n = new Streami18n({
+  DateTimeParser: momentTimezone,
+  timezone: 'Europe/Prague',
+})
+```
+
 ### Translating Messages
 
 Stream Chat provide the ability to run users' messages through automatic translation.
@@ -317,8 +339,7 @@ The `Streami18n` class wraps [`i18next`](https://www.npmjs.com/package/i18next)
 | logger                       | logs warnings/errors                                                                                                                                                 | function | () => {}   |
 | dayjsLocaleConfigForLanguage | internal Day.js [config object](https://github.com/iamkun/dayjs/tree/dev/src/locale) and [calendar locale config object](https://day.js.org/docs/en/plugin/calendar) | object   | 'enConfig' |
 | DateTimeParser               | custom date time parser                                                                                                                                              | function | Day.js     |
-
-####
+| timezone                     | valid timezone identifier string (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)                                                                                                                                             | function | Day.js     |
 
 ### Class Instance Methods
 

package.json

@@ -153,7 +153,7 @@
     "i18next-parser": "^6.0.0",
     "jest": "^26.6.3",
     "jest-axe": "^6.0.0",
-    "moment": "^2.29.1",
+    "moment-timezone": "^0.5.43",
     "postcss": "^8.1.10",
     "postcss-loader": "^4.1.0",
     "prettier": "^2.2.0",

src/context/TranslationContext.tsx

@@ -6,7 +6,7 @@ import localizedFormat from 'dayjs/plugin/localizedFormat';
 import { getDisplayName } from './utils/getDisplayName';
 
 import type { TFunction } from 'i18next';
-import type { Moment } from 'moment';
+import type { Moment } from 'moment-timezone';
 import type { TranslationLanguages } from 'stream-chat';
 
 import type { UnknownType } from '../types/types';

src/i18n/Streami18n.ts

@@ -5,8 +5,10 @@ import updateLocale from 'dayjs/plugin/updateLocale';
 import LocalizedFormat from 'dayjs/plugin/localizedFormat';
 import localeData from 'dayjs/plugin/localeData';
 import relativeTime from 'dayjs/plugin/relativeTime';
+import utc from 'dayjs/plugin/utc';
+import timezone from 'dayjs/plugin/timezone';
 
-import type moment from 'moment';
+import type momentTimezone from 'moment-timezone';
 import type { TranslationLanguages } from 'stream-chat';
 
 import type { TDateTimeParser } from '../context/TranslationContext';
@@ -57,6 +59,8 @@ type CalendarLocaleConfig = {
 };
 
 Dayjs.extend(updateLocale);
+Dayjs.extend(utc);
+Dayjs.extend(timezone);
 
 Dayjs.updateLocale('de', {
   calendar: {
@@ -227,17 +231,25 @@ const en_locale = {
   weekdays: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
 };
 
+type DateTimeParserModule = typeof Dayjs | typeof momentTimezone;
 // Type guards to check DayJs
-const isDayJs = (dateTimeParser: typeof Dayjs | typeof moment): dateTimeParser is typeof Dayjs =>
+const isDayJs = (dateTimeParser: DateTimeParserModule): dateTimeParser is typeof Dayjs =>
   (dateTimeParser as typeof Dayjs).extend !== undefined;
 
+type TimezoneParser = {
+  tz: momentTimezone.MomentTimezone | Dayjs.Dayjs;
+};
+const supportsTz = (dateTimeParser: unknown): dateTimeParser is TimezoneParser =>
+  (dateTimeParser as TimezoneParser).tz !== undefined;
+
 type Options = {
-  DateTimeParser?: typeof Dayjs | typeof moment;
+  DateTimeParser?: DateTimeParserModule;
   dayjsLocaleConfigForLanguage?: Partial<ILocale> & { calendar?: CalendarLocaleConfig };
   debug?: boolean;
   disableDateTimeTranslations?: boolean;
   language?: TranslationLanguages;
   logger?: (message?: string) => void;
+  timezone?: string;
   translationsForLanguage?: Partial<typeof enTranslations>;
 };
 
@@ -446,7 +458,7 @@ export class Streami18n {
    */
   logger: (msg?: string) => void;
   currentLanguage: TranslationLanguages;
-  DateTimeParser: typeof Dayjs | typeof moment;
+  DateTimeParser: DateTimeParserModule;
   isCustomDateTimeParser: boolean;
   i18nextConfig: {
     debug: boolean;
@@ -457,6 +469,10 @@ export class Streami18n {
     nsSeparator: false;
     parseMissingKeyHandler: (key: string) => string;
   };
+  /**
+   * A valid TZ identifier string (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
+   */
+  timezone?: string;
   /**
    * Constructor accepts following options:
    *  - language (String) default: 'en'
@@ -492,6 +508,7 @@ export class Streami18n {
     this.logger = finalOptions.logger;
     this.currentLanguage = finalOptions.language;
     this.DateTimeParser = finalOptions.DateTimeParser;
+    this.timezone = finalOptions.timezone;
 
     try {
       if (this.DateTimeParser && isDayJs(this.DateTimeParser)) {
@@ -561,21 +578,21 @@ export class Streami18n {
     }
 
     this.tDateTimeParser = (timestamp) => {
-      if (finalOptions.disableDateTimeTranslations || !this.localeExists(this.currentLanguage)) {
-        /**
-         * TS needs to know which is being called to accept the chain call
-         */
-        if (isDayJs(this.DateTimeParser)) {
-          return this.DateTimeParser(timestamp).locale(defaultLng);
-        }
-        return this.DateTimeParser(timestamp).locale(defaultLng);
-      }
+      const language =
+        finalOptions.disableDateTimeTranslations || !this.localeExists(this.currentLanguage)
+          ? defaultLng
+          : this.currentLanguage;
 
       if (isDayJs(this.DateTimeParser)) {
-        return this.DateTimeParser(timestamp).locale(this.currentLanguage);
+        return supportsTz(this.DateTimeParser)
+          ? this.DateTimeParser(timestamp).tz(this.timezone).locale(language)
+          : this.DateTimeParser(timestamp).locale(language);
       }
 
-      return this.DateTimeParser(timestamp).locale(this.currentLanguage);
+      if (supportsTz(this.DateTimeParser) && this.timezone) {
+        return this.DateTimeParser(timestamp).tz(this.timezone).locale(language);
+      }
+      return this.DateTimeParser(timestamp).locale(language);
     };
   }
 

src/i18n/__tests__/Streami18n.test.js

@@ -2,6 +2,7 @@
 import { Streami18n } from '../Streami18n';
 import { nanoid } from 'nanoid';
 import { default as Dayjs } from 'dayjs';
+import moment from 'moment-timezone';
 import { nlTranslations, frTranslations } from '../translations';
 import 'dayjs/locale/nl';
 import localeData from 'dayjs/plugin/localeData';
@@ -226,3 +227,36 @@ describe('setLanguage - switch to french', () => {
     }
   });
 });
+
+describe('Streami18n timezone', () => {
+  describe.each([
+    ['Dayjs', Dayjs],
+    ['moment', moment],
+  ])('%s', (moduleName, module) => {
+    it('is by default the local timezone', () => {
+      const streamI18n = new Streami18n({ DateTimeParser: module });
+      const date = new Date();
+      expect(streamI18n.tDateTimeParser(date).format('H')).toBe(date.getHours().toString());
+    });
+
+    it('can be set to different timezone on init', () => {
+      const streamI18n = new Streami18n({ DateTimeParser: module, timezone: 'Europe/Prague' });
+      const date = new Date();
+      expect(streamI18n.tDateTimeParser(date).format('H')).not.toBe(date.getHours().toString());
+      expect(streamI18n.tDateTimeParser(date).format('H')).not.toBe(
+        (date.getUTCHours() - 2).toString(),
+      );
+    });
+
+    it('is ignored if datetime parser does not support timezones', () => {
+      const tz = module.tz;
+      delete module.tz;
+
+      const streamI18n = new Streami18n({ DateTimeParser: module, timezone: 'Europe/Prague' });
+      const date = new Date();
+      expect(streamI18n.tDateTimeParser(date).format('H')).toBe(date.getHours().toString());
+
+      module.tz = tz;
+    });
+  });
+});

yarn.lock

@@ -10465,16 +10465,18 @@ modify-values@^1.0.0:
   resolved "https://registry.yarnpkg.com/modify-values/-/modify-values-1.0.1.tgz#b3939fa605546474e3e3e3c63d64bd43b4ee6022"
   integrity sha512-xV2bxeN6F7oYjZWTe/YPAy6MN2M+sL4u/Rlm2AHCIVGfo2p1yGmBHQ6vHehl4bRTZBdHu3TSkWdYgkwpYzAGSw==
 
-moment@*:
+moment-timezone@^0.5.43:
+  version "0.5.43"
+  resolved "https://registry.yarnpkg.com/moment-timezone/-/moment-timezone-0.5.43.tgz#3dd7f3d0c67f78c23cd1906b9b2137a09b3c4790"
+  integrity sha512-72j3aNyuIsDxdF1i7CEgV2FfxM1r6aaqJyLB2vwb33mXYyoyLly+F1zbWqhA3/bVIoJ4szlUoMbUnVdid32NUQ==
+  dependencies:
+    moment "^2.29.4"
+
+moment@*, moment@^2.29.4:
   version "2.29.4"
   resolved "https://registry.yarnpkg.com/moment/-/moment-2.29.4.tgz#3dbe052889fe7c1b2ed966fcb3a77328964ef108"
   integrity sha512-5LC9SOxjSc2HF6vO2CyuTDNivEdoz2IvyJJGj6X8DJ0eFyfszE0QiEd+iXmBvUP3WHxSjFH/vIsA0EN00cgr8w==
 
-moment@^2.29.1:
-  version "2.29.2"
-  resolved "https://registry.yarnpkg.com/moment/-/moment-2.29.2.tgz#00910c60b20843bcba52d37d58c628b47b1f20e4"
-  integrity sha512-UgzG4rvxYpN15jgCmVJwac49h9ly9NurikMWGPdVxm8GZD6XjkKPxDTjQQ43gtGgnV3X0cAyWDdP2Wexoquifg==
-
 move-concurrently@^1.0.1:
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/move-concurrently/-/move-concurrently-1.0.1.tgz#be2c005fda32e0b29af1f05d7c4b33214c701f92"