🇰🇭 MomentKH - Complete Khmer Calendar Library

MomentKH is a lightweight, zero-dependency JavaScript/TypeScript library for accurate Khmer (Cambodian) Lunar Calendar conversions. It provides a modern, standalone implementation with full TypeScript support.

🎮 Live Demo Playground

---

⚡ TLDR - Quick Start

// Import
const momentkh = require("@thyrith/momentkh");

// Convert date to Khmer format (default)
const khmer = momentkh.fromDate(new Date());
console.log(momentkh.format(khmer));
// Output: ថ្ងៃពុធ ១២រោច ខែមិគសិរ ឆ្នាំម្សាញ់ សប្តស័ក ពុទ្ធសករាជ ២៥៦៩

// Convert from gregorian data (ថ្ងៃសុរិយគតិ) to Khmer format
const date = momentkh.fromGregorian(2025, 12, 10); // ថ្ងៃទី១០ ខែធ្នូ ឆ្នាំ២០២៥
// or 
// const khmer = momentkh.fromGregorian(2025, 12, 10, 0, 0, 0); // (year, month, day, hour = 0, minute = 0, second = 0)
console.log(momentkh.format(date));
// Output: ថ្ងៃពុធ ៥រោច ខែមិគសិរ ឆ្នាំម្សាញ់ សប្តស័ក ពុទ្ធសករាជ ២៥៦៩

// Convert date to Khmer format (custom)
console.log(momentkh.format(date, "ប្រាសាទតាក្របីត្រូវបានចោរសៀមបាញ់បំផ្លាញទាំងស្រុង នៅថ្ងៃW ទីdsr ខែM ឆ្នាំcr ត្រូវនឹង ថ្ងៃទីDN ខែm ឆ្នាំa e ពុទ្ធសករាជ b។"));
// Output: ប្រាសាទតាក្របីត្រូវបានចោរសៀមបាញ់បំផ្លាញទាំងស្រុង នៅថ្ងៃពុធ ទី10 ខែធ្នូ ឆ្នាំ2025 ត្រូវនឹង ថ្ងៃទី០៥រោច ខែមិគសិរ ឆ្នាំម្សាញ់ សប្តស័ក ពុទ្ធសករាជ ២៥៦៩។

// Convert Khmer date to Gregorian
const gregorian = momentkh.fromKhmer(15, momentkh.MoonPhase.Waxing, momentkh.MonthIndex.Pisakh, 2568); // 15កើត ខែពិសាខ ព.ស.២៥៦៨
console.log(gregorian);
// Output: { year: 2025, month: 5, day: 11 }

// Get Khmer New Year
const newYear = momentkh.getNewYear(2025);
console.log(newYear);
// Output: { year: 2025, month: 4, day: 14, hour: 4, minute: 48 }

---

📑 Table of Contents

• Features
• Installation
• Quick Start
• API Reference
  • fromGregorian()
  • fromKhmer()
  • fromDate()
  • toDate()
  • getNewYear()
  • format()
• Using Enums (NEW in v3.0)
• Understanding Khmer Calendar
  • Buddhist Era (BE) Year
  • Animal Year
  • Sak
  • When Each Year Type Increases
• Format Codes
• Constants
• Migration Guide
• Examples
• Browser Support

---

✨ Features

• ✅ Zero Dependencies - Pure JavaScript, no external libraries required
• ✅ TypeScript Support - Full type definitions included for excellent IDE experience
• ✅ Type-Safe Enums - NEW in v3.0! Use enums for moonPhase, monthIndex, animalYear, sak, and dayOfWeek
• ✅ Bidirectional Conversion - Convert between Gregorian ↔ Khmer Lunar dates
• ✅ Accurate Calculations - Based on traditional Khmer astronomical algorithms
• ✅ Khmer New Year - Precise calculation of Moha Songkran timing
• ✅ Flexible Formatting - Customizable output with format tokens
• ✅ Universal - Works in Node.js, Browsers (ES5+), AMD, and ES Modules
• ✅ Lightweight - Single file (~36KB), no build step required
• ✅ Well-Tested - Comprehensive test suite with 1500+ test cases (100% pass rate)

---

📦 Installation

NPM (Recommended)

npm install @thyrith/momentkh

TypeScript

Type definitions are included automatically when you install via NPM. For direct downloads, you can also use momentkh.ts or the compiled .d.ts files from the dist/ folder.

---

🚀 Quick Start

Browser (HTML)

<!-- Include the browser-compatible UMD bundle -->
<script src="https://cdn.jsdelivr.net/gh/ThyrithSor/momentkh@3.0.3/momentkh.js"></script>
<script>
  // Convert today to Khmer
  const today = new Date();
  const khmer = momentkh.fromDate(today);
  console.log(momentkh.format(khmer));
  // Output: ថ្ងៃពុធ ១២រោច ខែមិគសិរ ឆ្នាំម្សាញ់ សប្តស័ក ពុទ្ធសករាជ ២៥៦៩
</script>

Note: Use momentkh.js (UMD bundle) for browsers. The dist/momentkh.js is CommonJS format for Node.js.

Node.js (CommonJS)

// Use the CommonJS module from dist/
const momentkh = require("@thyrith/momentkh");

// Convert specific date
const khmer = momentkh.fromGregorian(2024, 4, 14, 10, 30);
console.log(momentkh.format(khmer));

// Get Khmer New Year
const newYear = momentkh.getNewYear(2024);
console.log(newYear); // { year: 2024, month: 4, day: 13, hour: 22, minute: 17 }

ES Modules

import momentkh from "@thyrith/momentkh";

