date-vir 5.3.2 → 7.0.0

package/dist/formatting/simple-strings.js

@@ -0,0 +1,120 @@
+import { check } from '@augment-vir/assert';
+/**
+ * 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 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;
+}
+/**
+ * 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 function toSimpleTimePartString(fullDate, includeSeconds) {
+    const seconds = check.hasKey(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(check.isTruthy);
+    return timeParts.join(':');
+}
+/**
+ * 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 function toDatePartStrings(fullDate, options) {
+    return {
+        date: toSimpleDatePartString(fullDate),
+        time: toSimpleTimePartString(fullDate, options.includeSeconds),
+        timezone: fullDate.timezone,
+    };
+}
+/**
+ * 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 function toSimpleString(fullDate, options) {
+    const parts = toDatePartStrings(fullDate, options);
+    const stringParts = [
+        parts.date,
+        parts.time,
+        options.includeTimezone && `(${parts.timezone})`,
+    ].filter(check.isTruthy);
+    return stringParts.join(' ');
+}

package/dist/formatting/string-format-types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A string that represents only date parts of a date. It's intended to be used like this:
+ * year-month-day.
+ *
+ * @category Internal
+ */
+export type JustDateString = `${number}-${number}-${number}`;
+/**
+ * A string that represents only time parts of a date, with seconds. It's intended to be used like
+ * this: hour:minute:seconds.
+ *
+ * @category Internal
+ */
+export type JustTimeWithSecondsString = `${number}:${number}:${number}`;
+/**
+ * A string that represents only time parts of a date, without seconds. It's intended to be used
+ * like this: hour:minute.
+ *
+ * @category Internal
+ */
+export type JustTimeString = `${number}:${number}`;
+/**
+ * A string that represents date and time parts of a date, with seconds. It's intended to be used
+ * like this: year-month-dayThour:minute:seconds.
+ *
+ * @category Internal
+ */
+export type DateTimeWithSeconds = `${JustDateString}T${JustTimeWithSecondsString}`;
+/**
+ * A string that represents date and time parts of a date, without seconds. It's intended to be used
+ * like this: year-month-dayThour:minute.
+ *
+ * @category Internal
+ */
+export type DateTimeString = `${JustDateString}T${JustTimeString}`;
+/**
+ * A full UTC ISO date time string: YYYY-MM-DDTHH:mm:ss.sssZ.
+ *
+ * @category ISO
+ * @see
+ * - https://tc39.es/ecma262/multipage/numbers-and-dates.html#sec-date-time-string-format
+ * - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format
+ */
+export type UtcIsoString = `${JustDateString}T${JustTimeWithSecondsString}.${number}Z`;
+/**
+ * Checks if the input is a valid UTC ISO string and type guards the input.
+ *
+ * @category ISO
+ * @category Assertion
+ * @example
+ *
+ * ```ts
+ * import {isValidIsoString} from 'date-vir';
+ *
+ * isValidIsoString('no'); // `false`
+ * isValidIsoString('2024-05-01T20:18:17.123Z'); // `true`
+ * ```
+ */
+export declare function isValidIsoString(input: unknown): input is UtcIsoString;

package/dist/formatting/string-format-types.js

@@ -0,0 +1,19 @@
+import { DateTime } from 'luxon';
+/**
+ * Checks if the input is a valid UTC ISO string and type guards the input.
+ *
+ * @category ISO
+ * @category Assertion
+ * @example
+ *
+ * ```ts
+ * import {isValidIsoString} from 'date-vir';
+ *
+ * isValidIsoString('no'); // `false`
+ * isValidIsoString('2024-05-01T20:18:17.123Z'); // `true`
+ * ```
+ */
+export function isValidIsoString(input) {
+    const datetime = DateTime.fromISO(input);
+    return datetime.toUTC().toISO() === input;
+}

package/dist/formatting/timestamp.d.ts

