date-time-format-icu-package

A lightweight and flexible JavaScript utility to format dates using ICU date-time format tokens and standard preset styles. Ideal for any JavaScript/TypeScript project that requires locale-aware and timezone-aware date formatting.

✨ Features

• ✅ Supports all ICU date-time format tokens
• ✅ Includes common preset styles (short, medium, long, full)
• ✅ Locale-aware formatting
• ✅ Timezone support
• ✅ Handles null/undefined inputs gracefully
• ✅ Fully typed with TypeScript

📦 Installation

npm install date-time-format-icu

or with yarn:

yarn add date-time-format-icu

Built-in Presets (DateFormat Enum)

You can use the DateFormat enum for common date and time format presets:

Custom Formats

The formatter supports a subset of ICU/Angular-style date tokens:

Function: dateFormatter

The core utility function of this package is:

dateFormatter(
  input: Date | string | number,
  format?: keyof typeof DateFormat | string,
  locale?: string
): string

Parameters

Usage & Examples

// Import
 import { dateFormatter } from 'date-time-format-icu';

// Basic Example
const formatted = dateFormatter(new Date(), 'medium');
console.log(formatted); // e.g., "May 29, 2025, 2:15:30 PM"

// With Custom Format
const custom = dateFormatter(new Date(), 'dd/MM/yy');
console.log(custom); // e.g., "29/05/25"

// With Custom Locale
const french = dateFormatter(new Date(), 'fullDate', 'fr-FR');
console.log(french); // e.g., "jeudi 29 mai 2025"

// Example Scenarios

dateFormatter('2025-12-25T10:00:00', 'fullDate');
// Output: "Thursday, December 25, 2025";

dateFormatter(1735123200000, 'MMM d, y');
// Output: "Dec 25, 2025"

dateFormatter('invalid-date', 'medium');
// Output: "Invalid Date"

Notes

• Falls back to date.toISOString() if format parsing fails.
• Supports only tokens explicitly mapped to Intl.DateTimeFormatOptions.
• Ideal for lightweight date formatting without pulling in larger libraries like date-fns or moment.