date-vir 5.3.2 → 7.0.0

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

@@ -0,0 +1,95 @@
+import { type DurationBySelection, type DurationUnitSelection, type RoundOptions } from '@date-vir/duration';
+import { FullDate } from '../full-date/full-date-shape.js';
+/**
+ * Diffs two dates and returns the diff in the specified unit or units. When a multiple units are
+ * provided with the `units` input property, an array is returned with the full diff duration
+ * contained in each entry in the requested unit.
+ *
+ * Note: when years, quarters, or months are used for the unit, "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
+ *
+ * @category Calculation
+ * @example
+ *
+ * ```ts
+ * import {diffDates, DurationUnit} from 'date-vir';
+ *
+ * const exampleDate: FullDate = {
+ *     year: 2024,
+ *     month: 1,
+ *     day: 5,
+ *     hour: 1,
+ *     minute: 1,
+ *     second: 1,
+ *     millisecond: 1,
+ *     timezone: 'UTC',
+ * };
+ *
+ * // get the diff in days
+ * diffDates({start: exampleDate, end: {...exampleDate, day: 6}}, {days: true}); // {days: 1}
+ * // get the full diff separately in days and also years
+ * diffDates(
+ *     {
+ *         start: exampleDate,
+ *         end: {
+ *             ...exampleDate,
+ *             day: exampleDate.day + 1,
+ *             hour: exampleDate.hour + 3,
+ *         },
+ *     },
+ *     {
+ *         days: true,
+ *         hours: true,
+ *     },
+ * );
+ * // {days: 1, hours: 3}
+ * ```
+ */
+export declare function diffDates<const SelectedUnits extends Readonly<DurationUnitSelection>>({ start, end, }: Readonly<{
+    start: Readonly<FullDate>;
+    end: Readonly<FullDate>;
+}>, 
+/** Which units the output should contain. */
+units: SelectedUnits, options?: Readonly<RoundOptions>): DurationBySelection<SelectedUnits>;
+/**
+ * Checks if `fullDate` is after `relativeTo`.
+ *
+ * @category Calculation
+ * @example
+ *
+ * ```ts
+ * import {isDateAfter, type FullDate} from 'date-vir';
+ *
+ * const exampleDate: FullDate = {
+ *     year: 2024,
+ *     month: 1,
+ *     day: 5,
+ *     hour: 1,
+ *     minute: 1,
+ *     second: 1,
+ *     millisecond: 1,
+ *     timezone: 'UTC',
+ * };
+ *
+ * isDateAfter({
+ *     fullDate: exampleDate,
+ *     relativeTo: {
+ *         ...exampleDate,
+ *         year: 1900,
+ *     },
+ * }); // `true`
+ *
+ * isDateAfter({
+ *     fullDate: exampleDate,
+ *     relativeTo: {
+ *         ...exampleDate,
+ *         year: 3000,
+ *     },
+ * }); // `false`
+ * ```
+ */
+export declare function isDateAfter({ relativeTo, fullDate, }: {
+    relativeTo: Readonly<FullDate>;
+    fullDate: Readonly<FullDate>;
+}): boolean;

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

