date-vir/dist/formatting/relative-string.d.ts

Easy and explicit dates and times.

import { type PartialWithUndefined } from '@augment-vir/common';
import { AnyDuration, DurationUnitSelection } from '@date-vir/duration';
import { FullDate } from '../full-date/full-date-shape.js';
/**
 * Options for {@link toRelativeString}.
 *
 * @category Internal
 */
export type RelativeStringOptions = PartialWithUndefined<{
    /**
     * Set this to `true` to prevent the `'just now'` relative string from being used when the two
     * dates are very close.
     *
     * @default false // (`'just now'` is used)
     */
    blockJustNow: boolean;
    /**
     * Set this to `true` to only use the largest selected unit with a non-zero value. Otherwise,
     * the output string will contain all selected non-zero units.
     *
     * @default false
     */
    useOnlyLargestUnit: boolean;
    /**
     * The number of decimals to allow for each duration unit's value.
     *
     * @default 0
     */
    allowedDecimals: number;
    /**
     * Any values below this will trigger "just now".
     *
     * @default {
     *
     *         minutes: 1.5,
     *         seconds: 5,
     *         milliseconds: 500,
     * }
     */
    justNowThresholds: {
        minutes: number;
        seconds: number;
        milliseconds: number;
    };
}>;
/**
 * This function starts with a duration (either by being directly passed a duration or by diffing
 * two dates into a duration) and converts that duration into a relative string like "1 month ago"
 * or "in 1 month". Rounding is automatically set to 0 decimal points, but that can be changed.
 *
 * When extremely close to a `0` difference, the output string will be `'just now'`, which can be
 * disabled.
 *
 * @category Formatting
 * @example
 *
 * ```ts
 * import {toRelativeString, selectAllDurationUnits} from 'date-vir';
 *
 * toRelativeString({days: 1.6}, {days: true}); // `'in 2 days'`
 * toRelativeString({days: 1.6}, {days: true, hours: true}); // `'in 1 day, 14 hours'`
 * toRelativeString({seconds: 1}, selectAllDurationUnits); // `'just now'`
 * ```
 */
export declare function toRelativeString(datesOrDuration: Readonly<{
    start: Readonly<FullDate>;
    end: Readonly<FullDate>;
}> | Readonly<AnyDuration>, units: Readonly<DurationUnitSelection>, options?: Readonly<RelativeStringOptions>): string;