timepiece/node_modules/date-fns/formatDuration.d.mts

78 lines
2.0 KiB
TypeScript
Raw Normal View History

2024-05-14 14:54:12 +00:00
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;