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.