date-vir 5.3.2 → 7.0.0

package/dist/extra-utils/zero.js

@@ -0,0 +1,94 @@
+import { getEnumValues, pickObjectKeys, typedObjectFromEntries } from '@augment-vir/common';
+import { TimeKey } from '../full-date/full-date-parts.js';
+import { overrideDateParts } from './override-date.js';
+/**
+ * A {@link FullDate} instance that has the lowest, valid, non-negative, value for each property.
+ *
+ * @category Constants
+ */
+export const zeroDate = {
+    year: 0,
+    month: 1,
+    day: 1,
+    hour: 0,
+    minute: 0,
+    second: 0,
+    millisecond: 0,
+};
+/**
+ * A {@link FullDate} instance that has the lowest, valid, non-negative, value for each property.
+ * Alias for {@link zeroDate}.
+ *
+ * @category Constants
+ */
+export const emptyDate = zeroDate;
+/**
+ * An object that contains the time parts of {@link FullDate} all set to `0`.
+ *
+ * @category Constants
+ */
+export const zeroTime = pickObjectKeys(zeroDate, getEnumValues(TimeKey));
+/**
+ * Clear the time parts of a {@link FullDate}, setting them all to `0`.
+ *
+ * @category Clear
+ * @example
+ *
+ * ```ts
+ * import {clearTime, type FullDate} from 'date-vir';
+ *
+ * const exampleDate: Readonly<FullDate> = {
+ *     year: 2024,
+ *     month: 1,
+ *     day: 5,
+ *     hour: 1,
+ *     minute: 1,
+ *     second: 1,
+ *     millisecond: 1,
+ *     timezone: 'UTC',
+ * };
+ *
+ * clearTime(exampleDate);
+ * // `{year: 2024, month: 1, day: 5, hour: 0, minute: 0, second: 0, millisecond: 0, timezone: 'UTC'}`
+ * ```
+ */
+export function clearTime(inputFullDate) {
+    return clearParts(inputFullDate, getEnumValues(TimeKey));
+}
+/**
+ * Clear all the selected parts of {@link FullDate} by setting them each to their lowest, valid
+ * value. See {@link zeroDate} for the lowest valid values for each property.
+ *
+ * @category Clear
+ * @example
+ *
+ * ```ts
+ * import {clearTime, type FullDate} from 'date-vir';
+ *
+ * const exampleDate: Readonly<FullDate> = {
+ *     year: 2024,
+ *     month: 1,
+ *     day: 5,
+ *     hour: 1,
+ *     minute: 1,
+ *     second: 1,
+ *     millisecond: 1,
+ *     timezone: 'UTC',
+ * };
+ *
+ * clearParts(exampleDate, [
+ *     'year',
+ *     'day',
+ * ]);
+ * // `{year: 0, month: 1, day: 1, hour: 1, minute: 1, second: 1, millisecond: 1, timezone: 'UTC'}`
+ * ```
+ */
+export function clearParts(inputFullDate, parts) {
+    const clearParts = typedObjectFromEntries(parts.map((keyName) => {
+        return [
+            keyName,
+            zeroDate[keyName],
+        ];
+    }));
+    return overrideDateParts(inputFullDate, clearParts);
+}

package/dist/formatting/formatted-string.d.ts

