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

Easy and explicit dates and times.

import { type PartialWithUndefined, type RequiredAndNotNull } from '@augment-vir/common';
import { type AnyDuration, type DurationUnitSelection, type LocaleOptions, type RoundOptions } from '@date-vir/duration';
import { type FullDate } from '../full-date/full-date-shape.js';
/**
 * Options for {@link toRelativeString}.
 *
 * @category Internal
 */
export type RelativeStringOptions = PartialWithUndefined<{
    /**
     * Set this to `true` to block a "just now" string to be used when the two dates are very close
     * or the duration is very small (or 0).
     *
     * @default false // (`'just now'` is used)
     * @see `RelativeStringOptions.justNowThresholds`
     */
    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;
    /**
     * Any values below this will trigger "just now".
     *
     * @default `defaultJustNowThresholds`
     * @see {@link defaultJustNowThresholds} .
     */
    justNowThresholds: AnyDuration;
    /**
     * The separator between each unit.
     *
     * @default ', '
     */
    sep: string;
    /**
     * By default, when `blockJustNow` is `true` and there is no duration to print (the diff is 0),
     * this will return the smallest selected unit set to 0 and use "0 <unit> ago". Set this
     * property to `true` to instead use "in 0 <unit>".
     *
     * @default false
     */
    useFutureWhenNothing: boolean;
    /**
     * If `true`, unit names are abbreviated.
     *
     * @default false
     */
    abbreviate: boolean;
    /**
     * Customize translations. If this is not provided, or any property is missing, the default
     * english phrases will be used.
     */
    i18n: Partial<{
        /** Creates past relative strings like "5 seconds ago". */
        timeAgo(
        /**
         * This will look like "5 seconds" or "1 year", translated to the configured locale (or
         * the user's current locale.
         */
        unitString: string): string;
        /** Creates future relative strings like "in 5 seconds". */
        timeIn(
        /**
         * This will look like "5 seconds" or "1 year", translated to the configured locale (or
         * the user's current locale.
         */
        unitString: string): string;
        /** The string to be used when "just now" is chosen. */
        justNow: string;
    }>;
}> & RequiredAndNotNull<RoundOptions> & LocaleOptions;
/**
 * Default value for `RelativeStringOptions.justNowThresholds`.
 *
 * @category Internal
 */
export declare const defaultJustNowThresholds: AnyDuration;
/**
 * 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'`
 * ```
 *
 * @throws If no units are selected
 */
export declare function toRelativeString(datesOrDuration: Readonly<{
    start: Readonly<FullDate>;
    end: Readonly<FullDate>;
}> | Readonly<AnyDuration>, 
/** The units to use in the relative string. */
units: Readonly<DurationUnitSelection>, options: Readonly<RelativeStringOptions>): string;