VN Lunar Calendar

A Vietnamese lunar calendar conversion library for bidirectional conversion between Gregorian (solar) and Vietnamese lunar calendar dates.

Features

• Convert Gregorian dates to Vietnamese lunar calendar dates (1200-2199)
• Convert Vietnamese lunar calendar dates to Gregorian dates
• Support for leap months in lunar calendar
• Calculate Can Chi (Heavenly Stems and Earthly Branches) for years, months, and days
• Get Vietnamese day of week names
• Julian Day Number calculations
• TypeScript support with full type definitions

Installation

From npm (Recommended)

Install the package using your preferred package manager:

npm install @forvn/vn-lunar-calendar

or

yarn add @forvn/vn-lunar-calendar

or

pnpm add @forvn/vn-lunar-calendar

For Local Development (Standalone Library)

If you want to use this library locally without the full Nx monorepo:

1. Build the library:

npm run build
# or
yarn build
# or
pnpm build

2. Link the library locally:

# In the library directory
npm link
# or
yarn link
# or
pnpm link --global

3. Use in your project:

# In your project directory
npm link @forvn/vn-lunar-calendar
# or
yarn link @forvn/vn-lunar-calendar
# or
pnpm link --global @forvn/vn-lunar-calendar

For Nx Monorepo Development

If you're working within the Nx monorepo:

# Build the library
nx build vn-lunar-calendar

# Run tests
nx test vn-lunar-calendar

Then import directly in your apps:

import { LunarCalendar } from '@forvn/vn-lunar-calendar';

Usage

Basic Usage with LunarCalendar Class

The LunarCalendar class provides the simplest way to work with lunar dates:

import { LunarCalendar } from '@forvn/vn-lunar-calendar';

// Get today's lunar date
const today = LunarCalendar.today();
console.log(today.formatLunar()); // "25/10/2024"
console.log(today.formatSolar()); // "01/12/2024"

// Convert from solar to lunar
const calendar = LunarCalendar.fromSolar(25, 12, 2024);
console.log(calendar.lunarDate); // { day: 25, month: 11, year: 2024, leap: false, jd: ... }
console.log(calendar.formatLunar()); // "25/11/2024"

// Convert from lunar to solar
const lunarCal = LunarCalendar.fromLunar(15, 10, 2024);
console.log(lunarCal.solarDate); // { day: 16, month: 11, year: 2024, jd: ... }
console.log(lunarCal.formatSolar()); // "16/11/2024"

// Handle leap months
const leapMonth = LunarCalendar.fromLunar(15, 10, 2024, true);
console.log(leapMonth.formatLunar()); // "15/10/2024 (nhuận)"

Get Can Chi (Zodiac Information)

const calendar = LunarCalendar.fromSolar(1, 12, 2024);

console.log(calendar.yearCanChi); // "Giáp Thìn" (Year zodiac)
console.log(calendar.monthCanChi); // Month zodiac
console.log(calendar.dayCanChi); // Day zodiac
console.log(calendar.dayOfWeek); // "Chủ nhật" (Sunday in Vietnamese)

Using Core Functions Directly

For more control, you can use the core conversion functions:

import { getLunarDate, getSolarDate, getYearCanChi } from '@forvn/vn-lunar-calendar';

// Solar to Lunar
const lunarDate = getLunarDate(25, 12, 2024);
console.log(lunarDate);
// {
//   day: 25,
//   month: 11,
//   year: 2024,
//   leap: false,
//   jd: 2460669
// }

// Lunar to Solar
const solarDate = getSolarDate(15, 10, 2024, false);
console.log(solarDate);
// {
//   day: 16,
//   month: 11,
//   year: 2024,
//   jd: 2460630
// }

// Get year zodiac
const yearZodiac = getYearCanChi(2024);
console.log(yearZodiac); // "Giáp Thìn"

Working with LunarDate Objects

import { LunarDate } from '@forvn/vn-lunar-calendar';

const lunar = new LunarDate(15, 10, 2024, false, 2460630);

console.log(lunar.toString()); // "15/10/2024"
console.log(lunar.isValid()); // true

const lunar2 = new LunarDate(15, 10, 2024, false, 2460630);
console.log(lunar.equals(lunar2)); // true