@@ -0,0 +1,58 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type FullDate } from '../full-date/full-date-shape.js';
+/**
+ * Converts the given {@link FullDate} into a string based the user's locale, or the given locale
+ * options.
+ *
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {toLocaleString} from 'date-vir';
+ *
+ * ToLocaleString({
+ *     year: 2024,
+ *     month: 9,
+ *     day: 25,
+ *     hour: 0,
+ *     minute: 0,
+ *     second: 0,
+ *     millisecond: 0,
+ * });
+ * // `'9/25/2024'` in my locale, yours may be different
+ * ```
+ */
+export declare function toLocaleString(fullDate: FullDate, 
+/** Defaults to using the user's own locale. */
+formatOptions?: (Intl.DateTimeFormatOptions & PartialWithUndefined<{
+    locale: string;
+}>) | undefined): string;
+/**
+ * Provides arbitrary date formatting control (using Luxon under the hood). For full details on the
+ * options for format control, see https://moment.github.io/luxon/#/formatting?id=table-of-tokens
+ *
+ * In most cases you should prefer {@link toLocaleString} so your users see the format they expect.
+ * {@link toLocaleString} already has many formatting options.
+ *
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {toFormattedString} from 'date-vir';
+ *
+ * toFormattedString(
+ *     {
+ *         year: 2024,
+ *         month: 9,
+ *         day: 25,
+ *         hour: 0,
+ *         minute: 0,
+ *         second: 0,
+ *         millisecond: 0,
+ *     },
+ *     'MMM-yyyy',
+ * );
+ * // `'Sep-2024'`
+ * ```
+ */
+export declare function toFormattedString(fullDate: FullDate, format: string, localeOverride?: string): string;

package/dist/formatting/formatted-string.js

@@ -0,0 +1,73 @@
+import { toLuxonDateTime } from '../full-date/luxon-date-time-conversion.js';
+import { userLocale } from '../locales.js';
+/**
+ * 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.fromCodePoint(8239), 'g'), ' ');
+}
+/**
+ * Converts the given {@link FullDate} into a string based the user's locale, or the given locale
+ * options.
+ *
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {toLocaleString} from 'date-vir';
+ *
+ * ToLocaleString({
+ *     year: 2024,
+ *     month: 9,
+ *     day: 25,
+ *     hour: 0,
+ *     minute: 0,
+ *     second: 0,
+ *     millisecond: 0,
+ * });
+ * // `'9/25/2024'` in my locale, yours may be different
+ * ```
+ */
+export function toLocaleString(fullDate, 
+/** Defaults to using the user's own locale. */
+formatOptions) {
+    const localeString = toLuxonDateTime(fullDate).toLocaleString({
+        ...formatOptions,
+    }, {
+        locale: formatOptions?.locale ?? userLocale,
+    });
+    return fixChromiumSpace(localeString);
+}
+/**
+ * Provides arbitrary date formatting control (using Luxon under the hood). For full details on the
+ * options for format control, see https://moment.github.io/luxon/#/formatting?id=table-of-tokens
+ *
+ * In most cases you should prefer {@link toLocaleString} so your users see the format they expect.
+ * {@link toLocaleString} already has many formatting options.
+ *
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {toFormattedString} from 'date-vir';
+ *
+ * toFormattedString(
+ *     {
+ *         year: 2024,
+ *         month: 9,
+ *         day: 25,
+ *         hour: 0,
+ *         minute: 0,
+ *         second: 0,
+ *         millisecond: 0,
+ *     },
+ *     'MMM-yyyy',
+ * );
+ * // `'Sep-2024'`
+ * ```
+ */
+export function toFormattedString(fullDate, format, localeOverride = userLocale) {
+    const formattedString = toLuxonDateTime(fullDate).toFormat(format, { locale: localeOverride });
+    return fixChromiumSpace(formattedString);
+}

package/dist/formatting/html-input.d.ts

