@risadams/time-since/dist/time-since.d.ts

A robust, type-safe utility for calculating and formatting time differences. Supports multiple formats (relative, absolute, or individual time units) with internationalization support and accurate handling of future dates, leap years, and timezone differe

/**
 * @file time-since.ts
 * @description A utility for calculating elapsed time between dates in various formats
 * @author Ris Adams <ris@risadams.com>
 * @copyright 2025
 * @license MIT
 */
/**
 * Options for customizing the timeSince function output.
 *
 * @interface TimeSinceOptions
 * @property {string} [format='object'] - The format of the returned value
 * @property {string} [locale='en'] - The locale to use for relative formatting
 */
interface TimeSinceOptions {
    /**
     * The format of the returned value.
     *
     * @default 'object'
     * @type {'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years' | 'relative' | 'object'}
     * @description
     * - 'milliseconds': Returns the elapsed time in milliseconds
     * - 'seconds': Returns the elapsed time in seconds
     * - 'minutes': Returns the elapsed time in minutes
     * - 'hours': Returns the elapsed time in hours
     * - 'days': Returns the elapsed time in days
     * - 'months': Returns the elapsed time in months (approximate)
     * - 'years': Returns the elapsed time in years
     * - 'relative': Returns a human-readable string like "2 days ago" using Intl.RelativeTimeFormat
     * - 'object': Returns a detailed breakdown of all time components
     */
    format?: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years' | 'relative' | 'object';
    /**
     * The locale to use for relative formatting.
     *
     * @default 'en'
     * @type {string}
     * @description BCP 47 language tag (e.g., 'en-US', 'fr', 'de', 'ja')
     * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat}
     */
    locale?: string;
}
/**
 * Interface for the result object when using the default 'object' format.
 * Contains a detailed breakdown of the elapsed time in various units.
 *
 * @interface TimeSinceResult
 * @property {Date} date - The original date used for calculation
 * @property {Date} asOf - The current date/time when the calculation was performed
 * @property {number} years - Number of full years elapsed
 * @property {number} months - Number of months beyond full years (0-11)
 * @property {number} days - Number of days beyond full months (0-29)
 * @property {number} hours - Number of hours beyond full days (0-23)
 * @property {number} minutes - Number of minutes beyond full hours (0-59)
 * @property {number} seconds - Number of seconds beyond full minutes (0-59)
 * @property {number} milliseconds - Number of milliseconds beyond full seconds (0-999)
 */
interface TimeSinceResult {
    /** The original date used for calculation */
    date: Date;
    /** The current date/time when the calculation was performed */
    asOf: Date;
    /** Number of full years elapsed */
    years: number;
    /** Number of months beyond full years (0-11) */
    months: number;
    /** Number of days beyond full months (0-29) */
    days: number;
    /** Number of hours beyond full days (0-23) */
    hours: number;
    /** Number of minutes beyond full hours (0-59) */
    minutes: number;
    /** Number of seconds beyond full minutes (0-59) */
    seconds: number;
    /** Number of milliseconds beyond full seconds (0-999) */
    milliseconds: number;
}
/**
 * Calculates the time elapsed since a given date and returns it in various formats.
 *
 * This function computes the difference between the provided date and the current date/time,
 * then returns the result in the format specified in the options.
 *
 * Utilizes native JavaScript Date and Intl.RelativeTimeFormat for date difference calculations.
 *
 * @since 1.0.0
 * @param {Date | string} date - The starting date from which to calculate the elapsed time.
 *                               Can be a JavaScript Date object or a string that can be parsed into a date.
 * @param {TimeSinceOptions} [options={}] - Options to customize the output format.
 * @returns {TimeSinceResult | number | string} An object containing the original date, the date as of the calculation,
 *          or the elapsed time in a specified format.
 * @throws {Error} If the provided date is invalid.
 *
 * @example
 * // Get the default object result with time components
 * const breakdown = timeSince('2020-01-01');
 * console.log(breakdown);
 * // Output: { date: Date, asOf: Date, years: 5, months: 4, ... }
 *
 * @example
 * // Get elapsed time in specific units
 * const days = timeSince('2020-01-01', { format: 'days' });
 * console.log(days);
 * // Output: 1947 (days since 2020-01-01 as of May 1, 2025)
 *
 * @example
 * // Get human-readable relative time string
 * const relative = timeSince('2020-01-01', { format: 'relative', locale: 'fr' });
 * console.log(relative);
 * // Output: "il y a 5 ans" (French for "5 years ago")
 */
export declare function timeSince(date: Date | string, options?: TimeSinceOptions): TimeSinceResult | number | string;
export {};