date-vir 4.1.1 → 5.1.0

package/cspell.config.cjs

@@ -0,0 +1,13 @@
+const {baseConfig} = require('virmator/base-configs/base-cspell.js');
+
+module.exports = {
+    ...baseConfig,
+    ignorePaths: [
+        ...baseConfig.ignorePaths,
+    ],
+    words: [
+        ...baseConfig.words,
+        'datetime',
+        'longterm',
+    ],
+};

package/dist/cjs/date-operations/diff-dates.js

@@ -1,71 +1,105 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isDateAfter = exports.diffDatesAllUnits = exports.diffDates = void 0;
+exports.isDateAfter = exports.diffDates = exports.DiffType = void 0;
 const common_1 = require("@augment-vir/common");
-const duration_1 = require("../duration");
+const duration_unit_1 = require("../duration/duration-unit");
+const duration_utils_1 = require("../duration/duration-utils");
 const luxon_date_time_conversion_1 = require("../full-date/luxon-date-time-conversion");
+const accuracyPriority = {
+    longterm: 1,
+    casual: 0,
+};
 const conversionAccuracies = {
-    [duration_1.DurationUnit.Years]: 'longterm',
-    [duration_1.DurationUnit.Quarters]: 'longterm',
-    [duration_1.DurationUnit.Months]: 'longterm',
-    [duration_1.DurationUnit.Weeks]: 'casual',
-    [duration_1.DurationUnit.Days]: 'casual',
-    [duration_1.DurationUnit.Hours]: 'casual',
-    [duration_1.DurationUnit.Minutes]: 'casual',
-    [duration_1.DurationUnit.Seconds]: 'casual',
-    [duration_1.DurationUnit.Milliseconds]: 'casual',
+    [duration_unit_1.DurationUnit.Years]: 'longterm',
+    [duration_unit_1.DurationUnit.Quarters]: 'longterm',
+    [duration_unit_1.DurationUnit.Months]: 'longterm',
+    [duration_unit_1.DurationUnit.Weeks]: 'casual',
+    [duration_unit_1.DurationUnit.Days]: 'casual',
+    [duration_unit_1.DurationUnit.Hours]: 'casual',
+    [duration_unit_1.DurationUnit.Minutes]: 'casual',
+    [duration_unit_1.DurationUnit.Seconds]: 'casual',
+    [duration_unit_1.DurationUnit.Milliseconds]: 'casual',
 };
