date-vir 5.3.1 → 6.0.1

package/LICENSE-MIT

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 electrovir
+Copyright (c) 2024 electrovir
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,14 +2,14 @@
 
 Easy dates and times with explicit timezones (and typed timezones).
 
-`date-vir` revolves around the new `FullDate` type, which includes all the information you need to correctly pinpoint _and_ format a given point in time. Most notably, `FullDate` always includes a `timezone` property, so you _always_ know what timezone the date was originally defined in, or what timezone the date is intended to be used in:
-
 Full docs: http://electrovir.github.io/date-vir
 
+`date-vir` revolves around its [`FullDate`](http://electrovir.github.io/date-vir/types/FullDate.html) type. `FullDate` includes all the information you need to correctly pinpoint _and_ format a given point in time. Most notably, `FullDate` always includes a `timezone` property, so you _always_ know what timezone the date was originally defined in, or what timezone the date is intended to be used in:
+
 <!-- example-link: src/readme-examples/full-date.example.ts -->
 
 ```TypeScript
-import {FullDate, timezones} from 'date-vir';
+import {FullDate, utcTimezone} from 'date-vir';
 
 const myDate: FullDate = {
     year: 2023,
@@ -21,13 +21,13 @@ const myDate: FullDate = {
     second: 27,
     millisecond: 652,
 
-    timezone: timezones.UTC,
+    timezone: utcTimezone,
 };
 ```
 
-# Creating a FullDate
+## Creating a FullDate
 
-Several functions are available for creating `FullDate` objects, with `createFullDate` being the most commonly used:
+Several functions are available for creating `FullDate` objects:
 
 <!-- example-link: src/readme-examples/full-date-creation.example.ts -->
 
@@ -35,26 +35,26 @@ Several functions are available for creating `FullDate` objects, with `createFul
 import {
     createFullDate,
     getNowFullDate,
+    parseDateStringWithPattern,
     parseInputElementValue,
-    parseStrangeString,
-    timezones,
+    Timezone,
 } from 'date-vir';
 
 /**
  * Creates a FullDate from a wide range of possible inputs. See TypeScript types for full details on
  * available inputs.
  */
-createFullDate('2023-06-05', timezones['Europe/Rome']);
+createFullDate('2023-06-05', Timezone['Europe/Rome']);
 
 /** Get the current date and time right now in the given timezone. */
-getNowFullDate(timezones['America/Argentina/Buenos_Aires']);
+getNowFullDate(Timezone['America/Argentina/Buenos_Aires']);
 
 /**
  * Parsed the value of an <input> element directly from the element itself. This is intended to be
  * used for type="date" or type="time" <input> elements, but any input element with a valid date or
  * time string will work.
  */
-parseInputElementValue(document.querySelector('input'), timezones['Asia/Tokyo']);
+parseInputElementValue(document.querySelector('input'), Timezone['Asia/Tokyo']);
 
 /**
  * If you have a really oddly formatted date/time string and createFullDate does not suffice, you
@@ -62,14 +62,14 @@ parseInputElementValue(document.querySelector('input'), timezones['Asia/Tokyo'])
  * so you can see all the formatString options in its docs:
  * https://moment.github.io/luxon/#/parsing?id=table-of-tokens
  */
-parseStrangeString({
+parseDateStringWithPattern({
     dateString: '870-0-14-19 5 2023 6',
     formatString: 'S-s-h-m d yyyy M',
-    timezone: timezones['America/Cancun'],
+    timezone: Timezone['America/Cancun'],
 });
 ```
 
-# Outputs
+## Outputs
 
 `FullDate` objects are easily converted into other formats (usually strings) with the included functions:
 
@@ -77,17 +77,17 @@ parseStrangeString({
 
 ```TypeScript
 import {
-    FullDatePartEnum,
     createFullDate,
     formatPresets,
-    timezones,
+    FullDatePart,
+    Timezone,
     toHtmlInputString,
-    toIsoString,
     toLocaleString,
     toTimestamp,
+    toUtcIsoString,
 } from 'date-vir';
 
-const myFullDate = createFullDate('2023-06-05T14:19:00.870Z', timezones['America/Chicago']);
+const myFullDate = createFullDate('2023-06-05T14:19:00.870Z', Timezone['America/Chicago']);
 
 /**
  * Converts the given FullDate into a UTC unix timestamp with milliseconds. Since the output is a
@@ -101,7 +101,7 @@ toTimestamp(myFullDate); // returns 1685974740870
  * FullDate object is shifted to a different timezone, the output of this function will be the
  * same.
  */
-toIsoString(myFullDate); // returns '2023-06-05T14:19:00.870Z'
+toUtcIsoString(myFullDate); // returns '2023-06-05T14:19:00.870Z'
 
 /**
  * Converts the given FullDate to a locale-based formatted string. The second argument, the options
@@ -113,21 +113,21 @@ toLocaleString(myFullDate, formatPresets.DatetimeFull); // returns 'June 5, 2023
  * Formats the given FullDate to a string so that it is ready to be assigned to the value attribute
  * of an <input type="date" /> element.
  */
-toHtmlInputString(myFullDate, FullDatePartEnum.Date); // returns '2023-06-05'
+toHtmlInputString(myFullDate, FullDatePart.Date); // returns '2023-06-05'
 ```
 
-# Timezone
+## Timezone
 
 `date-vir` exposes a type-safe list of timezone names, including shortcuts for the user's timezone and the UTC timezone:
 
 <!-- example-link: src/readme-examples/timezones.example.ts -->
 
 ```TypeScript
-import {timezones, userTimezone, utcTimezone} from 'date-vir';
+import {Timezone, userTimezone, utcTimezone} from 'date-vir';
 
-timezones['Africa/Abidjan'];
-timezones['America/Los_Angeles'];
-timezones['Etc/GMT+1'];
+Timezone['Africa/Abidjan'];
+Timezone['America/Los_Angeles'];
+Timezone['Etc/GMT+1'];
 
 utcTimezone;
 userTimezone;
@@ -135,16 +135,16 @@ userTimezone;
 
 Note that the current list of timezone names included in this package was generated from Firefox 106.0.2.
 
-# Luxon
+## Luxon
 
 The parsing and timezone conversions in `date-vir` utilize the [`luxon`](https://www.npmjs.com/luxon) package under the hood. If you wish to gain full `luxon` control over a `FullDate` object, `date-vir` provides an easy conversion function:
 
 <!-- example-link: src/readme-examples/luxon-conversion.example.ts -->
 
 ```TypeScript
-import {createFullDate, timezones, toLuxonDateTime} from 'date-vir';
+import {createFullDate, Timezone, toLuxonDateTime} from 'date-vir';
 
-const myFullDate = createFullDate('2023-06-05T14:19:00.870Z', timezones['America/Chicago']);
+const myFullDate = createFullDate('2023-06-05T14:19:00.870Z', Timezone['America/Chicago']);
 
 toLuxonDateTime(myFullDate);
 ```

package/dist/date-operations/calculate-relative-date.d.ts

@@ -0,0 +1,17 @@
+import type { AnyDuration } from '@date-vir/duration';
+import { FullDate } from '../full-date/full-date-shape.js';
+import { Timezone } from '../timezone/timezones.js';
+/**
+ * Calculates a new date starting at the given fullDate and adding the given offsets. Offsets can be
+ * negative to go backwards in time.
+ *
+ * @category Calculation
+ * @example
+ *
+ * ```ts
+ * import {calculateRelativeDate} from 'date-vir';
+ *
+ * calculateRelativeDate(getNowInUserTimezone(), {days: 2});
+ * ```
+ */
+export declare function calculateRelativeDate<const SpecificTimezone extends Timezone>(fullDate: Readonly<FullDate<SpecificTimezone>>, offset: Readonly<AnyDuration>): FullDate<SpecificTimezone>;

package/dist/{esm/date-operations → date-operations}/calculate-relative-date.js

@@ -1,7 +1,16 @@
-import { parseLuxonDateTime, toLuxonDateTime } from '../full-date/luxon-date-time-conversion';
+import { parseLuxonDateTime, toLuxonDateTime } from '../full-date/luxon-date-time-conversion.js';
 /**
  * Calculates a new date starting at the given fullDate and adding the given offsets. Offsets can be
  * negative to go backwards in time.
+ *
+ * @category Calculation
+ * @example
+ *
+ * ```ts
+ * import {calculateRelativeDate} from 'date-vir';
+ *
+ * calculateRelativeDate(getNowInUserTimezone(), {days: 2});
+ * ```
  */
 export function calculateRelativeDate(fullDate, offset) {
     return parseLuxonDateTime(toLuxonDateTime(fullDate).plus(offset));

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

@@ -0,0 +1,43 @@
+import type { FullDatePart } from '../full-date/full-date-parts.js';
+import { DatePart, FullDate, TimePart } from '../full-date/full-date-shape.js';
+import type { Timezone } from '../timezone/timezones.js';
+/**
+ * An object containing date and/or time parts or neither. Used for {@link combineDateParts}
+ *
+ * @category Internal
+ */
+export type MaybeDateParts<SpecificTimezone extends Timezone> = Partial<{
+    [FullDatePart.Date]: DatePart<SpecificTimezone> | undefined | Partial<FullDate<SpecificTimezone>>;
+    [FullDatePart.Time]: TimePart<SpecificTimezone> | undefined | Partial<FullDate<SpecificTimezone>>;
+}>;
+/**
+ * A full date, time or date parts of a date, or undefined. Used for {@link combineDateParts}.
+ *
+ * @category Internal
+ */
+export type MaybeDatePart<SpecificTimezone extends Timezone> = FullDate<SpecificTimezone> | Partial<FullDate<SpecificTimezone>> | DatePart<SpecificTimezone> | TimePart<SpecificTimezone> | undefined;
+export declare function combineDateParts<const SpecificTimezone extends Timezone>(maybeDateParts: {
+    [FullDatePart.Date]: DatePart<SpecificTimezone>;
+    [FullDatePart.Time]: TimePart<SpecificTimezone>;
+}): FullDate<SpecificTimezone>;
+export declare function combineDateParts(maybeDateParts: {
+    [FullDatePart.Date]?: undefined;
+    [FullDatePart.Time]?: undefined;
+}): undefined;
+export declare function combineDateParts<const SpecificTimezone extends Timezone>(maybeDateParts: {
+    [FullDatePart.Date]: DatePart<SpecificTimezone>;
+    [FullDatePart.Time]?: undefined;
+}): DatePart<SpecificTimezone>;
+export declare function combineDateParts<const SpecificTimezone extends Timezone>(maybeDateParts: {
+    [FullDatePart.Date]: DatePart<SpecificTimezone>;
+    [FullDatePart.Time]?: TimePart<SpecificTimezone> | undefined | Partial<FullDate<SpecificTimezone>>;
+}): FullDate<SpecificTimezone> | DatePart<SpecificTimezone>;
+export declare function combineDateParts<const SpecificTimezone extends Timezone>(maybeDateParts: {
+    [FullDatePart.Date]?: undefined;
+    [FullDatePart.Time]: TimePart<SpecificTimezone>;
+}): TimePart<SpecificTimezone>;
+export declare function combineDateParts<const SpecificTimezone extends Timezone>(maybeDateParts: {
+    [FullDatePart.Date]?: DatePart<SpecificTimezone> | undefined | Partial<FullDate<SpecificTimezone>>;
+    [FullDatePart.Time]: TimePart<SpecificTimezone>;
+}): FullDate<SpecificTimezone> | TimePart<SpecificTimezone>;
+export declare function combineDateParts<const SpecificTimezone extends Timezone>(maybeDateParts: MaybeDateParts<SpecificTimezone>): MaybeDatePart<SpecificTimezone>;

package/dist/{esm/date-operations → date-operations}/combine-dates.js

@@ -1,9 +1,11 @@
 import { isValidShape } from 'object-shape-tester';
-import { FullDatePartEnum, datePartShape, timePartShape, } from '../full-date/full-date-shape';
+import { datePartShape, timePartShape, } from '../full-date/full-date-shape.js';
 /**
- * Combine two parts of a FullDate objects into a filled-in FullDate. Note that the timezones must
- * match for both inputs. If two complete FullDate objects are passed in, only the respective parts
- * of each is used.
+ * Combine two parts of a {@link FullDate} objects into a filled-in {@link FullDate}. Note that the
+ * timezones must match for both inputs. If two complete {@link FullDate} objects are passed in, only
+ * the respective parts of each is used.
+ *
+ * @category Util
  */
 export function combineDateParts(maybeDateParts) {
     const timePart = isValidShape(maybeDateParts.time, timePartShape, {

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