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