date-vir 3.0.0 → 4.0.0

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

@@ -1,18 +1,71 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isDateAfter = exports.diffDates = void 0;
+exports.isDateAfter = exports.diffDatesAllUnits = exports.diffDates = void 0;
+const common_1 = require("@augment-vir/common");
 const duration_1 = require("../duration");
 const luxon_date_time_conversion_1 = require("../full-date/luxon-date-time-conversion");
+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',
+};
+/**
+ * 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, }) {
     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)
+        .diff(luxonDateStart, unit, {
+        conversionAccuracy: conversionAccuracies[unit],
+    })
         .toObject();
     return diff;
 }
 exports.diffDates = diffDates;
-function isDateAfter({ start, end }) {
-    return diffDates({ start, end, unit: duration_1.DurationUnit.Milliseconds }).milliseconds >= 0;
+/**
+ * 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 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;
+}
+exports.diffDatesAllUnits = diffDatesAllUnits;
+function isDateAfter({ relativeTo, fullDate, }) {
+    return (diffDates({ start: relativeTo, end: fullDate, unit: duration_1.DurationUnit.Milliseconds })
+        .milliseconds >= 0);
 }
 exports.isDateAfter = isDateAfter;

package/dist/cjs/duration.js

@@ -1,16 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DurationUnit = void 0;
-/**
- * Exclude the higher order units of time measure for diffing because they vary significantly,
- * causing inaccuracies and many issues. See
- * https://moment.github.io/luxon/#/math?id=casual-vs-longterm-conversion-accuracy for more info.
- *
- * If you REALLY want to use these higher order units, convert the dates to luxon objects with
- * toLuxonDateTime and then run diff calculations there.
- */
+exports.orderedDurationUnits = exports.singularDurationUnitNames = exports.DurationUnit = void 0;
 var DurationUnit;
 (function (DurationUnit) {
+    DurationUnit["Years"] = "years";
+    DurationUnit["Quarters"] = "quarters";
+    DurationUnit["Months"] = "months";
     DurationUnit["Weeks"] = "weeks";
     DurationUnit["Days"] = "days";
     DurationUnit["Hours"] = "hours";
@@ -18,3 +13,29 @@ var DurationUnit;
     DurationUnit["Seconds"] = "seconds";
     DurationUnit["Milliseconds"] = "milliseconds";
 })(DurationUnit || (exports.DurationUnit = DurationUnit = {}));
+exports.singularDurationUnitNames = {
+    [DurationUnit.Milliseconds]: 'millisecond',
+    [DurationUnit.Seconds]: 'second',
+    [DurationUnit.Minutes]: 'minute',
+    [DurationUnit.Hours]: 'hour',
+    [DurationUnit.Days]: 'day',
+    [DurationUnit.Weeks]: 'week',
+    [DurationUnit.Months]: 'month',
+    [DurationUnit.Quarters]: 'quarter',
+    [DurationUnit.Years]: 'year',
+};
+/**
+ * Array of DurationUnit values: from smallest unit (milliseconds at index 0) to longest unit
+ * (years).
+ */
+exports.orderedDurationUnits = [
+    DurationUnit.Milliseconds,
+    DurationUnit.Seconds,
+    DurationUnit.Minutes,
+    DurationUnit.Hours,
+    DurationUnit.Days,
+    DurationUnit.Weeks,
+    DurationUnit.Months,
+    DurationUnit.Quarters,
+    DurationUnit.Years,
+];

package/dist/cjs/extra-utils/has-date-props.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertHasDateProps = exports.hasDateProps = void 0;
+function hasDateProps(dateInput, keys) {
+    try {
+        assertHasDateProps(dateInput, keys);
+        return true;
+    }
+    catch (error) {
+        return false;
+    }
+}
+exports.hasDateProps = hasDateProps;
+function assertHasDateProps(dateInput, keys) {
+    const missingKeys = [];
+    keys.forEach((key) => {
+        if (dateInput[key] == undefined) {
+            missingKeys.push(key);
+        }
+    });
+    if (missingKeys.length) {
+        throw new Error(`Missing required FullDate key(s): ${missingKeys.join(', ')}`);
+    }
+}
+exports.assertHasDateProps = assertHasDateProps;