@@ -0,0 +1,30 @@
+import { FullDatePart } from '../full-date/full-date-parts.js';
+import { DatePart, FullDate } from '../full-date/full-date-shape.js';
+import { DateTimeString, DateTimeWithSeconds, JustDateString, JustTimeString, JustTimeWithSecondsString } from './string-format-types.js';
+/**
+ * Only the date part of a {@link FullDate}, without timezone.
+ *
+ * @category Internal
+ */
+export type OnlyDatePart = Omit<DatePart, 'timezone'>;
+/**
+ * Only the hour and minute part of a {@link FullDate}, made optional.
+ *
+ * @category Internal
+ */
+export type OnlyHourMinutePart = Pick<Partial<FullDate>, 'hour' | 'minute'>;
+/**
+ * Only the hour, minute, and second part of a {@link FullDate}, made optional.
+ *
+ * @category Internal
+ */
+export type OnlyHourMinuteSecondPart = Pick<Partial<FullDate>, 'hour' | 'minute' | 'second'>;
+export declare function toHtmlInputString(fullDate: Omit<FullDate, 'timezone'>, inputType: FullDatePart.DateTime, includeSeconds: true): DateTimeWithSeconds;
+export declare function toHtmlInputString(fullDate: Omit<FullDate, 'timezone'>, inputType: FullDatePart.DateTime, includeSeconds?: false | undefined): DateTimeString;
+export declare function toHtmlInputString(fullDate: OnlyDatePart, inputType: FullDatePart.Date): JustDateString;
+export declare function toHtmlInputString(fullDate: OnlyHourMinutePart, inputType: FullDatePart.Time, includeSeconds?: false | undefined): JustTimeString;
+export declare function toHtmlInputString(fullDate: OnlyHourMinuteSecondPart, inputType: FullDatePart.Time, includeSeconds: true): JustTimeWithSecondsString;
+export declare function toHtmlInputString(fullDate: OnlyHourMinutePart | OnlyHourMinuteSecondPart, inputType: FullDatePart.Time, includeSeconds?: boolean | undefined): JustTimeWithSecondsString | JustTimeString;
+export declare function toHtmlInputString(fullDate: OnlyHourMinuteSecondPart | OnlyDatePart, inputType: FullDatePart, includeSeconds: true): JustDateString | JustTimeWithSecondsString;
+export declare function toHtmlInputString(fullDate: OnlyHourMinutePart | OnlyDatePart, inputType: FullDatePart, includeSeconds?: false | undefined): JustDateString | JustTimeString;
+export declare function toHtmlInputString(fullDate: Omit<FullDate, 'timezone'> | OnlyHourMinutePart | OnlyHourMinuteSecondPart | OnlyDatePart, inputType: FullDatePart, includeSeconds?: boolean | undefined): JustDateString | JustTimeWithSecondsString | JustTimeString | DateTimeWithSeconds | DateTimeString;

package/dist/formatting/html-input.js

@@ -0,0 +1,47 @@
+import { getEnumValues } from '@augment-vir/common';
+import { assertHasFullDateKeys } from '../extra-utils/has-date-props.js';
+import { FullDatePart } from '../full-date/full-date-parts.js';
+import { toSimpleDatePartString, toSimpleTimePartString } from './simple-strings.js';
+/**
+ * Converts a {@link FullDate} instance into a string that is understood by
+ * [`type="date"`](https://developer.mozilla.org/docs/Web/HTML/Element/input/date) or
+ * [`type="time"`](https://developer.mozilla.org/docs/Web/HTML/Element/input/time) instances of
+ * [`HTMLInputElement`](https://developer.mozilla.org/docs/Web/HTML/Element/input). This can
+ * optionally include seconds as well for `type="time"`.
+ *
+ * This function ignores timezone, the literal stored date and time numbers are simply concatenated
+ * into a string. If you wish to convert time zones, first call {@link toNewTimezone} on your
+ * {@link FullDate} instance.
+ *
+ * @category HTML
+ * @category Formatting
+ */
+export function toHtmlInputString(fullDate, inputType, includeSeconds) {
+    const internalFullDate = fullDate;
+    if (inputType === FullDatePart.Date) {
+        assertHasFullDateKeys(internalFullDate, [
+            'year',
+            'month',
+            'day',
+        ]);
+        return toSimpleDatePartString(internalFullDate);
+    }
+    else if (inputType === FullDatePart.Time) {
+        if (includeSeconds && internalFullDate.second == undefined) {
+            throw new Error('Tried to include seconds in the time string but no seconds were provided.');
+        }
+        assertHasFullDateKeys(internalFullDate, [
+            'hour',
+            'minute',
+        ]);
+        return toSimpleTimePartString(internalFullDate, !!includeSeconds);
+    }
+    else if (inputType === FullDatePart.DateTime) {
+        const datePart = toHtmlInputString(fullDate, FullDatePart.Date);
+        const timePart = toHtmlInputString(fullDate, FullDatePart.Time, includeSeconds);
+        return `${datePart}T${timePart}`;
+    }
+    else {
+        throw new Error(`Unexpected inputTyped: '${String(inputType)}'. Expected usage of FullDatePart, one of ${getEnumValues(FullDatePart).join(', ')}.`);
+    }
+}

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