@@ -0,0 +1,124 @@
+import { DurationUnit, flattenUnitSelection, roundDuration, } from '@date-vir/duration';
+import { toLuxonDateTime } from '../full-date/luxon-date-time-conversion.js';
+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',
+};
+function getHighestPriorityConversionAccuracy(units) {
+    if (units.some((unit) => conversionAccuracies[unit] === 'longterm')) {
+        return 'longterm';
+    }
+    else {
+        return 'casual';
+    }
+}
+/**
+ * Diffs two dates and returns the diff in the specified unit or units. When a multiple units are
+ * provided with the `units` input property, an array is returned with the full diff duration
+ * contained in each entry in the requested unit.
+ *
+ * Note: when years, quarters, or months are used for the unit, "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
+ *
+ * @category Calculation
+ * @example
+ *
+ * ```ts
+ * import {diffDates, DurationUnit} from 'date-vir';
+ *
+ * const exampleDate: FullDate = {
+ *     year: 2024,
+ *     month: 1,
+ *     day: 5,
+ *     hour: 1,
+ *     minute: 1,
+ *     second: 1,
+ *     millisecond: 1,
+ *     timezone: 'UTC',
+ * };
+ *
+ * // get the diff in days
+ * diffDates({start: exampleDate, end: {...exampleDate, day: 6}}, {days: true}); // {days: 1}
+ * // get the full diff separately in days and also years
+ * diffDates(
+ *     {
+ *         start: exampleDate,
+ *         end: {
+ *             ...exampleDate,
+ *             day: exampleDate.day + 1,
+ *             hour: exampleDate.hour + 3,
+ *         },
+ *     },
+ *     {
+ *         days: true,
+ *         hours: true,
+ *     },
+ * );
+ * // {days: 1, hours: 3}
+ * ```
+ */
+export function diffDates({ start, end, }, 
+/** Which units the output should contain. */
+units, options = {}) {
+    const luxonDateStart = toLuxonDateTime(start);
+    const luxonDateEnd = toLuxonDateTime(end);
+    const selectedUnits = flattenUnitSelection(units);
+    const conversionAccuracy = getHighestPriorityConversionAccuracy(selectedUnits);
+    const additiveDiff = luxonDateEnd
+        .diff(luxonDateStart, selectedUnits, {
+        conversionAccuracy,
+    })
+        .toObject();
+    return roundDuration(additiveDiff, options);
+}
+/**
+ * Checks if `fullDate` is after `relativeTo`.
+ *
+ * @category Calculation
+ * @example
+ *
+ * ```ts
+ * import {isDateAfter, type FullDate} from 'date-vir';
+ *
+ * const exampleDate: FullDate = {
+ *     year: 2024,
+ *     month: 1,
+ *     day: 5,
+ *     hour: 1,
+ *     minute: 1,
+ *     second: 1,
+ *     millisecond: 1,
+ *     timezone: 'UTC',
+ * };
+ *
+ * isDateAfter({
+ *     fullDate: exampleDate,
+ *     relativeTo: {
+ *         ...exampleDate,
+ *         year: 1900,
+ *     },
+ * }); // `true`
+ *
+ * isDateAfter({
+ *     fullDate: exampleDate,
+ *     relativeTo: {
+ *         ...exampleDate,
+ *         year: 3000,
+ *     },
+ * }); // `false`
+ * ```
+ */
+export function isDateAfter({ relativeTo, fullDate, }) {
+    return (diffDates({
+        start: relativeTo,
+        end: fullDate,
+    }, { milliseconds: true }).milliseconds >= 0);
+}

package/dist/extra-utils/end.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A partial {@link FullDate} instance that has the highest value for each time property.
+ *
+ * @category Constants
+ */
+export declare const endTime: {
+    readonly hour: 23;
+    readonly minute: 59;
+    readonly second: 59;
+    readonly millisecond: 999;
+};

package/dist/extra-utils/end.js

@@ -0,0 +1,11 @@
+/**
+ * A partial {@link FullDate} instance that has the highest value for each time property.
+ *
+ * @category Constants
+ */
+export const endTime = {
+    hour: 23,
+    minute: 59,
+    second: 59,
+    millisecond: 999,
+};

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

@@ -0,0 +1,35 @@
+import { type PartialWithUndefined, type SetRequiredAndNotNull } from '@augment-vir/common';
+import { type FullDate } from '../full-date/full-date-shape.js';
+import type { Timezone } from '../timezone/timezones.js';
+/**
+ * Checks that the input has all the requested {@link FullDate} keys.
+ *
+ * @category Util
+ * @example
+ *
+ * ```ts
+ * import {hasFullDateKeys} from 'date-vir';
+ *
+ * hasFullDateKeys({year: 2024}, ['year']); // `true`
+ * hasFullDateKeys({year: 2024}, ['day']); // `false`
+ * ```
+ */
+export declare function hasFullDateKeys<SpecificTimezone extends Timezone, PartialFullDate extends PartialWithUndefined<FullDate<SpecificTimezone>>, 
+/** A union of strings. */
+RequiredKeys extends keyof FullDate<SpecificTimezone>>(partialFullDate: PartialWithUndefined<FullDate<SpecificTimezone>>, keys: ReadonlyArray<RequiredKeys>): partialFullDate is SetRequiredAndNotNull<PartialFullDate, RequiredKeys>;
+/**
+ * Asserts that the input has all the requested {@link FullDate} keys.
+ *
+ * @category Util
+ * @example
+ *
+ * ```ts
+ * import {assertHasFullDateKeys} from 'date-vir';
+ *
+ * assertHasFullDateKeys({year: 2024}, ['year']); // passes
+ * assertHasFullDateKeys({year: 2024}, ['day']); // fails
+ * ```
+ */
+export declare function assertHasFullDateKeys<SpecificTimezone extends Timezone, PartialFullDate extends PartialWithUndefined<FullDate<SpecificTimezone>>, 
+/** A union of strings. */
+RequiredKeys extends keyof FullDate<SpecificTimezone>>(partialFullDate: PartialWithUndefined<FullDate<SpecificTimezone>>, keys: ReadonlyArray<RequiredKeys>): asserts partialFullDate is SetRequiredAndNotNull<PartialFullDate, RequiredKeys>;

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

