timeago

A lightweight Gleam library for formatting timestamps as human-readable relative time strings (e.g., ‘5 minutes ago’, ‘in 2 hours’) with support for multiple locales.

Installation

gleam add timeago@2

Usage

Basic Usage

import gleam/time/duration
import gleam/time/timestamp
import timeago

pub fn main() {
  let past = timestamp.add(timestamp.system_time(), duration.minutes(-5))

  timeago.new()
  |> timeago.format(past)
  // -> "5 minutes ago"
}

Custom Reference Time

import gleam/time/timestamp
import timeago

pub fn main() {
  let assert Ok(reference) = timestamp.parse_rfc3339("2024-01-01T12:00:00Z")
  let assert Ok(past) = timestamp.parse_rfc3339("2024-01-01T11:00:00Z")

  timeago.new()
  |> timeago.with_now(reference)
  |> timeago.format(past)
  // -> "1 hour ago"
}

Localization

The library includes built-in support for multiple languages:

import gleam/time/duration
import gleam/time/timestamp
import timeago

pub fn main() {
  let past = timestamp.add(timestamp.system_time(), duration.hours(-2))

  // English (US) - default
  timeago.new()
  |> timeago.format(past)
  // -> "2 hours ago"

  // French
  timeago.new()
  |> timeago.with_locale(timeago.fr)
  |> timeago.format(past)
  // -> "il y a 2 heures"
}

Time Unit Selection

The library automatically selects appropriate time units based on the magnitude of the difference:

import gleam/time/duration
import gleam/time/timestamp
import timeago

pub fn main() {
  let now = timestamp.system_time()
  let formatter = timeago.new()

  // Sub-second durations
  formatter |> timeago.format(timestamp.add(now, duration.milliseconds(-500)))
  // -> "just now"

  // Seconds to years
  formatter |> timeago.format(timestamp.add(now, duration.seconds(-45)))
  // -> "45 seconds ago"

  formatter |> timeago.format(timestamp.add(now, duration.days(-3)))
  // -> "3 days ago"

  formatter |> timeago.format(timestamp.add(now, duration.days(365)))
  // -> "in 1 year"
}

Further documentation can be found at https://hexdocs.pm/timeago.

Development

gleam run   # Run the project
gleam test  # Run the tests