date-vir
Version:
Easy and explicit dates and times.
168 lines (167 loc) • 6.43 kB
TypeScript
import { DateUnit } from '@date-vir/duration';
import { type FullDate } from '../full-date/full-date-shape.js';
import { type 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").Shape<import("object-shape-tester").Shape<import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TObject<{
get: import("@sinclair/typebox").TUnsafe<DateUnit.Month>;
in: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TUnsafe<DateUnit.Year>[]>;
}> | import("@sinclair/typebox").TObject<{
get: import("@sinclair/typebox").TUnsafe<DateUnit.Week>;
in: import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TUnsafe<DateUnit.Month> | import("@sinclair/typebox").TUnsafe<DateUnit.Year>)[]>;
}> | import("@sinclair/typebox").TObject<{
get: import("@sinclair/typebox").TUnsafe<DateUnit.Day>;
in: import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TUnsafe<DateUnit.Month> | import("@sinclair/typebox").TUnsafe<DateUnit.Year> | import("@sinclair/typebox").TUnsafe<DateUnit.Week>)[]>;
}> | import("@sinclair/typebox").TObject<{
get: import("@sinclair/typebox").TUnsafe<DateUnit.Hour>;
in: import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TUnsafe<DateUnit.Month> | import("@sinclair/typebox").TUnsafe<DateUnit.Year> | import("@sinclair/typebox").TUnsafe<DateUnit.Week> | import("@sinclair/typebox").TUnsafe<DateUnit.Day>)[]>;
}> | import("@sinclair/typebox").TObject<{
get: import("@sinclair/typebox").TUnsafe<DateUnit.Minute>;
in: import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TUnsafe<DateUnit.Month> | import("@sinclair/typebox").TUnsafe<DateUnit.Year> | import("@sinclair/typebox").TUnsafe<DateUnit.Week> | import("@sinclair/typebox").TUnsafe<DateUnit.Day> | import("@sinclair/typebox").TUnsafe<DateUnit.Hour>)[]>;
}> | import("@sinclair/typebox").TObject<{
get: import("@sinclair/typebox").TUnsafe<DateUnit.Second>;
in: import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TUnsafe<DateUnit.Month> | import("@sinclair/typebox").TUnsafe<DateUnit.Year> | import("@sinclair/typebox").TUnsafe<DateUnit.Week> | import("@sinclair/typebox").TUnsafe<DateUnit.Day> | import("@sinclair/typebox").TUnsafe<DateUnit.Hour> | import("@sinclair/typebox").TUnsafe<DateUnit.Minute>)[]>;
}> | import("@sinclair/typebox").TObject<{
get: import("@sinclair/typebox").TUnsafe<DateUnit.Millisecond>;
in: import("@sinclair/typebox").TUnion<(import("@sinclair/typebox").TUnsafe<DateUnit.Month> | import("@sinclair/typebox").TUnsafe<DateUnit.Year> | import("@sinclair/typebox").TUnsafe<DateUnit.Week> | import("@sinclair/typebox").TUnsafe<DateUnit.Day> | import("@sinclair/typebox").TUnsafe<DateUnit.Hour> | import("@sinclair/typebox").TUnsafe<DateUnit.Minute> | import("@sinclair/typebox").TUnsafe<DateUnit.Second>)[]>;
}>)[]>>>;
/**
* 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;