date-vir 5.3.2 → 6.0.1

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,48 @@
+import type { ArrayElement } from '@augment-vir/common';
+/**
+ * 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 const timeFullDateKeys: readonly ["hour", "minute", "second", "millisecond"];
+/**
+ * {@link FullDate} keys used for telling time only.
+ *
+ * @category Internal
+ */
+export type TimeFullDateKeys = ArrayElement<typeof timeFullDateKeys>;
+/**
+ * {@link FullDate} keys used for telling the date only.
+ *
+ * @category Internal
+ */
+export declare const dateFullDateKeys: readonly ["year", "month", "day"];
+/**
+ * {@link FullDate} keys used for telling the date only.
+ *
+ * @category Internal
+ */
+export type DateFullDateKeys = ArrayElement<typeof dateFullDateKeys>;

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

@@ -0,0 +1,45 @@
+/**
+ * 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 const timeFullDateKeys = [
+    'hour',
+    'minute',
+    'second',
+    'millisecond',
+];
+/**
+ * {@link FullDate} keys used for telling the date only.
+ *
+ * @category Internal
+ */
+export const dateFullDateKeys = [
+    'year',
+    'month',
+    'day',
+];

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

@@ -0,0 +1,106 @@
+import { Overwrite, type SetRequired } from '@augment-vir/common';
+import { type Timezone } from '../timezone/timezones.js';
+/**
+ * Time part of {@link FullDate} represented in a shape definition.
+ *
+ * @category Shape
+ */
+export declare const timePartShape: import("object-shape-tester").ShapeDefinition<{
+    /** Hour of the day in 24 time: 0-23 */
+    hour: number;
+    /** Minute of the hour: 0-59 */
+    minute: number;
+    /** Second of the minute: 0-59 */
+    second: number;
+    /** Millisecond of the second: 0-999 */
+    millisecond: number;
+    /** The timezone that this date/time is meant for / originated from. */
+    timezone: Timezone;
+}, false>;
+/**
+ * Time part of a {@link FullDate}.
+ *
+ * @category Internal
+ */
+export type TimePart<SpecificTimezone extends Timezone = Timezone> = SetRequired<Partial<FullDate<SpecificTimezone>>, keyof (typeof timePartShape)['runtimeType']>;
+/**
+ * Date part of {@link FullDate} represented in a shape definition.
+ *
+ * @category Shape
+ */
+export declare const datePartShape: import("object-shape-tester").ShapeDefinition<{
+    /**
+     * The full, four digit year.
+     *
+     * @example 2023;
+     */
+    year: number;
+    /** A month of the year: 1-12 */
+    month: number;
+    /** A day of the month: 1-31 depending on the month */
+    day: number;
+    /** The timezone that this date/time is meant for / originated from. */
+    timezone: Timezone;
+}, false>;
+/**
+ * Date part of {@link FullDate}.
+ *
+ * @category Internal
+ */
+export type DatePart<SpecificTimezone extends Timezone = Timezone> = SetRequired<Partial<FullDate<SpecificTimezone>>, keyof (typeof datePartShape)['runtimeType']>;
+/**
+ * The complete {@link FullDate} represented in a shape definition.
+ *
+ * @category Shape
+ */
+export declare const fullDateShape: import("object-shape-tester").ShapeDefinition<import("object-shape-tester").ShapeAnd<[import("object-shape-tester").ShapeDefinition<{
+    /**
+     * The full, four digit year.
+     *
+     * @example 2023;
+     */
+    year: number;
+    /** A month of the year: 1-12 */
+    month: number;
+    /** A day of the month: 1-31 depending on the month */
+    day: number;
+    /** The timezone that this date/time is meant for / originated from. */
+    timezone: Timezone;
+}, false>, import("object-shape-tester").ShapeDefinition<{
+    /** Hour of the day in 24 time: 0-23 */
+    hour: number;
+    /** Minute of the hour: 0-59 */
+    minute: number;
+    /** Second of the minute: 0-59 */
+    second: number;
+    /** Millisecond of the second: 0-999 */
+    millisecond: number;
+    /** The timezone that this date/time is meant for / originated from. */
+    timezone: Timezone;
+}, false>]>, false>;
+/**
+ * A serializable object that completely specifies how any given date should be represented,
+ * including its timezone, to millisecond accuracy. This is the core type of the `date-vir` package,
+ * with most operations either requiring or returning this type.
+ *
+ * @category FullDate
+ * @example
+ *
+ * ```ts
+ * import {FullDate, timezones} from 'date-vir';
+ *
+ * const myDate: FullDate = {
+ *     year: 2024,
+ *     month: 6,
+ *     day: 2,
+ *     hour: 13,
+ *     minute: 32,
+ *     second: 12,
+ *     milliseconds: 94,
+ *     timezone: timezones['Australia/Brisbane'],
+ * };
+ * ```
+ */
+export type FullDate<SpecificTimezone extends Timezone = Timezone> = Overwrite<(typeof fullDateShape)['runtimeType'], {
+    timezone: SpecificTimezone;
+}>;

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

