# Date helpers — `formatTime`, `formatDateOnly`

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

## Purpose

`formatTime` and `formatDateOnly` pre-bind `formatDate` with the
appropriate preset for time-only or date-only rendering. They exist
because the most common UI patterns ("show just the time", "show just
the date") shouldn't require the caller to remember the preset
discriminant string.

## Features

- `formatTime(date, locale, long?)` — pre-binds `time-short` (`long === false`) or `time-long` (`long === true`)
- `formatDateOnly(date, locale, long?)` — pre-binds `date-short` (`long === false`) or `date-long` (`long === true`)
- Both default `long` to `false`
- Both go through the cached `formatDate` path — every advantage of the per-(locale, options-hash) cache and OTel emission applies

## Usage: Basic Example

```ts
import {
    formatDateOnly,
    formatTime,
} from "@suaveplan/i18n-formatter-date";

const now = new Date(2026, 0, 1, 14, 30, 45);

formatTime(now, "en-GB"); // "14:30"
formatTime(now, "en-GB", true); // "14:30:45"

formatDateOnly(now, "en-GB"); // "01/01/2026"
formatDateOnly(now, "en-GB", true); // "1 January 2026"
```

## Usage: Advanced Example

```ts
import {
    formatDateOnly,
    formatTime,
} from "@suaveplan/i18n-formatter-date";

// Render a chat message timestamp — short form by default,
// long form on hover/expand.
function renderTimestamp(d: Date, locale: string, expanded: boolean) {
    const date = formatDateOnly(d, locale, expanded);
    const time = formatTime(d, locale, expanded);
    return expanded ? `${date} at ${time}` : `${date} ${time}`;
}

renderTimestamp(new Date(2026, 5, 15, 9, 5), "en-GB", false);
// "15/06/2026 09:05"

renderTimestamp(new Date(2026, 5, 15, 9, 5, 30), "en-GB", true);
// "15 June 2026 at 09:05:30"
```

## API Reference

### `formatTime(date, locale, long?): string`

Pre-binds `formatDate` with `preset: long ? "time-long" : "time-short"`.

- `date` — a `Date` instance.
- `locale` — BCP-47 locale tag.
- `long` — when `true`, includes seconds.

Throws every error class `formatDate` throws.

### `formatDateOnly(date, locale, long?): string`

Pre-binds `formatDate` with `preset: long ? "date-long" : "date-short"`.

- `date` — a `Date` instance.
- `locale` — BCP-47 locale tag.
- `long` — when `true`, uses the long month name (e.g. "January"
  instead of "01").

Throws every error class `formatDate` throws.

## Implementation Notes

- Both helpers are one-line wrappers around `formatDate`. The
  per-(locale, options-hash) cache shared with `formatDate` and
  `formatDateRange` covers them automatically.
- Default of `long = false` matches the monolith behaviour to
  minimise behavioural drift during the modular split.