shelving/util/duration.d.ts

Toolkit for using data in JavaScript.

import { type PossibleDate } from "./date.js";
import type { AnyCaller } from "./function.js";
import { type TimeUnitKey, type Unit } from "./units.js";
/**
 * Duration object.
 * - This should be compatible with `Intl.DurationFormat` when that is available.
 */
export type Duration = {
    readonly years?: number | undefined;
    readonly months?: number | undefined;
    readonly weeks?: number | undefined;
    readonly days?: number | undefined;
    readonly hours?: number | undefined;
    readonly minutes?: number | undefined;
    readonly seconds?: number | undefined;
    readonly milliseconds?: number | undefined;
    readonly microseconds?: number | undefined;
    readonly nanoseconds?: number | undefined;
};
/** Get the millisecond difference between two dates. */
export declare function getMilliseconds(from?: PossibleDate, to?: PossibleDate, caller?: AnyCaller): number;
/** Count the various time units between two dates and return a `Duration` format. */
export declare function getDuration(from?: PossibleDate, to?: PossibleDate, caller?: AnyCaller): Duration;
/** Get the various time units until a certain date. */
export declare function getUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): Duration;
/** Get the various time units since a certain date. */
export declare function getAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): Duration;
/** Count the milliseconds until a date. */
export declare function getMillisecondsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/** Count the milliseconds since a date. */
export declare function getMillisecondsAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/**
 * Count the whole seconds until a date.
 * - Rounds to the nearest whole second, i.e. `1 second 499 ms` returns `1`
 */
export declare function getSecondsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/**
 * Count the whole seconds since a date.
 * - Rounds to the nearest whole second, i.e. `1 second 499 ms` returns `1`
 */
export declare function getSecondsAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/**
 * Count the whole minutes until a date.
 * - Rounds to the nearest whole minute, i.e. `1 min 29 seconds` returns `1`
 */
export declare function getMinutesUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/**
 * Count the whole minutes since a date.
 * - Rounds to the nearest whole minute, i.e. `1 min 29 seconds` returns `1`
 */
export declare function getMinutesAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/**
 * Count the whole hours until a date.
 * - Rounds to the nearest whole hour, i.e. `1 hour 29 minutes` returns `1`
 */
export declare function getHoursUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/**
 * Count the whole hours since a date.
 * - Rounds to the nearest whole hour, i.e. `1 hour 29 minutes` returns `1`
 */
export declare function getHoursAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/**
 * Count the calendar days until a date.
 * - e.g. from 23:59 to 00:01 is 1 day, even though it's only 1 minutes.
 */
export declare function getDaysUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/**
 * Count the calendar days since a date.
 * - Rounds to the nearest whole days.
 */
export declare function getDaysAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/**
 * Count the whole weeks until a date.
 * - Rounds down to the nearest whole week, i.e.
 */
export declare function getWeeksUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/**
 * Count the whole weeks since a date.
 * - Rounds to the nearest whole week.
 */
export declare function getWeeksAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/**
 * Count the calendar months until a date.
 * - e.g. from March 31st to April 1st is 1 month, even though it's only 1 day.
 */
export declare function getMonthsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/**
 * Count the calendar months since a date.
 * - e.g. from March 31st to April 1st is 1 month, even though it's only 1 day.
 */
export declare function getMonthsAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/**
 * Count the calendar years until a date.
 * - e.g. from December 31st to January 1st is 1 year, even though it's only 1 day.
 */
export declare function getYearsUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/**
 * Count the calendar years since a date.
 * - Note this counts calendar years, not 365-day periods.
 * - e.g. from December 31st to January 1st is -1 years, even though it's only 1 day.
 */
export declare function getYearsAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): number;
/** Is a date in the past? */
export declare function isPast(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
/** Is a date in the future? */
export declare function isFuture(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
/** Is a date today (taking into account midnight). */
export declare function isToday(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): boolean;
/**
 * Get a best-fit time unit based on an amount in milliseconds.
 * - Makes a sensible choice about the best time unit to use.
 * - Years will be used for anything 18 months or more, e.g. `in 2 years`
 * - Months will be used for anything 10 weeks or more, e.g. `in 14 months`
 * - Weeks will be used for anything 2 weeks or more, e.g. `in 9 weeks`
 * - Days will be used for anything 24 hours or more, e.g. `in 13 days`
 * - Hours will be used for anything 90 minutes or more, e.g. `in 23 hours`
 * - Minutes will be used for anything 1 second or more, e.g. `1 minute ago` or `in 59 minutes`
 * - Seconds will be used for anything 1000 milliseconds or more, e.g. `in 59 seconds`
 */
export declare function getBestTimeUnit(ms: number): Unit<TimeUnitKey>;