# date-vir

> Easy and explicit dates and times.

Latest version **9.4.1** (published 2026-10-22) · (MIT OR CC0-1.0) license · 0 weekly downloads

## Install

```sh
npm install date-vir
pnpm add date-vir
yarn add date-vir
bun add date-vir
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 9.4.1 |
| Published | 2026-10-22 |
| First published | 2023-06-03 |
| Weekly downloads | 0 |
| License | (MIT OR CC0-1.0) |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22 |
| Dependencies | 7 |
| Unpacked size | 197.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | electrovir |
| Maintainers | electrovir |
| Keywords | date, duration, time, util, vir |

## Links

- npm: https://www.npmjs.com/package/date-vir
- Repository: https://github.com/electrovir/date-vir
- Issues: https://github.com/electrovir/date-vir/issues
- npm.io page: https://npm.io/package/date-vir

## Dependencies (7)

- [luxon](https://npm.io/package/luxon.md) ^3.7.2
- [type-fest](https://npm.io/package/type-fest.md) ^5.10.0
- [@types/luxon](https://npm.io/package/@types/luxon.md) ^3.7.6
- [@date-vir/duration](https://npm.io/package/@date-vir/duration.md) ^9.4.1
- [@augment-vir/assert](https://npm.io/package/@augment-vir/assert.md) ^32.6.0
- [@augment-vir/common](https://npm.io/package/@augment-vir/common.md) ^32.6.0
- [object-shape-tester](https://npm.io/package/object-shape-tester.md) ^6.15.1

## Alternatives

- [@js-joda/timezone](https://npm.io/package/@js-joda/timezone.md) — 383.4K weekly downloads
- [chartjs-adapter-moment](https://npm.io/package/chartjs-adapter-moment.md) — 210.8K weekly downloads
- [strftime](https://npm.io/package/strftime.md) — 171.2K weekly downloads
- [vue-flatpickr-component](https://npm.io/package/vue-flatpickr-component.md) — 115.8K weekly downloads
- [timepicker](https://npm.io/package/timepicker.md) — 51.0K weekly downloads

## Recent versions

- 9.4.1 (latest) — 2026-10-22
- 9.4.0 — 2026-10-08
- 9.3.0 — 2026-10-03
- 9.2.1 — 2026-09-29
- 9.2.0 — 2026-09-22
- 9.1.1 — 2026-08-20
- 9.1.0 — 2026-08-16
- 9.0.0 — 2026-08-12
- 8.6.4 — 2026-08-12
- 8.6.3 — 2026-08-12
- 8.6.2 — 2026-07-01
- 8.6.1 — 2026-06-18
- 8.6.0 — 2026-06-18
- 8.5.1 — 2026-06-18
- 8.5.0 — 2026-06-09
- … 67 more at https://npm.io/package/date-vir/versions

## README

# 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`](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 {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,
};
```

## Creating a FullDate

Several functions are available for creating `FullDate` objects:

<!-- example-link: src/readme-examples/full-date-creation.example.ts -->

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

/** Get the current date and time right now in the given timezone. */
getNowFullDate(TimezoneName['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'), TimezoneName['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: TimezoneName['America/Cancun'],
});
```

## Outputs

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

<!-- example-link: src/readme-examples/full-date-conversions.example.ts -->

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

const myFullDate = createFullDate('2023-06-05T14:19:00.870Z', TimezoneName['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'
```

## 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 {TimezoneName, userTimezone, utcTimezone} from 'date-vir';

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

utcTimezone;
userTimezone;
```

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`](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, TimezoneName, toLuxonDateTime} from 'date-vir';

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

toLuxonDateTime(myFullDate);
```

---
_Source: https://npm.io/package/date-vir · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._