const khmer = momentkh.fromDate(new Date());
console.log(momentkh.format(khmer));

TypeScript

Full TypeScript support with complete type definitions and enums:

import momentkh, {
  KhmerConversionResult,
  NewYearInfo,
  GregorianDate,
  MoonPhase,
  MonthIndex,
  AnimalYear,
  Sak,
  DayOfWeek,
} from "@thyrith/momentkh";

// Convert with full type safety
const khmer: KhmerConversionResult = momentkh.fromGregorian(
  2024,
  4,
  14,
  10,
  30
);
console.log(momentkh.format(khmer));

// Access enum values (NEW in v3.0!)
console.log(khmer.khmer.moonPhase === MoonPhase.Waxing); // Type-safe comparison
console.log(khmer.khmer.monthIndex === MonthIndex.Cheit); // Enum comparison
console.log(khmer.khmer.dayOfWeek === DayOfWeek.Sunday); // Autocomplete support!

// Reverse conversion with enums (type-safe!)
const gregorianDate: GregorianDate = momentkh.fromKhmer(
  15,
  MoonPhase.Waxing, // Use enum instead of 0
  MonthIndex.Pisakh, // Use enum instead of 5
  2568
);
console.log(
  `${gregorianDate.year}-${gregorianDate.month}-${gregorianDate.day}`
);

// Still supports numbers for backward compatibility
const gregorianDate2: GregorianDate = momentkh.fromKhmer(15, 0, 5, 2568);

// Get New Year with typed result
const newYear: NewYearInfo = momentkh.getNewYear(2024);
console.log(
  `${newYear.year}-${newYear.month}-${newYear.day} ${newYear.hour}:${newYear.minute}`
);

// Access constants with full autocomplete
const monthName = momentkh.constants.LunarMonthNames[4]; // "ចេត្រ"

Available Types:

• KhmerConversionResult - Full conversion result object
• GregorianDate - Gregorian date object
• KhmerDateInfo - Khmer date information (now with enum fields!)
• NewYearInfo - New Year timing information
• Constants - Calendar constants interface

Available Enums (NEW in v3.0):

• 🌙 MoonPhase - Waxing (កើត) and Waning (រោច)
• 📅 MonthIndex - All 14 Khmer lunar months
• 🐉 AnimalYear - All 12 animal years
• ⭐ Sak - All 10 Saks
• 📆 DayOfWeek - Sunday through Saturday

---

📖 API Reference

fromGregorian(year, month, day, [hour], [minute], [second])

Converts a Gregorian (Western) date to a Khmer Lunar date.

Parameters: | Parameter | Type | Required | Range | Description | |-----------|------|----------|-------|-------------| | year | Number | ✅ Yes | Any | 📅 Gregorian year (e.g., 2024) | | month | Number | ✅ Yes | 1-12 | 📅 1-based month (1=January, 12=December) | | day | Number | ✅ Yes | 1-31 | 📅 Day of month | | hour | Number | ⚪ No | 0-23 | ⏰ Hour (default: 0) | | minute | Number | ⚪ No | 0-59 | ⏰ Minute (default: 0) | | second | Number | ⚪ No | 0-59 | ⏰ Second (default: 0) |

Returns: Object

{
  gregorian: {
    year: 2024,          // Number: Gregorian year
    month: 4,            // Number: Gregorian month (1-12)
    day: 14,             // Number: Day of month
    hour: 10,            // Number: Hour (0-23)
    minute: 30,          // Number: Minute (0-59)
    second: 0,           // Number: Second (0-59)
    dayOfWeek: 0         // Number: 0=Sunday, 1=Monday, ..., 6=Saturday
  },
  khmer: {
    day: 6,                      // Number: Lunar day (1-15)
    moonPhase: 0,                // MoonPhase enum: 0=Waxing (កើត), 1=Waning (រោច)
    moonPhaseName: 'កើត',        // String: Moon phase name (NEW in v3.0)
    monthIndex: 4,               // MonthIndex enum: 0-13 (see table below)
    monthName: 'ចេត្រ',          // String: Khmer month name
    beYear: 2568,                // Number: Buddhist Era year
    jsYear: 1386,                // Number: Jolak Sakaraj (Chula Sakaraj) year
    animalYear: 4,               // AnimalYear enum: 0-11 (NEW in v3.0)
    animalYearName: 'រោង',       // String: Animal year name
    sak: 6,                  // Sak enum: 0-9 (NEW in v3.0)
    sakName: 'ឆស័ក',         // String: Sak name
    dayOfWeek: 0,                // DayOfWeek enum: 0=Sunday, 6=Saturday (NEW in v3.0)
    dayOfWeekName: 'អាទិត្យ'     // String: Khmer weekday name
  },
  _khmerDateObj: KhmerDate // Internal: KhmerDate object (for advanced use)
}

✨ NEW in v3.0: The khmer object now includes both enum values AND string names for easier usage:

• 🔢 Use enum values (e.g., moonPhase, monthIndex) for type-safe comparisons
• 📝 Use string names (e.g., moonPhaseName, monthName) for display purposes

Example:

const result = momentkh.fromGregorian(2024, 4, 14);
console.log(result.khmer.beYear); // 2567
console.log(result.khmer.monthName); // 'ចេត្រ'
console.log(result.khmer.animalYear); // 4 (រោង)

---

fromKhmer(day, moonPhase, monthIndex, beYear)

Converts a Khmer Lunar date to a Gregorian date.

Parameters: | Parameter | Type | Required | Range | Description | |-----------|------|----------|-------|-------------| | day | Number | ✅ Yes | 1-15