Skip to content
helpers4helpers4

timeAgo

Formats a date as a human-readable relative time string.

Uses Intl.RelativeTimeFormat under the hood, making the output locale-aware (e.g. “il y a 3 jours” in French).

Returns null if the input date is invalid.

Available since v2.0.0

Import

Section titled “Import”
import { timeAgo } from '@helpers4/date';

Signature

Section titled “Signature”
timeAgo(date: DateLike, options: TimeAgoOptions): string | null

Parameters

Section titled “Parameters”
ParameterTypeDescription
dateDateLikeThe date to describe relative to now
optionsTimeAgoOptionsOptional configuration (reference date, locale, numeric style)

Returns

Section titled “Returns”

string | null — A locale-aware relative time string, or null

Examples

Section titled “Examples”

timeAgo

Section titled “timeAgo”
timeAgo('2025-01-17T00:00:00Z', { now: '2025-01-19T00:00:00Z' })
// => "2 days ago"

timeAgo('2025-01-20T00:00:00Z', { now: '2025-01-19T00:00:00Z' })
// => "in 1 day"  (or "tomorrow" with numeric: 'auto')

timeAgo('2025-01-19T00:00:00Z', { now: '2025-01-19T00:00:05Z' })
// => "5 seconds ago"
Section titled “Related Types”

TimeAgoOptions

Section titled “TimeAgoOptions”

Options for timeAgo.

interface TimeAgoOptions {
  locale?: string;
  now?: DateLike;
  numeric?: "always" | "auto";
}

DateLike

Section titled “DateLike”

A value that can be converted to a Date.

  • Date — used as-is (validated for Invalid Date)
  • number — treated as a timestamp (seconds or milliseconds, auto-detected); 0 is treated as invalid and produces null in ensureDate
  • string — parsed via new Date(string)
  • Temporal.Instant | Temporal.ZonedDateTime — read via their epochMilliseconds property
type DateLike = Date | number | string | Temporal.Instant | Temporal.ZonedDateTime

Source

Section titled “Source”

View source on GitHub