format-datetime

A robust, lightweight utility to format dates and times into localized strings using native JavaScript APIs. It supports custom date/time patterns, localized digits (e.g., Khmer numerals), and time-of-day phrases.

Features

• 📅 Flexible Formatting: Format dates exactly how you want using familiar tokens (YYYY, MMMM, hh, A, etc.).
• 🌍 Localization (i18n): Fully supports BCP 47 locale tags (e.g., en-US, km-KH, fr-FR).
• 🇰🇭 Khmer Support: Built-in support for Khmer (km-KH) localized digits (e.g., ២០២៦) and time-of-day phrases (e.g., ព្រឹក, រសៀល).
• 🌙 Lunar Calendar: Full support for Khmer lunar dates, Buddhist era (BE), and animal years.
• ⚡ Zero Dependencies: Pure native JavaScript (Intl.DateTimeFormat, Date).
• 📦 Multi-Runtime: Works flawlessly in Node.js, Bun, Deno (via JSR), Cloudflare Workers (Edge), and the Browser.

Installation

Node.js / Bun / Cloudflare Workers

npm install @pphatdev/format-datetime
# or
bun add @pphatdev/format-datetime

Deno (JSR)

deno add @pphatdev/format-datetime

Browser (CDN)

You can include it directly in your HTML using UNPKG:

<script src="https://unpkg.com/@pphatdev/format-datetime"></script>
<script>
  const dt = new FormatDateTime(new Date(), "DDDD, MMMM d, YYYY", "km-KH");
  console.log(dt.formatDate()); 
</script>

Usage

Basic Example

import FormatDateTime from '@pphatdev/format-datetime';

// 1. Initialize with Date, format string, and locale
const dt = new FormatDateTime(new Date(), "DDDD, MMMM d, YYYY, hh:mm:ss A", "km-KH");

// 2. Format the date
console.log(dt.formatDate()); 
// Output: "ចន្ទ, កក្កដា ១៣, ២០២៦, ០១:៣០:៤៥ រសៀល"

Khmer Lunar Date Example

import { KhmerDate } from '@pphatdev/format-datetime';

const date = new Date(2026, 6, 13); // July 13, 2026
const kd = new KhmerDate(date);

// Built-in presets
console.log(kd.toLunarDate('full')); 
// Output: "ថ្ងៃចន្ទ ១៣រោច ខែបឋមាសាឍ ឆ្នាំមមី អដ្ឋស័ក ពុទ្ធសករាជ ២៥៧០"

console.log(kd.toLunarDate('short')); 
// Output: "១៣រោច ខែបឋមាសាឍ"

// Custom Format Tokens
console.log(kd.toLunarDate('lW ldd lN lM')); 
// Output: "ចន្ទ ១៣ រោច បឋមាសាឍ"

Available Tokens

| Token | Description | Example (en-US) | Example (km-KH) | | --- | --- | --- | --- | | YYYY / yyyy | 4-digit year | 2026 | ២០២៦ | | YY / yy | 2-digit year | 26 | ២៦ | | MMMM | Full month name | July | កក្កដា | | MMM | Short month name | Jul | កក្កដា | | MM | 2-digit month | 07 | ០៧ | | M | Month number | 7 | ៧ | | DDDD | Full day name | Monday | ចន្ទ | | DDD | Short day name | Mon | ចន្ទ | | dd | 2-digit day of month | 13 | ១៣ | | d | Day of month | 13 | ១៣ | | HH | 24-hour time (2 digits) | 14 | ១៤ | | H | 24-hour time | 14 | ១៤ | | hh | 12-hour time (2 digits) | 02 | ០២ | | h | 12-hour time | 2 | ២ | | mm | Minutes (2 digits) | 30 | ៣០ | | m | Minutes | 30 | ៣០ | | ss | Seconds (2 digits) | 45 | ៤៥ | | s | Seconds | 45 | ៤៥ | | A | Uppercase AM/PM | PM | រសៀល | | a | Lowercase AM/PM | pm | រសៀល | | ZZ | ISO 8601 offset (w/ sec) | +07:00:00 | +07:00:00 | | Z | ISO 8601 offset | +07:00 | +07:00 |

Lunar Date Tokens (Khmer)

| Token | Description | Example | | --- | --- | --- | | BBBB | Buddhist Era Year | ២៥៧០ | | JJJJ | Jolak Sakaraj Year | ១៣៨៨ | | lA | Animal Year | មមី | | lE | Era Year / Sak | អដ្ឋស័ក | | lM | Lunar Month | បឋមាសាឍ | | ldd | Lunar Day count (2 digits) | ១៣ | | ld | Lunar Day count | ១៣ | | lN | Moon Status | រោច / កើត | | ln | Moon Status (Short) | រ / ក | | lW | Day of Week (Khmer) | ចន្ទ | | lw | Day of Week (Short) | ច |

API Reference

new FormatDateTime(date?, format?, locale?)

• date (string | Date | null): The date to format. Can be a string (e.g., "2026-07-13"), a Date object, or null/undefined (defaults to the current date and time).
• format (string | null): The format string containing tokens. Defaults to "dd-MM-yyyy hh:mm:ss".
• locale (string): The BCP 47 locale tag. Defaults to "en-US".

dt.formatDate(): string

Processes the date and applies the formatting pattern with localized strings.

dt.formatLunarDate(format?)

Shorthand to format the date using the lunar calendar without explicitly instantiating KhmerDate.

• format (string): The lunar format pattern or preset ("full", "medium", "short", etc). Defaults to "full".

dt.toString()

Implicitly calls dt.formatDate() when the object is cast to a string.

new KhmerDate(date)

• date (Date): The date to convert into a Khmer Lunar Date.

kd.toLunarDate(format?)

• format (string): The format string containing lunar tokens, or a preset ("full", "medium", "short"). Defaults to "full".

kd.khDay(): number

Returns the lunar day number.

kd.khMonth(): number

Returns the lunar month index.

kd.khYear(): number

Returns the Buddhist Era (BE) year.

kd.toKhmerDate(format?)

Formats the standard solar date in Khmer language.

• format (string): Defaults to "ទី{day} ខែ{month} ឆ្នាំ{year}".

Static Helpers on KhmerDate

• KhmerDate.getKhmerMonthNames(): Returns an array of Khmer lunar month names.
• KhmerDate.getAnimalYearNames(): Returns an array of animal years (e.g., ជូត, ឆ្លូវ).
• KhmerDate.getEraYearNames(): Returns an array of era years (e.g., ឯកស័ក, ទោស័ក).
• KhmerDate.arabicToKhmerNumber(numberString): Converts an Arabic number string to a Khmer number string (e.g. "123" to "១២៣").
• KhmerDate.khmerToArabicNumber(khmerNumberString): Converts a Khmer number string to an Arabic number string.

License

MIT © PPhat [email protected]