// Leap month
const leapLunar = new LunarDate(15, 10, 2024, true, 2460630);
console.log(leapLunar.toString()); // "15/10/2024 (nhuận)"

Julian Day Number Utilities

import { jdn, jdn2date } from '@forvn/vn-lunar-calendar';

// Calculate Julian Day Number from Gregorian date
const julianDay = jdn(1, 12, 2024);
console.log(julianDay); // 2460645

// Convert Julian Day Number back to Gregorian date
const [day, month, year, dayOfWeek] = jdn2date(2460645);
console.log(day, month, year); // 1, 12, 2024
console.log(dayOfWeek); // 0-6 (0 = Sunday)

API Reference

Classes

LunarCalendar

Main calendar class for bidirectional conversions.

Constructor:

new LunarCalendar(day: number, month: number, year: number, isLunar: boolean = false)

Static Methods:

• LunarCalendar.fromSolar(day, month, year) - Create from Gregorian date
• LunarCalendar.fromLunar(day, month, year, leap?) - Create from lunar date
• LunarCalendar.today() - Create from current date

Properties:

• lunarDate: LunarDate - Lunar date information
• solarDate: SolarDateInfo - Solar date information
• yearCanChi: string - Year zodiac (e.g., "Giáp Thìn")
• monthCanChi: string - Month zodiac
• dayCanChi: string - Day zodiac
• dayOfWeek: string - Vietnamese day name

Methods:

• formatLunar(): string - Format lunar date as string
• formatSolar(): string - Format solar date as string
• toString(): string - Format both dates

LunarDate

Represents a lunar calendar date.

Constructor:

new LunarDate(day: number, month: number, year: number, leap: boolean, jd: number)

Properties:

• day: number - Day of month (1-30)
• month: number - Month (1-12)
• year: number - Year (1200-2199)
• leap: boolean - Whether this is a leap month
• jd: number - Julian Day Number

Methods:

• toString(): string - String representation
• isValid(): boolean - Check if date is valid
• equals(other: LunarDate): boolean - Compare with another lunar date

Functions

Core Conversion Functions

// Convert solar to lunar
getLunarDate(day: number, month: number, year: number): LunarDate

// Convert lunar to solar
getSolarDate(day: number, month: number, year: number, leap?: boolean): SolarDateInfo

// Get Can Chi for year
getYearCanChi(year: number): string

// Get Can Chi for day (requires Julian Day Number)
getDayCanChi(jd: number): string

// Get Can Chi for month
getMonthCanChi(month: number, year: number): string

Utility Functions

// Calculate Julian Day Number from Gregorian date
jdn(day: number, month: number, year: number): number

// Convert Julian Day Number to Gregorian date
jdn2date(jd: number): [day: number, month: number, year: number, dayOfWeek: number]

// Decode lunar year information
decodeLunarYear(year: number, k: number): LunarDate[]

// Get complete year information
getYearInfo(year: number): LunarDate[]

Types

interface LunarDateInfo {
  day: number;
  month: number;
  year: number;
  leap: boolean; // true if this is a leap month
  jd: number; // Julian Day Number
}

interface SolarDateInfo {
  day: number;
  month: number;
  year: number;
  jd: number; // Julian Day Number
}

Supported Date Range

The library supports dates from 1200 to 2199 (Gregorian calendar years).

Vietnamese Zodiac System

The library uses the traditional Vietnamese Can Chi (Heavenly Stems and Earthly Branches) system:

Can (Heavenly Stems): Giáp, Ất, Bình, Đinh, Mậu, Kỷ, Canh, Tân, Nhâm, Quý

Chi (Earthly Branches): Tý, Sửu, Dần, Mão, Thìn, Tỵ, Ngọ, Mùi, Thân, Dậu, Tuất, Hợi

Example Application

A complete preview tool is available here: https://quick-tools.space/lunar-calendar

Development

Building

# In Nx monorepo
nx build vn-lunar-calendar

# Standalone
npm run build

Testing

# In Nx monorepo
nx test vn-lunar-calendar

# Standalone
npm test

Type Checking

nx run vn-lunar-calendar:type-check

Credits

Based on astronomical calculations for the Vietnamese lunar calendar system using pre-calculated lookup tables for efficient date conversion.