suaveplan/packages/localization/i18n/i18n-formatter-date/src/helpers/helpers.md

Date helpers — formatTime, formatDateOnly

(no submodules)

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

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

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.