shelving/util/duration.d.ts

Toolkit for using data in JavaScript.

import { type PossibleDate } from "./date.js";
import type { FormatOptions, UnitFormatOptions } from "./format.js";
import type { AnyCaller } from "./function.js";
import type { MapKey } from "./map.js";
import { type Unit, UnitList } from "./units.js";
/** Duration data object. */
export type DurationData = {
    [K in Intl.DurationFormatUnit]?: number;
};
/** 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): DurationData;
/** Get the various time units until a certain date. */
export declare function getUntil(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): DurationData;
/** Get the various time units since a certain date. */
export declare function getAgo(target: PossibleDate, current?: PossibleDate, caller?: AnyCaller): DurationData;
/** 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;
/** Duration units. */
export declare const DURATION_UNITS: UnitList<"day" | "hour" | "millisecond" | "minute" | "month" | "second" | "week" | "year">;
export type DurationUnitKey = MapKey<typeof DURATION_UNITS>;
/**
 * Get a best-fit duration 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 10 days or more, e.g. `in 9 weeks`
 * - Days will be used for anything 1 day or more, e.g. `in 13 days`
 * - Hours will be used for anything 1 hour or more, e.g. `in 23 hours`
 * - Minutes will be used for anything 1 minute 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 getBestDurationUnit(ms: number): Unit<DurationUnitKey>;
/**
 * Compact best-fit when a date happens/happened, e.g. `in 10d` or `2h ago` or `in 1w` or `just now`
 * - See `getBestTimeUnit()` for details on how the best-fit unit is chosen.
 * - But: anything under 30 seconds will show `just now`, which makes more sense in most UIs.
 */
export declare function formatWhen(target: PossibleDate, current?: PossibleDate, options?: UnitFormatOptions, caller?: AnyCaller): string;
/** Compact when a date happens, e.g. `10d` or `2h` or `-1w` */
export declare function formatUntil(target: PossibleDate, current?: PossibleDate, options?: UnitFormatOptions, caller?: AnyCaller): string;
/** Compact when a date will happen, e.g. `10d` or `2h` or `-1w` */
export declare function formatAgo(target: PossibleDate, current?: PossibleDate, options?: UnitFormatOptions, caller?: AnyCaller): string;
interface DurationFormatOptions extends FormatOptions, Intl.DurationFormatOptions {
}
/** Format a duration as a string, e.g. `1 year, 2 months, 3 days` or `1y 2m 3d` */
export declare function formatDuration(duration: DurationData, options?: DurationFormatOptions): string;
export {};