short-time-ago/dist/index.d.ts

A small, no dependencies, Typescript utility to describe time differences in a human readable format (for example, '1 minute ago')

/**
 * This package exports a single function, {@link timeAgo},
 * which describes the time elapsed between a given date and the current date
 * in a human readable format (for example, `10 minutes ago`, `in 3 seconds`).
 *
 * @packageDocumentation
 */
/**
 * `timeAgo` returns a string describing the time elapsed between
 * a given date and the current time at which the function is called.
 *
 * @remarks
 * `timeAgo` only supports the `en_US` locale.
 *
 * The following table describes `timeAgo`'s output.
 *
 * ```
 * | Time elapsed          | Past output       | Future output    |
 * | --------------------- | ----------------- | ---------------- |
 * | < 1 second            | `just now`        | `just now`       |
 * | < 1 minute            | `N second(s) ago` | `in N second(s)` |
 * | < 1 hour              | `N minute(s) ago` | `in N minute(s)` |
 * | < 1 day               | `N hour(s) ago`   | `in N hour(s)`   |
 * | < 1 month (30.5 days) | `N day(s) ago`    | `in N day(s)`    |
 * | < 1 year (365 days)   | `N month(s) ago`  | `in N month(s)`  |
 * | > 1 year              | `N year(s) ago`   | `in N year(s)`   |
 * ```
 *
 * @example
 * Basic usage:
 *
 * ```typescript
 * import { timeAgo } from 'short-time-ago';
 *
 * const myDate = new Date();
 * const description = timeAgo(myDate);
 *
 * // Output: `just now`.
 * console.log(description);
 * ```
 *
 * @example
 * Specifying a custom current date with the `now` parameter:
 *
 * ```typescript
 * import { timeAgo } from 'short-time-ago';
 *
 * const myDate = new Date('2019-01-01T00:00:00.000Z');
 * const now = new Date('2019-01-01T00:01:00.000Z');
 * const description = timeAgo(myDate, now);
 *
 * // Output: `1 minute ago`.
 * console.log(description);
 * ```
 *
 * ```typescript
 * import { timeAgo } from 'short-time-ago';
 *
 * const myDate = new Date('2019-01-02T00:00:00.000Z');
 * const now = new Date('2019-01-01T00:00:00.000Z');
 * const description = timeAgo(myDate, now);
 *
 * // Output: `in 1 day`.
 * console.log(description);
 * ```
 *
 * @param date - a {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date | Date}
 * @param now - the current date (optional, defaults to `new Date()`)
 */
declare function timeAgo(date: Date, now?: Date): string;

export { timeAgo };