date-vir
Version:
Easy and explicit dates and times.
168 lines (167 loc) • 7.19 kB
TypeScript
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 "get" unit within the given "in" unit.
*
* @category Calculation
* @example
*
* ```ts
* import {calculateDatePosition, DateUnit} from 'date-vir';
*
* calculateDatePosition(
* {
* year: 2020,
* month: 4,
* day: 5,
*
* hour: 0,
* minute: 0,
* second: 0,
* millisecond: 0,
*
* timezone: utcTimezone,
* },
* {
* get: DateUnit.Week,
* in: DateUnit.Year,
* },
* );
* // result is ~14.14 (always round up for week in the year numbers, thus yielding week 15)
*
* calculateDatePosition(
* {
* year: 2020,
* month: 4,
* day: 5,
*
* hour: 0,
* minute: 0,
* second: 0,
* millisecond: 0,
* timezone: utcTimezone,
* },
* {
* get: DateUnit.Day,
* in: DateUnit.Week,
* },
* );
* // result is 0 (Sunday)
* ```
*/
export declare function calculateDatePosition(date: Readonly<FullDate>, calculation: Readonly<DatePositionCalculation>): number;