skills/docs/localization/i18n/i18n-formatter-relative-time/src/helpers/helpers.md

Relative-Time Helper Formatters

(no submodules)

Purpose

Pre-bound shortcuts over formatRelativeTime for the two most common relative-time shapes in product UIs: past-tense ("5 minutes ago") and future-tense ("in 5 minutes"). These are net-new ergonomic helpers introduced by the Wave-3 split — the monolith's formatting/relative-time/ ships only the class and standalone, while every other Wave-3 formatter carries a sibling helper module.

The helpers route every call through formatRelativeTime, so they inherit Zod option validation, the per-(locale, style, numeric) cache, and the OTel histogram + cache-hit counter. selectRelativeUnit is re-exported from the helpers subpath so callers that import only @suaveplan/i18n-formatter-relative-time/helpers for tree-shaking still get the auto-unit-selection function.

Features

• formatTimeAgo(ageMs, locale, options?) — past-tense shortcut that negates internally so callers never have to remember the past = negative convention
• formatTimeIn(intervalMs, locale, options?) — future-tense shortcut that abs-es internally
• formatRelativeTimeStyled(deltaMs, locale, style) — style-only override without an options bag
• selectRelativeUnit(deltaMs) — re-export of the auto-unit-selection helper

Usage: Basic Example

import {
    formatRelativeTimeStyled,
    formatTimeAgo,
    formatTimeIn,
    selectRelativeUnit,
} from "@suaveplan/i18n-formatter-relative-time/helpers";

formatTimeAgo(3_600_000, "en-US"); // → "1 hour ago"
formatTimeIn(60_000, "en-US");     // → "in 1 minute"
formatRelativeTimeStyled(86_400_000, "en-US", "short"); // → "in 1 day"
selectRelativeUnit(90_000);        // → { unit: "minutes", value: 2 }

Usage: Advanced Example — Activity feed timestamps

import { formatTimeAgo } from "@suaveplan/i18n-formatter-relative-time/helpers";

function renderActivity(events, locale) {
    return events.map((event) => ({
        title: event.title,
        when: formatTimeAgo(Date.now() - event.timestamp, locale, {
            style: "short",
        }),
    }));
}

API Reference

formatTimeAgo(ageMs, locale, options?)

Pre-bound shortcut for past-tense relative-time strings. Accepts an absolute (non-negative) age in milliseconds and renders it as "5 seconds ago", "1 hour ago", etc. Negates the input internally so callers never have to remember the past = negative convention of Intl.RelativeTimeFormat.

formatTimeIn(intervalMs, locale, options?)

Pre-bound shortcut for future-tense relative-time strings. Accepts a non-negative interval in milliseconds and renders it as "in 5 seconds", "in 1 hour", etc.

formatRelativeTimeStyled(deltaMs, locale, style)

Re-binds the style argument so the caller can skip the options bag for a one-shot style override. Accepts the original signed-delta convention (positive = future, negative = past).

selectRelativeUnit(deltaMs)

Re-export of the formatter's auto-unit-selection helper. Returns { unit, value } so callers can inspect the chosen unit without rendering through Intl.RelativeTimeFormat.

Implementation Notes

formatTimeAgo uses Math.abs(ageMs) and negates the result before passing to formatRelativeTime so callers can pass either a positive duration or the natural Date.now() - eventTime form (which can be either sign depending on clock skew) without surprises. The same pattern in formatTimeIn ensures the future-tense helper always renders future-tense output even if the caller accidentally supplies a negative value.

formatRelativeTimeStyled is intentionally kept as a separate function rather than a default-arg overload of formatRelativeTime because the latter would change the standalone helper's call signature, breaking the formatBridge design contract that the slim core wires up in Wave 6.