@@ -0,0 +1,53 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { AnyDuration, DurationUnitSelection } from '@date-vir/duration';
+import { FullDate } from '../full-date/full-date-shape.js';
+/**
+ * Options for {@link toRelativeString}.
+ *
+ * @category Internal
+ */
+export type RelativeStringOptions = PartialWithUndefined<{
+    /**
+     * Set this to `true` to prevent the `'just now'` relative string from being used when the two
+     * dates are very close.
+     *
+     * @default false // (`'just now'` is used)
+     */
+    blockJustNow: boolean;
+    /**
+     * Set this to `true` to only use the largest selected unit with a non-zero value. Otherwise,
+     * the output string will contain all selected non-zero units.
+     *
+     * @default false
+     */
+    useOnlyLargestUnit: boolean;
+    /**
+     * The number of decimals to allow for each duration unit's value.
+     *
+     * @default 0
+     */
+    allowedDecimals: number;
+}>;
+/**
+ * This function starts with a duration (either by being directly passed a duration or by diffing
+ * two dates into a duration) and converts that duration into a relative string like "1 month ago"
+ * or "in 1 month". Rounding is automatically set to 0 decimal points, but that can be changed.
+ *
+ * When extremely close to a `0` difference, the output string will be `'just now'`, which can be
+ * disabled.
+ *
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {toRelativeString, selectAllDurationUnits} from 'date-vir';
+ *
+ * toRelativeString({days: 1.6}, {days: true}); // `'in 2 days'`
+ * toRelativeString({days: 1.6}, {days: true, hours: true}); // `'in 1 day, 14 hours'`
+ * toRelativeString({seconds: 1}, selectAllDurationUnits); // `'just now'`
+ * ```
+ */
+export declare function toRelativeString(datesOrDuration: Readonly<{
+    start: Readonly<FullDate>;
+    end: Readonly<FullDate>;
+}> | Readonly<AnyDuration>, units: Readonly<DurationUnitSelection>, options?: Readonly<RelativeStringOptions>): string;

package/dist/formatting/relative-string.js

