78 lines
2.0 KiB
TypeScript
78 lines
2.0 KiB
TypeScript
import type { Duration, DurationUnit, LocalizedOptions } from "./types.js";
|
|
/**
|
|
* The {@link formatDuration} function options.
|
|
*/
|
|
export interface FormatDurationOptions
|
|
extends LocalizedOptions<"formatDistance"> {
|
|
/** The array of units to format */
|
|
format?: DurationUnit[];
|
|
/** Should be zeros be included in the output? */
|
|
zero?: boolean;
|
|
/** The delimiter string to use */
|
|
delimiter?: string;
|
|
}
|
|
/**
|
|
* @name formatDuration
|
|
* @category Common Helpers
|
|
* @summary Formats a duration in human-readable format
|
|
*
|
|
* @description
|
|
* Return human-readable duration string i.e. "9 months 2 days"
|
|
*
|
|
* @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
|
|
*
|
|
* @param duration - The duration to format
|
|
* @param options - An object with options.
|
|
*
|
|
* @returns The formatted date string
|
|
*
|
|
* @example
|
|
* // Format full duration
|
|
* formatDuration({
|
|
* years: 2,
|
|
* months: 9,
|
|
* weeks: 1,
|
|
* days: 7,
|
|
* hours: 5,
|
|
* minutes: 9,
|
|
* seconds: 30
|
|
* })
|
|
* //=> '2 years 9 months 1 week 7 days 5 hours 9 minutes 30 seconds'
|
|
*
|
|
* @example
|
|
* // Format partial duration
|
|
* formatDuration({ months: 9, days: 2 })
|
|
* //=> '9 months 2 days'
|
|
*
|
|
* @example
|
|
* // Customize the format
|
|
* formatDuration(
|
|
* {
|
|
* years: 2,
|
|
* months: 9,
|
|
* weeks: 1,
|
|
* days: 7,
|
|
* hours: 5,
|
|
* minutes: 9,
|
|
* seconds: 30
|
|
* },
|
|
* { format: ['months', 'weeks'] }
|
|
* ) === '9 months 1 week'
|
|
*
|
|
* @example
|
|
* // Customize the zeros presence
|
|
* formatDuration({ years: 0, months: 9 })
|
|
* //=> '9 months'
|
|
* formatDuration({ years: 0, months: 9 }, { zero: true })
|
|
* //=> '0 years 9 months'
|
|
*
|
|
* @example
|
|
* // Customize the delimiter
|
|
* formatDuration({ years: 2, months: 9, weeks: 3 }, { delimiter: ', ' })
|
|
* //=> '2 years, 9 months, 3 weeks'
|
|
*/
|
|
export declare function formatDuration(
|
|
duration: Duration,
|
|
options?: FormatDurationOptions,
|
|
): string;
|