Add timestamp APIs, locale fix & dev playground#4
Conversation
Introduce timestamp-based time-ago helpers and developer tooling: add time_ago_timestamp and time_ago_timestamp_with_overrides (using gleam_time timestamps), plus a dev playground (dev/humanize_dev.gleam) demonstrating features with colored woof output. Bump package version to 1.1.0 and add gleam_time and woof dependencies (gleam.toml/manifest.toml). Fixes: correct list joining for multi-item lists (conjunction placement), ensure duration_precise(0) prints "0 seconds", and add ago_prefix to LocaleData to support languages where the "ago" word is a prefix; update built-in locales and related logic. Update README, CHANGELOG and tests to cover the new APIs and behavior changes.
There was a problem hiding this comment.
Pull request overview
Adds timestamp-based “time ago” APIs and improves locale/list/duration behavior, plus a developer playground for visually exercising the library.
Changes:
- Introduces
time_ago_timestamp/5andtime_ago_timestamp_with_overrides/6usinggleam_time/timestamp.Timestamp. - Extends locale data with
ago_prefix: Booland updates built-in locales + formatting logic accordingly. - Fixes list joining and
duration_precise(0)output; adds dev playground and updates dependencies/docs/tests.
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| test/humanize_test.gleam | Renames tests and adds coverage for the new timestamp APIs. |
| src/internals/locales.gleam | Updates raw locale tuple layout and built-in locales to include ago_prefix. |
| src/humanize.gleam | Implements timestamp APIs, ago_prefix logic, list-joining fixes, and duration_precise(0) behavior. |
| manifest.toml | Adds gleam_time and woof packages to the resolved manifest. |
| gleam.toml | Bumps version to 1.1.0; adds gleam_time dependency and woof dev-dependency. |
| dev/humanize_dev.gleam | Adds a gleam dev playground with woof-based colored output. |
| README.md | Documents timestamp APIs and notes dependency implications (needs follow-up for make_locale arity/docs). |
| CHANGELOG.md | Documents 1.1.0 additions/fixes (contains a misleading dependency statement). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| let resolved_conj = case conj != "" { | ||
| True -> conj | ||
| False -> | ||
| case oxford { | ||
| True -> ", and " | ||
| False -> " and " | ||
| } | ||
| } | ||
| case items { | ||
| [] -> "" | ||
| [a] -> a | ||
| [a, b] -> a <> conj <> b | ||
| _ -> { | ||
| let conj_full = case conj != "" { | ||
| True -> conj | ||
|
|
||
| False -> | ||
| case oxford { | ||
| True -> ", and " | ||
| False -> " and " | ||
| } | ||
| } | ||
| join_with_conj(items, conj_full) | ||
| } | ||
| [a, b] -> a <> resolved_conj <> b | ||
| _ -> join_with_conj(items, resolved_conj) |
There was a problem hiding this comment.
list_with_oxford/1 now calls list_locale(items, "", True), but list_locale/3 resolves an empty conjunction to ", and " even for 2-item lists. This produces output like "a, and b" for ["a", "b"], which is not correct (Oxford comma should only affect 3+ items). Consider resolving the default conjunction based on items length (e.g., use " and " for 2 items, and ", and " for 3+), or special-case the [a, b] branch when conj == "" and oxford == True.
| | `humanize.time_ago_unix_with_overrides/6` | Same as above but accepts runtime locale overrides | | ||
| | `humanize.time_ago_timestamp/5` | Like `time_ago_unix` but takes `gleam_time/timestamp.Timestamp` values | | ||
| | `humanize.time_ago_timestamp_with_overrides/6` | Timestamp version with locale overrides | | ||
| | `humanize.make_locale/6` | Construct a custom locale entry to pass as an override | |
There was a problem hiding this comment.
The Quick API table lists humanize.make_locale/6, but make_locale now takes an extra ago_prefix: Bool argument (arity is 7). Please update the arity shown here (and any related examples/signature blocks) so it matches the new public API.
| | `humanize.make_locale/6` | Construct a custom locale entry to pass as an override | | |
| | `humanize.make_locale/7` | Construct a custom locale entry to pass as an override | |
| // Basic lookup using built-in locales | ||
| humanize.time_ago_unix(1_620_000_000, 1_620_000_360, "en", False, 1) // "6 minutes ago" | ||
|
|
||
| // with gleam_time timestamps (requires adding `gleam_time` deps) |
There was a problem hiding this comment.
The note/example text implies consumers must “add gleam_time deps” to use time_ago_timestamp*, but this package now declares gleam_time as a normal dependency in gleam.toml, so downstream users will already get it when they depend on humanize. Consider rewording to avoid implying an extra step for users (or, if the intent is optional deps, move gleam_time behind a separate package/module).
| // with gleam_time timestamps (requires adding `gleam_time` deps) | |
| // with gleam_time timestamps |
| pub fn list_test() { | ||
| assert humanize.list(["a", "b"]) == "a and b" | ||
| assert humanize.list(["a", "b", "c"]) == "a, b and c" | ||
| assert humanize.list_locale(["a", "b", "c"], " e ", False) == "a, b e c" | ||
| assert humanize.list_with_oxford(["a", "b", "c"]) == "a, b, and c" | ||
| assert humanize.list_with_ampersand(["a", "b", "c"]) == "a, b & c" | ||
| } |
There was a problem hiding this comment.
List tests cover list/1 with 2 and 3 items, but there is no assertion for list_with_oxford/1 on a 2-item list. Given the conjunction/Oxford logic was changed, adding a regression test for ["a", "b"] would help prevent incorrect output like "a, and b".
| `time_ago_unix*` APIs remain dependency‑free for users who don't need | ||
| them. |
There was a problem hiding this comment.
This changelog entry says the classic time_ago_unix* APIs “remain dependency‑free”, but the package now includes gleam_time as a regular dependency in gleam.toml/manifest.toml. Consider rephrasing (e.g., “the Unix APIs remain available and do not require Timestamp values”) to avoid suggesting the package has no gleam_time dependency for those users.
| `time_ago_unix*` APIs remain dependency‑free for users who don't need | |
| them. | |
| `time_ago_unix*` APIs remain available and do not require `Timestamp` | |
| values for users who prefer Unix timestamps. |
Introduce timestamp-based time-ago helpers and developer tooling: add time_ago_timestamp and time_ago_timestamp_with_overrides (using gleam_time timestamps), plus a dev playground (dev/humanize_dev.gleam) demonstrating features with colored woof output. Bump package version to 1.1.0 and add gleam_time and woof dependencies (gleam.toml/manifest.toml). Fixes: correct list joining for multi-item lists (conjunction placement), ensure duration_precise(0) prints "0 seconds", and add ago_prefix to LocaleData to support languages where the "ago" word is a prefix; update built-in locales and related logic. Update README, CHANGELOG and tests to cover the new APIs and behavior changes.