@@ -0,0 +1,51 @@
+import { FullDate } from '../full-date/full-date-shape.js';
+import { UtcIsoString } from './string-format-types.js';
+/**
+ * Convert a FullDate into a unix timestamp with milliseconds.
+ *
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {toTimestamp} from 'date-vir';
+ *
+ * const exampleDate: FullDate = {
+ *     year: 2024,
+ *     month: 1,
+ *     day: 5,
+ *     hour: 1,
+ *     minute: 1,
+ *     second: 1,
+ *     millisecond: 1,
+ *     timezone: 'UTC',
+ * };
+ *
+ * toTimestamp(exampleDate); // `1704416461001`
+ * ```
+ */
+export declare function toTimestamp(fullDate: FullDate): number;
+/**
+ * Convert a FullDate into a UTC ISO string, always ending in Z.
+ *
+ * @category ISO
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {toUtcIsoString} from 'date-vir';
+ *
+ * const exampleDate: FullDate = {
+ *     year: 2024,
+ *     month: 1,
+ *     day: 5,
+ *     hour: 1,
+ *     minute: 1,
+ *     second: 1,
+ *     millisecond: 1,
+ *     timezone: 'UTC',
+ * };
+ *
+ * toUtcIsoString(exampleDate); // `'2024-01-05T01:01:01.001Z'`
+ * ```
+ */
+export declare function toUtcIsoString(fullDate: FullDate): UtcIsoString;

package/dist/formatting/timestamp.js

