date-vir 5.3.2 → 7.0.0

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/date-position.d.ts

@@ -0,0 +1,149 @@
+import { DateUnit } from '@date-vir/duration';
+import { type FullDate } from '../full-date/full-date-shape.js';
+import { Timezone } from '../timezone/timezones.js';
+/**
+ * Get the {@link DateUnit} value of a {@link FullDate}.
+ *
+ * @category Calculation
+ * @example
+ *
+ * ```ts
+ * import {getDateUnit, DateUnit, utcTimezone} from 'date-vir';
+ *
+ * getDateUnit(
+ *     {
+ *         year: 2024,
+ *         month: 11,
+ *         day: 7,
+ *
+ *         hour: 12,
+ *         minute: 12,
+ *         second: 12,
+ *         millisecond: 12,
+ *
+ *         timezone: utcTimezone,
+ *     },
+ *     DateUnit.Week,
+ * ); // outputs `45`
+ * ```
+ */
+export declare function getDateUnit(date: Readonly<FullDate>, unit: DateUnit): number;
+/**
+ * Get the start date of a specific {@link DateUnit} based on a given {@link FullDate}.
+ *
+ * @category Calculation
+ * @example
+ *
+ * ```ts
+ * import {getStartDate, DateUnit, utcTimezone} from 'date-vir';
+ *
+ * getStartDate(
+ *     {
+ *         year: 2024,
+ *         month: 11,
+ *         day: 7,
+ *
+ *         hour: 12,
+ *         minute: 12,
+ *         second: 12,
+ *         millisecond: 12,
+ *
+ *         timezone: utcTimezone,
+ *     },
+ *     DateUnit.Month,
+ * ); // outputs {year: 2024, month: 11, day: 1, hour: 0, minute: 0, second: 0, millisecond: 0, timezone: utcTimezone}
+ * ```
+ */
+export declare function getStartDate<const SpecificTimezone extends Timezone>(date: Readonly<FullDate<SpecificTimezone>>, unit: DateUnit): FullDate<SpecificTimezone>;
+/**
+ * Get the end date of a specific {@link DateUnit} based on a given {@link FullDate}.
+ *
+ * @category Calculation
+ * @example
+ *
+ * ```ts
+ * import {getEndDate, DateUnit, utcTimezone} from 'date-vir';
+ *
+ * getEndDate(
+ *     {
+ *         year: 2024,
+ *         month: 11,
+ *         day: 7,
+ *
+ *         hour: 12,
+ *         minute: 12,
+ *         second: 12,
+ *         millisecond: 12,
+ *
+ *         timezone: utcTimezone,
+ *     },
+ *     DateUnit.Month,
+ * ); // outputs {year: 2024, month: 11, day: 30, hour: 23, minute: 59, second: 59, millisecond: 999, timezone: utcTimezone}
+ * ```
+ */
+export declare function getEndDate<const SpecificTimezone extends Timezone>(date: Readonly<FullDate<SpecificTimezone>>, unit: DateUnit): FullDate<SpecificTimezone>;
+/**
+ * Shape definition for all valid date position calculations. Used for {@link calculateDatePosition}.
+ *
+ * @category Internal
+ */
+export declare const datePositionCalculationShape: import("object-shape-tester").ShapeDefinition<import("object-shape-tester").ShapeOr<[{
+    get: import("object-shape-tester").ShapeExact<readonly [DateUnit.Month]>;
+    in: import("object-shape-tester").ShapeOr<[import("object-shape-tester").ShapeExact<readonly [DateUnit.Year]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Quarter]>]>;
+}, {
+    get: import("object-shape-tester").ShapeExact<readonly [DateUnit.Week]>;
+    in: import("object-shape-tester").ShapeOr<[import("object-shape-tester").ShapeExact<readonly [DateUnit.Year]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Quarter]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Month]>]>;
+}, {
+    get: import("object-shape-tester").ShapeExact<readonly [DateUnit.Day]>;
+    in: import("object-shape-tester").ShapeOr<[import("object-shape-tester").ShapeExact<readonly [DateUnit.Year]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Quarter]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Month]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Week]>]>;
+}, {
+    get: import("object-shape-tester").ShapeExact<readonly [DateUnit.Hour]>;
+    in: import("object-shape-tester").ShapeOr<[import("object-shape-tester").ShapeExact<readonly [DateUnit.Year]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Quarter]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Month]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Week]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Day]>]>;
+}, {
+    get: import("object-shape-tester").ShapeExact<readonly [DateUnit.Minute]>;
+    in: import("object-shape-tester").ShapeOr<[import("object-shape-tester").ShapeExact<readonly [DateUnit.Year]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Quarter]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Month]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Week]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Day]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Hour]>]>;
+}, {
+    get: import("object-shape-tester").ShapeExact<readonly [DateUnit.Second]>;
+    in: import("object-shape-tester").ShapeOr<[import("object-shape-tester").ShapeExact<readonly [DateUnit.Year]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Quarter]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Month]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Week]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Day]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Hour]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Minute]>]>;
+}, {
+    get: import("object-shape-tester").ShapeExact<readonly [DateUnit.Millisecond]>;
+    in: import("object-shape-tester").ShapeOr<[import("object-shape-tester").ShapeExact<readonly [DateUnit.Year]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Quarter]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Month]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Week]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Day]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Hour]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Minute]>, import("object-shape-tester").ShapeExact<readonly [DateUnit.Second]>]>;
+}]>, false>;
+/**
+ * All valid date position calculations. Used for {@link calculateDatePosition}.
+ *
+ * @category Internal
+ */
+export type DatePositionCalculation = typeof datePositionCalculationShape.runtimeType;
+/**
+ * Calculate the position of the given date's day within the given date unit. Only date units larger
+ * than a day are allowed.
+ *
+ * @category Calculation
+ * @example
+ *
+ * ```ts
+ * import {calculateDatePosition, DateUnit} from 'date-vir';
+ *
+ * calculateDatePosition(
+ *     {
+ *         day: 5,
+ *         month: 4,
+ *         year: 2020,
+ *     },
+ *     DateUnit.Month,
+ * );
+ * // result is 5
+ *
+ * calculateDatePosition(
+ *     {
+ *         day: 5,
+ *         month: 4,
+ *         year: 2020,
+ *     },
+ *     DateUnit.Week,
+ * );
+ * // result is
+ * ```
+ */
+export declare function calculateDatePosition(date: Readonly<FullDate>, calculation: Readonly<DatePositionCalculation>): number;