-/**
- * Diffs two dates and returns the diff in the specific unit.
- *
- * Note: when years, quarters, or months are used for the unit then "long term" durations are used
- * to calculate the diff. See more details here:
- * https://moment.github.io/luxon/#/math?id=casual-vs-longterm-conversion-accuracy
- */
-function diffDates({ start, end, unit, }) {
+function getHighestPriorityConversionAccuracy(units) {
+    const currentConversionAccuracies = units.map((unit) => conversionAccuracies[unit]);
+    const highestPriorityAccuracy = currentConversionAccuracies.reduce((priorityAccuracy, currentAccuracy) => {
+        if (accuracyPriority[currentAccuracy] > accuracyPriority[priorityAccuracy]) {
+            return currentAccuracy;
+        }
+        else {
+            return priorityAccuracy;
+        }
+    });
+    return highestPriorityAccuracy;
+}
+var DiffType;
+(function (DiffType) {
+    /**
+     * Causes the diffDates function to output the diff split between each unit provided. To get the
+     * full duration, each output unit needs to be added together.
+     */
+    DiffType["AdditiveUnits"] = "additive-units";
+    /**
+     * Causes the diffDates function to output the diff in each unit provided with each unit being
+     * equivalent in value. Meaning, each unit will be the same duration of time converted into that
+     * unit.
+     */
+    DiffType["EquivalentUnits"] = "equivalent-units";
+})(DiffType || (exports.DiffType = DiffType = {}));
+function diffDates({ start, end, units: unitsInput, unit: unitInput, diffType: diffTypeInput, decimalCount, }) {
     const luxonDateStart = (0, luxon_date_time_conversion_1.toLuxonDateTime)(start);
     const luxonDateEnd = (0, luxon_date_time_conversion_1.toLuxonDateTime)(end);
-    const diff = luxonDateEnd
-        .diff(luxonDateStart, unit, {
-        conversionAccuracy: conversionAccuracies[unit],
-    })
-        .toObject();
-    return diff;
-}
-exports.diffDates = diffDates;
-/**
- * Diffs two dates and returns that diff in each unit. Note that the unit in the returned object are
- * not meant to be added together, each unit is instead the same value but calculated in that given
- * unit.
- *
- * Note: when years, quarters, or months are used for the unit then "long term" durations are used
- * to calculate the diff. See more details here:
- * https://moment.github.io/luxon/#/math?id=casual-vs-longterm-conversion-accuracy
- */
-function diffDatesAllUnits({ start, end }) {
-    const allUnitDiffEntries = duration_1.orderedDurationUnits.map((durationUnit) => {
-        const diff = diffDates({
-            start,
-            end,
-            unit: durationUnit,
+    const units = (unitsInput ?? [unitInput]);
+    const diffType = units.length === 1
+        ? /**
+           * When only one unit is provided, it doesn't matter which diff type we use so lets just use this
+           * one.
+           */
+            DiffType.EquivalentUnits
+        : diffTypeInput;
+    if (!diffType) {
+        throw new Error('Failed to diff dates: no diffType was provided.');
+    }
+    if (diffType === DiffType.AdditiveUnits) {
+        const conversionAccuracy = getHighestPriorityConversionAccuracy(units);
+        const additiveDiff = luxonDateEnd
+            .diff(luxonDateStart, (0, common_1.makeWritable)(units), {
+            conversionAccuracy,
+        })
+            .toObject();
+        return (0, duration_utils_1.roundDuration)(additiveDiff, decimalCount);
+    }
+    else if (diffType === DiffType.EquivalentUnits) {
+        const allUnitDiffEntries = units.map((durationUnit) => {
+            const diff = luxonDateEnd
+                .diff(luxonDateStart, durationUnit, {
+                conversionAccuracy: conversionAccuracies[durationUnit],
+            })
+                .toObject();
+            const duration = diff[durationUnit];
+            /** Ignore this edge case in coverage cause its for type guarding. */
+            /* c8 ignore next 5 */
+            if (duration == undefined) {
+                throw new Error(`Internal date-vir error: failed to find duration for '${durationUnit}'`);
+            }
+            return [
+                durationUnit,
+                duration,
+            ];
         });
-        const duration = diff[durationUnit];
-        /** Ignore this edge case in coverage cause its for type guarding. */
-        /* c8 ignore next 5 */
-        if (duration == undefined) {
-            throw new Error(`Internal date-vir error: failed to find duration for '${durationUnit}'`);
-        }
-        return [
-            durationUnit,
-            duration,
-        ];
-    });
-    const allDurations = (0, common_1.typedObjectFromEntries)(allUnitDiffEntries);
-    return allDurations;
+        const equivalentDiff = (0, common_1.typedObjectFromEntries)(allUnitDiffEntries);
+        return (0, duration_utils_1.roundDuration)(equivalentDiff, decimalCount);
+    }
+    else {
+        throw new Error(`Failed to diff dates: provided diffType is invalid: '${diffType}'`);
+    }
 }
-exports.diffDatesAllUnits = diffDatesAllUnits;
+exports.diffDates = diffDates;
 function isDateAfter({ relativeTo, fullDate, }) {
-    return (diffDates({ start: relativeTo, end: fullDate, unit: duration_1.DurationUnit.Milliseconds })
-        .milliseconds >= 0);
+    return (diffDates({
+        start: relativeTo,
+        end: fullDate,
+        unit: duration_unit_1.DurationUnit.Milliseconds,
+    }).milliseconds >= 0);
 }
 exports.isDateAfter = isDateAfter;

package/dist/cjs/duration/duration-utils.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertDuration = exports.roundDuration = void 0;
+const common_1 = require("@augment-vir/common");
+const luxon_1 = require("luxon");
+const run_time_assertions_1 = require("run-time-assertions");
+/** Round every unit in a given duration to the given number of decimal points. */
+function roundDuration(duration, 
+/**
+ * How many decimals to round to. Leave undefined to skip rounding. (Though if you skip
+ * rounding, why are you using this function?)
+ */
+decimalCount) {
+    return (0, common_1.mapObjectValues)(duration, (key, value) => {
+        if (decimalCount == undefined || !(0, run_time_assertions_1.isRunTimeType)(value, 'number')) {
+            return value;
+        }
+        else {
+            return (0, common_1.round)({ number: value, digits: decimalCount });
+        }
+    });
+}
+exports.roundDuration = roundDuration;
+/** Convert a duration from any combination of units into a single unit. */
+function convertDuration(inputDuration, requiredUnit) {
+    const luxonDuration = luxon_1.Duration.fromObject(inputDuration);
+    const newUnitValue = luxonDuration.as(requiredUnit);
+    return { [requiredUnit]: newUnitValue };
+}
+exports.convertDuration = convertDuration;

package/dist/cjs/duration/duration.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/extra-utils/zero.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.clearParts = exports.clearTime = exports.zeroTime = exports.zeroDate = void 0;
+exports.clearParts = exports.clearTime = exports.zeroTime = exports.emptyDate = exports.zeroDate = void 0;
 const common_1 = require("@augment-vir/common");
 const full_date_shape_1 = require("../full-date/full-date-shape");
 const date_transforms_1 = require("./date-transforms");
@@ -13,6 +13,7 @@ exports.zeroDate = {
     second: 0,
     millisecond: 0,
 };
+exports.emptyDate = exports.zeroDate;
 exports.zeroTime = (0, common_1.pickObjectKeys)(exports.zeroDate, full_date_shape_1.timeFullDateKeys);
 function clearTime(inputFullDate) {
     return clearParts(inputFullDate, full_date_shape_1.timeFullDateKeys);

package/dist/cjs/formatting/relative-string.js

@@ -3,23 +3,25 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.toRelativeString = void 0;
 const common_1 = require("@augment-vir/common");
 const diff_dates_1 = require("../date-operations/diff-dates");
-const duration_1 = require("../duration");
+const duration_unit_1 = require("../duration/duration-unit");
 const maxDurations = {
-    [duration_1.DurationUnit.Milliseconds]: 1000,
-    [duration_1.DurationUnit.Seconds]: 60,
-    [duration_1.DurationUnit.Minutes]: 60,
-    [duration_1.DurationUnit.Hours]: 24,
-    [duration_1.DurationUnit.Days]: 30,
-    [duration_1.DurationUnit.Weeks]: 4,
-    [duration_1.DurationUnit.Months]: 12,
-    [duration_1.DurationUnit.Quarters]: 4,
-    [duration_1.DurationUnit.Years]: Infinity,
+    [duration_unit_1.DurationUnit.Milliseconds]: 1000,
+    [duration_unit_1.DurationUnit.Seconds]: 60,
+    [duration_unit_1.DurationUnit.Minutes]: 60,
+    [duration_unit_1.DurationUnit.Hours]: 24,
+    [duration_unit_1.DurationUnit.Days]: 30,
+    [duration_unit_1.DurationUnit.Weeks]: 4,
+    [duration_unit_1.DurationUnit.Months]: 12,
+    [duration_unit_1.DurationUnit.Quarters]: 4,
+    [duration_unit_1.DurationUnit.Years]: Infinity,
 };
 function toRelativeString({ fullDate, relativeTo, options = {}, }) {
     const roundingDigits = options.decimalDigitCount || 0;
-    const allUnitDiffs = (0, diff_dates_1.diffDatesAllUnits)({
+    const allUnitDiffs = (0, diff_dates_1.diffDates)({
         start: fullDate,
         end: relativeTo,
+        units: duration_unit_1.orderedDurationUnits,
+        diffType: diff_dates_1.DiffType.EquivalentUnits,
     });
     const unitsWithinBounds = (0, common_1.mapObjectValues)(allUnitDiffs, (durationUnit, duration) => {
         const roundedDuration = Math.floor(Math.abs((0, common_1.round)({ digits: 1, number: duration })));
@@ -29,7 +31,7 @@ function toRelativeString({ fullDate, relativeTo, options = {}, }) {
             : true;
         return isAboveZero && isBelowMax;
     });
-    const unitToUse = duration_1.orderedDurationUnits.reduce((chosenUnit, currentUnit) => {
+    const unitToUse = duration_unit_1.orderedDurationUnits.reduce((chosenUnit, currentUnit) => {
         const isUnitAllowed = !options.blockedRelativeUnits?.includes(currentUnit);
         if (isUnitAllowed && unitsWithinBounds[currentUnit]) {
             return currentUnit;
@@ -41,9 +43,9 @@ function toRelativeString({ fullDate, relativeTo, options = {}, }) {
     const shouldUseJustNow = options.blockJustNow
         ? false
         : (0, common_1.areJsonEqual)(fullDate, relativeTo) ||
-            (unitToUse === duration_1.DurationUnit.Minutes && allUnitDiffs.minutes < 2) ||
-            (unitToUse === duration_1.DurationUnit.Seconds && allUnitDiffs.seconds < 11) ||
-            (unitToUse === duration_1.DurationUnit.Milliseconds && allUnitDiffs.milliseconds < 710);
+            (unitToUse === duration_unit_1.DurationUnit.Minutes && allUnitDiffs.minutes < 2) ||
+            (unitToUse === duration_unit_1.DurationUnit.Seconds && allUnitDiffs.seconds < 11) ||
+            (unitToUse === duration_unit_1.DurationUnit.Milliseconds && allUnitDiffs.milliseconds < 710);
     /** Some short circuits. */
     if (shouldUseJustNow) {
         return 'just now';
@@ -55,7 +57,7 @@ function toRelativeString({ fullDate, relativeTo, options = {}, }) {
     const roundedAbsoluteDuration = Math.abs((0, common_1.round)({ digits: roundingDigits, number: duration }));
     const isDurationSingular = roundedAbsoluteDuration === 1;
     const unitName = [
-        duration_1.singularDurationUnitNames[unitToUse],
+        duration_unit_1.singularDurationUnitNames[unitToUse],
         isDurationSingular ? '' : 's',
     ].join('');
     const value = isDurationSingular ? 'a' : roundedAbsoluteDuration;

package/dist/cjs/index.js

@@ -17,7 +17,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./date-operations/calculate-relative-date"), exports);
 __exportStar(require("./date-operations/combine-dates"), exports);
 __exportStar(require("./date-operations/diff-dates"), exports);
-__exportStar(require("./duration"), exports);
+__exportStar(require("./duration/duration"), exports);
+__exportStar(require("./duration/duration-unit"), exports);
+__exportStar(require("./duration/duration-utils"), exports);
 __exportStar(require("./extra-utils/date-transforms"), exports);
 __exportStar(require("./extra-utils/has-date-props"), exports);
 __exportStar(require("./extra-utils/js-date-conversion"), exports);

package/dist/esm/date-operations/calculate-relative-date.d.ts

@@ -1,4 +1,4 @@
-import { AnyDuration } from '../duration';
+import { AnyDuration } from '../duration/duration';
 import { FullDate } from '../full-date/full-date-shape';
 /**
  * Calculates a new date starting at the given fullDate and adding the given offsets. Offsets can be

package/dist/esm/date-operations/diff-dates.d.ts

@@ -1,5 +1,20 @@
-import { AllDurations, Duration, DurationUnit } from '../duration';
+import { ArrayElement } from '@augment-vir/common';
+import { Duration } from '../duration/duration';
+import { DurationUnit } from '../duration/duration-unit';
 import { FullDate } from '../full-date/full-date-shape';
+export declare enum DiffType {
+    /**
+     * Causes the diffDates function to output the diff split between each unit provided. To get the
+     * full duration, each output unit needs to be added together.
+     */
+    AdditiveUnits = "additive-units",
+    /**
+     * Causes the diffDates function to output the diff in each unit provided with each unit being
+     * equivalent in value. Meaning, each unit will be the same duration of time converted into that
+     * unit.
+     */
+    EquivalentUnits = "equivalent-units"
+}
 /**
  * Diffs two dates and returns the diff in the specific unit.
  *
@@ -7,25 +22,45 @@ import { FullDate } from '../full-date/full-date-shape';
  * to calculate the diff. See more details here:
  * https://moment.github.io/luxon/#/math?id=casual-vs-longterm-conversion-accuracy
  */
-export declare function diffDates<const ChosenDurationKey extends DurationUnit>({ start, end, unit, }: {
-    start: FullDate;
-    end: FullDate;
-    unit: ChosenDurationKey;
-}): Duration<ChosenDurationKey>;
-/**
- * Diffs two dates and returns that diff in each unit. Note that the unit in the returned object are
- * not meant to be added together, each unit is instead the same value but calculated in that given
- * unit.
- *
- * Note: when years, quarters, or months are used for the unit then "long term" durations are used
- * to calculate the diff. See more details here:
- * https://moment.github.io/luxon/#/math?id=casual-vs-longterm-conversion-accuracy
- */
-export declare function diffDatesAllUnits({ start, end }: {
-    start: FullDate;
-    end: FullDate;
-}): AllDurations;
+export declare function diffDates<const ChosenDurationUnits extends DurationUnit>(params: {
+    start: Readonly<FullDate>;
+    end: Readonly<FullDate>;
+    /** The unit which the output should contain. */
+    unit: ChosenDurationUnits;
+    /**
+     * Determine the diff type calculation. See DiffType values for explanations on each one.
+     * Optional when only one unit is provided, as the diffType will not change the output either
+     * way.
+     */
+    diffType?: DiffType | undefined;
+    /** How many decimals to round the outputs to. Leave undefined to skip rounding entirely. */
+    decimalCount?: number | undefined;
+}): Duration<ChosenDurationUnits>;
+export declare function diffDates<const ChosenDurationUnits extends Readonly<[DurationUnit]>>(params: {
+    start: Readonly<FullDate>;
+    end: Readonly<FullDate>;
+    /** Which units the output should contain. */
+    units: ChosenDurationUnits;
+    /**
+     * Determine the diff type calculation. See DiffType values for explanations on each one.
+     * Optional when only one unit is provided, as the diffType will not change the output either
+     * way.
+     */
+    diffType?: DiffType | undefined;
+    /** How many decimals to round the outputs to. Leave undefined to skip rounding entirely. */
+    decimalCount?: number | undefined;
+}): Duration<ArrayElement<ChosenDurationUnits>>;
+export declare function diffDates<const ChosenDurationUnits extends ReadonlyArray<DurationUnit>>(params: {
+    start: Readonly<FullDate>;
+    end: Readonly<FullDate>;
+    /** Which units the output should contain. */
+    units: ChosenDurationUnits;
+    /** Determine the diff type calculation. See DiffType values for explanations on each one. */
+    diffType: DiffType;
+    /** How many decimals to round the outputs to. Leave undefined to skip rounding entirely. */
+    decimalCount?: number | undefined;
+}): Duration<ArrayElement<ChosenDurationUnits>>;
 export declare function isDateAfter({ relativeTo, fullDate, }: {
-    relativeTo: FullDate;
-    fullDate: FullDate;
+    relativeTo: Readonly<FullDate>;
+    fullDate: Readonly<FullDate>;
 }): boolean;

package/dist/esm/date-operations/diff-dates.js

@@ -1,6 +1,11 @@
-import { typedObjectFromEntries } from '@augment-vir/common';
-import { DurationUnit, orderedDurationUnits } from '../duration';
+import { makeWritable, typedObjectFromEntries } from '@augment-vir/common';
+import { DurationUnit } from '../duration/duration-unit';
+import { roundDuration } from '../duration/duration-utils';
 import { toLuxonDateTime } from '../full-date/luxon-date-time-conversion';
+const accuracyPriority = {
+    longterm: 1,
+    casual: 0,
+};
 const conversionAccuracies = {
     [DurationUnit.Years]: 'longterm',
     [DurationUnit.Quarters]: 'longterm',
@@ -12,54 +17,84 @@ const conversionAccuracies = {
     [DurationUnit.Seconds]: 'casual',
     [DurationUnit.Milliseconds]: 'casual',
 };
-/**
- * Diffs two dates and returns the diff in the specific unit.
- *
- * Note: when years, quarters, or months are used for the unit then "long term" durations are used
- * to calculate the diff. See more details here:
- * https://moment.github.io/luxon/#/math?id=casual-vs-longterm-conversion-accuracy
- */
-export function diffDates({ start, end, unit, }) {
+function getHighestPriorityConversionAccuracy(units) {
+    const currentConversionAccuracies = units.map((unit) => conversionAccuracies[unit]);
+    const highestPriorityAccuracy = currentConversionAccuracies.reduce((priorityAccuracy, currentAccuracy) => {
+        if (accuracyPriority[currentAccuracy] > accuracyPriority[priorityAccuracy]) {
+            return currentAccuracy;
+        }
+        else {
+            return priorityAccuracy;
+        }
+    });
+    return highestPriorityAccuracy;
+}
+export var DiffType;
+(function (DiffType) {
+    /**
+     * Causes the diffDates function to output the diff split between each unit provided. To get the
+     * full duration, each output unit needs to be added together.
+     */
+    DiffType["AdditiveUnits"] = "additive-units";
+    /**
+     * Causes the diffDates function to output the diff in each unit provided with each unit being
+     * equivalent in value. Meaning, each unit will be the same duration of time converted into that
+     * unit.
+     */
+    DiffType["EquivalentUnits"] = "equivalent-units";
+})(DiffType || (DiffType = {}));
+export function diffDates({ start, end, units: unitsInput, unit: unitInput, diffType: diffTypeInput, decimalCount, }) {
     const luxonDateStart = toLuxonDateTime(start);
     const luxonDateEnd = toLuxonDateTime(end);
-    const diff = luxonDateEnd
-        .diff(luxonDateStart, unit, {
-        conversionAccuracy: conversionAccuracies[unit],
-    })
-        .toObject();
-    return diff;
-}
-/**
- * Diffs two dates and returns that diff in each unit. Note that the unit in the returned object are
- * not meant to be added together, each unit is instead the same value but calculated in that given
- * unit.
- *
- * Note: when years, quarters, or months are used for the unit then "long term" durations are used
- * to calculate the diff. See more details here:
- * https://moment.github.io/luxon/#/math?id=casual-vs-longterm-conversion-accuracy
- */
-export function diffDatesAllUnits({ start, end }) {
-    const allUnitDiffEntries = orderedDurationUnits.map((durationUnit) => {
-        const diff = diffDates({
-            start,
-            end,
-            unit: durationUnit,
+    const units = (unitsInput ?? [unitInput]);
+    const diffType = units.length === 1
+        ? /**
+           * When only one unit is provided, it doesn't matter which diff type we use so lets just use this
+           * one.
+           */
+            DiffType.EquivalentUnits
+        : diffTypeInput;
+    if (!diffType) {
+        throw new Error('Failed to diff dates: no diffType was provided.');
+    }
+    if (diffType === DiffType.AdditiveUnits) {
+        const conversionAccuracy = getHighestPriorityConversionAccuracy(units);
+        const additiveDiff = luxonDateEnd
+            .diff(luxonDateStart, makeWritable(units), {
+            conversionAccuracy,
+        })
+            .toObject();
+        return roundDuration(additiveDiff, decimalCount);
+    }
+    else if (diffType === DiffType.EquivalentUnits) {
+        const allUnitDiffEntries = units.map((durationUnit) => {
+            const diff = luxonDateEnd
+                .diff(luxonDateStart, durationUnit, {
+                conversionAccuracy: conversionAccuracies[durationUnit],
+            })
+                .toObject();
+            const duration = diff[durationUnit];
+            /** Ignore this edge case in coverage cause its for type guarding. */
+            /* c8 ignore next 5 */
+            if (duration == undefined) {
+                throw new Error(`Internal date-vir error: failed to find duration for '${durationUnit}'`);
+            }
+            return [
+                durationUnit,
+                duration,
+            ];
         });
-        const duration = diff[durationUnit];
-        /** Ignore this edge case in coverage cause its for type guarding. */
-        /* c8 ignore next 5 */
-        if (duration == undefined) {
-            throw new Error(`Internal date-vir error: failed to find duration for '${durationUnit}'`);
-        }
-        return [
-            durationUnit,
-            duration,
-        ];
-    });
-    const allDurations = typedObjectFromEntries(allUnitDiffEntries);
-    return allDurations;
+        const equivalentDiff = typedObjectFromEntries(allUnitDiffEntries);
+        return roundDuration(equivalentDiff, decimalCount);
+    }
+    else {
+        throw new Error(`Failed to diff dates: provided diffType is invalid: '${diffType}'`);
+    }
 }
 export function isDateAfter({ relativeTo, fullDate, }) {
-    return (diffDates({ start: relativeTo, end: fullDate, unit: DurationUnit.Milliseconds })
-        .milliseconds >= 0);
+    return (diffDates({
+        start: relativeTo,
+        end: fullDate,
+        unit: DurationUnit.Milliseconds,
+    }).milliseconds >= 0);
 }

package/dist/esm/duration/duration-unit.d.ts

@@ -0,0 +1,27 @@
+export declare enum DurationUnit {
+    Years = "years",
+    Quarters = "quarters",
+    Months = "months",
+    Weeks = "weeks",
+    Days = "days",
+    Hours = "hours",
+    Minutes = "minutes",
+    Seconds = "seconds",
+    Milliseconds = "milliseconds"
+}
+export declare const singularDurationUnitNames: {
+    readonly milliseconds: "millisecond";
+    readonly seconds: "second";
+    readonly minutes: "minute";
+    readonly hours: "hour";
+    readonly days: "day";
+    readonly weeks: "week";
+    readonly months: "month";
+    readonly quarters: "quarter";
+    readonly years: "year";
+};
+/**
+ * Array of DurationUnit values: from smallest unit (milliseconds at index 0) to longest unit
+ * (years).
+ */
+export declare const orderedDurationUnits: readonly [DurationUnit.Milliseconds, DurationUnit.Seconds, DurationUnit.Minutes, DurationUnit.Hours, DurationUnit.Days, DurationUnit.Weeks, DurationUnit.Months, DurationUnit.Quarters, DurationUnit.Years];

package/dist/esm/duration/duration-utils.d.ts

@@ -0,0 +1,11 @@
+import { AnyDuration, Duration } from './duration';
+import { DurationUnit } from './duration-unit';
+/** Round every unit in a given duration to the given number of decimal points. */
+export declare function roundDuration<InputDuration extends AnyDuration>(duration: Readonly<InputDuration>, 
+/**
+ * How many decimals to round to. Leave undefined to skip rounding. (Though if you skip
+ * rounding, why are you using this function?)
+ */
+decimalCount: number | undefined): InputDuration;
+/** Convert a duration from any combination of units into a single unit. */
+export declare function convertDuration<RequiredDurationUnit extends DurationUnit>(inputDuration: AnyDuration, requiredUnit: RequiredDurationUnit): Duration<RequiredDurationUnit>;

package/dist/esm/duration/duration-utils.js

@@ -0,0 +1,25 @@
+import { mapObjectValues, round } from '@augment-vir/common';
+import { Duration as LuxonDuration } from 'luxon';
+import { isRunTimeType } from 'run-time-assertions';
+/** Round every unit in a given duration to the given number of decimal points. */
+export function roundDuration(duration, 
+/**
+ * How many decimals to round to. Leave undefined to skip rounding. (Though if you skip
+ * rounding, why are you using this function?)
+ */
+decimalCount) {
+    return mapObjectValues(duration, (key, value) => {
+        if (decimalCount == undefined || !isRunTimeType(value, 'number')) {
+            return value;
+        }
+        else {
+            return round({ number: value, digits: decimalCount });
+        }
+    });
+}
+/** Convert a duration from any combination of units into a single unit. */
+export function convertDuration(inputDuration, requiredUnit) {
+    const luxonDuration = LuxonDuration.fromObject(inputDuration);
+    const newUnitValue = luxonDuration.as(requiredUnit);
+    return { [requiredUnit]: newUnitValue };
+}

package/dist/esm/duration/duration.d.ts

@@ -0,0 +1,32 @@
+import { RequiredAndNotNull } from '@augment-vir/common';
+import { IsUnknown, RequireAtLeastOne, UnionToIntersection } from 'type-fest';
+import { DurationUnit } from './duration-unit';
+/**
+ * All possible options for the more strict Duration type. Matches the DurationObjectUnits type from
+ * the luxon package.
+ */
+export type AnyDuration = {
+    years?: number | undefined;
+    quarters?: number | undefined;
+    months?: number | undefined;
+    weeks?: number | undefined;
+    days?: number | undefined;
+    hours?: number | undefined;
+    minutes?: number | undefined;
+    seconds?: number | undefined;
+    milliseconds?: number | undefined;
+};
+/** Requires at least one duration unit to be set. */
+export type AtLeastOneDuration = RequireAtLeastOne<RequiredAndNotNull<AnyDuration>>;
+/**
+ * All possible duration units at once. Whether these duration units should be added together to
+ * form the whole picture or whether each duration is the same value but calculated in different
+ * units depends on the context of this type's usage.
+ */
+export type AllDurations = RequiredAndNotNull<AnyDuration>;
+/**
+ * Not a single date instance, but a description of a date duration. Used to calculate diffs between
+ * dates, or add offsets to an existing date, or describe a single time duration. Usually only one
+ * property is set on this at any given time.
+ */
+export type Duration<DurationKeys extends DurationUnit | unknown> = UnionToIntersection<IsUnknown<DurationKeys> extends true ? AnyDuration : DurationKeys extends DurationUnit ? Pick<AllDurations, `${DurationKeys}`> : never>;

package/dist/esm/duration/duration.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/extra-utils/zero.d.ts

@@ -8,6 +8,15 @@ export declare const zeroDate: {
     readonly second: 0;
     readonly millisecond: 0;
 };
+export declare const emptyDate: {
+    readonly year: 0;
+    readonly month: 1;
+    readonly day: 1;
+    readonly hour: 0;
+    readonly minute: 0;
+    readonly second: 0;
+    readonly millisecond: 0;
+};
 export declare const zeroTime: Pick<{
     year: 0;
     month: 1;

package/dist/esm/extra-utils/zero.js

@@ -10,6 +10,7 @@ export const zeroDate = {
     second: 0,
     millisecond: 0,
 };
+export const emptyDate = zeroDate;
 export const zeroTime = pickObjectKeys(zeroDate, timeFullDateKeys);
 export function clearTime(inputFullDate) {
     return clearParts(inputFullDate, timeFullDateKeys);

package/dist/esm/formatting/relative-string.d.ts

@@ -1,5 +1,5 @@
 import { PartialAndUndefined } from '@augment-vir/common';
-import { DurationUnit } from '../duration';
+import { DurationUnit } from '../duration/duration-unit';
 import { FullDate } from '../full-date/full-date-shape';
 export type RelativeStringOptions = {
     /**

package/dist/esm/formatting/relative-string.js

@@ -1,6 +1,6 @@
 import { areJsonEqual, mapObjectValues, round } from '@augment-vir/common';
-import { diffDatesAllUnits } from '../date-operations/diff-dates';
-import { DurationUnit, orderedDurationUnits, singularDurationUnitNames } from '../duration';
+import { DiffType, diffDates } from '../date-operations/diff-dates';
+import { DurationUnit, orderedDurationUnits, singularDurationUnitNames, } from '../duration/duration-unit';
 const maxDurations = {
     [DurationUnit.Milliseconds]: 1000,
     [DurationUnit.Seconds]: 60,
@@ -14,9 +14,11 @@ const maxDurations = {
 };
 export function toRelativeString({ fullDate, relativeTo, options = {}, }) {
     const roundingDigits = options.decimalDigitCount || 0;
-    const allUnitDiffs = diffDatesAllUnits({
+    const allUnitDiffs = diffDates({
         start: fullDate,
         end: relativeTo,
+        units: orderedDurationUnits,
+        diffType: DiffType.EquivalentUnits,
     });
     const unitsWithinBounds = mapObjectValues(allUnitDiffs, (durationUnit, duration) => {
         const roundedDuration = Math.floor(Math.abs(round({ digits: 1, number: duration })));

package/dist/esm/index.d.ts

@@ -1,7 +1,9 @@
 export * from './date-operations/calculate-relative-date';
 export * from './date-operations/combine-dates';
 export * from './date-operations/diff-dates';
-export * from './duration';
+export * from './duration/duration';
+export * from './duration/duration-unit';
+export * from './duration/duration-utils';
 export * from './extra-utils/date-transforms';
 export * from './extra-utils/has-date-props';
 export * from './extra-utils/js-date-conversion';

package/dist/esm/index.js

@@ -1,7 +1,9 @@
 export * from './date-operations/calculate-relative-date';
 export * from './date-operations/combine-dates';
 export * from './date-operations/diff-dates';
-export * from './duration';
+export * from './duration/duration';
+export * from './duration/duration-unit';
+export * from './duration/duration-utils';
 export * from './extra-utils/date-transforms';
 export * from './extra-utils/has-date-props';
 export * from './extra-utils/js-date-conversion';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "date-vir",
-    "version": "4.1.1",
+    "version": "5.1.0",
     "description": "Easy and explicit dates and times",
     "keywords": [
         "date",
@@ -41,45 +41,41 @@
         "test:watch": "web-test-runner --watch --color --config configs/web-test-runner.config.mjs"
     },
     "dependencies": {
-        "@augment-vir/common": "^22.0.0",
-        "@types/luxon": "^3.3.4",
+        "@augment-vir/common": "^22.4.0",
+        "@types/luxon": "^3.4.1",
         "luxon": "^3.4.4",
-        "object-shape-tester": "^1.0.2",
-        "type-fest": "^4.8.1"
+        "object-shape-tester": "^1.0.3",
+        "type-fest": "^4.9.0"
     },
     "devDependencies": {
-        "@augment-vir/browser": "^22.0.0",
-        "@augment-vir/browser-testing": "^22.0.0",
+        "@augment-vir/browser": "^22.4.0",
+        "@augment-vir/browser-testing": "^22.4.0",
         "@open-wc/testing": "^4.0.0",
-        "@types/chai": "^4.3.10",
-        "@types/mocha": "^10.0.4",
+        "@types/chai": "^4.3.11",
+        "@types/mocha": "^10.0.6",
         "@web/dev-server-esbuild": "^1.0.1",
         "@web/test-runner": "^0.18.0",
         "@web/test-runner-commands": "^0.9.0",
         "@web/test-runner-playwright": "^0.11.0",
         "@web/test-runner-visual-regression": "^0.9.0",
-        "cspell": "^8.0.0",
-        "dependency-cruiser": "^15.3.0",
-        "element-vir": "^17.0.0",
-        "esbuild": "^0.19.6",
+        "cspell": "^8.3.2",
+        "dependency-cruiser": "^16.0.0",
+        "element-vir": "^20.0.6",
+        "esbuild": "^0.19.11",
         "istanbul-smart-text-reporter": "^1.1.3",
         "markdown-code-example-inserter": "^0.3.3",
         "npm-check-updates": "~16.12.3",
-        "prettier": "^3.1.0",
+        "prettier": "3.2.2",
         "prettier-plugin-interpolated-html-tags": "^1.0.3",
-        "prettier-plugin-jsdoc": "^1.1.1",
+        "prettier-plugin-jsdoc": "^1.3.0",
         "prettier-plugin-multiline-arrays": "^3.0.1",
         "prettier-plugin-organize-imports": "^3.2.4",
-        "prettier-plugin-packagejson": "^2.4.6",
+        "prettier-plugin-packagejson": "^2.4.9",
         "prettier-plugin-sort-json": "^3.1.0",
-        "prettier-plugin-toml": "^1.0.0",
-        "run-time-assertions": "^0.2.1",
-        "typedoc": "^0.25.3",
-        "typescript": "^5.2.2",
-        "virmator": "^11.1.2"
-    },
-    "overrides": {
-        "@open-wc/scoped-elements": "2.2.3",
-        "@open-wc/testing-helpers": "2.3.0"
+        "prettier-plugin-toml": "^2.0.1",
+        "run-time-assertions": "^0.3.0",
+        "typedoc": "^0.25.7",
+        "typescript": "^5.3.3",
+        "virmator": "^11.3.1"
     }
 }

package/dist/esm/duration.d.ts

@@ -1,55 +0,0 @@
-import { RequiredAndNotNull } from '@augment-vir/common';
-export declare enum DurationUnit {
-    Years = "years",
-    Quarters = "quarters",
-    Months = "months",
-    Weeks = "weeks",
-    Days = "days",
-    Hours = "hours",
-    Minutes = "minutes",
-    Seconds = "seconds",
-    Milliseconds = "milliseconds"
-}
-export declare const singularDurationUnitNames: {
-    readonly milliseconds: "millisecond";
-    readonly seconds: "second";
-    readonly minutes: "minute";
-    readonly hours: "hour";
-    readonly days: "day";
-    readonly weeks: "week";
-    readonly months: "month";
-    readonly quarters: "quarter";
-    readonly years: "year";
-};
-/**
- * Array of DurationUnit values: from smallest unit (milliseconds at index 0) to longest unit
- * (years).
- */
-export declare const orderedDurationUnits: readonly [DurationUnit.Milliseconds, DurationUnit.Seconds, DurationUnit.Minutes, DurationUnit.Hours, DurationUnit.Days, DurationUnit.Weeks, DurationUnit.Months, DurationUnit.Quarters, DurationUnit.Years];
-/**
- * All possible options for the more strict Duration type. Matches the DurationObjectUnits type from
- * the luxon package.
- */
-export type AnyDuration = {
-    years?: number | undefined;
-    quarters?: number | undefined;
-    months?: number | undefined;
-    weeks?: number | undefined;
-    days?: number | undefined;
-    hours?: number | undefined;
-    minutes?: number | undefined;
-    seconds?: number | undefined;
-    milliseconds?: number | undefined;
-};
-/**
- * All possible duration units at once. Whether these duration units should be added together to
- * form the whole picture or whether each duration is the same value but calculated in different
- * units depends on the context of this type's usage.
- */
-export type AllDurations = RequiredAndNotNull<AnyDuration>;
-/**
- * Not a single date instance, but a description of a date duration. Used to calculate diffs between
- * dates, or add offsets to an existing date, or describe a single time duration. Usually only one
- * property is set on this at any given time.
- */
-export type Duration<DurationKeys extends DurationUnit = DurationUnit> = DurationUnit extends DurationKeys ? AnyDuration : Pick<AllDurations, `${DurationKeys}`>;