package/dist/cjs/extra-utils/js-date-conversion.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toJsDate = void 0;
-const primitive_conversions_1 = require("../full-date/primitive-conversions");
+const timestamp_1 = require("../formatting/timestamp");
 function toJsDate(fullDate) {
-    return new Date((0, primitive_conversions_1.toTimestamp)(fullDate));
+    return new Date((0, timestamp_1.toTimestamp)(fullDate));
 }
 exports.toJsDate = toJsDate;

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

@@ -1,15 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getNowInUserTimezone = exports.getNowInIsoString = void 0;
+const timestamp_1 = require("../formatting/timestamp");
 const create_full_date_1 = require("../full-date/create-full-date");
-const primitive_conversions_1 = require("../full-date/primitive-conversions");
 const timezones_1 = require("../timezone/timezones");
 function getNowInIsoString() {
     /**
      * The time zone doesn't matter here because the ISO string will be identical for a given date
      * no matter what its timezone is.
      */
-    return (0, primitive_conversions_1.toIsoString)((0, create_full_date_1.getNowFullDate)(timezones_1.utcTimezone));
+    return (0, timestamp_1.toIsoString)((0, create_full_date_1.getNowFullDate)(timezones_1.utcTimezone));
 }
 exports.getNowInIsoString = getNowInIsoString;
 function getNowInUserTimezone() {

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

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toFormattedString = exports.toLocaleString = void 0;
+const luxon_date_time_conversion_1 = require("../full-date/luxon-date-time-conversion");
+const locales_1 = require("../locales");
+/**
+ * Chromium has a weird behavior where the "NARROW NO-BREAK SPACE" character (code 8239) is used
+ * instead of a space (code 32) before AM/PM.
+ */
+function fixChromiumSpace(original) {
+    return original.replace(new RegExp(String.fromCharCode(8239), 'g'), ' ');
+}
+/** Converts the given FullDate into a string in the user's locale, or the given localeOverride. */
+function toLocaleString(fullDate, formatOptions) {
+    const localeString = (0, luxon_date_time_conversion_1.toLuxonDateTime)(fullDate).toLocaleString({
+        ...formatOptions,
+    }, {
+        locale: formatOptions?.locale ?? locales_1.userLocale,
+    });
+    return fixChromiumSpace(localeString);
+}
+exports.toLocaleString = toLocaleString;
+/**
+ * Provides arbitrary date formatting using Luxon. For full details on the options for the format
+ * string input, see https://moment.github.io/luxon/#/formatting?id=table-of-tokens
+ *
+ * You probably should **prefer toLocaleString** so your users see the format they expect. It
+ * already has many formatting options.
+ */
+function toFormattedString(fullDate, format, localeOverride = locales_1.userLocale) {
+    const formattedString = (0, luxon_date_time_conversion_1.toLuxonDateTime)(fullDate).toFormat(format, { locale: localeOverride });
+    return fixChromiumSpace(formattedString);
+}
+exports.toFormattedString = toFormattedString;

package/dist/cjs/formatting/html-input.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toHtmlInputString = void 0;
+const common_1 = require("@augment-vir/common");
+const has_date_props_1 = require("../extra-utils/has-date-props");
+const full_date_shape_1 = require("../full-date/full-date-shape");
+const simple_strings_1 = require("./simple-strings");
+function toHtmlInputString(fullDate, inputType, includeSeconds) {
+    const internalFullDate = fullDate;
+    if (inputType === full_date_shape_1.FullDatePartEnum.Date) {
+        (0, has_date_props_1.assertHasDateProps)(internalFullDate, [
+            'year',
+            'month',
+            'day',
+        ]);
+        return (0, simple_strings_1.toSimpleDatePartString)(internalFullDate);
+    }
+    else if (inputType === full_date_shape_1.FullDatePartEnum.Time) {
+        if (includeSeconds && internalFullDate.second == undefined) {
+            throw new Error('Tried to include seconds in the time string but no seconds were provided.');
+        }
+        (0, has_date_props_1.assertHasDateProps)(internalFullDate, [
+            'hour',
+            'minute',
+        ]);
+        return (0, simple_strings_1.toSimpleTimePartString)(internalFullDate, !!includeSeconds);
+    }
+    else if (inputType === full_date_shape_1.FullDatePartEnum.DateTime) {
+        const datePart = toHtmlInputString(fullDate, full_date_shape_1.FullDatePartEnum.Date);
+        const timePart = toHtmlInputString(fullDate, full_date_shape_1.FullDatePartEnum.Time, includeSeconds);
+        return `${datePart}T${timePart}`;
+    }
+    else {
+        throw new Error(`Unexpected inputTyped: '${inputType}'. Expected usage of FullDatePartEnum or one of ${(0, common_1.getEnumTypedValues)(full_date_shape_1.FullDatePartEnum).join(', ')}.`);
+    }
+}
+exports.toHtmlInputString = toHtmlInputString;

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

@@ -0,0 +1,52 @@
+"use strict";
+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");
+function toRelativeString({ fullDate, relativeTo, options = {}, }) {
+    const allUnitDiffs = (0, diff_dates_1.diffDatesAllUnits)({
+        start: fullDate,
+        end: relativeTo,
+    });
+    const unitsWithinBounds = (0, common_1.mapObjectValues)(allUnitDiffs, (durationUnit, duration) => {
+        const isAboveZero = Math.floor(Math.abs(duration)) > 0;
+        return isAboveZero;
+    });
+    const unitToUse = duration_1.orderedDurationUnits.reduce((chosenUnit, currentUnit) => {
+        const isUnitAllowed = !options.blockedRelativeUnits?.includes(currentUnit);
+        if (isUnitAllowed && unitsWithinBounds[currentUnit]) {
+            return currentUnit;
+        }
+        else {
+            return chosenUnit;
+        }
+    }, undefined);
+    const shouldUseJustNow = options.blockJustNow
+        ? false
+        : (unitToUse === duration_1.DurationUnit.Minutes && allUnitDiffs.minutes < 2) ||
+            (unitToUse === duration_1.DurationUnit.Seconds && allUnitDiffs.seconds < 11) ||
+            (unitToUse === duration_1.DurationUnit.Milliseconds && allUnitDiffs.milliseconds < 710);
+    /** Some short circuits. */
+    if (unitToUse == undefined) {
+        return undefined;
+    }
+    else if (shouldUseJustNow) {
+        return 'just now';
+    }
+    const duration = allUnitDiffs[unitToUse];
+    const roundedAbsoluteDuration = Math.abs((0, common_1.round)({ digits: options.decimalDigitCount || 0, number: duration }));
+    const isDurationSingular = roundedAbsoluteDuration === 1;
+    const unitName = [
+        duration_1.singularDurationUnitNames[unitToUse],
+        isDurationSingular ? '' : 's',
+    ].join('');
+    const value = isDurationSingular ? 'a' : roundedAbsoluteDuration;
+    if (duration < 0) {
+        return `in ${value} ${unitName}`;
+    }
+    else {
+        return `${value} ${unitName} ago`;
+    }
+}
+exports.toRelativeString = toRelativeString;

package/dist/cjs/formatting/simple-strings.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toSimpleString = exports.toSimplePartStrings = exports.toSimpleTimePartString = exports.toSimpleDatePartString = void 0;
+const common_1 = require("@augment-vir/common");
+/**
+ * Create a string based on just the date parts of a FullDate.
+ *
+ * CAUTION: this does not user locale setting and should therefore not be used for user-facing date
+ * formatting. Prefer using `toLocaleString` instead for user-facing strings.
+ *
+ * Example output: `'2023-12-05'`
+ */
+function toSimpleDatePartString(fullDate) {
+    const dateParts = [
+        String(Math.abs(fullDate.year)).padStart(4, '0'),
+        String(Math.abs(fullDate.month)).padStart(2, '0'),
+        String(Math.abs(fullDate.day)).padStart(2, '0'),
+    ];
+    const dateString = dateParts.join('-');
+    return dateString;
+}
+exports.toSimpleDatePartString = toSimpleDatePartString;
+function toSimpleTimePartString(fullDate, includeSeconds) {
+    const seconds = (0, common_1.typedHasProperty)(fullDate, 'second') && includeSeconds
+        ? String(Math.abs(fullDate.second)).padStart(2, '0')
+        : undefined;
+    const timeParts = [
+        String(Math.abs(fullDate.hour)).padStart(2, '0'),
+        String(Math.abs(fullDate.minute)).padStart(2, '0'),
+        seconds,
+    ].filter(common_1.isTruthy);
+    return timeParts.join(':');
+}
+exports.toSimpleTimePartString = toSimpleTimePartString;
+function toSimplePartStrings(fullDate, options) {
+    return {
+        date: toSimpleDatePartString(fullDate),
+        time: toSimpleTimePartString(fullDate, options.includeSeconds),
+        timezone: fullDate.timezone,
+    };
+}
+exports.toSimplePartStrings = toSimplePartStrings;
+/**
+ * Converts a date into a simple, unambiguous date string.
+ *
+ * CAUTION: this does not user locale setting and should therefore not be used for user-facing date
+ * formatting. Prefer using `toLocaleString` instead for user-facing strings.
+ */
+function toSimpleString(fullDate, options) {
+    const parts = toSimplePartStrings(fullDate, options);
+    const stringParts = [
+        parts.date,
+        parts.time,
+        options.includeTimezone && `(${parts.timezone})`,
+    ].filter(common_1.isTruthy);
+    return stringParts.join(' ');
+}
+exports.toSimpleString = toSimpleString;

package/dist/cjs/formatting/timestamp.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toIsoString = exports.toTimestamp = void 0;
+const luxon_date_time_conversion_1 = require("../full-date/luxon-date-time-conversion");
+const timezones_1 = require("../timezone/timezones");
+/** Convert a FullDate into a unix timestamp with milliseconds. */
+function toTimestamp(fullDate) {
+    return (0, luxon_date_time_conversion_1.toLuxonDateTime)(fullDate).toMillis();
+}
+exports.toTimestamp = toTimestamp;
+/** Convert a FullDate into an ISO string in UTC; always ends in Z. */
+function toIsoString(fullDate) {
+    const isoString = (0, luxon_date_time_conversion_1.toLuxonDateTime)(fullDate).setZone(timezones_1.utcTimezone).toISO();
+    /** Ignore this edge case in the types and idk how to trigger it. */
+    /* c8 ignore next 3 */
+    if (!isoString) {
+        throw new Error(`Unable to get ISO string for '${JSON.stringify(fullDate)}'`);
+    }
+    return isoString;
+}
+exports.toIsoString = toIsoString;

package/dist/cjs/index.js

@@ -14,15 +14,21 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./augments/type"), exports);
 __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("./extra-utils/date-transforms"), exports);