@@ -0,0 +1,46 @@
+/**
+ * Checks that the input has all the requested {@link FullDate} keys.
+ *
+ * @category Util
+ * @example
+ *
+ * ```ts
+ * import {hasFullDateKeys} from 'date-vir';
+ *
+ * hasFullDateKeys({year: 2024}, ['year']); // `true`
+ * hasFullDateKeys({year: 2024}, ['day']); // `false`
+ * ```
+ */
+export function hasFullDateKeys(partialFullDate, keys) {
+    try {
+        assertHasFullDateKeys(partialFullDate, keys);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Asserts that the input has all the requested {@link FullDate} keys.
+ *
+ * @category Util
+ * @example
+ *
+ * ```ts
+ * import {assertHasFullDateKeys} from 'date-vir';
+ *
+ * assertHasFullDateKeys({year: 2024}, ['year']); // passes
+ * assertHasFullDateKeys({year: 2024}, ['day']); // fails
+ * ```
+ */
+export function assertHasFullDateKeys(partialFullDate, keys) {
+    const missingKeys = [];
+    keys.forEach((key) => {
+        if (partialFullDate[key] == undefined) {
+            missingKeys.push(key);
+        }
+    });
+    if (missingKeys.length) {
+        throw new Error(`Missing required FullDate key(s): ${missingKeys.join(', ')}`);
+    }
+}

package/dist/extra-utils/js-date-conversion.d.ts

@@ -0,0 +1,26 @@
+import { FullDate } from '../full-date/full-date-shape.js';
+/**
+ * Convert a {@link FullDate} from a built-in JS
+ * [`Date`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date).
+ *
+ * @category Conversion
+ * @example
+ *
+ * ```ts
+ * import {toJsDate, 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',
+ * };
+ *
+ * toJsDate(exampleDate);
+ * ```
+ */
+export declare function toJsDate(fullDate: Readonly<FullDate>): Date;

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

@@ -0,0 +1,28 @@
+import { toTimestamp } from '../formatting/timestamp.js';
+/**
+ * Convert a {@link FullDate} from a built-in JS
+ * [`Date`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date).
+ *
+ * @category Conversion
+ * @example
+ *
+ * ```ts
+ * import {toJsDate, 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',
+ * };
+ *
+ * toJsDate(exampleDate);
+ * ```
+ */
+export function toJsDate(fullDate) {
+    return new Date(toTimestamp(fullDate));
+}

package/dist/extra-utils/now.d.ts

@@ -0,0 +1,56 @@
+import { UtcIsoString } from '../formatting/string-format-types.js';
+import { FullDate } from '../full-date/full-date-shape.js';
+import { Timezone, UtcTimezone } from '../timezone/timezones.js';
+/**
+ * Get the time right now as a UTC ISO.
+ *
+ * @category Now
+ * @example
+ *
+ * ```ts
+ * import {getNowInIsoString} from 'date-vir';
+ *
+ * getNowInIsoString();
+ * ```
+ */
+export declare function getNowInIsoString(): UtcIsoString;
+/**
+ * Get the time right now as a {@link FullDate} represented in the current user's timezone.
+ *
+ * @category Now
+ * @example
+ *
+ * ```ts
+ * import {getNowInUserTimezone} from 'date-vir';
+ *
+ * getNowInUserTimezone();
+ * ```
+ */
+export declare function getNowInUserTimezone(): FullDate;
+/**
+ * Get the time right now as a {@link FullDate} represented in the UTC timezone.
+ *
+ * @category Now
+ * @example
+ *
+ * ```ts
+ * import {getNowInUtcTimezone} from 'date-vir';
+ *
+ * getNowInUtcTimezone();
+ * ```
+ */
+export declare function getNowInUtcTimezone(): FullDate<UtcTimezone>;
+/**
+ * Get the time right now as a {@link FullDate} represented in the given timezone.
+ *
+ * @category Now
+ * @example
+ *
+ * ```ts
+ * import {getNowFullDate, utcTimezone, timezones} from 'date-vir';
+ *
+ * getNowFullDate(utcTimezone);
+ * getNowFullDate(timezones['Australia/Brisbane']);
+ * ```
+ */
+export declare function getNowFullDate<const SpecificTimezone extends Timezone>(timezone: SpecificTimezone): FullDate<SpecificTimezone>;

package/dist/extra-utils/now.js

@@ -0,0 +1,68 @@
+import { toUtcIsoString } from '../formatting/timestamp.js';
+import { createFullDate } from '../full-date/create-full-date.js';
+import { userTimezone, utcTimezone } from '../timezone/timezones.js';
+/**
+ * Get the time right now as a UTC ISO.
+ *
+ * @category Now
+ * @example
+ *
+ * ```ts
+ * import {getNowInIsoString} from 'date-vir';
+ *
+ * getNowInIsoString();
+ * ```
+ */
+export 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 toUtcIsoString(getNowFullDate(utcTimezone));
+}
+/**
+ * Get the time right now as a {@link FullDate} represented in the current user's timezone.
+ *
+ * @category Now
+ * @example
+ *
+ * ```ts
+ * import {getNowInUserTimezone} from 'date-vir';
+ *
+ * getNowInUserTimezone();
+ * ```
+ */
+export function getNowInUserTimezone() {
+    return getNowFullDate(userTimezone);
+}
+/**
+ * Get the time right now as a {@link FullDate} represented in the UTC timezone.
+ *
+ * @category Now
+ * @example
+ *
+ * ```ts
+ * import {getNowInUtcTimezone} from 'date-vir';
+ *
+ * getNowInUtcTimezone();
+ * ```
+ */
+export function getNowInUtcTimezone() {
+    return getNowFullDate(utcTimezone);
+}
+/**
+ * Get the time right now as a {@link FullDate} represented in the given timezone.
+ *
+ * @category Now
+ * @example
+ *
+ * ```ts
+ * import {getNowFullDate, utcTimezone, timezones} from 'date-vir';
+ *
+ * getNowFullDate(utcTimezone);
+ * getNowFullDate(timezones['Australia/Brisbane']);
+ * ```
+ */
+export function getNowFullDate(timezone) {
+    return createFullDate(Date.now(), timezone);
+}

package/dist/extra-utils/override-date.d.ts

@@ -0,0 +1,27 @@
+import { FullDate } from '../full-date/full-date-shape.js';
+import { Timezone } from '../timezone/timezones.js';
+/**
+ * Override the initial provided FullDate with all subsequent FullDate parts.
+ *
+ * @category Util
+ * @example
+ *
+ * ```ts
+ * import {overrideDateParts, 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',
+ * };
+ *
+ * overrideDateParts(exampleDate, {day: 20}, {second: 10});
+ * // `{year: 2024, month: 1, day: 20, hour: 1, minute: 1, second: 10, millisecond: 1, timezone: 'UTC'}`
+ * ```
+ */
+export declare function overrideDateParts<const SpecificTimezone extends Timezone>(date: FullDate<SpecificTimezone>, ...overrides: Partial<FullDate<SpecificTimezone>>[]): FullDate<SpecificTimezone>;

package/dist/extra-utils/override-date.js

@@ -0,0 +1,27 @@
+/**
+ * Override the initial provided FullDate with all subsequent FullDate parts.
+ *
+ * @category Util
+ * @example
+ *
+ * ```ts
+ * import {overrideDateParts, 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',
+ * };
+ *
+ * overrideDateParts(exampleDate, {day: 20}, {second: 10});
+ * // `{year: 2024, month: 1, day: 20, hour: 1, minute: 1, second: 10, millisecond: 1, timezone: 'UTC'}`
+ * ```
+ */
+export function overrideDateParts(date, ...overrides) {
+    return Object.assign({}, date, ...overrides);
+}

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

@@ -0,0 +1,109 @@
+import { TimeKey } from '../full-date/full-date-parts.js';
+import { FullDate } from '../full-date/full-date-shape.js';
+import { Timezone } from '../timezone/timezones.js';
+/**
+ * A {@link FullDate} instance that has the lowest, valid, non-negative, value for each property.
+ *
+ * @category Constants
+ */
+export declare const zeroDate: {
+    readonly year: 0;
+    readonly month: 1;
+    readonly day: 1;
+    readonly hour: 0;
+    readonly minute: 0;
+    readonly second: 0;
+    readonly millisecond: 0;
+};
+/**
+ * A {@link FullDate} instance that has the lowest, valid, non-negative, value for each property.
+ * Alias for {@link zeroDate}.
+ *
+ * @category Constants
+ */
+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;
+};
+/**
+ * An object that contains the time parts of {@link FullDate} all set to `0`.
+ *
+ * @category Constants
+ */
+export declare const zeroTime: Pick<{
+    year: 0;
+    month: 1;
+    day: 1;
+    hour: 0;
+    minute: 0;
+    second: 0;
+    millisecond: 0;
+}, 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 declare function clearTime<const SpecificTimezone extends Timezone>(inputFullDate: Readonly<FullDate<SpecificTimezone>>): FullDate<SpecificTimezone>;
+/**
+ * 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 declare function clearParts<const SpecificTimezone extends Timezone>(inputFullDate: Readonly<FullDate<SpecificTimezone>>, parts: ReadonlyArray<Exclude<keyof FullDate, 'timezone'>>): {
+    hour: import("@date-vir/duration").Hour;
+    minute: import("@date-vir/duration").Minute;
+    second: import("@date-vir/duration").Minute;
+    millisecond: number;
+    year: number;
+    month: import("@date-vir/duration").MonthNumber;
+    day: import("@date-vir/duration").DayOfMonth;
+    timezone: SpecificTimezone;
+};