date-vir

Easy dates and times with explicit timezones (and typed timezones).

Full docs: http://electrovir.github.io/date-vir

date-vir revolves around its FullDate 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:

import {type FullDate, utcTimezone} from 'date-vir';

const myDate: FullDate = {
    year: 2023,
    month: 6,
    day: 5,

    hour: 5,
    minute: 23,
    second: 27,
    millisecond: 652,

    timezone: utcTimezone,
};
Copy

Creating a FullDate

Several functions are available for creating FullDate objects:

import {
    createFullDate,
    getNowFullDate,
    parseDateStringWithPattern,
    parseInputElementValue,
    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', Timezone['Europe/Rome']);

/** Get the current date and time right now in the given timezone. */
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'), Timezone['Asia/Tokyo']);

/**
 * If you have a really oddly formatted date/time string and createFullDate does not suffice, you
 * can have full parsing control using this function. Luxon is used under the hood for this parsing,
 * so you can see all the formatString options in its docs:
 * https://moment.github.io/luxon/#/parsing?id=table-of-tokens
 */
parseDateStringWithPattern({
    dateString: '870-0-14-19 5 2023 6',
    formatString: 'S-s-h-m d yyyy M',
    timezone: Timezone['America/Cancun'],
});
Copy

Outputs

FullDate objects are easily converted into other formats (usually strings) with the included functions:

import {
    createFullDate,
    formatPresets,
    FullDatePart,
    Timezone,
    toHtmlInputString,
    toLocaleString,
    toTimestamp,
    toUtcIsoString,
} from 'date-vir';

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
 * UTC timestamp, the number will be the same even if you convert your FullDate to a different time
 * zone.
 */
toTimestamp(myFullDate); // returns 1685974740870

/**
 * Converts the given FullDate into a UTC ISO string. Since the output is in UTC, even if your
 * FullDate object is shifted to a different timezone, the output of this function will be the
 * same.
 */
toUtcIsoString(myFullDate); // returns '2023-06-05T14:19:00.870Z'

/**
 * Converts the given FullDate to a locale-based formatted string. The second argument, the options
 * argument, is optional and contains many options therein.
 */
toLocaleString(myFullDate, formatPresets.DatetimeFull); // returns 'June 5, 2023 at 9:19 AM CDT' in the en-us locale

/**
 * 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, FullDatePart.Date); // returns '2023-06-05'
Copy

Timezone

date-vir exposes a type-safe list of timezone names, including shortcuts for the user's timezone and the UTC timezone:

import {Timezone, userTimezone, utcTimezone} from 'date-vir';

Timezone['Africa/Abidjan'];
Timezone['America/Los_Angeles'];
Timezone['Etc/GMT+1'];

utcTimezone;
userTimezone;
Copy

Note that the current list of timezone names included in this package was generated from Firefox 106.0.2.

Luxon

The parsing and timezone conversions in date-vir utilize the luxon package under the hood. If you wish to gain full luxon control over a FullDate object, date-vir provides an easy conversion function:

import {createFullDate, Timezone, toLuxonDateTime} from 'date-vir';

const myFullDate = createFullDate('2023-06-05T14:19:00.870Z', Timezone['America/Chicago']);

toLuxonDateTime(myFullDate);
Copy