+__exportStar(require("./extra-utils/has-date-props"), exports);
 __exportStar(require("./extra-utils/js-date-conversion"), exports);
 __exportStar(require("./extra-utils/now"), exports);
 __exportStar(require("./extra-utils/zero"), exports);
+__exportStar(require("./formatting/formatted-string"), exports);
+__exportStar(require("./formatting/html-input"), exports);
+__exportStar(require("./formatting/relative-string"), exports);
+__exportStar(require("./formatting/simple-strings"), exports);
+__exportStar(require("./formatting/string-format-types"), exports);
+__exportStar(require("./formatting/timestamp"), exports);
 __exportStar(require("./full-date/create-full-date"), exports);
 __exportStar(require("./full-date/date-like"), exports);
 __exportStar(require("./full-date/format-presets"), exports);
@@ -30,8 +36,6 @@ __exportStar(require("./full-date/full-date-shape"), exports);
 __exportStar(require("./full-date/is-valid-full-date"), exports);
 __exportStar(require("./full-date/luxon-date-time-conversion"), exports);
 __exportStar(require("./full-date/parsing"), exports);
-__exportStar(require("./full-date/primitive-conversions"), exports);
-__exportStar(require("./full-date/string-format-types"), exports);
 __exportStar(require("./locales"), exports);
 __exportStar(require("./timezone/timezone-checks"), exports);
 __exportStar(require("./timezone/timezone-names"), exports);

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

