@openmrs/esm-utils 9.0.3-pre.4260 → 9.0.3-pre.4264

package/src/age-helpers.ts

@@ -1,57 +1,33 @@
 /** @module @category Utility */
-import { attempt } from 'any-date-parser';
 import dayjs from 'dayjs';
-import objectSupport from 'dayjs/plugin/objectSupport.js';
-import { omit } from 'lodash-es';
-import { getLocale } from './get-locale';
-
-dayjs.extend(objectSupport);
+import { formatDuration, parseDateInput } from './dates/date-util';
 
 /**
- * Gets a human readable and locale supported representation of a person's age, given their birthDate,
- * The representation logic follows the guideline here:
- * https://webarchive.nationalarchives.gov.uk/ukgwa/20160921162509mp_/http://systems.digital.nhs.uk/data/cui/uig/patben.pdf
- * (See Tables 7 and 8)
+ * Gets the age of a person as a structured duration object, following NHS Digital guidelines
+ * (Tables 7 and 8) for which units to include based on the person's age.
  *
- * @param birthDate The birthDate. If birthDate is null, returns null.
- * @param currentDate Optional. If provided, calculates the age of the person at the provided currentDate (instead of now).
- * @returns A human-readable string version of the age.
+ * @see https://webarchive.nationalarchives.gov.uk/ukgwa/20160921162509mp_/http://systems.digital.nhs.uk/data/cui/uig/patben.pdf
+ * @param birthDate The birthDate. If null, returns null.
+ * @param currentDate Optional. If provided, calculates the age at the provided date instead of now.
+ * @returns A DurationInput object, or null if birthDate is null or unparseable.
+ *
+ * @example
+ * // For infants, returns fine-grained units
+ * ageAsDuration('2024-07-29', '2024-07-30') // => { hours: 24 }
+ *
+ * @example
+ * // For adults (>= 18), returns years only
+ * ageAsDuration('2000-01-15', '2024-07-30') // => { years: 24 }
  */
