🌙 Vietnamese Lunar Calendar (viet-lunar)

A comprehensive, deterministic TypeScript library for the Vietnamese Lunar Calendar (Âm Lịch Việt Nam). Convert between Solar ↔ Lunar dates, compute Can-Chi (Sexagenary cycles), Solar Terms (24 Tiết Khí), Hoàng Đạo hours, and Vietnamese auspicious/inauspicious day rules.

✨ Features

• ✅ Accurate Solar ↔ Lunar Conversion with Vietnamese timezone (UTC+7)
• ✅ Can-Chi (干支) Calculations for year, month, day, and hour
• ✅ 24 Solar Terms (Tiết Khí) computation
• ✅ Hoàng Đạo Hours (Auspicious hours for daily activities)
• ✅ Vietnamese Day Analysis (Nên/Kiêng - Should Do/Avoid)
• ✅ 12 Trực (建除十二客) and 28 Lunar Mansions (Nhị Thập Bát Tú)
• ✅ Vietnamese Holidays detection (Tết, Giỗ Tổ, Trung Thu, etc.)
• ✅ Leap Month handling
• ✅ Dual Localization (Vietnamese & English)
• ✅ Pure Functions - deterministic and testable
• ✅ ESM + CJS exports

📦 Installation

# Using npm
npm install @baostudio/viet-lunar

# Using bun
bun add @baostudio/viet-lunar

# Using yarn
yarn add @baostudio/viet-lunar

🚀 Quick Start

import { solarToLunar, analyzeDay } from '@baostudio/viet-lunar';

// Convert solar to lunar date
const lunar = solarToLunar({ year: 2024, month: 2, day: 10 });
console.log(lunar); 
// { year: 2024, month: 1, day: 1, leapMonth: false } - Tết 2024!

// Analyze a day
const analysis = analyzeDay({ year: 2025, month: 11, day: 4 });
console.log(analysis.lunar);      // Lunar date
console.log(analysis.canChi);     // Can-Chi for year, month, day
console.log(analysis.nen);        // Activities recommended
console.log(analysis.kieng);      // Activities to avoid
console.log(analysis.quality);    // Day quality: excellent/good/neutral/poor/bad

📖 API Documentation

Core Conversions

solarToLunar(solar: SolarDate): LunarDate

Convert a Gregorian (solar) date to Vietnamese lunar date.

import { solarToLunar } from '@baostudio/viet-lunar';

const lunar = solarToLunar({ year: 2024, month: 2, day: 10 });
// Returns: { year: 2024, month: 1, day: 1, leapMonth: false }

lunarToSolar(lunar: LunarDate): SolarDate

Convert a Vietnamese lunar date to Gregorian date.

import { lunarToSolar } from '@baostudio/viet-lunar';

const solar = lunarToSolar({ year: 2025, month: 1, day: 1, leapMonth: false });
// Returns: { year: 2025, month: 1, day: 29 } - Tết 2025

Can-Chi (Sexagenary) Calculations

getCanChiYear(year: number): Sexagenary

Get the Can-Chi for a year.

import { getCanChiYear } from '@baostudio/viet-lunar';

const yearCanChi = getCanChiYear(2024);
// Returns: { stem: "Giáp", branch: "Thìn", code: 40 }

getCanChiDay(solar: SolarDate): Sexagenary

Get the Can-Chi for a specific day.

import { getCanChiDay } from '@baostudio/viet-lunar';

const dayCanChi = getCanChiDay({ year: 2025, month: 11, day: 4 });
// Returns: { stem: "Bính", branch: "Tý", code: 12 }

getAllCanChi(solar: SolarDate, hour?: number): CanChiInfo

Get all Can-Chi (year, month, day, hour) for a date.

import { getAllCanChi } from '@baostudio/viet-lunar';

const canChi = getAllCanChi({ year: 2025, month: 11, day: 4 }, 9);
console.log(canChi.year);   // Year Can-Chi
console.log(canChi.month);  // Month Can-Chi
console.log(canChi.day);    // Day Can-Chi
console.log(canChi.hour);   // Hour Can-Chi

Day Analysis

