# timeago

[![Package Version](https://img.shields.io/hexpm/v/timeago)](https://hex.pm/packages/timeago)
[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/timeago/)

A localized library for formatting timestamps as human-readable relative time strings.

## Installation

```sh
gleam add timeago@2
```

## Usage

### Basic Usage

```gleam
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

```gleam
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:

```gleam
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:

```gleam
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

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