@@ -1,26 +1,10 @@
 import { and, defineShape } from 'object-shape-tester';
-import { utcTimezone } from '../timezone/timezones';
+import { utcTimezone } from '../timezone/timezones.js';
 /**
- * Represents various parts of a FullDate. Each value is also a valid "type" attribute for an
- * <input> HTML element.
+ * Time part of {@link FullDate} represented in a shape definition.
+ *
+ * @category Shape
  */
-export var FullDatePartEnum;
-(function (FullDatePartEnum) {
-    FullDatePartEnum["Date"] = "date";
-    FullDatePartEnum["Time"] = "time";
-    FullDatePartEnum["DateTime"] = "datetime-local";
-})(FullDatePartEnum || (FullDatePartEnum = {}));
-export const timeFullDateKeys = [
-    'hour',
-    'minute',
-    'second',
-    'millisecond',
-];
-export const dateFullDateKeys = [
-    'year',
-    'month',
-    'day',
-];
 export const timePartShape = defineShape({
     /** Hour of the day in 24 time: 0-23 */
     hour: 14,
@@ -33,12 +17,16 @@ export const timePartShape = defineShape({
     /** The timezone that this date/time is meant for / originated from. */
     timezone: utcTimezone,
 });
+/**
+ * Date part of {@link FullDate} represented in a shape definition.
+ *
+ * @category Shape
+ */
 export const datePartShape = defineShape({
     /**
      * The full, four digit year.
      *
-     * @example
-     *     2023;
+     * @example 2023;
      */
     year: 2023,
     /** A month of the year: 1-12 */
@@ -48,4 +36,9 @@ export const datePartShape = defineShape({
     /** The timezone that this date/time is meant for / originated from. */
     timezone: utcTimezone,
 });
+/**
+ * The complete {@link FullDate} represented in a shape definition.
+ *
+ * @category Shape
+ */
 export const fullDateShape = defineShape(and(datePartShape, timePartShape));

package/dist/full-date/is-valid-full-date.d.ts

@@ -0,0 +1,21 @@
+import { Timezone } from '../timezone/timezones.js';
+import { FullDate } from './full-date-shape.js';
+/**
+ * Asserts that the input is a valid {@link FullDate}.
+ *
+ * @category Assertion
+ * @throws An Error if the input is not a valid {@link FullDate}.
+ */
+export declare function assertValidFullDate(input: unknown): asserts input is FullDate;
+/**
+ * Checks and type guards that the input is a valid {@link FullDate}.
+ *
+ * @category Assertion
+ */
+export declare function isValidFullDate(input: unknown): input is FullDate;
+/**
+ * Checks and type guards that the given {@link FullDate} instance has the given timezone.
+ *
+ * @category Assertion
+ */
+export declare function hasTimezone<const SpecificTimezone extends Timezone>(input: FullDate, timezone: SpecificTimezone): input is FullDate<SpecificTimezone>;

package/dist/full-date/is-valid-full-date.js

@@ -0,0 +1,38 @@
+import { assertValidShape } from 'object-shape-tester';
+import { assertValidTimezone } from '../timezone/timezone-checks.js';
+import { fullDateShape } from './full-date-shape.js';
+import { toLuxonDateTime } from './luxon-date-time-conversion.js';
+/**
+ * Asserts that the input is a valid {@link FullDate}.
+ *
+ * @category Assertion
+ * @throws An Error if the input is not a valid {@link FullDate}.
+ */
+export function assertValidFullDate(input) {
+    assertValidShape(input, fullDateShape);
+    assertValidTimezone(input.timezone);
+    /** Check that the input can be converted to a luxon date correctly. */
+    toLuxonDateTime(input);
+}
+/**
+ * Checks and type guards that the input is a valid {@link FullDate}.
+ *
+ * @category Assertion
+ */
+export function isValidFullDate(input) {
+    try {
+        assertValidFullDate(input);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Checks and type guards that the given {@link FullDate} instance has the given timezone.
+ *
+ * @category Assertion
+ */
+export function hasTimezone(input, timezone) {
+    return input.timezone === timezone;
+}

package/dist/full-date/luxon-date-time-conversion.d.ts

@@ -0,0 +1,19 @@
+import { DateTime } from 'luxon';
+import { Timezone } from '../timezone/timezones.js';
+import { FullDate } from './full-date-shape.js';
+/**
+ * Converts a {@link FullDate} object into a Luxon DateTime library. This is only needed if you need
+ * complex operations on dates. It does, however, internally power a lot of date-vir functionality
+ * as it uses the Luxon library for conversions between timezones.
+ *
+ * @category Internal
+ */
+export declare function toLuxonDateTime(fullDateInput: Readonly<FullDate>): DateTime;
+/**
+ * Convert a Luxon DateTime object into a {@link FullDate} instance. Used internally inside of
+ * date-vir, but could be helpful if you need it. Usually you should prefer using the
+ * `createFullDate` function instead.
+ *
+ * @category Internal
+ */
+export declare function parseLuxonDateTime<const SpecificTimezone extends Timezone>(dateTimeInput: Readonly<DateTime>, forcedTimezone?: SpecificTimezone): FullDate<SpecificTimezone>;

package/dist/{esm/full-date → full-date}/luxon-date-time-conversion.js

@@ -1,9 +1,11 @@
 import { omitObjectKeys } from '@augment-vir/common';
 import { DateTime } from 'luxon';
 /**
- * Converts a FullDate object into a Luxon DateTime library. This is only needed if you need complex
- * operations on dates. It does, however, internally power a lot of the date-vir functionality as it
- * uses the Luxon library for conversions between timezones.
+ * Converts a {@link FullDate} object into a Luxon DateTime library. This is only needed if you need
+ * complex operations on dates. It does, however, internally power a lot of date-vir functionality
+ * as it uses the Luxon library for conversions between timezones.
+ *
+ * @category Internal
  */
 export function toLuxonDateTime(fullDateInput) {
     const dateTime = DateTime.fromObject(omitObjectKeys(fullDateInput, ['timezone']), {
@@ -17,9 +19,11 @@ export function toLuxonDateTime(fullDateInput) {
     return dateTime;
 }
 /**
- * Convert a Luxon DateTime object into a DateTime object. Used internally inside of date-vir, but
- * could be helpful if you need it. Usually you should prefer using the createFullDate function
- * instead.
+ * Convert a Luxon DateTime object into a {@link FullDate} instance. Used internally inside of
+ * date-vir, but could be helpful if you need it. Usually you should prefer using the
+ * `createFullDate` function instead.
+ *
+ * @category Internal
  */
 export function parseLuxonDateTime(dateTimeInput, forcedTimezone) {
     if (!dateTimeInput.isValid) {

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

@@ -0,0 +1,33 @@
+import { Timezone } from '../timezone/timezones.js';
+import { FullDate } from './full-date-shape.js';
+/**
+ * Parses any date string into a {@link FullDate} using the specified pattern and timezone. Prefer
+ * using {@link createFullDate} if possible.
+ *
+ * Since this supports any arbitrary date string pattern, it is more flexible than
+ * {@link createFullDate} but you must know the date pattern ahead of time.
+ *
+ * The `formatString` input is passed to Luxon. All format pattern options are listed here:
+ * https://moment.github.io/luxon/#/parsing?id=table-of-tokens
+ *
+ * @category FullDate
+ */
+export declare function parseDateStringWithPattern<const SpecificTimezone extends Timezone>({ dateString, formatString, timezone, }: {
+    /** The date string to be parsed. */
+    dateString: string;
+    /**
+     * The format string that should match Luxon's expectations here:
+     * https://moment.github.io/luxon/#/parsing?id=table-of-tokens
+     */
+    formatString: string;
+    /** The timezone that this date/time is meant for / originated from. */
+    timezone: SpecificTimezone;
+}): FullDate<SpecificTimezone>;
+/**
+ * Read either an `HTMLInputElement`'s value directly, or the value string retrieved from an
+ * `HTMLInputElement`. Handles both `type="date"` and `type="time"` <input> elements.
+ *
+ * @category FullDate
+ * @category HTML
+ */
+export declare function parseInputElementValue<const SpecificTimezone extends Timezone>(elementOrValue: Readonly<Pick<HTMLInputElement, 'value'>> | string | null | undefined, timezone: SpecificTimezone): FullDate<SpecificTimezone> | undefined;

package/dist/full-date/parsing.js

@@ -0,0 +1,47 @@
+import { check } from '@augment-vir/assert';
+import { DateTime } from 'luxon';
+import { createFullDate } from './create-full-date.js';
+import { parseLuxonDateTime } from './luxon-date-time-conversion.js';
+/**
+ * Parses any date string into a {@link FullDate} using the specified pattern and timezone. Prefer
+ * using {@link createFullDate} if possible.
+ *
+ * Since this supports any arbitrary date string pattern, it is more flexible than
+ * {@link createFullDate} but you must know the date pattern ahead of time.
+ *
+ * The `formatString` input is passed to Luxon. All format pattern options are listed here:
+ * https://moment.github.io/luxon/#/parsing?id=table-of-tokens
+ *
+ * @category FullDate
+ */
+export function parseDateStringWithPattern({ dateString, formatString, timezone, }) {
+    try {
+        const dateTime = DateTime.fromFormat(dateString, formatString, {
+            zone: timezone,
+            setZone: true,
+        });
+        return parseLuxonDateTime(dateTime);
+    }
+    catch {
+        throw new Error(`Failed to parse string '${dateString}' with format '${formatString}'`);
+    }
+}
+/**
+ * Read either an `HTMLInputElement`'s value directly, or the value string retrieved from an
+ * `HTMLInputElement`. Handles both `type="date"` and `type="time"` <input> elements.
+ *
+ * @category FullDate
+ * @category HTML
+ */
+export function parseInputElementValue(elementOrValue, timezone) {
+    if (!elementOrValue) {
+        return undefined;
+    }
+    const value = check.isString(elementOrValue) ? elementOrValue : elementOrValue.value;
+    try {
+        return createFullDate(value, timezone);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/full-date/string-parsing.d.ts

@@ -0,0 +1,9 @@
+import { DateTime } from 'luxon';
+import { Timezone } from '../timezone/timezones.js';
+/**
+ * Tries extra known formats for parsing date strings, even those that browsers do not natively
+ * support.
+ *
+ * @category Internal
+ */
+export declare function parseDateString(dateString: string, timezone: Timezone): DateTime | undefined;

package/dist/{esm/full-date → full-date}/string-parsing.js

@@ -11,6 +11,12 @@ const knownStringFormats = [
     // january-2021
     'LLLL-y',
 ];
+/**
+ * Tries extra known formats for parsing date strings, even those that browsers do not natively
+ * support.
+ *
+ * @category Internal
+ */
 export function parseDateString(dateString, timezone) {
     const isoAttempt = DateTime.fromISO(dateString, { zone: timezone });
     if (isoAttempt.isValid) {