Packages

timeago

2.0.0
2.5.0 2.4.0 2.3.0 2.2.0 2.1.0 2.0.0 1.1.0 1.0.0

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.

HexDocs

Current section

8 Versions

Jump to
Readme
8 Versions
2 Dependencies
Dependants
Files
Activity
Hide whitespace

Compare versions

7 files changed
+720 additions
-138 deletions
  @@ -3,30 +3,100 @@
3 3 [![Package Version](https://img.shields.io/hexpm/v/timeago)](https://hex.pm/packages/timeago)
4 4 [![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/timeago/)
5 5
6 + A localized library for formatting timestamps as human-readable relative time strings.
7 +
8 + ## Installation
9 +
6 10 ```sh
7 - gleam add timeago@1
11 + gleam add timeago@2
8 12 ```
13 +
14 + ## Usage
15 +
16 + ### Basic Usage
17 +
9 18 ```gleam
10 - import timeago
11 - import gleam/time/timestamp
12 19 import gleam/time/duration
20 + import gleam/time/timestamp
21 + import timeago
13 22
14 - pub fn main() -> Nil {
23 + pub fn main() {
24 + let past = timestamp.add(timestamp.system_time(), duration.minutes(-5))
25 +
26 + timeago.new()
27 + |> timeago.format(past)
28 + // -> "5 minutes ago"
29 + }
30 + ```
31 +
32 + ### Custom Reference Time
33 +
34 + ```gleam
35 + import gleam/time/timestamp
36 + import timeago
37 +
38 + pub fn main() {
39 + let assert Ok(reference) = timestamp.parse_rfc3339("2024-01-01T12:00:00Z")
40 + let assert Ok(past) = timestamp.parse_rfc3339("2024-01-01T11:00:00Z")
41 +
42 + timeago.new()
43 + |> timeago.with_now(reference)
44 + |> timeago.format(past)
45 + // -> "1 hour ago"
46 + }
47 + ```
48 +
49 + ### Localization
50 +
51 + The library includes built-in support for multiple languages:
52 +
53 + ```gleam
54 + import gleam/time/duration
55 + import gleam/time/timestamp
56 + import timeago
57 +
58 + pub fn main() {
59 + let past = timestamp.add(timestamp.system_time(), duration.hours(-2))
60 +
61 + // English (US) - default
62 + timeago.new()
63 + |> timeago.format(past)
64 + // -> "2 hours ago"
65 +
66 + // French
67 + timeago.new()
68 + |> timeago.with_locale(timeago.fr)
69 + |> timeago.format(past)
70 + // -> "il y a 2 heures"
71 + }
72 + ```
73 +
74 + ### Time Unit Selection
75 +
76 + The library automatically selects appropriate time units based on the magnitude of the difference:
77 +
78 + ```gleam
79 + import gleam/time/duration
80 + import gleam/time/timestamp
81 + import timeago
82 +
83 + pub fn main() {
15 84 let now = timestamp.system_time()
16 - timeago.time_ago(now, None, None)
17 - // -> "just now"
18 -
19 - let now = timestamp.system_time()
20 - timeago.time_ago(timestamp.add(now, duration.minutes(-1)), None, None)
21 - // -> "1 minute ago"
22 -
23 - let now = timestamp.system_time()
24 - timeago.time_ago(timestamp.add(now, duration.hours(3)), None, None)
25 - // -> "in 3 hours"
26 -
27 - let now = timestamp.system_time()
28 - timeago.time_ago(timestamp.add(now, duration.hours(3)), timestamp.add(now, duration.hours(3)), None)
85 + let formatter = timeago.new()
86 +
87 + // Sub-second durations
88 + formatter |> timeago.format(timestamp.add(now, duration.milliseconds(-500)))
29 89 // -> "just now"
90 +
91 + // Seconds to years
92 + formatter |> timeago.format(timestamp.add(now, duration.seconds(-45)))
93 + // -> "45 seconds ago"
94 +
95 + formatter |> timeago.format(timestamp.add(now, duration.days(-3)))
96 + // -> "3 days ago"
97 +
98 + formatter |> timeago.format(timestamp.add(now, duration.days(365)))
99 + // -> "in 1 year"
30 100 }
31 101 ```
32 102
  @@ -37,4 +107,4 @@ Further documentation can be found at <https://hexdocs.pm/timeago>.
37 107 ```sh
38 108 gleam run # Run the project
39 109 gleam test # Run the tests
40 - ```
110 + ```
\ No newline at end of file
  @@ -1,5 +1,5 @@
1 1 name = "timeago"
2 - version = "1.1.0"
2 + version = "2.0.0"
3 3
4 4 # Fill out these fields if you intend to generate HTML documentation or publish
5 5 # your project to the Hex package manager.
  @@ -1,6 +1,6 @@
1 1 {<<"name">>, <<"timeago">>}.
2 2 {<<"app">>, <<"timeago">>}.
3 - {<<"version">>, <<"1.1.0">>}.
3 + {<<"version">>, <<"2.0.0">>}.
4 4 {<<"description">>, <<"A lightweight library for describing time differences in a human readable format (e.g., '1 minute ago')."/utf8>>}.
5 5 {<<"licenses">>, [<<"Apache-2.0">>]}.
6 6 {<<"build_tools">>, [<<"gleam">>]}.
  @@ -8,21 +8,22 @@
8 8 {<<"Repository">>, <<"https://github.com/ayoung19/timeago">>}
9 9 ]}.
10 10 {<<"requirements">>, [
11 - {<<"gleam_stdlib">>, [
12 - {<<"app">>, <<"gleam_stdlib">>},
13 - {<<"optional">>, false},
14 - {<<"requirement">>, <<">= 0.44.0 and < 2.0.0">>}
15 - ]},
16 11 {<<"gleam_time">>, [
17 12 {<<"app">>, <<"gleam_time">>},
18 13 {<<"optional">>, false},
19 14 {<<"requirement">>, <<">= 1.3.0 and < 2.0.0">>}
15 + ]},
16 + {<<"gleam_stdlib">>, [
17 + {<<"app">>, <<"gleam_stdlib">>},
18 + {<<"optional">>, false},
19 + {<<"requirement">>, <<">= 0.44.0 and < 2.0.0">>}
20 20 ]}
21 21 ]}.
22 22 {<<"files">>, [
23 23 <<"LICENSE">>,
24 24 <<"README.md">>,
25 25 <<"gleam.toml">>,
26 + <<"include/timeago_TimeAgo.hrl">>,
26 27 <<"src/timeago.app.src">>,
27 28 <<"src/timeago.erl">>,
28 29 <<"src/timeago.gleam">>
  @@ -0,0 +1,4 @@
1 + -record(time_ago, {
2 + now :: gleam@time@timestamp:timestamp(),
3 + locale :: fun((timeago:tense(), gleam@time@duration:unit(), integer()) -> binary())
4 + }).
  @@ -1,5 +1,5 @@
1 1 {application, timeago, [
2 - {vsn, "1.1.0"},
2 + {vsn, "2.0.0"},
3 3 {applications, [gleam_stdlib,
4 4 gleam_time]},
5 5 {description, "A lightweight library for describing time differences in a human readable format (e.g., '1 minute ago')."},
Loading more files…