@@ -0,0 +1,93 @@
+import { check } from '@augment-vir/assert';
+import { arrayToObject, filterMap } from '@augment-vir/common';
+import { DurationUnit, convertDuration, flattenUnitSelection, singularDurationUnitNames, } from '@date-vir/duration';
+import { diffDates } from '../date-operations/diff-dates.js';
+/**
+ * This function starts with a duration (either by being directly passed a duration or by diffing
+ * two dates into a duration) and converts that duration into a relative string like "1 month ago"
+ * or "in 1 month". Rounding is automatically set to 0 decimal points, but that can be changed.
+ *
+ * When extremely close to a `0` difference, the output string will be `'just now'`, which can be
+ * disabled.
+ *
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {toRelativeString, selectAllDurationUnits} from 'date-vir';
+ *
+ * toRelativeString({days: 1.6}, {days: true}); // `'in 2 days'`
+ * toRelativeString({days: 1.6}, {days: true, hours: true}); // `'in 1 day, 14 hours'`
+ * toRelativeString({seconds: 1}, selectAllDurationUnits); // `'just now'`
+ * ```
+ */
+export function toRelativeString(datesOrDuration, units, options = {}) {
+    const selectedUnits = flattenUnitSelection(units);
+    /** If there are no selected units, return nothing. */
+    if (!check.isLengthAtLeast(selectedUnits, 1)) {
+        return '';
+    }
+    const diff = convertDuration('start' in datesOrDuration ? diffDates(datesOrDuration, units) : datesOrDuration, units, {
+        roundToDigits: options.allowedDecimals || 0,
+    });
+    const isDiffPositive = convertDuration(diff, { milliseconds: true }).milliseconds >= 0;
+    const unitValues = filterMap(selectedUnits, (unit) => {
+        const quantity = diff[unit] || 0;
+        if (!quantity) {
+            return undefined;
+        }
+        return {
+            quantity,
+            unit,
+        };
+    }, check.isTruthy).reverse();
+    const shouldUseJustNow = !options.blockJustNow &&
+        (!check.isLengthAtLeast(unitValues, 1) ||
+            (unitValues[0].unit === DurationUnit.Minutes && (diff.minutes || 0) < 1.5) ||
+            (unitValues[0].unit === DurationUnit.Seconds && (diff.seconds || 0) < 11) ||
+            (unitValues[0].unit === DurationUnit.Milliseconds && (diff.milliseconds || 0) < 750));
+    if (shouldUseJustNow) {
+        return 'just now';
+    }
+    else if (options.useOnlyLargestUnit) {
+        return toRelativeString(datesOrDuration, { [unitValues[0].unit]: true }, {
+            ...options,
+            useOnlyLargestUnit: false,
+        });
+    }
+    else if (unitValues.length < selectedUnits.length) {
+        /**
+         * If the finalized units are less than the selected units, rerun the whole calculation to
+         * make sure we're using the right accuracy.
+         */
+        return toRelativeString(datesOrDuration, arrayToObject(unitValues, ({ unit }) => {
+            return {
+                key: unit,
+                value: true,
+            };
+        }), options);
+    }
+    const unitsString = unitValues
+        .map(({ quantity, unit }) => {
+        const absoluteQuantity = Math.abs(quantity);
+        return [
+            absoluteQuantity,
+            ' ',
+            singularDurationUnitNames[unit],
+            absoluteQuantity > 1 ? 's' : '',
+        ].join('');
+    })
+        .join(', ');
+    if (isDiffPositive) {
+        return [
+            'in',
+            unitsString,
+        ].join(' ');
+    }
+    else {
+        return [
+            unitsString,
+            'ago',
+        ].join(' ');
+    }
+}

package/dist/formatting/simple-strings.d.ts

