# Relative-Time Helper Formatters

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## 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

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

```typescript
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.