date-vir 5.3.1 → 6.0.1

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;

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>;