@naturalcycles/js-lib

import type { MutateOptions, SortOptions } from '../array/array.util.js'; import { Iterable2 } from '../iter/iterable2.js'; import type { Inclusiveness, IsoDate, IsoDateTime, MonthId, UnixTimestamp, UnixTimestampMillis } from '../types.js'; import type { DateObject, ISODayOfWeek, LocalTime } from './localTime.js'; export type LocalDateUnit = LocalDateUnitStrict | 'week'; export type LocalDateUnitStrict = 'year' | 'month' | 'day'; export type LocalDateInput = LocalDate | Date | IsoDate; export type LocalDateInputNullable = LocalDateInput | null | undefined; export type LocalDateFormatter = (ld: LocalDate) => string; /** * LocalDate represents a date without time. * It is timezone-independent. */ export declare class LocalDate { year: number; month: number; day: number; constructor(year: number, month: number, day: number); get(unit: LocalDateUnitStrict): number; set(unit: LocalDateUnitStrict, v: number, opt?: MutateOptions): LocalDate; setYear(v: number): LocalDate; setMonth(v: number): LocalDate; setDay(v: number): LocalDate; get dayOfWeek(): ISODayOfWeek; /** * Returns LocalDate for the given DayOfWeek (e.g Monday), that is in the same week as this. * It may move the time into the future, or the past, depending on how the desired DayOfWeek is in * relation to `this`. */ setDayOfWeek(dow: ISODayOfWeek): LocalDate; /** * Returns LocalDate for the given DayOfWeek (e.g Monday), that is in the future, * in relation to this. * If this LocalDate is Monday, and desired DoW is also Monday - `this` is returned. */ setNextDayOfWeek(dow: ISODayOfWeek): LocalDate; isSame(d: LocalDateInput): boolean; isBefore(d: LocalDateInput, inclusive?: boolean): boolean; isSameOrBefore(d: LocalDateInput): boolean; isAfter(d: LocalDateInput, inclusive?: boolean): boolean; isSameOrAfter(d: LocalDateInput): boolean; isBetween(min: LocalDateInput, max: LocalDateInput, incl: Inclusiveness): boolean; /** * Checks if this localDate is older (<) than "today" by X units. * * Example: * * localDate(expirationDate).isOlderThan(5, 'day') * * Third argument allows to override "today". */ isOlderThan(n: number, unit: LocalDateUnit, today?: LocalDateInput): boolean; /** * Checks if this localDate is same or older (<=) than "today" by X units. */ isSameOrOlderThan(n: number, unit: LocalDateUnit, today?: LocalDateInput): boolean; /** * Checks if this localDate is younger (>) than "today" by X units. * * Example: * * localDate(expirationDate).isYoungerThan(5, 'day') * * Third argument allows to override "today". */ isYoungerThan(n: number, unit: LocalDateUnit, today?: LocalDateInput): boolean; /** * Checks if this localDate is same or younger (>=) than "today" by X units. */ isSameOrYoungerThan(n: number, unit: LocalDateUnit, today?: LocalDateInput): boolean; isToday(): boolean; isAfterToday(): boolean; isSameOrAfterToday(): boolean; isBeforeToday(): boolean; isSameOrBeforeToday(): boolean; getAgeInYears(today?: LocalDateInput): number; getAgeInMonths(today?: LocalDateInput): number; getAgeInDays(today?: LocalDateInput): number; getAgeIn(unit: LocalDateUnit, today?: LocalDateInput): number; /** * Returns 1 if this > d * returns 0 if they are equal * returns -1 if this < d */ compare(d: LocalDateInput): -1 | 0 | 1; /** * Same as Math.abs( diff ) */ absDiff(d: LocalDateInput, unit: LocalDateUnit): number; /** * Returns the number of **full** units difference (aka `Math.floor`). * * a.diff(b) means "a minus b" */ diff(d: LocalDateInput, unit: LocalDateUnit): number; plusDays(num: number): LocalDate; plusWeeks(num: number): LocalDate; plusMonths(num: number): LocalDate; plusYears(num: number): LocalDate; minusDays(num: number): LocalDate; minusWeeks(num: number): LocalDate; minusMonths(num: number): LocalDate; minusYears(num: number): LocalDate; plus(num: number, unit: LocalDateUnit, opt?: MutateOptions): LocalDate; minus(num: number, unit: LocalDateUnit, opt?: MutateOptions): LocalDate; startOf(unit: LocalDateUnitStrict): LocalDate; endOf(unit: LocalDateUnitStrict): LocalDate; /** * Returns how many days are in the current month. * E.g 31 for January. */ get daysInMonth(): number; clone(): LocalDate; /** * Converts LocalDate into instance of Date. * Year, month and day will match. * Hour, minute, second, ms will be 0. * Timezone will match local timezone. */ toDate(): Date; /** * Converts LocalDate to Date in UTC timezone. * Unlike normal `.toDate` that uses browser's timezone by default. */ toDateInUTC(): Date; toDateObject(): DateObject; /** * Converts LocalDate to LocalTime with 0 hours, 0 minutes, 0 seconds. * LocalTime's Date will be in local timezone. */ toLocalTime(): LocalTime; /** * Returns e.g: `1984-06-21` */ toISODate(): IsoDate; /** * Returns e.g: `1984-06-21T00:00:00` * Hours, minutes and seconds are 0. */ toISODateTime(): IsoDateTime; /** * Returns e.g: `1984-06-21T00:00:00Z` (notice the Z at the end, which indicates UTC). * Hours, minutes and seconds are 0. */ toISODateTimeInUTC(): IsoDateTime; toString(): IsoDate; /** * Returns e.g: `19840621` */ toStringCompact(): string; /** * Returns e.g: `1984-06` */ toMonthId(): MonthId; /** * Returns unix timestamp of 00:00:00 of that date (in UTC, because unix timestamp always reflects UTC). */ get unix(): UnixTimestamp; /** * Same as .unix(), but in milliseconds. */ get unixMillis(): UnixTimestampMillis; toJSON(): IsoDate; format(fmt: Intl.DateTimeFormat | LocalDateFormatter): string; } declare class LocalDateFactory { /** * Creates a LocalDate from the input, unless it's falsy - then returns undefined. * * Similar to `localDate.orToday`, but that will instead return Today on falsy input. */ orUndefined(d: LocalDateInputNullable): LocalDate | undefined; /** * Creates a LocalDate from the input, unless it's falsy - then returns localDate.today. */ orToday(d: LocalDateInputNullable): LocalDate; /** * Creates LocalDate that represents `today` (in local timezone). */ today(): LocalDate; /** * Creates LocalDate that represents `today` in UTC. */ todayInUTC(): LocalDate; /** Convenience function to return current today's IsoDate representation, e.g `2024-06-21` */ todayString(): IsoDate; /** * Create LocalDate from LocalDateInput. * Input can already be a LocalDate - it is returned as-is in that case. * String - will be parsed as yyyy-mm-dd. * Date - will be converted to LocalDate (as-is, in whatever timezone it is - local or UTC). * No other formats are supported. * * Will throw if it fails to parse/construct LocalDate. */ fromInput(input: LocalDateInput): LocalDate; /** * Returns true if input is valid to create LocalDate. */ isValid(input: LocalDateInputNullable): boolean; /** * Returns true if isoString is a valid iso8601 string like `yyyy-mm-dd`. */ isValidString(isoString: string | undefined | null): boolean; /** * Tries to convert/parse the input into LocalDate. * Uses LOOSE parsing. * If invalid - doesn't throw, but returns undefined instead. */ try(input: LocalDateInputNullable): LocalDate | undefined; /** * Performs STRICT parsing. * Only allows IsoDate input, nothing else. */ fromString(s: IsoDate): LocalDate; /** * Parses "compact iso8601 format", e.g `19840621` into LocalDate. * Throws if it fails to do so. */ fromCompactString(s: string): LocalDate; /** * Throws if it fails to parse the input string via Regex and YMD validation. */ private parseToLocalDate; /** * Tries to parse the input string, returns undefined if input is invalid. */ private parseToLocalDateOrUndefined; /** * Throws on invalid value. */ private validateDateObject; isDateObjectValid({ year, month, day }: DateObject): boolean; /** * Constructs LocalDate from Date. * Takes Date as-is, in its timezone - local or UTC. */ fromDate(d: Date): LocalDate; /** * Constructs LocalDate from Date. * Takes Date's year/month/day components in UTC, using getUTCFullYear, getUTCMonth, getUTCDate. */ fromDateInUTC(d: Date): LocalDate; fromDateObject(o: DateObject): LocalDate; /** * Sorts an array of LocalDates in `dir` order (ascending by default). */ sort(items: LocalDate[], opt?: SortOptions): LocalDate[]; /** * Returns the earliest (min) LocalDate from the array, or undefined if the array is empty. */ minOrUndefined(items: LocalDateInputNullable[]): LocalDate | undefined; /** * Returns the earliest LocalDate from the array. * Throws if the array is empty. */ min(items: LocalDateInputNullable[]): LocalDate; /** * Returns the latest (max) LocalDate from the array, or undefined if the array is empty. */ maxOrUndefined(items: LocalDateInputNullable[]): LocalDate | undefined; /** * Returns the latest LocalDate from the array. * Throws if the array is empty. */ max(items: LocalDateInputNullable[]): LocalDate; /** * Returns the range (array) of LocalDates between min and max. * By default, min is included, max is excluded. */ range(min: LocalDateInput, max: LocalDateInput, incl: Inclusiveness, step?: number, stepUnit?: LocalDateUnit): LocalDate[]; /** * Returns the Iterable2 of LocalDates between min and max. * By default, min is included, max is excluded. */ rangeIterable(min: LocalDateInput, max: LocalDateInput, incl: Inclusiveness, step?: number, stepUnit?: LocalDateUnit): Iterable2<LocalDate>; getYearLength(year: number): number; getMonthLength(year: number, month: number): number; isLeapYear(year: number): boolean; } interface LocalDateFn extends LocalDateFactory { (d: LocalDateInput): LocalDate; } export declare const localDate: LocalDateFn; export {};