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

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
-[0] Successfully compiled: 13 files with swc (195.69ms)
+[0] Successfully compiled: 13 files with swc (155.24ms)
 [0] swc --strip-leading-paths src -d dist exited with code 0
 [1] tsc --project tsconfig.build.json exited with code 0

package/dist/age-helpers.d.ts

@@ -1,4 +1,23 @@
+/** @module @category Utility */
 import dayjs from 'dayjs';
+/**
+ * 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.
+ *
+ * @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 declare function ageAsDuration(birthDate: dayjs.ConfigType, currentDate?: dayjs.ConfigType): Intl.DurationInput | null;
 /**
  * Gets a human readable and locale supported representation of a person's age, given their birthDate,
  * The representation logic follows the guideline here:
@@ -8,6 +27,13 @@ import dayjs from 'dayjs';
  * @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 declare function age(birthDate: dayjs.ConfigType, currentDate?: dayjs.ConfigType): string | null;
 //# sourceMappingURL=age-helpers.d.ts.map

package/dist/age-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"age-helpers.d.ts","sourceRoot":"","sources":["../src/age-helpers.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAC;AAO1B;;;;;;;;;GASG;AACH,wBAAgB,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,UAAU,EAAE,WAAW,GAAE,KAAK,CAAC,UAAoB,GAAG,MAAM,GAAG,IAAI,CAyEvG"}
+{"version":3,"file":"age-helpers.d.ts","sourceRoot":"","sources":["../src/age-helpers.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,KAAK,CAAC,UAAU,EAC3B,WAAW,GAAE,KAAK,CAAC,UAAoB,GACtC,IAAI,CAAC,aAAa,GAAG,IAAI,CAuC3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,UAAU,EAAE,WAAW,GAAE,KAAK,CAAC,UAAoB,GAAG,MAAM,GAAG,IAAI,CAcvG"}

package/dist/age-helpers.js

@@ -1,50 +1,26 @@
-/** @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.js";
-dayjs.extend(objectSupport);
+/** @module @category Utility */ import dayjs from "dayjs";
+import { formatDuration, parseDateInput } from "./dates/date-util.js";
 /**
- * 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.
- */ export function age(birthDate, currentDate = dayjs()) {
-    if (birthDate == null) {
-        return null;
-    }
-    const locale = getLocale();
+ * @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 ageAsDuration(birthDate, currentDate = dayjs()) {
     const to = dayjs(currentDate);
-    let from;
-    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;
-        }
-        // 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);
+    const from = parseDateInput(birthDate, to);
+    if (from == null) {
+        return null;
     }
     const hourDiff = to.diff(from, 'hours');
     const dayDiff = to.diff(from, 'days');
@@ -52,16 +28,8 @@ dayjs.extend(objectSupport);
     const monthDiff = to.diff(from, 'months');
     const yearDiff = to.diff(from, 'years');
     const duration = {};
-    const options = {
-        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) {
@@ -81,5 +49,35 @@ dayjs.extend(objectSupport);
     } else {
         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, currentDate = dayjs()) {
+    const durationInput = ageAsDuration(birthDate, currentDate);
+    if (durationInput == null) {
+        return null;
+    }
+    const options = {
+        style: 'short',
+        localeMatcher: 'lookup'
+    };
+    if ('minutes' in durationInput && durationInput.minutes === 0) {
+        options.minutesDisplay = 'always';
+    }
+    return formatDuration(durationInput, options);
 }

package/dist/dates/date-util.d.ts

@@ -3,6 +3,7 @@
  * @category Date and Time
  */
 import { type CalendarDate, type CalendarDateTime, type CalendarIdentifier, type ZonedDateTime } from '@internationalized/date';
+import dayjs from 'dayjs';
 export type DateInput = string | number | Date;
 /**
  * This function checks whether a date string is the OpenMRS ISO format.
@@ -167,4 +168,88 @@ export declare function convertToLocaleCalendar(date: CalendarDate | CalendarDat
  * @returns The formatted duration string.
  */
 export declare function formatDuration(duration: Intl.DurationInput, options?: Intl.DurationFormatOptions): string;
+/**
+ * Parses a date input into a dayjs object. String inputs are interpreted using
+ * any-date-parser with corrections for its month/day representation differences
+ * with dayjs. Non-string inputs are passed directly to dayjs.
+ *
+ * @param dateInput The date to parse.
+ * @param referenceDate Used as the base when resolving partial string dates (e.g., '2000' resolves missing fields from this date).
+ * @returns A dayjs object, or null if the string could not be parsed.
+ */
+export declare function parseDateInput(dateInput: dayjs.ConfigType, referenceDate: dayjs.Dayjs): dayjs.Dayjs | null;
+type DurationUnitPlural = 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years';
+type DurationUnitSingular = 'second' | 'minute' | 'hour' | 'day' | 'month' | 'year';
+/** Accepts both singular ('year') and plural ('years') forms, mirroring Temporal.Duration.round(). */
+export type DurationUnit = DurationUnitPlural | DurationUnitSingular;
+export interface DurationOptions {
+    /** Override auto-selection thresholds. Each value is in the unit's own terms (e.g., seconds: 30 means "use seconds if < 30 seconds"). */
+    thresholds?: Partial<Record<DurationUnit, number>>;
+    /**
+     * Coarsest unit to include. Accepts 'auto' (default when smallestUnit is set),
+     * which resolves to the largest non-zero unit or smallestUnit, whichever is greater.
+     * Mirrors Temporal.Duration.round() behavior.
+     */
+    largestUnit?: DurationUnit | 'auto';
+    /** Finest unit to include. Defaults to largestUnit when largestUnit is an explicit unit, giving a single-unit result. */
+    smallestUnit?: DurationUnit;
+}
+export interface DurationOptionsWithFormat extends DurationOptions {
+    /** Options passed to Intl.DurationFormat. Defaults to { style: 'short', localeMatcher: 'lookup' }. */
+    formatOptions?: Intl.DurationFormatOptions;
+}
+/**
+ * Calculates the duration between two dates as a structured duration object.
+ *
+ * When called with no options or a single unit string, the unit is auto-selected
+ * using dayjs relativeTime thresholds:
+ * - < 45 seconds → seconds
+ * - < 45 minutes → minutes
+ * - < 22 hours → hours
+ * - < 26 days → days
+ * - < 11 months → months
+ * - otherwise → years
+ *
+ * With a {@link DurationOptions} object, you can override thresholds and/or request
+ * a multi-unit decomposition via largestUnit/smallestUnit.
+ *
+ * @param startDate The start date. If null, returns null.
+ * @param endDate Optional. Defaults to now.
+ * @param options A unit string for single-unit output, or a DurationOptions object.
+ * @returns A DurationInput object, or null if either date is null or unparseable.
+ *
+ * @example
+ * // Auto-selects the appropriate unit
+ * duration('2022-01-01', '2024-07-30') // => { years: 2 }
+ *
+ * @example
+ * // Multi-unit decomposition
+ * duration('2022-01-01', '2024-07-30', { largestUnit: 'year', smallestUnit: 'day' })
+ * // => { years: 2, months: 6, days: 29 }
+ */
+export declare function duration(startDate: dayjs.ConfigType, endDate?: dayjs.ConfigType, options?: DurationUnit | DurationOptions): Intl.DurationInput | null;
+/**
+ * Calculates the duration between two dates and formats it as a locale-aware string.
+ * Uses the same unit-selection logic as {@link duration} and delegates formatting
+ * to {@link formatDuration}.
+ *
+ * @param startDate The start date. If null, returns null.
+ * @param endDate Optional. Defaults to now.
+ * @param options A unit string for single-unit output, or a {@link DurationOptionsWithFormat} object.
+ *   The `formatOptions` field is passed to Intl.DurationFormat (defaults to short style).
+ * @returns A formatted duration string, or null if either date is null or unparseable.
+ *
+ * @example
+ * formatDurationBetween('2022-01-01', '2024-07-30') // => '2 yrs'
+ *
+ * @example
+ * // Multi-unit with long-form formatting
+ * formatDurationBetween('2022-01-01', '2024-07-30', {
+ *   largestUnit: 'year',
+ *   smallestUnit: 'day',
+ *   formatOptions: { style: 'long' },
+ * }) // => '2 years, 6 months, 29 days'
+ */
+export declare function formatDurationBetween(startDate: dayjs.ConfigType, endDate?: dayjs.ConfigType, options?: DurationUnit | DurationOptionsWithFormat): string | null;
+export {};
 //# sourceMappingURL=date-util.d.ts.map

package/dist/dates/date-util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"date-util.d.ts","sourceRoot":"","sources":["../../src/dates/date-util.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAGnB,MAAM,yBAAyB,CAAC;AAajC,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAI/C;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAuBnE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,WAE9C;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAMtE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,UAAQ,GAAG,MAAM,CAQtE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,QAE3C;AA6CD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,QAEnF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,MAAM,GAAG,SAAS,kCAI1E;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,MAAM,CAAC;AAEjD,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,EAAE,cAAc,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,IAAI,GAAG,KAAK,GAAG,WAAW,CAAC;IACjC,wCAAwC;IACxC,GAAG,EAAE,OAAO,CAAC;IACb,0CAA0C;IAC1C,KAAK,EAAE,OAAO,CAAC;IACf,kCAAkC;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,0CAA0C;IAC1C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAWF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,iBAAiB,CAAM,iBAuC7F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,UAkE1E;AAiBD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,UAKpC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,UAE5F;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,YAAY,GAAG,gBAAgB,GAAG,aAAa,EACrD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM,mDAM7B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,UAGhG"}
+{"version":3,"file":"date-util.d.ts","sourceRoot":"","sources":["../../src/dates/date-util.ts"],"names":[],"mappings":"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"}

package/dist/dates/date-util.js

@@ -360,3 +360,227 @@ const formatParts = (separator)=>{
     const formatter = new Intl.DurationFormat(getLocale(), options);
     return formatter.format(duration);
 }
+/**
+ * Parses a date input into a dayjs object. String inputs are interpreted using
+ * any-date-parser with corrections for its month/day representation differences
+ * with dayjs. Non-string inputs are passed directly to dayjs.
+ *
+ * @param dateInput The date to parse.
+ * @param referenceDate Used as the base when resolving partial string dates (e.g., '2000' resolves missing fields from this date).
+ * @returns A dayjs object, or null if the string could not be parsed.
+ */ export function parseDateInput(dateInput, referenceDate) {
+    if (dateInput == null) {
+        return null;
+    }
+    if (typeof dateInput === 'string') {
+        const locale = getLocale();
+        let parsedDate = attempt(dateInput, locale);
+        if (parsedDate.invalid) {
+            console.warn(`Could not interpret '${dateInput}' 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 = {
+                ...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;
+        }
+        // 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 = {
+                ...omit(parsedDate, 'day'),
+                ...{
+                    date: parsedDate.day
+                }
+            };
+        }
+        return dayjs(referenceDate).set(parsedDate);
+    }
+    return dayjs(dateInput);
+}
+const UNIT_ORDER = [
+    'years',
+    'months',
+    'days',
+    'hours',
+    'minutes',
+    'seconds'
+];
+const SINGULAR_TO_PLURAL = {
+    second: 'seconds',
+    minute: 'minutes',
+    hour: 'hours',
+    day: 'days',
+    month: 'months',
+    year: 'years'
+};
+function normalizeUnit(unit) {
+    return SINGULAR_TO_PLURAL[unit] ?? unit;
+}
+/**
+ * Normalizes threshold keys from singular/plural to plural, then merges with defaults.
+ */ function normalizeThresholds(thresholds) {
+    const result = {
+        ...DEFAULT_THRESHOLDS
+    };
+    if (thresholds) {
+        for (const [key, value] of Object.entries(thresholds)){
+            if (value !== undefined) {
+                result[normalizeUnit(key)] = value;
+            }
+        }
+    }
+    return result;
+}
+const DEFAULT_THRESHOLDS = {
+    seconds: 45,
+    minutes: 45,
+    hours: 22,
+    days: 26,
+    months: 11,
+    years: Infinity
+};
+/**
+ * Auto-selects the appropriate unit based on the magnitude of the duration,
+ * using the provided thresholds (or defaults).
+ */ function autoSelectUnit(from, to, thresholds) {
+    const t = normalizeThresholds(thresholds);
+    if (to.diff(from, 'seconds') < t.seconds) return 'seconds';
+    if (to.diff(from, 'minutes') < t.minutes) return 'minutes';
+    if (to.diff(from, 'hours') < t.hours) return 'hours';
+    if (to.diff(from, 'days') < t.days) return 'days';
+    if (to.diff(from, 'months') < t.months) return 'months';
+    return 'years';
+}
+/**
+ * Finds the largest unit with a non-zero diff, or falls back to smallestUnit.
+ * Mirrors the Temporal.Duration.round() 'auto' behavior for largestUnit.
+ */ function autoLargestUnit(from, to, smallestUnit) {
+    const smallestIdx = UNIT_ORDER.indexOf(smallestUnit);
+    for(let i = 0; i < UNIT_ORDER.length; i++){
+        const unit = UNIT_ORDER[i];
+        if (to.diff(from, unit) > 0) {
+            // Return this unit or smallestUnit, whichever is coarser (lower index)
+            return i <= smallestIdx ? unit : smallestUnit;
+        }
+    }
+    return smallestUnit;
+}
+/**
+ * Decomposes the duration between two dates across a range of units, from
+ * largestUnit down to smallestUnit. Each unit's value is the remainder after
+ * subtracting all larger units.
+ */ function decompose(from, to, largestUnit, smallestUnit) {
+    const startIdx = UNIT_ORDER.indexOf(largestUnit);
+    const endIdx = UNIT_ORDER.indexOf(smallestUnit);
+    const units = UNIT_ORDER.slice(startIdx, endIdx + 1);
+    const result = {};
+    let current = from;
+    for (const unit of units){
+        const diff = to.diff(current, unit);
+        result[unit] = diff;
+        current = current.add(diff, unit);
+    }
+    return result;
+}
+/**
+ * Calculates the duration between two dates as a structured duration object.
+ *
+ * When called with no options or a single unit string, the unit is auto-selected
+ * using dayjs relativeTime thresholds:
+ * - < 45 seconds → seconds
+ * - < 45 minutes → minutes
+ * - < 22 hours → hours
+ * - < 26 days → days
+ * - < 11 months → months
+ * - otherwise → years
+ *
+ * With a {@link DurationOptions} object, you can override thresholds and/or request
+ * a multi-unit decomposition via largestUnit/smallestUnit.
+ *
+ * @param startDate The start date. If null, returns null.
+ * @param endDate Optional. Defaults to now.
+ * @param options A unit string for single-unit output, or a DurationOptions object.
+ * @returns A DurationInput object, or null if either date is null or unparseable.
+ *
+ * @example
+ * // Auto-selects the appropriate unit
+ * duration('2022-01-01', '2024-07-30') // => { years: 2 }
+ *
+ * @example
+ * // Multi-unit decomposition
+ * duration('2022-01-01', '2024-07-30', { largestUnit: 'year', smallestUnit: 'day' })
+ * // => { years: 2, months: 6, days: 29 }
+ */ export function duration(startDate, endDate = dayjs(), options) {
+    const to = dayjs(endDate);
+    const from = parseDateInput(startDate, to);
+    if (from == null) {
+        return null;
+    }
+    if (typeof options === 'string') {
+        const normalized = normalizeUnit(options);
+        return {
+            [normalized]: to.diff(from, normalized)
+        };
+    }
+    const { thresholds, largestUnit: rawLargest, smallestUnit: rawSmallest } = options ?? {};
+    if (rawLargest !== undefined || rawSmallest !== undefined) {
+        const smallest = rawSmallest ? normalizeUnit(rawSmallest) : undefined;
+        let largest;
+        if (rawLargest === 'auto' || rawLargest === undefined) {
+            // 'auto' or omitted: resolve to the largest non-zero unit, or smallestUnit, whichever is coarser
+            const effectiveSmallest = smallest ?? 'seconds';
+            largest = autoLargestUnit(from, to, effectiveSmallest);
+        } else {
+            largest = normalizeUnit(rawLargest);
+        }
+        return decompose(from, to, largest, smallest ?? largest);
+    }
+    const selected = autoSelectUnit(from, to, thresholds);
+    return {
+        [selected]: to.diff(from, selected)
+    };
+}
+const DEFAULT_FORMAT_OPTIONS = {
+    style: 'short',
+    localeMatcher: 'lookup'
+};
+/**
+ * Calculates the duration between two dates and formats it as a locale-aware string.
+ * Uses the same unit-selection logic as {@link duration} and delegates formatting
+ * to {@link formatDuration}.
+ *
+ * @param startDate The start date. If null, returns null.
+ * @param endDate Optional. Defaults to now.
+ * @param options A unit string for single-unit output, or a {@link DurationOptionsWithFormat} object.
+ *   The `formatOptions` field is passed to Intl.DurationFormat (defaults to short style).
+ * @returns A formatted duration string, or null if either date is null or unparseable.
+ *
+ * @example
+ * formatDurationBetween('2022-01-01', '2024-07-30') // => '2 yrs'
+ *
+ * @example
+ * // Multi-unit with long-form formatting
+ * formatDurationBetween('2022-01-01', '2024-07-30', {
+ *   largestUnit: 'year',
+ *   smallestUnit: 'day',
+ *   formatOptions: { style: 'long' },
+ * }) // => '2 years, 6 months, 29 days'
+ */ export function formatDurationBetween(startDate, endDate = dayjs(), options) {
+    const durationInput = duration(startDate, endDate, options);
+    if (durationInput == null) {
+        return null;
+    }
+    const formatOpts = typeof options === 'object' && options.formatOptions ? {
+        ...DEFAULT_FORMAT_OPTIONS,
+        ...options.formatOptions
+    } : DEFAULT_FORMAT_OPTIONS;
+    return formatDuration(durationInput, formatOpts);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-utils",
-  "version": "9.0.3-pre.4257",
+  "version": "9.0.3-pre.4264",
   "license": "MPL-2.0",
   "description": "Helper utilities for OpenMRS",
   "type": "module",
@@ -63,7 +63,7 @@
     "rxjs": "6.x"
   },
   "devDependencies": {
-    "@openmrs/esm-globals": "9.0.3-pre.4257",
+    "@openmrs/esm-globals": "9.0.3-pre.4264",
     "@swc/cli": "0.8.0",
     "@swc/core": "1.15.18",
     "@types/lodash-es": "^4.17.12",

package/src/age-helpers.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import dayjs from 'dayjs';
 import type { i18n } from 'i18next';
-import { age } from '.';
+import { age, ageAsDuration } from '.';
 
 window.i18next = { language: 'en' } as i18n;
 
@@ -101,3 +101,80 @@ describe('Age Helper', () => {
     expect(age(birthDate, now)).toBe(expectedOutput);
   });
 });
+
+describe('ageAsDuration', () => {
+  const now = dayjs('2024-07-30T08:30:55Z');
+
+  it('returns null for null birthDate', () => {
+    expect(ageAsDuration(null)).toBeNull();
+  });
+
+  it.each([
+    {
+      label: 'just born',
+      birthDate: now,
+      expected: { minutes: 0 },
+    },
+    {
+      label: 'aged 1 hour 30 minutes',
+      birthDate: now.subtract(1, 'hour').subtract(30, 'minutes'),
+      expected: { minutes: 90 },
+    },
+    {
+      label: 'aged 1 day 2 hours 5 minutes',
+      birthDate: now.subtract(1, 'day').subtract(2, 'hours').subtract(5, 'minutes'),
+      expected: { hours: 26 },
+    },
+    {
+      label: 'aged 3 days 17 hours 30 minutes',
+      birthDate: now.subtract(3, 'days').subtract(17, 'hours').subtract(30, 'minutes'),
+      expected: { days: 3 },
+    },
+    {
+      label: 'aged 29 days 5 hours 2 minutes',
+      birthDate: now.subtract(29, 'days').subtract(5, 'hours').subtract(2, 'minutes'),
+      expected: { weeks: 4, days: 1 },
+    },
+    {
+      label: 'aged 1 year 8 days 5 hours',
+      birthDate: now.subtract(1, 'year').subtract(8, 'days').subtract(5, 'hours'),
+      expected: { months: 12, days: 8 },
+    },
+    {
+      label: 'aged 4 years 38 days',
+      birthDate: now.subtract(4, 'years').subtract(38, 'days').subtract(5, 'hours'),
+      expected: { years: 4, months: 1 },
+    },
+    {
+      label: 'aged 18 years 38 days',
+      birthDate: now.subtract(18, 'years').subtract(38, 'days'),
+      expected: { years: 18 },
+    },
+    {
+      label: 'born in 2000 (string)',
+      birthDate: '2000',
+      expected: { years: 24 },
+    },
+    {
+      label: 'born in June 2020 (string)',
+      birthDate: '2020-06',
+      expected: { years: 4, months: 1 },
+    },
+    {
+      label: 'born Feb 29th 2020 (string)',
+      birthDate: '2020-02-29',
+      expected: { years: 4, months: 5 },
+    },
+    {
+      label: 'born January 1st 2020 (string)',
+      birthDate: '2020-01-01',
+      expected: { years: 4, months: 6 },
+    },
+  ])('returns $expected for person $label', ({ birthDate, expected }) => {
+    expect(ageAsDuration(birthDate, now)).toEqual(expected);
+  });
+
+  it('returns null for an invalid string', () => {
+    expect(ageAsDuration('not a date', now)).toBeNull();
+  });
+});