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

``bash
npm install date-time-format-icu
`

or with yarn:

`bash
yarn add date-time-format-icu
`

Built-in Presets (DateFormat Enum)

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

Key	Pattern	Example Output
short	'M/d/yy, h:mm a'	5/29/25, 2:15 PM
medium	'MMM d, y, h:mm:ss a'	May 29, 2025, 2:15:30 PM
long	'MMMM d, y, h:mm:ss a z'	May 29, 2025, 2:15:30 PM GMT+5
full	'EEEE, MMMM d, y, h:mm:ss a zzzz'	Thursday, May 29, 2025, 2:15:30 PM Pakistan Standard Time
shortDate	'M/d/yy'	5/29/25
mediumDate	'MMM d, y'	May 29, 2025
longDate	'MMMM d, y'	May 29, 2025
fullDate	'EEEE, MMMM d, y'	Thursday, May 29, 2025
shortTime	'h:mm a'	2:15 PM
mediumTime	'h:mm:ss a'	2:15:30 PM
longTime	'h:mm:ss a z'	2:15:30 PM GMT+5
fullTime	'h:mm:ss a zzzz'	2:15:30 PM Pakistan Standard Time

Custom Formats

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

Token	Meaning	Example
y	Year (numeric)	2025
yy	Year (2-digit)	25
M	Month (numeric)	5
MM	Month (2-digit)	05
MMM	Month (short text)	May
MMMM	Month (full text)	May
d	Day (numeric)	9
dd	Day (2-digit)	09
EEE	Weekday (short)	Thu
EEEE	Weekday (long)	Thursday
h/hh	Hour (12-hour)	2 / 02
H/HH	Hour (24-hour)	14 / 14
m/mm	Minute	5 / 05
s/ss	Second	9 / 09
a	AM/PM	PM
z	Time zone (short)	GMT+5
zzzz	Time zone (long)	Pakistan Standard Time

Function: dateFormatter



The core utility function of this package is:

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

`

$3

Parameter	Type	Default	Description
input	Date | string | number	Required	The input date to format. Can be a Date object, ISO string ('2025-12-25T10:00:00'), or a timestamp (1735123200000).
format	keyof DateFormat | string	'medium'	A custom ICU/Angular-style format string (e.g. 'dd/MM/yy') or a key from the built-in DateFormat enum ('short', 'fullTime', etc.).
locale	string	'en-US'	Locale code to control localization of month names, day names, AM/PM, etc. Examples: 'en-US', 'fr-FR', 'ur-PK'.

Usage & Examples

`bash
// 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.