-export function age(birthDate: dayjs.ConfigType, currentDate: dayjs.ConfigType = dayjs()): string | null {
-  if (birthDate == null) {
-    return null;
-  }
-
-  const locale = getLocale();
-
+export function ageAsDuration(
+  birthDate: dayjs.ConfigType,
+  currentDate: dayjs.ConfigType = dayjs(),
+): Intl.DurationInput | null {
   const to = dayjs(currentDate);
-  let from: dayjs.Dayjs;
-
-  if (typeof birthDate === 'string') {
-    let parsedDate = attempt(birthDate, locale);
-    if (parsedDate.invalid) {
-      console.warn(`Could not interpret '${birthDate}' as a date`);
-      return null;
-    }
-
-    // hack here but any date interprets 2000-01, etc. as yyyy-dd rather than yyyy-mm
-    if (parsedDate.day && !parsedDate.month) {
-      parsedDate = Object.assign({}, omit(parsedDate, 'day'), { month: parsedDate.day });
-    }
-
-    // dayjs' object support uses 0-based months, whereas any-date-parser uses 1-based months
-    if (parsedDate.month) {
-      parsedDate.month -= 1;
-    }
+  const from = parseDateInput(birthDate, to);
 
-    // in dayjs day is day of week; in any-date-parser, its day of month, so we need to convert them
-    if (parsedDate.day) {
-      parsedDate = Object.assign({}, omit(parsedDate, 'day'), { date: parsedDate.day });
-    }
-
-    from = dayjs(to).set(parsedDate);
-  } else {
-    from = dayjs(birthDate);
+  if (from == null) {
+    return null;
   }
 
   const hourDiff = to.diff(from, 'hours');
@@ -61,14 +37,9 @@ export function age(birthDate: dayjs.ConfigType, currentDate: dayjs.ConfigType =
   const yearDiff = to.diff(from, 'years');
 
   const duration: Intl.DurationInput = {};
-  const options: Intl.DurationFormatOptions = { style: 'short', localeMatcher: 'lookup' };
 
   if (hourDiff < 2) {
-    const minuteDiff = to.diff(from, 'minutes');
-    duration['minutes'] = minuteDiff;
-    if (minuteDiff === 0) {
-      options.minutesDisplay = 'always';
-    }
+    duration['minutes'] = to.diff(from, 'minutes');
   } else if (dayDiff < 2) {
     duration['hours'] = hourDiff;
   } else if (weekDiff < 4) {
@@ -89,5 +60,38 @@ export function age(birthDate: dayjs.ConfigType, currentDate: dayjs.ConfigType =
     duration['years'] = yearDiff;
   }
 
-  return new Intl.DurationFormat(locale, options).format(duration);
+  return duration;
+}
+
+/**
+ * Gets a human readable and locale supported representation of a person's age, given their birthDate,
+ * The representation logic follows the guideline here:
+ * https://webarchive.nationalarchives.gov.uk/ukgwa/20160921162509mp_/http://systems.digital.nhs.uk/data/cui/uig/patben.pdf
+ * (See Tables 7 and 8)
+ *
+ * @param birthDate The birthDate. If birthDate is null, returns null.
+ * @param currentDate Optional. If provided, calculates the age of the person at the provided currentDate (instead of now).
+ * @returns A human-readable string version of the age.
+ *
+ * @example
+ * age('2020-02-29', '2024-07-30') // => '4 yrs, 5 mths'
+ *
+ * @example
+ * // String dates with partial precision are supported
+ * age('2000', '2024-07-30') // => '24 yrs'
+ */
+export function age(birthDate: dayjs.ConfigType, currentDate: dayjs.ConfigType = dayjs()): string | null {
+  const durationInput = ageAsDuration(birthDate, currentDate);
+
+  if (durationInput == null) {
+    return null;
+  }
+
+  const options: Intl.DurationFormatOptions = { style: 'short', localeMatcher: 'lookup' };
+
+  if ('minutes' in durationInput && durationInput.minutes === 0) {
+    options.minutesDisplay = 'always';
+  }
+
+  return formatDuration(durationInput, options);
 }

package/src/dates/date-util.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { afterAll, describe, expect, it } from 'vitest';
 import dayjs from 'dayjs';
 import timezoneMock from 'timezone-mock';
 import type { i18n } from 'i18next';
@@ -12,11 +12,15 @@ import {
   registerDefaultCalendar,
   formatPartialDate,
   formatDuration,
+  duration,
+  formatDurationBetween,
 } from './date-util';
 
 window.i18next = { language: 'en' } as i18n;
 
 describe('Openmrs Dates', () => {
+  afterAll(() => timezoneMock.unregister());
+
   it('converts js Date object to omrs date string version', () => {
     let date = dayjs('2018-03-19T00:05:03.999+0300', 'YYYY-MM-DDTHH:mm:ss.SSSZZ').toDate();
     expect(toOmrsIsoString(date, true)).toEqual('2018-03-18T21:05:03.999+0000');
@@ -200,13 +204,297 @@ describe('Openmrs Dates', () => {
 
   it('formats duration with respect to the locale', () => {
     window.i18next.language = 'en';
-    const duration = { hours: 1, minutes: 1, seconds: 1, days: 1, months: 1, years: 1 };
-    expect(formatDuration(duration, { style: 'narrow' })).toMatch(/1y.*1m.*1d.*1h.*1m.*1s/);
-    expect(formatDuration(duration, { style: 'short' })).toMatch(
-      /1\s+yr,.*1\s+mth,.*1\s+day,.*1\s+hr,.*1\s+min,.*1\s+sec/,
-    );
-    expect(formatDuration(duration, { style: 'long' })).toMatch(
+    const dur = { hours: 1, minutes: 1, seconds: 1, days: 1, months: 1, years: 1 };
+    expect(formatDuration(dur, { style: 'narrow' })).toMatch(/1y.*1m.*1d.*1h.*1m.*1s/);
+    expect(formatDuration(dur, { style: 'short' })).toMatch(/1\s+yr,.*1\s+mth,.*1\s+day,.*1\s+hr,.*1\s+min,.*1\s+sec/);
+    expect(formatDuration(dur, { style: 'long' })).toMatch(
       /1\s+year,.*1\s+month,.*1\s+day,.*1\s+hour,.*1\s+minute,.*1\s+second/,
     );
   });
 });
+
+describe('duration', () => {
+  const now = dayjs('2024-07-30T08:30:55Z');
+
+  it('returns null for null startDate', () => {
+    expect(duration(null, now)).toBeNull();
+  });
+
+  describe('auto-selected units', () => {
+    it.each([
+      {
+        label: '0 seconds ago',
+        startDate: now,
+        expected: { seconds: 0 },
+      },
+      {
+        label: '30 seconds ago',
+        startDate: now.subtract(30, 'seconds'),
+        expected: { seconds: 30 },
+      },
+      {
+        label: '44 seconds ago (still seconds)',
+        startDate: now.subtract(44, 'seconds'),
+        expected: { seconds: 44 },
+      },
+      {
+        label: '45 seconds ago (switches to minutes)',
+        startDate: now.subtract(45, 'seconds'),
+        expected: { minutes: 0 },
+      },
+      {
+        label: '30 minutes ago',
+        startDate: now.subtract(30, 'minutes'),
+        expected: { minutes: 30 },
+      },
+      {
+        label: '44 minutes ago (still minutes)',
+        startDate: now.subtract(44, 'minutes'),
+        expected: { minutes: 44 },
+      },
+      {
+        label: '45 minutes ago (switches to hours)',
+        startDate: now.subtract(45, 'minutes'),
+        expected: { hours: 0 },
+      },
+      {
+        label: '10 hours ago',
+        startDate: now.subtract(10, 'hours'),
+        expected: { hours: 10 },
+      },
+      {
+        label: '22 hours ago (switches to days)',
+        startDate: now.subtract(22, 'hours'),
+        expected: { days: 0 },
+      },
+      {
+        label: '20 days ago',
+        startDate: now.subtract(20, 'days'),
+        expected: { days: 20 },
+      },
+      {
+        label: '26 days ago (switches to months)',
+        startDate: now.subtract(26, 'days'),
+        expected: { months: 0 },
+      },
+      {
+        label: '6 months ago',
+        startDate: now.subtract(6, 'months'),
+        expected: { months: 6 },
+      },
+      {
+        label: '11 months ago (switches to years)',
+        startDate: now.subtract(11, 'months'),
+        expected: { years: 0 },
+      },
+      {
+        label: '3 years ago',
+        startDate: now.subtract(3, 'years'),
+        expected: { years: 3 },
+      },
+    ])('returns $expected for $label', ({ startDate, expected }) => {
+      expect(duration(startDate, now)).toEqual(expected);
+    });
+  });
+
+  describe('explicit unit', () => {
+    it.each([
+      { unit: 'days' as const, expected: { days: 366 } },
+      { unit: 'hours' as const, expected: { hours: 8784 } },
+      { unit: 'months' as const, expected: { months: 12 } },
+      { unit: 'years' as const, expected: { years: 1 } },
+      { unit: 'year' as const, expected: { years: 1 } },
+    ])('returns $expected for explicit unit "$unit"', ({ unit, expected }) => {
+      const oneYearAgo = now.subtract(1, 'year');
+      expect(duration(oneYearAgo, now, unit)).toEqual(expected);
+    });
+  });
+
+  describe('string dates', () => {
+    it('handles year-only string', () => {
+      expect(duration('2000', now)).toEqual({ years: 24 });
+    });
+
+    it('handles year-month string', () => {
+      expect(duration('2020-06', now)).toEqual({ years: 4 });
+    });
+
+    it('handles full date string', () => {
+      expect(duration('2024-07-30', now)).toEqual({ seconds: 0 });
+    });
+
+    it('returns null for invalid string', () => {
+      expect(duration('not a date', now)).toBeNull();
+    });
+  });
+
+  describe('custom thresholds', () => {
+    it('uses custom seconds threshold', () => {
+      const thirtySecondsAgo = now.subtract(30, 'seconds');
+      // Default threshold is 45, so 30s would be seconds. With threshold 20, it should be minutes.
+      expect(duration(thirtySecondsAgo, now, { thresholds: { seconds: 20 } })).toEqual({ minutes: 0 });
+    });
+
+    it('uses custom days threshold', () => {
+      const twentyDaysAgo = now.subtract(20, 'days');
+      // Default threshold is 26, so 20 days would be days. With threshold 15, it should be months.
+      expect(duration(twentyDaysAgo, now, { thresholds: { days: 15 } })).toEqual({ months: 0 });
+    });
+  });
+
+  describe('multi-unit decomposition', () => {
+    it('decomposes years, months, days', () => {
+      const start = now.subtract(2, 'years').subtract(3, 'months').subtract(15, 'days');
+      const result = duration(start, now, { largestUnit: 'years', smallestUnit: 'days' });
+      expect(result).toEqual({ years: 2, months: 3, days: 15 });
+    });
+
+    it('decomposes hours and minutes', () => {
+      const start = now.subtract(5, 'hours').subtract(30, 'minutes');
+      const result = duration(start, now, { largestUnit: 'hours', smallestUnit: 'minutes' });
+      expect(result).toEqual({ hours: 5, minutes: 30 });
+    });
+
+    it('accepts singular unit forms', () => {
+      const start = now.subtract(2, 'years').subtract(3, 'months');
+      const result = duration(start, now, { largestUnit: 'year', smallestUnit: 'month' });
+      expect(result).toEqual({ years: 2, months: 3 });
+    });
+
+    it('single unit when largestUnit === smallestUnit', () => {
+      const start = now.subtract(100, 'days');
+      const result = duration(start, now, { largestUnit: 'days', smallestUnit: 'days' });
+      expect(result).toEqual({ days: 100 });
+    });
+
+    it('defaults smallestUnit to largestUnit when only largestUnit is given', () => {
+      const start = now.subtract(100, 'days');
+      const result = duration(start, now, { largestUnit: 'days' });
+      expect(result).toEqual({ days: 100 });
+    });
+
+    it('defaults smallestUnit to largestUnit for single-unit result', () => {
+      const start = now.subtract(2, 'years').subtract(3, 'months');
+      const result = duration(start, now, { largestUnit: 'months' });
+      expect(result).toEqual({ months: 27 });
+    });
+  });
+
+  describe('largestUnit auto', () => {
+    it('finds the largest non-zero unit', () => {
+      const start = now.subtract(3, 'months').subtract(5, 'days');
+      const result = duration(start, now, { largestUnit: 'auto', smallestUnit: 'days' });
+      expect(result).toEqual({ months: 3, days: 5 });
+    });
+
+    it('falls back to smallestUnit when diff is zero', () => {
+      const result = duration(now, now, { largestUnit: 'auto', smallestUnit: 'seconds' });
+      expect(result).toEqual({ seconds: 0 });
+    });
+
+    it('resolves auto when smallestUnit is omitted', () => {
+      const start = now.subtract(2, 'hours');
+      const result = duration(start, now, { largestUnit: 'auto', smallestUnit: 'minutes' });
+      expect(result).toEqual({ hours: 2, minutes: 0 });
+    });
+
+    it('uses auto as default when only smallestUnit is set', () => {
+      const start = now.subtract(1, 'year').subtract(3, 'months');
+      const result = duration(start, now, { smallestUnit: 'months' });
+      expect(result).toEqual({ years: 1, months: 3 });
+    });
+  });
+});
+
+describe('formatDurationBetween', () => {
+  const now = dayjs('2024-07-30T08:30:55Z');
+
+  it('returns null for null startDate', () => {
+    expect(formatDurationBetween(null, now)).toBeNull();
+  });
+
+  it.each([
+    {
+      label: '30 seconds ago',
+      startDate: now.subtract(30, 'seconds'),
+      expectedPattern: /30\s+sec/,
+    },
+    {
+      label: '30 minutes ago',
+      startDate: now.subtract(30, 'minutes'),
+      expectedPattern: /30\s+min/,
+    },
+    {
+      label: '10 hours ago',
+      startDate: now.subtract(10, 'hours'),
+      expectedPattern: /10\s+hr/,
+    },
+    {
+      label: '20 days ago',
+      startDate: now.subtract(20, 'days'),
+      expectedPattern: /20\s+days/,
+    },
+    {
+      label: '6 months ago',
+      startDate: now.subtract(6, 'months'),
+      expectedPattern: /6\s+mths/,
+    },
+    {
+      label: '3 years ago',
+      startDate: now.subtract(3, 'years'),
+      expectedPattern: /3\s+yrs/,
+    },
+  ])('formats $label', ({ startDate, expectedPattern }) => {
+    window.i18next.language = 'en';
+    expect(formatDurationBetween(startDate, now)).toMatch(expectedPattern);
+  });
+
+  it('formats with explicit unit', () => {
+    window.i18next.language = 'en';
+    const oneYearAgo = now.subtract(1, 'year');
+    expect(formatDurationBetween(oneYearAgo, now, 'days')).toMatch(/366\s+days/);
+  });
+
+  it('handles year-only string', () => {
+    window.i18next.language = 'en';
+    expect(formatDurationBetween('2000', now)).toMatch(/24\s+yrs/);
+  });
+
+  it('handles year-month string', () => {
+    window.i18next.language = 'en';
+    expect(formatDurationBetween('2020-06', now)).toMatch(/4\s+yrs/);
+  });
+
+  it('returns null for invalid string', () => {
+    expect(formatDurationBetween('not a date', now)).toBeNull();
+  });
+
+  it('formats multi-unit decomposition', () => {
+    window.i18next.language = 'en';
+    const start = now.subtract(2, 'years').subtract(3, 'months').subtract(15, 'days');
+    const result = formatDurationBetween(start, now, { largestUnit: 'years', smallestUnit: 'days' });
+    expect(result).toMatch(/2\s+yrs.*3\s+mths.*15\s+days/);
+  });
+
+  it('supports custom formatOptions with long style', () => {
+    window.i18next.language = 'en';
+    const start = now.subtract(2, 'years').subtract(3, 'months');
+    const result = formatDurationBetween(start, now, {
+      largestUnit: 'years',
+      smallestUnit: 'months',
+      formatOptions: { style: 'long' },
+    });
+    expect(result).toMatch(/2\s+years.*3\s+months/);
+  });
+
+  it('supports custom formatOptions with narrow style', () => {
+    window.i18next.language = 'en';
+    const start = now.subtract(2, 'years').subtract(3, 'months');
+    const result = formatDurationBetween(start, now, {
+      largestUnit: 'years',
+      smallestUnit: 'months',
+      formatOptions: { style: 'narrow' },
+    });
+    expect(result).toMatch(/2y.*3m/);
+  });
+});