@@ -0,0 +1,187 @@
+import type { SetOptionalAndNullable } from '@augment-vir/common';
+import { FullDate } from '../full-date/full-date-shape.js';
+import { JustDateString, JustTimeString, JustTimeWithSecondsString } from './string-format-types.js';
+/**
+ * Create a string based on just the date parts of a FullDate.
+ *
+ * **CAUTION**: this does not user locale setting. Prefer {@link toLocaleString} whenever possible.
+ *
+ * Example output: `'2023-12-05'`
+ *
+ * @category Internal
+ */
+export declare function toSimpleDatePartString(fullDate: Pick<FullDate, 'year' | 'month' | 'day'>): JustDateString;
+/**
+ * Creates a string based on just the time parts of a FullDate.
+ *
+ * **CAUTION**: this does not user locale setting. Prefer {@link toLocaleString} whenever possible.
+ *
+ * Example output: `'05:32:21'`
+ *
+ * @category Internal
+ */
+export declare function toSimpleTimePartString(fullDate: Pick<FullDate, 'hour' | 'minute' | 'second'> | Pick<FullDate, 'hour' | 'minute'>, includeSeconds: boolean): JustTimeWithSecondsString | JustTimeString;
+/**
+ * The parts of {@link FullDate} required for {@link toDatePartStrings}.
+ *
+ * @category Internal
+ */
+export type FullDateForParts = SetOptionalAndNullable<FullDate, 'millisecond'>;
+/**
+ * Splits a FullDate up into multiple formatted string representations.
+ *
+ * **CAUTION**: this does not user locale setting. Prefer {@link toLocaleString} whenever possible.
+ *
+ * This uses numbers for everything.
+ *
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {toDatePartStrings, utcTimezone} from 'date-vir';
+ *
+ * let result = toDatePartStrings(
+ *     {
+ *         year: 2024,
+ *         month: 4,
+ *         day: 24,
+ *         hour: 6,
+ *         minute: 4,
+ *         second: 9,
+ *         millisecond: 123,
+ *         timezone: utcTimezone,
+ *     },
+ *     {includeSeconds: true},
+ * );
+ * // outputs:
+ * result = {
+ *     date: '2024-04-24',
+ *     time: '06:04:09',
+ *     timezone: 'UTC',
+ * };
+ * ```
+ */
+export declare function toDatePartStrings(fullDate: FullDateForParts, options: {
+    includeSeconds: true;
+}): {
+    date: JustDateString;
+    time: JustTimeWithSecondsString;
+    timezone: string;
+};
+/**
+ * Splits a FullDate up into multiple formatted string representations.
+ *
+ * **CAUTION**: this does not user locale setting. Prefer {@link toLocaleString} whenever possible.
+ *
+ * This uses numbers for everything.
+ *
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {toDatePartStrings, utcTimezone} from 'date-vir';
+ *
+ * let result = toDatePartStrings(
+ *     {
+ *         year: 2024,
+ *         month: 4,
+ *         day: 24,
+ *         hour: 6,
+ *         minute: 4,
+ *         second: 9,
+ *         millisecond: 123,
+ *         timezone: utcTimezone,
+ *     },
+ *     {includeSeconds: true},
+ * );
+ * // outputs:
+ * result = {
+ *     date: '2024-04-24',
+ *     time: '06:04:09',
+ *     timezone: 'UTC',
+ * };
+ * ```
+ */
+export declare function toDatePartStrings(fullDate: SetOptionalAndNullable<FullDateForParts, 'second'>, options: {
+    includeSeconds: false;
+}): {
+    date: JustDateString;
+    time: JustTimeString;
+    timezone: string;
+};
+/**
+ * Splits a FullDate up into multiple formatted string representations.
+ *
+ * **CAUTION**: this does not user locale setting. Prefer {@link toLocaleString} whenever possible.
+ *
+ * This uses numbers for everything.
+ *
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {toDatePartStrings, utcTimezone} from 'date-vir';
+ *
+ * let result = toDatePartStrings(
+ *     {
+ *         year: 2024,
+ *         month: 4,
+ *         day: 24,
+ *         hour: 6,
+ *         minute: 4,
+ *         second: 9,
+ *         millisecond: 123,
+ *         timezone: utcTimezone,
+ *     },
+ *     {includeSeconds: true},
+ * );
+ * // outputs:
+ * result = {
+ *     date: '2024-04-24',
+ *     time: '06:04:09',
+ *     timezone: 'UTC',
+ * };
+ * ```
+ */
+export declare function toDatePartStrings(fullDate: FullDateForParts, options: {
+    includeSeconds: boolean;
+}): {
+    date: JustDateString;
+    time: JustTimeWithSecondsString | JustTimeString;
+    timezone: string;
+};
+/**
+ * Converts a date into a simple, unambiguous date string.
+ *
+ * **CAUTION**: this does not user locale setting. Prefer {@link toLocaleString} whenever possible.
+ *
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {toSimpleString} from 'date-vir';
+ *
+ * let result = toSimpleString(
+ *     {
+ *         year: 2024,
+ *         month: 4,
+ *         day: 24,
+ *         hour: 6,
+ *         minute: 4,
+ *         second: 9,
+ *         millisecond: 123,
+ *         timezone: utcTimezone,
+ *     },
+ *     {
+ *         includeSeconds: false,
+ *         includeTimezone: false,
+ *     },
+ * );
+ * // outputs:
+ * result = '2024-04-24 06:04';
+ * ```
+ */
+export declare function toSimpleString(fullDate: FullDateForParts, options: {
+    includeSeconds: boolean;
+    includeTimezone: boolean;
+}): string;