@koech/esm-core 8.0.0

package/packages/framework/esm-utils/src/dates/date-util.ts

@@ -0,0 +1,429 @@
+/**
+ * @module
+ * @category Date and Time
+ */
+import {
+  type CalendarDate,
+  type CalendarDateTime,
+  type CalendarIdentifier,
+  type ZonedDateTime,
+  createCalendar,
+  toCalendar,
+} from '@internationalized/date';
+import { DurationFormat } from '@formatjs/intl-durationformat';
+import { attempt } from 'any-date-parser';
+import dayjs from 'dayjs';
+import isToday from 'dayjs/plugin/isToday.js';
+import objectSupport from 'dayjs/plugin/objectSupport.js';
+import utc from 'dayjs/plugin/utc.js';
+import { isNil, omit } from 'lodash-es';
+import { getLocale } from '../';
+import type { DurationFormatOptions, DurationInput } from '@formatjs/intl-durationformat/src/types';
+
+dayjs.extend(isToday);
+dayjs.extend(utc);
+dayjs.extend(objectSupport);
+
+export type DateInput = string | number | Date;
+
+const isoFormat = 'YYYY-MM-DDTHH:mm:ss.SSSZZ';
+
+/**
+ * This function checks whether a date string is the OpenMRS ISO format.
+ * The format should be YYYY-MM-DDTHH:mm:ss.SSSZZ
+ */
+export function isOmrsDateStrict(omrsPayloadString: string): boolean {
+  // omrs format 2018-03-19T00:00:00.000+0300
+  if (omrsPayloadString === null || omrsPayloadString === undefined || omrsPayloadString.trim().length !== 28) {
+    return false;
+  }
+  omrsPayloadString = omrsPayloadString.trim();
+
+  // 11th character will always be T
+  if (omrsPayloadString[10] !== 'T') {
+    return false;
+  }
+
+  // checking time format
+  if (omrsPayloadString[13] !== ':' || omrsPayloadString[16] !== ':' || omrsPayloadString[19] !== '.') {
+    return false;
+  }
+
+  // checking UTC offset format
+  if (!(omrsPayloadString[23] === '+' || omrsPayloadString[23] === '-')) {
+    return false;
+  }
+
+  return dayjs(omrsPayloadString, isoFormat).isValid();
+}
+
+/**
+ *
+ * @param date Checks if the provided date is today.
+ */
+export function isOmrsDateToday(date: DateInput) {
+  return dayjs(date).isToday();
+}
+
+/**
+ * Converts the object to a date object if it is an OpenMRS ISO date time string.
+ * Otherwise returns null.
+ */
+export function toDateObjectStrict(omrsDateString: string): Date | null {
+  if (!isOmrsDateStrict(omrsDateString)) {
+    return null;
+  }
+
+  return dayjs(omrsDateString, isoFormat).toDate();
+}
+
+/**
+ * Formats the input to OpenMRS ISO format: "YYYY-MM-DDTHH:mm:ss.SSSZZ".
+ */
+export function toOmrsIsoString(date: DateInput, toUTC = false): string {
+  let d = dayjs(date);
+
+  if (toUTC) {
+    d = d.utc();
+  }
+
+  return d.format(isoFormat);
+}
+
+/**
+ * Utility function to parse an arbitrary string into a date.
+ * Uses `dayjs(dateString)`.
+ */
+export function parseDate(dateString: string) {
+  return dayjs(dateString).toDate();
+}
+
+/**
+ * Internal cache for per-locale calendars
+ */
+class LocaleCalendars {
+  #registry = new Map<string, CalendarIdentifier>();
+
+  constructor() {}
+
+  register(locale: string, calendar: CalendarIdentifier) {
+    this.#registry.set(locale, calendar);
+  }
+
+  getCalendar(locale: Intl.Locale): CalendarIdentifier | undefined {
+    if (!Boolean(locale)) {
+      return undefined;
+    }
+
+    if (locale.calendar) {
+      return locale.calendar as CalendarIdentifier;
+    }
+
+    if (locale.region) {
+      const key = `${locale.language}-${locale.region}`;
+      if (this.#registry.has(key)) {
+        return this.#registry.get(key);
+      }
+    }
+
+    if (locale.language && this.#registry.has(locale.language)) {
+      return this.#registry.get(locale.language);
+    }
+
+    const defaultCalendar = new Intl.DateTimeFormat(locale.toString()).resolvedOptions().calendar as CalendarIdentifier;
+
+    // cache this result
+    this.#registry.set(`${locale.language}${locale.region ? `-${locale.region}` : ''}`, defaultCalendar);
+
+    return defaultCalendar;
+  }
+}
+
+const registeredLocaleCalendars = new LocaleCalendars();
+
+/**
+ * Provides the name of the calendar to associate, as a default, with the given base locale.
+ *
+ * @example
+ * ```
+ * registerDefaultCalendar('en', 'buddhist') // sets the default calendar for the 'en' locale to Buddhist.
+ * ```
+ *
+ * @param locale the locale to register this calendar for
+ * @param calendar the calendar to use for this registration
+ */
+export function registerDefaultCalendar(locale: string, calendar: CalendarIdentifier) {
+  registeredLocaleCalendars.register(locale, calendar);
+}
+
+/**
+ * Retrieves the default calendar for the specified locale if any.
+ *
+ * @param locale the locale to look-up
+ */
+export function getDefaultCalendar(locale: Intl.Locale | string | undefined) {
+  const locale_ = locale ?? getLocale();
+
+  return registeredLocaleCalendars.getCalendar(locale_ instanceof Intl.Locale ? locale_ : new Intl.Locale(locale_));
+}
+
+export type FormatDateMode = 'standard' | 'wide';
+
+export type FormatDateOptions = {
+  /**
+   * The calendar to use when formatting this date.
+   */
+  calendar?: string;
+  /**
+   * The locale to use when formatting this date
+   */
+  locale?: string;
+  /**
+   * - `standard`: "03 Feb 2022"
+   * - `wide`:     "03 — Feb — 2022"
+   */
+  mode: FormatDateMode;
+  /**
+   * Whether the time should be included in the output always (`true`),
+   * never (`false`), or only when the input date is today (`for today`).
+   */
+  time: true | false | 'for today';
+  /** Whether to include the day number */
+  day: boolean;
+  /** Whether to include the month number */
+  month: boolean;
+  /** Whether to include the year */
+  year: boolean;
+  /** The unicode numbering system to use */
+  numberingSystem?: string;
+  /**
+   * Disables the special handling of dates that are today. If false
+   * (the default), then dates that are today will be formatted as "Today"
+   * in the locale language. If true, then dates that are today will be
+   * formatted the same as all other dates.
+   */
+  noToday: boolean;
+};
+
+const defaultOptions: FormatDateOptions = {
+  mode: 'standard',
+  time: 'for today',
+  day: true,
+  month: true,
+  year: true,
+  noToday: false,
+};
+
+/**
+ * Formats the string representing a date, including partial representations of dates, according to the current
+ * locale and the given options.
+ *
+ * Default options:
+ *  - mode: "standard",
+ *  - time: "for today",
+ *  - day: true,
+ *  - month: true,
+ *  - year: true
+ *  - noToday: false
+ *
+ * If the date is today then "Today" is produced (in the locale language).
+ * This behavior can be disabled with `noToday: true`.
+ *
+ * When time is included, it is appended with a comma and a space. This
+ * agrees with the output of `Date.prototype.toLocaleString` for *most*
+ * locales.
+ */
+// TODO: Shouldn't throw on null input
+export function formatPartialDate(dateString: string, options: Partial<FormatDateOptions> = {}) {
+  const locale = getLocale();
+  let parsed: ReturnType<typeof attempt> & { date?: number } = attempt(dateString, locale);
+
+  if (parsed.invalid) {
+    console.warn(`Could not parse invalid date '${dateString}'`);
+    return null;
+  }
+
+  // hack here but any date interprets 2000-01, etc. as yyyy-dd rather than yyyy-mm
+  if (!isNil(parsed.day) && isNil(parsed.month)) {
+    parsed = Object.assign({}, omit(parsed, 'day'), { month: parsed.day });
+  }
+
+  // dayjs' object support uses 0-based months, whereas any-date-parser uses 1-based months
+  if (parsed.month) {
+    parsed.month -= 1;
+  }
+
+  // in dayjs day is day of week; in any-date-parser, its day of month, so we need to convert them
+  if (parsed.day) {
+    parsed = Object.assign({}, omit(parsed, 'day'), { date: parsed.day });
+  }
+
+  const date = dayjs().set(parsed).toDate();
+
+  if (isNil(parsed.year)) {
+    options.year = false;
+  }
+
+  if (isNil(parsed.month)) {
+    options.month = false;
+  }
+
+  if (isNil(parsed.date)) {
+    options.day = false;
+  }
+
+  return formatDate(date, options);
+}
+
+/**
+ * Formats the input date according to the current locale and the
+ * given options.
+ *
+ * Default options:
+ *  - mode: "standard",
+ *  - time: "for today",
+ *  - day: true,
+ *  - month: true,
+ *  - year: true
+ *  - noToday: false
+ *
+ * If the date is today then "Today" is produced (in the locale language).
+ * This behavior can be disabled with `noToday: true`.
+ *
+ * When time is included, it is appended with a comma and a space. This
+ * agrees with the output of `Date.prototype.toLocaleString` for *most*
+ * locales.
+ */
+// TODO: Shouldn't throw on null input
+export function formatDate(date: Date, options?: Partial<FormatDateOptions>) {
+  let locale = options?.locale ?? getLocale();
+  const _locale = new Intl.Locale(locale);
+
+  const { calendar, mode, time, day, month, year, noToday, numberingSystem }: FormatDateOptions = {
+    ...defaultOptions,
+    ...{ noToday: _locale.language === 'am' ? true : false },
+    ...options,
+  };
+
+  const formatCalendar = calendar ?? getDefaultCalendar(_locale);
+
+  const formatterOptions: Intl.DateTimeFormatOptions = {
+    calendar: formatCalendar,
+    year: year ? 'numeric' : undefined,
+    month: month ? 'short' : undefined,
+    day: day ? '2-digit' : undefined,
+    numberingSystem,
+  };
+
+  let localeString: string;
+  const isToday = dayjs(date).isToday();
+  if (isToday && !noToday) {
+    // This produces the word "Today" in the language of `locale`
+    const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+    localeString = rtf.format(0, 'day');
+    localeString = localeString[0].toLocaleUpperCase(locale) + localeString.slice(1);
+  } else {
+    if (_locale.language === 'en') {
+      // This locale override is here rather than in `getLocale`
+      // because Americans should see AM/PM for times.
+      locale = 'en-GB';
+    }
+
+    const formatter = new Intl.DateTimeFormat(locale, formatterOptions);
+    let parts = formatter.formatToParts(date);
+
+    if ((_locale.language === 'en' || _locale.language === 'am') && mode == 'standard' && year && day) {
+      // Custom formatting for English and Amharic. Use hyphens instead of spaces.
+      parts = parts.map(formatParts('-'));
+    }
+
+    if (mode == 'wide') {
+      parts = parts.map(formatParts(' — ')); // space-emdash-space
+    }
+
+    // omit the era when using the Ethiopic calendar
+    if (formatterOptions.calendar === 'ethiopic') {
+      parts = parts.filter((part, idx, values) => {
+        if (
+          part.type === 'era' ||
+          (part.type === 'literal' && idx < values.length - 1 && values[idx + 1].type === 'era')
+        ) {
+          return false;
+        }
+
+        return true;
+      });
+    }
+
+    localeString = parts.map((p) => p.value).join('');
+  }
+  if (time === true || (isToday && time === 'for today')) {
+    localeString += `, ${formatTime(date)}`;
+  }
+  return localeString;
+}
+
+// Internal curried call-back for map()
+const formatParts = (separator: string) => {
+  return (part: Intl.DateTimeFormatPart, idx: number, values: Array<Intl.DateTimeFormatPart>) => {
+    if (part.type !== 'literal' || part.value !== ' ') {
+      return part;
+    }
+
+    if (idx < values.length - 1 && values[idx + 1].type === 'era') {
+      return part;
+    }
+
+    return { type: 'literal', value: separator } as Intl.DateTimeFormatPart;
+  };
+};
+
+/**
+ * Formats the input as a time, according to the current locale.
+ * 12-hour or 24-hour clock depends on locale.
+ */
+export function formatTime(date: Date) {
+  return date.toLocaleTimeString(getLocale(), {
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+}
+
+/**
+ * Formats the input into a string showing the date and time, according
+ * to the current locale. The `mode` parameter is as described for
+ * `formatDate`.
+ *
+ * This is created by concatenating the results of `formatDate`
+ * and `formatTime` with a comma and space. This agrees with the
+ * output of `Date.prototype.toLocaleString` for *most* locales.
+ */
+export function formatDatetime(date: Date, options?: Partial<Omit<FormatDateOptions, 'time'>>) {
+  return formatDate(date, { ...options, time: true });
+}
+
+/**
+ * Converts a calendar date to the equivalent locale calendar date.
+ * @returns CalendarDate
+ */
+export function convertToLocaleCalendar(
+  date: CalendarDate | CalendarDateTime | ZonedDateTime,
+  locale: string | Intl.Locale,
+) {
+  let locale_ = typeof locale === 'string' ? new Intl.Locale(locale) : locale;
+  const localCalendarName = getDefaultCalendar(locale_);
+
+  return localCalendarName ? toCalendar(date, createCalendar(localCalendarName)) : date;
+}
+
+/**
+ * Formats the input duration according to the current locale.
+ *
+ * @param duration The duration to format (DurationInput object).
+ * @param options Optional options for formatting.
+ * @returns The formatted duration string.
+ */
+export function formatDuration(duration: DurationInput, options?: DurationFormatOptions) {
+  const formatter = new DurationFormat(getLocale(), options);
+  return formatter.format(duration);
+}

package/packages/framework/esm-utils/src/dates/index.ts

@@ -0,0 +1 @@
+export * from './date-util';

package/packages/framework/esm-utils/src/get-locale.ts

@@ -0,0 +1,14 @@
+/**
+ * Returns the current locale of the application.
+ * @returns string
+ */
+export function getLocale() {
+  let language = window.i18next.language;
+  language = language.replace('_', '-'); // just in case
+  // Hack for `ht` until all browsers update their unicode support with ht to fr mapping.
+  // See https://unicode-org.atlassian.net/browse/CLDR-14956
+  if (language === 'ht') {
+    language = 'fr-HT';
+  }
+  return language;
+}

package/packages/framework/esm-utils/src/index.ts

@@ -0,0 +1,10 @@
+export * from './age-helpers';
+export * from './dates';
+export * from './get-locale';
+export * from './is-online';
+export * from './patient-helpers';
+export * from './shallowEqual';
+export * from './storage';
+export * from './test-helpers';
+export * from './version';
+export * from './retry';

package/packages/framework/esm-utils/src/is-online.ts

@@ -0,0 +1,5 @@
+import type {} from '@openmrs/esm-globals';
+
+export function isOnline(online?: boolean) {
+  return window.offlineEnabled ? online ?? navigator.onLine : true;
+}

package/packages/framework/esm-utils/src/patient-helpers.test.data.ts

@@ -0,0 +1,146 @@
+export const nameWithFormat = {
+  id: 'efdb246f-4142-4c12-a27a-9be60b9592e9',
+  family: 'Wilson',
+  given: ['John'],
+  text: 'Wilson, John',
+};
+
+export const nameWithoutFormat = {
+  id: 'efdb246f-4142-4c12-a27a-9be60b9592e9',
+  family: 'family name',
+  given: ['given', 'middle'],
+};
+
+export const familyNameOnly = {
+  id: 'efdb246f-4142-4c12-a27a-9be60b9592e9',
+  family: 'family name',
+};
+
+export const givenNameOnly = {
+  id: 'efdb246f-4142-4c12-a27a-9be60b9592e9',
+  given: ['given'],
+};
+
+export const mockPatient = {
+  resourceType: 'Patient',
+  id: '8673ee4f-e2ab-4077-ba55-4980f408773e',
+  extension: [
+    {
+      url: 'http://fhir-es.transcendinsights.com/stu3/StructureDefinition/resource-date-created',
+      valueDateTime: '2017-01-18T09:42:40+00:00',
+    },
+    {
+      url: 'https://purl.org/elab/fhir/StructureDefinition/Creator-crew-version1',
+      valueString: 'daemon',
+    },
+  ],
+  identifier: [
+    {
+      id: '1f0ad7a1-430f-4397-b571-59ea654a52db',
+      use: 'secondary',
+      system: 'Old Identification Number',
+      value: '100732HE',
+    },
+    {
+      id: '1f0ad7a1-430f-4397-b571-59ea654a52db',
+      use: 'usual',
+      system: 'OpenMRS ID',
+      value: '100GEJ',
+    },
+  ],
+  active: true,
+  name: [nameWithFormat],
+  gender: 'male',
+  birthDate: '1972-04-04',
+  deceasedBoolean: false,
+  address: [],
+};
+
+export const mockPatientWithNoName = {
+  ...mockPatient,
+  name: [],
+};
+
+export const mockPatientWithMultipleNames = {
+  // name usage may be: usual | official | temp | nickname | anonymous | old | maiden
+  ...mockPatient,
+  name: [
+    {
+      id: 'id-of-nickname-1',
+      use: 'nickname',
+      given: ['nick', 'name'],
+    },
+    {
+      id: 'id-of-nickname-2',
+      use: 'nickname',
+      given: ['nick', 'name'],
+    },
+    {
+      id: 'id-of-anonymous-name-1',
+      use: 'anonymous',
+      given: ['john', 'doe'],
+    },
+    {
+      id: 'id-of-old-name-1',
+      use: 'old',
+      given: ['previous'],
+      family: 'name',
+    },
+    {
+      id: 'id-of-maiden-name-1',
+      use: 'maiden',
+      family: 'maiden name',
+    },
+    {
+      // this is the actual display name
+      id: 'id-of-usual-name-1',
+      given: ['John', 'Murray'],
+      family: 'Smith',
+      text: 'Smith, John Murray',
+    },
+    {
+      // this is usable as a display name, but the usual name will take precedence.
+      id: 'id-of-official-name-1',
+      use: 'official',
+      given: ['my', 'official'],
+      family: 'name',
+    },
+  ],
+};
+
+export const mockPatientWithOfficialName = {
+  ...mockPatient,
+  name: [
+    {
+      // this is usable as a display name, but the usual name should be preferred
+      id: 'id-of-official-name-1',
+      use: 'official',
+      given: ['my', 'official'],
+      family: 'name',
+    },
+    {
+      // this is the preferred display name, even though it comes after the official name
+      id: 'id-of-usual-name-1',
+      use: 'usual', // explicitly marked as usual name
+      given: ['my', 'actual'],
+      family: 'name',
+    },
+  ],
+};
+
+export const mockPatientWithNickAndOfficialName = {
+  ...mockPatient,
+  name: [
+    {
+      id: 'id-of-nickname-1',
+      use: 'nickname',
+      given: ['nick', 'name'],
+    },
+    {
+      id: 'id-of-official-name-1',
+      use: 'official',
+      given: ['my', 'official'],
+      family: 'name',
+    },
+  ],
+};

package/packages/framework/esm-utils/src/patient-helpers.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import { type NameUse } from '@openmrs/esm-globals';
+import { formatPatientName, getPatientName, selectPreferredName } from './patient-helpers';
+import {
+  mockPatientWithNoName,
+  mockPatientWithOfficialName,
+  nameWithFormat,
+  nameWithoutFormat,
+  familyNameOnly,
+  givenNameOnly,
+  mockPatientWithMultipleNames,
+  mockPatientWithNickAndOfficialName,
+} from './patient-helpers.test.data';
+
+describe('Formatted display name', () => {
+  it.each([
+    [nameWithFormat, 'Wilson, John'],
+    [nameWithoutFormat, 'given middle family name'],
+    [familyNameOnly, 'family name'],
+    [givenNameOnly, 'given'],
+    [mockPatientWithNoName, ''],
+  ])('Is formatted name text if present else default name format', (name, expected) => {
+    const result = formatPatientName(name);
+    expect(result).toBe(expected);
+  });
+});
+
+describe('Patient display name', () => {
+  it.each([
+    [mockPatientWithMultipleNames, 'Smith, John Murray'],
+    [mockPatientWithOfficialName, 'my actual name'],
+    [mockPatientWithNickAndOfficialName, 'my official name'],
+  ])('Is selected from usual name or official name', (patient, expected) => {
+    const result = getPatientName(patient);
+    expect(result).toBe(expected);
+  });
+});
+
+const usual: NameUse = 'usual';
+const official: NameUse = 'official';
+const maiden: NameUse = 'maiden';
+const nickname: NameUse = 'nickname';
+const temp: NameUse = 'temp';
+
+describe('Preferred patient name', () => {
+  it.each([
+    [mockPatientWithMultipleNames, [], 'id-of-usual-name-1'],
+    [mockPatientWithMultipleNames, [usual], 'id-of-usual-name-1'],
+    [mockPatientWithMultipleNames, [usual, official], 'id-of-usual-name-1'],
+    [mockPatientWithMultipleNames, [official], 'id-of-official-name-1'],
+    [mockPatientWithMultipleNames, [official, usual], 'id-of-official-name-1'],
+    [mockPatientWithMultipleNames, [maiden, usual, official], 'id-of-maiden-name-1'],
+    [mockPatientWithOfficialName, [usual, official], 'id-of-usual-name-1'],
+    [mockPatientWithNickAndOfficialName, [nickname, official], 'id-of-nickname-1'],
+  ])('Is selected according to preferred usage', (patient, preferredUsage, expectedNameId) => {
+    const result = selectPreferredName(patient, ...preferredUsage);
+    expect(result?.id).toBe(expectedNameId);
+  });
+});
+
+describe('Preferred patient name', () => {
+  it.each([
+    [mockPatientWithMultipleNames, [temp]],
+    [mockPatientWithNoName, [usual]],
+    [mockPatientWithNoName, []],
+  ])('Is empty if preferred name is not present.', (patient, preferredUsage) => {
+    const result = selectPreferredName(patient, ...preferredUsage);
+    expect(result).toBeUndefined();
+  });
+});