@@ -0,0 +1,61 @@
+import { toLuxonDateTime } from '../full-date/luxon-date-time-conversion.js';
+import { utcTimezone } from '../timezone/timezones.js';
+/**
+ * Convert a FullDate into a unix timestamp with milliseconds.
+ *
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {toTimestamp} from 'date-vir';
+ *
+ * const exampleDate: FullDate = {
+ *     year: 2024,
+ *     month: 1,
+ *     day: 5,
+ *     hour: 1,
+ *     minute: 1,
+ *     second: 1,
+ *     millisecond: 1,
+ *     timezone: 'UTC',
+ * };
+ *
+ * toTimestamp(exampleDate); // `1704416461001`
+ * ```
+ */
+export function toTimestamp(fullDate) {
+    return toLuxonDateTime(fullDate).toMillis();
+}
+/**
+ * Convert a FullDate into a UTC ISO string, always ending in Z.
+ *
+ * @category ISO
+ * @category Formatting
+ * @example
+ *
+ * ```ts
+ * import {toUtcIsoString} from 'date-vir';
+ *
+ * const exampleDate: FullDate = {
+ *     year: 2024,
+ *     month: 1,
+ *     day: 5,
+ *     hour: 1,
+ *     minute: 1,
+ *     second: 1,
+ *     millisecond: 1,
+ *     timezone: 'UTC',
+ * };
+ *
+ * toUtcIsoString(exampleDate); // `'2024-01-05T01:01:01.001Z'`
+ * ```
+ */
+export function toUtcIsoString(fullDate) {
+    const isoString = toLuxonDateTime(fullDate).setZone(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;
+}

package/dist/full-date/create-full-date.d.ts

@@ -0,0 +1,91 @@
+import { Timezone, UtcTimezone } from '../timezone/timezones.js';
+import { DateLike } from './date-like.js';
+import { FullDate } from './full-date-shape.js';
+/**
+ * Parses the given {@link DateLike} and converts it into a {@link FullDate} instance with the user's
+ * current timezone.
+ *
+ * @category FullDate
+ * @example
+ *
+ * ```ts
+ * import {createFullDateInUserTimezone} from 'date-vir';
+ *
+ * createFullDateInUserTimezone('June 1, 2024');
+ * createFullDateInUserTimezone(new Date());
+ * createFullDateInUserTimezone(112300120);
+ * ```
+ */
+export declare function createFullDateInUserTimezone(dateLike: Readonly<DateLike>): FullDate;
+/**
+ * Parses the given {@link DateLike} and converts it into a {@link FullDate} instance with the UTC
+ * timezone.
+ *
+ * @category FullDate
+ * @example
+ *
+ * ```ts
+ * import {createUtcFullDate} from 'date-vir';
+ *
+ * createUtcFullDate('June 1, 2024');
+ * createUtcFullDate(new Date());
+ * createUtcFullDate(112300120);
+ * ```
+ */
+export declare function createUtcFullDate(dateLike: Readonly<DateLike>): FullDate<UtcTimezone>;
+/**
+ * Parses the given {@link DateLike} and converts it into a {@link FullDate} instance with the given
+ * timezone.
+ *
+ * @category FullDate
+ * @example
+ *
+ * ```ts
+ * import {createFullDate, timezones, utcTimezone} from 'date-vir';
+ *
+ * createFullDate('June 1, 2024', utcTimezone);
+ * createFullDate(new Date(), timezones['Australia/Brisbane']);
+ * createFullDate(112300120, timezones['Etc/GMT-11']);
+ * ```
+ */
+export declare function createFullDate<const SpecificTimezone extends Timezone>(
+/** The original date representation to be converted into a FullDate. */
+dateLike: Readonly<DateLike>, 
+/** The timezone that this date/time is meant for / originated from. */
+timezone: SpecificTimezone): FullDate<SpecificTimezone>;
+/**
+ * Converts a {@link FullDate} instance into a new instance with the original's date and time
+ * represented in the new timezone.
+ *
+ * @category Conversion
+ * @example
+ *
+ * ```ts
+ * import {toNewTimezone} from 'date-vir';
+ *
+ * const exampleDate: FullDate = {
+ *     year: 2024,
+ *     month: 1,
+ *     day: 5,
+ *     hour: 1,
+ *     minute: 1,
+ *     second: 1,
+ *     millisecond: 1,
+ *     timezone: 'UTC',
+ * };
+ *
+ * let result = toNewTimezone(exampleDate, timezones['Australia/Brisbane']);
+ * // output:
+ * result = {
+ *     year: 2024,
+ *     month: 1,
+ *     day: 5,
+ *     hour: 11,
+ *     minute: 1,
+ *     second: 1,
+ *     millisecond: 1,
+ *     timezone: timezones['Australia/Brisbane'],
+ * };
+ * ```
+ */
+export declare function toNewTimezone<const SpecificTimezone extends Timezone>(fullDate: Readonly<FullDate>, timezone: SpecificTimezone): FullDate<SpecificTimezone>;

package/dist/full-date/create-full-date.js

@@ -0,0 +1,142 @@
+import { DateTime } from 'luxon';
+import { check } from '@augment-vir/assert';
+import { stringify } from '@augment-vir/common';
+import { userTimezone, utcTimezone } from '../timezone/timezones.js';
+import { isValidFullDate } from './is-valid-full-date.js';
+import { parseLuxonDateTime, toLuxonDateTime } from './luxon-date-time-conversion.js';
+import { parseDateString } from './string-parsing.js';
+/**
+ * Parses the given {@link DateLike} and converts it into a {@link FullDate} instance with the user's
+ * current timezone.
+ *
+ * @category FullDate
+ * @example
+ *
+ * ```ts
+ * import {createFullDateInUserTimezone} from 'date-vir';
+ *
+ * createFullDateInUserTimezone('June 1, 2024');
+ * createFullDateInUserTimezone(new Date());
+ * createFullDateInUserTimezone(112300120);
+ * ```
+ */
+export function createFullDateInUserTimezone(dateLike) {
+    return createFullDate(dateLike, userTimezone);
+}
+/**
+ * Parses the given {@link DateLike} and converts it into a {@link FullDate} instance with the UTC
+ * timezone.
+ *
+ * @category FullDate
+ * @example
+ *
+ * ```ts
+ * import {createUtcFullDate} from 'date-vir';
+ *
+ * createUtcFullDate('June 1, 2024');
+ * createUtcFullDate(new Date());
+ * createUtcFullDate(112300120);
+ * ```
+ */
+export function createUtcFullDate(dateLike) {
+    return createFullDate(dateLike, utcTimezone);
+}
+/**
+ * Parses the given {@link DateLike} and converts it into a {@link FullDate} instance with the given
+ * timezone.
+ *
+ * @category FullDate
+ * @example
+ *
+ * ```ts
+ * import {createFullDate, timezones, utcTimezone} from 'date-vir';
+ *
+ * createFullDate('June 1, 2024', utcTimezone);
+ * createFullDate(new Date(), timezones['Australia/Brisbane']);
+ * createFullDate(112300120, timezones['Etc/GMT-11']);
+ * ```
+ */
+export function createFullDate(
+/** The original date representation to be converted into a FullDate. */
+dateLike, 
+/** The timezone that this date/time is meant for / originated from. */
+timezone) {
+    const dateTime = convertDateLikeToLuxonDateTime(dateLike, timezone);
+    if (!dateTime?.isValid) {
+        throw new Error(`Failed to parse date input ${stringify(dateLike)}`);
+    }
+    return parseLuxonDateTime(dateTime, timezone);
+}
+/**
+ * Converts a {@link FullDate} instance into a new instance with the original's date and time
+ * represented in the new timezone.
+ *
+ * @category Conversion
+ * @example
+ *
+ * ```ts
+ * import {toNewTimezone} from 'date-vir';
+ *
+ * const exampleDate: FullDate = {
+ *     year: 2024,
+ *     month: 1,
+ *     day: 5,
+ *     hour: 1,
+ *     minute: 1,
+ *     second: 1,
+ *     millisecond: 1,
+ *     timezone: 'UTC',
+ * };
+ *
+ * let result = toNewTimezone(exampleDate, timezones['Australia/Brisbane']);
+ * // output:
+ * result = {
+ *     year: 2024,
+ *     month: 1,
+ *     day: 5,
+ *     hour: 11,
+ *     minute: 1,
+ *     second: 1,
+ *     millisecond: 1,
+ *     timezone: timezones['Australia/Brisbane'],
+ * };
+ * ```
+ */
+export function toNewTimezone(fullDate, timezone) {
+    if (fullDate.timezone === timezone) {
+        return fullDate;
+    }
+    return createFullDate(fullDate, timezone);
+}
+function lastDitchConversion(dateLike) {
+    /** As any cast for last ditch effort to convert the dateLike into a date. */
+    const dateTime = DateTime.fromJSDate(new Date(dateLike));
+    if (dateTime.isValid) {
+        return dateTime;
+    }
+    else {
+        return undefined;
+    }
+}
+function convertDateLikeToLuxonDateTime(dateLike, timezone) {
+    if (isValidFullDate(dateLike)) {
+        dateLike = toLuxonDateTime(dateLike).toMillis();
+    }
+    if (DateTime.isDateTime(dateLike)) {
+        return dateLike.setZone(timezone);
+    }
+    else if (check.isNumber(dateLike)) {
+        return DateTime.fromMillis(dateLike, { zone: utcTimezone }).setZone(timezone);
+    }
+    else if (check.isString(dateLike)) {
+        const parsedStringDate = parseDateString(dateLike, timezone);
+        if (parsedStringDate) {
+            return parsedStringDate;
+        }
+    }
+    else if (dateLike instanceof Date) {
+        const dateTime = DateTime.fromJSDate(dateLike);
+        return dateTime.setZone(timezone);
+    }
+    return lastDitchConversion(dateLike);
+}

package/dist/full-date/date-like.d.ts

@@ -0,0 +1,9 @@
+import { DateTime } from 'luxon';
+import { Timezone } from '../timezone/timezones.js';
+import { FullDate } from './full-date-shape.js';
+/**
+ * Types that can be converted into {@link FullDate} instances.
+ *
+ * @category Internal
+ */
+export type DateLike<SpecificTimezone extends Timezone = Timezone> = string | Date | number | DateTime | FullDate<SpecificTimezone>;

package/dist/{esm/full-date → full-date}/format-presets.d.ts

@@ -1,6 +1,8 @@
 /**
- * Format preset re-exported from luxon to be used with toLocaleString. To see examples of all
- * presets, go here: https://moment.github.io/luxon/#/formatting?id=presets
+ * Format presets to be used with {@link toLocaleString}. To see examples of all presets, go here:
+ * https://moment.github.io/luxon/#/formatting?id=presets
+ *
+ * @category Formatting
  */
 export declare const formatPresets: {
     readonly DateShort: Intl.DateTimeFormatOptions;

package/dist/{esm/full-date → full-date}/format-presets.js

@@ -1,7 +1,9 @@
 import { DateTime } from 'luxon';
 /**
- * Format preset re-exported from luxon to be used with toLocaleString. To see examples of all
- * presets, go here: https://moment.github.io/luxon/#/formatting?id=presets
+ * Format presets to be used with {@link toLocaleString}. To see examples of all presets, go here:
+ * https://moment.github.io/luxon/#/formatting?id=presets
+ *
+ * @category Formatting
  */
 export const formatPresets = {
     DateShort: DateTime.DATE_SHORT,

package/dist/full-date/full-date-parts.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Represents various parts of a {@link FullDate}. Each value is also a valid "type" attribute for an
+ * `<input>` HTML element.
+ *
+ * @category Internal
+ */
+export declare enum FullDatePart {
+    /**
+     * Used for `type="date"` HTML `<input>` elements:
+     * https://developer.mozilla.org/docs/Web/HTML/Element/input/date
+     */
+    Date = "date",
+    /**
+     * Used for `type="time"` HTML `<input>` elements:
+     * https://developer.mozilla.org/docs/Web/HTML/Element/input/time
+     */
+    Time = "time",
+    /**
+     * Used for `type="datetime-local"` HTML `<input>` elements:
+     * https://developer.mozilla.org/docs/Web/HTML/Element/input/datetime-local
+     */
+    DateTime = "datetime-local"
+}
+/**
+ * {@link FullDate} keys used for telling time only.
+ *
+ * @category Internal
+ */
+export declare enum TimeKey {
+    Hour = "hour",
+    Minute = "minute",
+    Second = "second",
+    Millisecond = "millisecond"
+}
+/**
+ * {@link FullDate} keys used for telling the date only.
+ *
+ * @category Internal
+ */
+export declare enum DateKey {
+    Year = "year",
+    Month = "month",
+    Day = "day"
+}

package/dist/full-date/full-date-parts.js

@@ -0,0 +1,47 @@
+/**
+ * Represents various parts of a {@link FullDate}. Each value is also a valid "type" attribute for an
+ * `<input>` HTML element.
+ *
+ * @category Internal
+ */
+export var FullDatePart;
+(function (FullDatePart) {
+    /**
+     * Used for `type="date"` HTML `<input>` elements:
+     * https://developer.mozilla.org/docs/Web/HTML/Element/input/date
+     */
+    FullDatePart["Date"] = "date";
+    /**
+     * Used for `type="time"` HTML `<input>` elements:
+     * https://developer.mozilla.org/docs/Web/HTML/Element/input/time
+     */
+    FullDatePart["Time"] = "time";
+    /**
+     * Used for `type="datetime-local"` HTML `<input>` elements:
+     * https://developer.mozilla.org/docs/Web/HTML/Element/input/datetime-local
+     */
+    FullDatePart["DateTime"] = "datetime-local";
+})(FullDatePart || (FullDatePart = {}));
+/**
+ * {@link FullDate} keys used for telling time only.
+ *
+ * @category Internal
+ */
+export var TimeKey;
+(function (TimeKey) {
+    TimeKey["Hour"] = "hour";
+    TimeKey["Minute"] = "minute";
+    TimeKey["Second"] = "second";
+    TimeKey["Millisecond"] = "millisecond";
+})(TimeKey || (TimeKey = {}));
+/**
+ * {@link FullDate} keys used for telling the date only.
+ *
+ * @category Internal
+ */
+export var DateKey;
+(function (DateKey) {
+    DateKey["Year"] = "year";
+    DateKey["Month"] = "month";
+    DateKey["Day"] = "day";
+})(DateKey || (DateKey = {}));