package/dist/date-operations/date-position.js

@@ -0,0 +1,175 @@
+import { check } from '@augment-vir/assert';
+import { stringify } from '@augment-vir/common';
+import { DateUnit, oneIndexedDateUnits } from '@date-vir/duration';
+import { defineShape, exact, isValidShape, or } from 'object-shape-tester';
+import { createFullDate } from '../full-date/create-full-date.js';
+import { toLuxonDateTime } from '../full-date/luxon-date-time-conversion.js';
+import { diffDates } from './diff-dates.js';
+/**
+ * Get the {@link DateUnit} value of a {@link FullDate}.
+ *
+ * @category Calculation
+ * @example
+ *
+ * ```ts
+ * import {getDateUnit, DateUnit, utcTimezone} from 'date-vir';
+ *
+ * getDateUnit(
+ *     {
+ *         year: 2024,
+ *         month: 11,
+ *         day: 7,
+ *
+ *         hour: 12,
+ *         minute: 12,
+ *         second: 12,
+ *         millisecond: 12,
+ *
+ *         timezone: utcTimezone,
+ *     },
+ *     DateUnit.Week,
+ * ); // outputs `45`
+ * ```
+ */
+export function getDateUnit(date, unit) {
+    const luxonInstance = toLuxonDateTime(date);
+    if (unit === DateUnit.Week) {
+        return luxonInstance.weekNumber;
+    }
+    else {
+        return luxonInstance[unit];
+    }
+}
+/**
+ * Get the start date of a specific {@link DateUnit} based on a given {@link FullDate}.
+ *
+ * @category Calculation
+ * @example
+ *
+ * ```ts
+ * import {getStartDate, DateUnit, utcTimezone} from 'date-vir';
+ *
+ * getStartDate(
+ *     {
+ *         year: 2024,
+ *         month: 11,
+ *         day: 7,
+ *
+ *         hour: 12,
+ *         minute: 12,
+ *         second: 12,
+ *         millisecond: 12,
+ *
+ *         timezone: utcTimezone,
+ *     },
+ *     DateUnit.Month,
+ * ); // outputs {year: 2024, month: 11, day: 1, hour: 0, minute: 0, second: 0, millisecond: 0, timezone: utcTimezone}
+ * ```
+ */
+export function getStartDate(date, unit) {
+    const luxonInstance = toLuxonDateTime(date);
+    return createFullDate(luxonInstance.startOf(unit), date.timezone);
+}
+/**
+ * Get the end date of a specific {@link DateUnit} based on a given {@link FullDate}.
+ *
+ * @category Calculation
+ * @example
+ *
+ * ```ts
+ * import {getEndDate, DateUnit, utcTimezone} from 'date-vir';
+ *
+ * getEndDate(
+ *     {
+ *         year: 2024,
+ *         month: 11,
+ *         day: 7,
+ *
+ *         hour: 12,
+ *         minute: 12,
+ *         second: 12,
+ *         millisecond: 12,
+ *
+ *         timezone: utcTimezone,
+ *     },
+ *     DateUnit.Month,
+ * ); // outputs {year: 2024, month: 11, day: 30, hour: 23, minute: 59, second: 59, millisecond: 999, timezone: utcTimezone}
+ * ```
+ */
+export function getEndDate(date, unit) {
+    const luxonInstance = toLuxonDateTime(date);
+    return createFullDate(luxonInstance.endOf(unit), date.timezone);
+}
+/**
+ * Shape definition for all valid date position calculations. Used for {@link calculateDatePosition}.
+ *
+ * @category Internal
+ */
+export const datePositionCalculationShape = defineShape(or({
+    get: exact(DateUnit.Month),
+    in: or(exact(DateUnit.Year), exact(DateUnit.Quarter)),
+}, {
+    get: exact(DateUnit.Week),
+    in: or(exact(DateUnit.Year), exact(DateUnit.Quarter), exact(DateUnit.Month)),
+}, {
+    get: exact(DateUnit.Day),
+    in: or(exact(DateUnit.Year), exact(DateUnit.Quarter), exact(DateUnit.Month), exact(DateUnit.Week)),
+}, {
+    get: exact(DateUnit.Hour),
+    in: or(exact(DateUnit.Year), exact(DateUnit.Quarter), exact(DateUnit.Month), exact(DateUnit.Week), exact(DateUnit.Day)),
+}, {
+    get: exact(DateUnit.Minute),
+    in: or(exact(DateUnit.Year), exact(DateUnit.Quarter), exact(DateUnit.Month), exact(DateUnit.Week), exact(DateUnit.Day), exact(DateUnit.Hour)),
+}, {
+    get: exact(DateUnit.Second),
+    in: or(exact(DateUnit.Year), exact(DateUnit.Quarter), exact(DateUnit.Month), exact(DateUnit.Week), exact(DateUnit.Day), exact(DateUnit.Hour), exact(DateUnit.Minute)),
+}, {
+    get: exact(DateUnit.Millisecond),
+    in: or(exact(DateUnit.Year), exact(DateUnit.Quarter), exact(DateUnit.Month), exact(DateUnit.Week), exact(DateUnit.Day), exact(DateUnit.Hour), exact(DateUnit.Minute), exact(DateUnit.Second)),
+}));
+/**
+ * Calculate the position of the given date's day within the given date unit. Only date units larger
+ * than a day are allowed.
+ *
+ * @category Calculation
+ * @example
+ *
+ * ```ts
+ * import {calculateDatePosition, DateUnit} from 'date-vir';
+ *
+ * calculateDatePosition(
+ *     {
+ *         day: 5,
+ *         month: 4,
+ *         year: 2020,
+ *     },
+ *     DateUnit.Month,
+ * );
+ * // result is 5
+ *
+ * calculateDatePosition(
+ *     {
+ *         day: 5,
+ *         month: 4,
+ *         year: 2020,
+ *     },
+ *     DateUnit.Week,
+ * );
+ * // result is
+ * ```
+ */
+export function calculateDatePosition(date, calculation) {
+    if (!isValidShape(calculation, datePositionCalculationShape)) {
+        throw new Error(`Invalid date position calculation for '${stringify(date)}': cannot get ${calculation.get} in ${calculation.in}.`);
+    }
+    const start = getStartDate(date, calculation.in);
+    const diffUnit = `${calculation.get}s`;
+    const diff = diffDates({ start, end: date }, { [diffUnit]: true });
+    const value = diff[diffUnit];
+    if (check.isIn(calculation.get, oneIndexedDateUnits)) {
+        return value + 1;
+    }
+    else {
+        return value;
+    }
+}