analyzeDay(solar: SolarDate, options?: AnalysisOptions): DayAnalysis

Comprehensive analysis of a day including:

• Lunar date
• Can-Chi for year, month, day, hour
• Solar term
• Hoàng Đạo hours
• Trực (12 Positions)
• Nên (recommended activities)
• Kiêng (activities to avoid)
• Holidays
• Overall quality

import { analyzeDay } from '@baostudio/viet-lunar';

const analysis = analyzeDay(
  { year: 2025, month: 11, day: 4 },
  { hour: 9, locale: 'vi' }
);

console.log(analysis.lunar);           // { year: 2025, month: 9, day: 15, leapMonth: false }
console.log(analysis.canChi.day);      // Day's Can-Chi
console.log(analysis.hoangDao.hours);  // ["Tý", "Sửu", "Mão", ...]
console.log(analysis.nen);             // ["cưới hỏi", "khai trương", ...]
console.log(analysis.kieng);           // ["động thổ", ...]
console.log(analysis.quality);         // "good"

findGoodDays(startDate, endDate, criteria?): DayAnalysis[]

Find good days within a date range.

import { findGoodDays } from '@baostudio/viet-lunar';

const goodDays = findGoodDays(
  { year: 2025, month: 11, day: 1 },
  { year: 2025, month: 11, day: 30 },
  'excellent'
);

console.log(`Found ${goodDays.length} excellent days`);

Solar Terms

getSolarTerm(solar: SolarDate): SolarTerm | undefined

Get the solar term if the date falls on one.

import { getSolarTerm } from '@baostudio/viet-lunar';

const term = getSolarTerm({ year: 2024, month: 2, day: 4 });
// Returns solar term if date is Lập Xuân, Vũ Thủy, etc.

Formatting

toRichText(analysis: DayAnalysis, locale?: 'vi' | 'en'): string

Format analysis result as rich text.

import { toRichText, analyzeDay } from '@baostudio/viet-lunar';

const analysis = analyzeDay({ year: 2025, month: 11, day: 4 });
const text = toRichText(analysis, 'vi');
console.log(text);

🎯 Use Cases

1. Wedding Date Selection

import { findDaysForActivity } from '@baostudio/viet-lunar';

const weddingDays = findDaysForActivity(
  { year: 2025, month: 12, day: 1 },
  { year: 2026, month: 2, day: 28 },
  'cưới hỏi'
);

console.log(`Found ${weddingDays.length} suitable days for weddings`);

2. Business Opening

import { analyzeDay } from '@baostudio/viet-lunar';

const analysis = analyzeDay({ year: 2025, month: 11, day: 4 });

if (analysis.nen.includes('khai trương')) {
  console.log('Good day to open business!');
  console.log('Auspicious hours:', analysis.hoangDao.hours);
}

3. Calendar Widget

import { analyzeDay, toDisplayObject } from '@baostudio/viet-lunar';

const today = { year: 2025, month: 11, day: 4 };
const analysis = analyzeDay(today);
const display = toDisplayObject(analysis, 'vi');

// Use display object in your UI
// display.date.lunar, display.canChi, display.recommendations, etc.

🧪 Testing

# Run tests
bun test

# Run with watch mode
bun test --watch

🏗️ Building

# Build all formats (ESM + CJS + Types)
bun run build

# Build individual formats
bun run build:esm
bun run build:cjs
bun run build:types

📚 Documentation

For detailed documentation on algorithms and Vietnamese lunar calendar rules, see:

• 01-chuyen-doi-duong-lich-sang-am-lich.md - Solar↔Lunar conversion
• 02-cach-tinh-can-chi.md - Can-Chi calculations
• 03-gio-hoang-dao.md - Hoàng Đạo hours
• 04-luan-ngay-tot-xau.md - Day quality rules

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE for details

🙏 Acknowledgments

• Based on Vietnamese astronomical calculations and traditional calendar rules
• Algorithms adapted from Jean Meeus' "Astronomical Algorithms"
• Vietnamese calendar research by Prof. Hoàng Xuân Hãn

📮 Contact

Created by Bao Studio

For issues or questions, please open an issue on GitHub.

Built with ❤️ using Bun and TypeScript