@@ -1,12 +1,31 @@
-import { MaybeTuple } from '../augments/type';
-import { Duration, DurationUnit } from '../duration';
+import { AllDurations, Duration, DurationUnit } from '../duration';
 import { FullDate } from '../full-date/full-date-shape';
-export declare function diffDates<const DurationKeys extends MaybeTuple<DurationUnit> = MaybeTuple<DurationUnit>>({ start, end, unit, }: {
+/**
+ * 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 declare function diffDates<const ChosenDurationKey extends DurationUnit>({ start, end, unit, }: {
     start: FullDate;
     end: FullDate;
-    unit: DurationKeys;
-}): Duration<DurationKeys>;
-export declare function isDateAfter({ start, end }: {
+    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 isDateAfter({ relativeTo, fullDate, }: {
+    relativeTo: FullDate;
+    fullDate: FullDate;
 }): boolean;

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

@@ -1,13 +1,65 @@
-import { DurationUnit } from '../duration';
+import { typedObjectFromEntries } from '@augment-vir/common';
+import { DurationUnit, orderedDurationUnits } from '../duration';
 import { toLuxonDateTime } from '../full-date/luxon-date-time-conversion';
+const conversionAccuracies = {
+    [DurationUnit.Years]: 'longterm',
+    [DurationUnit.Quarters]: 'longterm',
+    [DurationUnit.Months]: 'longterm',
+    [DurationUnit.Weeks]: 'casual',
+    [DurationUnit.Days]: 'casual',
+    [DurationUnit.Hours]: 'casual',
+    [DurationUnit.Minutes]: 'casual',
+    [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, }) {
     const luxonDateStart = toLuxonDateTime(start);
     const luxonDateEnd = toLuxonDateTime(end);
     const diff = luxonDateEnd
-        .diff(luxonDateStart, unit)
+        .diff(luxonDateStart, unit, {
+        conversionAccuracy: conversionAccuracies[unit],
+    })
         .toObject();
     return diff;
 }
-export function isDateAfter({ start, end }) {
-    return diffDates({ start, end, unit: DurationUnit.Milliseconds }).milliseconds >= 0;
+/**
+ * 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 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;
+}
+export function isDateAfter({ relativeTo, fullDate, }) {
+    return (diffDates({ start: relativeTo, end: fullDate, unit: DurationUnit.Milliseconds })
+        .milliseconds >= 0);
 }

package/dist/esm/duration.d.ts

@@ -1,15 +1,8 @@
-import { AtLeastTuple, RequiredAndNotNull } from '@augment-vir/common';
-import { DurationObjectUnits } from 'luxon';
-import { MaybeTuple } from './augments/type';
-/**
- * Exclude the higher order units of time measure for diffing because they vary significantly,
- * causing inaccuracies and many issues. See
- * https://moment.github.io/luxon/#/math?id=casual-vs-longterm-conversion-accuracy for more info.
- *
- * If you REALLY want to use these higher order units, convert the dates to luxon objects with
- * toLuxonDateTime and then run diff calculations there.
- */
+import { RequiredAndNotNull } from '@augment-vir/common';
 export declare enum DurationUnit {
+    Years = "years",
+    Quarters = "quarters",
+    Months = "months",
     Weeks = "weeks",
     Days = "days",
     Hours = "hours",
@@ -17,11 +10,46 @@ export declare enum DurationUnit {
     Seconds = "seconds",
     Milliseconds = "milliseconds"
 }
-/** All possible options for the more strict Duration type. */
-export type AnyDuration = DurationObjectUnits;
+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 MaybeTuple<DurationUnit>> = MaybeTuple<DurationUnit> extends DurationKeys ? Pick<AnyDuration, DurationUnit> : Pick<RequiredAndNotNull<AnyDuration>, DurationKeys extends AtLeastTuple<infer InnerValue, 1> ? InnerValue : DurationKeys>;
+export type Duration<DurationKeys extends DurationUnit = DurationUnit> = DurationUnit extends DurationKeys ? AnyDuration : Pick<AllDurations, `${DurationKeys}`>;

package/dist/esm/duration.js

@@ -1,13 +1,8 @@
-/**
- * Exclude the higher order units of time measure for diffing because they vary significantly,
- * causing inaccuracies and many issues. See
- * https://moment.github.io/luxon/#/math?id=casual-vs-longterm-conversion-accuracy for more info.
- *
- * If you REALLY want to use these higher order units, convert the dates to luxon objects with
- * toLuxonDateTime and then run diff calculations there.
- */
 export var DurationUnit;
 (function (DurationUnit) {
+    DurationUnit["Years"] = "years";
+    DurationUnit["Quarters"] = "quarters";
+    DurationUnit["Months"] = "months";
     DurationUnit["Weeks"] = "weeks";
     DurationUnit["Days"] = "days";
     DurationUnit["Hours"] = "hours";
@@ -15,3 +10,29 @@ export var DurationUnit;
     DurationUnit["Seconds"] = "seconds";
     DurationUnit["Milliseconds"] = "milliseconds";
 })(DurationUnit || (DurationUnit = {}));
+export const singularDurationUnitNames = {
+    [DurationUnit.Milliseconds]: 'millisecond',
+    [DurationUnit.Seconds]: 'second',
+    [DurationUnit.Minutes]: 'minute',
+    [DurationUnit.Hours]: 'hour',
+    [DurationUnit.Days]: 'day',
+    [DurationUnit.Weeks]: 'week',
+    [DurationUnit.Months]: 'month',
+    [DurationUnit.Quarters]: 'quarter',
+    [DurationUnit.Years]: 'year',
+};
+/**
+ * Array of DurationUnit values: from smallest unit (milliseconds at index 0) to longest unit
+ * (years).
+ */
+export const orderedDurationUnits = [
+    DurationUnit.Milliseconds,
+    DurationUnit.Seconds,
+    DurationUnit.Minutes,
+    DurationUnit.Hours,
+    DurationUnit.Days,
+    DurationUnit.Weeks,
+    DurationUnit.Months,
+    DurationUnit.Quarters,
+    DurationUnit.Years,
+];

package/dist/esm/extra-utils/has-date-props.d.ts

@@ -0,0 +1,8 @@
+import { PartialAndUndefined, RequiredAndNotNullBy } from '@augment-vir/common';
+import { FullDate } from '../full-date/full-date-shape';
+export declare function hasDateProps<PartialFullDate extends PartialAndUndefined<FullDate>, 
+/** A union of strings. */
+RequiredKeysUnion extends keyof FullDate>(dateInput: PartialAndUndefined<FullDate>, keys: ReadonlyArray<RequiredKeysUnion>): dateInput is RequiredAndNotNullBy<PartialFullDate, RequiredKeysUnion>;
+export declare function assertHasDateProps<PartialFullDate extends PartialAndUndefined<FullDate>, 
+/** A union of strings. */
+RequiredKeysUnion extends keyof FullDate>(dateInput: PartialAndUndefined<FullDate>, keys: ReadonlyArray<RequiredKeysUnion>): asserts dateInput is RequiredAndNotNullBy<PartialFullDate, RequiredKeysUnion>;