npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

vietnamese-lunar

v2.2.1

Published

Vietnamese lunar calendar: solar to lunar conversion, Can Chi, solar terms, Hoàng Đạo days and Vietnamese holidays

Readme

🌕 Vietnamese Lunar Calendar

A lightweight JavaScript utility to convert Gregorian (solar) dates to traditional lunar calendar dates — perfect for apps with cultural, astrological, or calendrical features.

🔗 Live demo: amlich.tandd.dev


✨ Features

  • Convert solar (Gregorian) dates to lunar dates
  • Vietnamese lunar calendar (computed for UTC+7 — may differ from the Chinese calendar on some dates, e.g. Tết 2007)
  • Accurate leap month handling (data range 1800–2199)
  • Can Chi (ganzhi) of day / month / year, solar terms, auspicious hours
  • Hoàng Đạo / Hắc Đạo days (12-star system, Nguyệt Kiến by solar terms)
  • Vietnamese holidays (solar + lunar, statutory days off)
  • Zero runtime dependencies; ESM + CommonJS builds
  • Written in TypeScript, ships with type definitions

📦 Installation

npm install

npm install vietnamese-lunar

yarn install

yarn add vietnamese-lunar

bun install

bun add vietnamese-lunar

🚀 Usage

import {dayInfo, lunarDay} from "vietnamese-lunar";

const lunarDate = lunarDay("17/10/2025") // Convert a Gregorian date to lunar date
console.log(lunarDate);

outputs:

{
  date: 26,
  date_text: { date: "Kỷ Mùi", month: "Ất Dậu", year: "Ất Tỵ" },
  dateText: { date: "Kỷ Mùi", month: "Ất Dậu", year: "Ất Tỵ" },
  month: 8,
  isLeap: false
}
const dateInfo = dayInfo("17/10/2025"); // Get detailed info about a specific date
console.log(dateInfo);

outputs:

{
  day: "Thứ Sáu",
  solarDate: "17/10/2025",
  lunarDate: { date: 26, month: 8, isLeap: false, monthDays: 29 },
  lunarDateText: { date: "Kỷ Mùi", month: "Ất Dậu", year: "Ất Tỵ" },
  firstHour: "Giáp Tý",
  solarTerms: "Hàn Lộ",
  auspiciousHours: "Bính Dần (3-5), Đinh Mão (5-7), Kỷ Tỵ (9-11), Nhâm Thân (15-17), Giáp Tuất (19-21), Ất Hợi (21-23)",
  inAuspiciousHours: "Giáp Tý (23-1), Ất Sửu (1-3), Mậu Thìn (7-9), Canh Ngọ (11-13), Tân Mùi (13-15), Quý Dậu (17-19)",
  dayMaster: "Thiên Thượng Hỏa",
  napAm: "Thiên Thượng Hỏa",
  element: "Hỏa",
  dayStar: {
    star: "Chu Tước",
    isAuspicious: false,
    index: 4,
    category: "hac-dao",
    system: "hiep-ky",
    monthBasis: "solar-term",
    aliases: []
  },
  holidays: [],
  hours: [
    { chi: "Tý", canChi: "Giáp Tý", start: 23, end: 1, star: "Thiên Hình", category: "hac-dao" },
    { chi: "Sửu", canChi: "Ất Sửu", start: 1, end: 3, star: "Chu Tước", category: "hac-dao" },
    { chi: "Dần", canChi: "Bính Dần", start: 3, end: 5, star: "Kim Quỹ", category: "hoang-dao" },
    { chi: "Mão", canChi: "Đinh Mão", start: 5, end: 7, star: "Thiên Đức", category: "hoang-dao" },
    { chi: "Thìn", canChi: "Mậu Thìn", start: 7, end: 9, star: "Bạch Hổ", category: "hac-dao" },
    { chi: "Tỵ", canChi: "Kỷ Tỵ", start: 9, end: 11, star: "Ngọc Đường", category: "hoang-dao" },
    { chi: "Ngọ", canChi: "Canh Ngọ", start: 11, end: 13, star: "Thiên Lao", category: "hac-dao" },
    { chi: "Mùi", canChi: "Tân Mùi", start: 13, end: 15, star: "Huyền Vũ", category: "hac-dao" },
    { chi: "Thân", canChi: "Nhâm Thân", start: 15, end: 17, star: "Tư Mệnh", category: "hoang-dao" },
    { chi: "Dậu", canChi: "Quý Dậu", start: 17, end: 19, star: "Câu Trận", category: "hac-dao" },
    {
      chi: "Tuất",
      canChi: "Giáp Tuất",
      start: 19,
      end: 21,
      star: "Thanh Long",
      category: "hoang-dao"
    },
    { chi: "Hợi", canChi: "Ất Hợi", start: 21, end: 23, star: "Minh Đường", category: "hoang-dao" }
  ],
  solarTerm: {
    current: {
      name: "Hàn Lộ",
      index: 13,
      start: 2025-10-08T00:37:00.000Z,
      startLocal: { day: 8, month: 10, year: 2025, hour: 7, minute: 37 }
    },
    next: {
      name: "Sương Giáng",
      index: 14,
      start: 2025-10-23T03:47:00.000Z,
      startLocal: { day: 23, month: 10, year: 2025, hour: 10, minute: 47 },
      daysUntil: 6
    }
  },
  canChi: {
    day: { can: 5, chi: 7, text: "Kỷ Mùi" },
    month: { can: 1, chi: 9, text: "Ất Dậu" },
    year: { can: 1, chi: 5, text: "Ất Tỵ" },
    hour: { can: 0, chi: 0, text: "Giáp Tý" }
  },
  clash: { canChi: [ "Ất Sửu", "Đinh Sửu" ], chi: [ "Sửu" ] },
  compatible: { tamHop: [ "Hợi", "Mão" ], lucHop: "Ngọ" }
}

Interface

Fields of dayInfo(). Fields marked (2.1.0) / (2.1.1) were added in that version; everything else is from 2.0.x.

| Property | | |----------------------|-----------------------------------------| | day | the day of week, Sunday to Saturday | | solarDate | Solar date | | lunarDate | lunar date object (date, month, isLeap, monthDays) | | lunarDate.date | the lunar date in number | | lunarDate.month | the lunar month in number | | lunarDate.isLeap | whether the lunar month is a leap month | | lunarDate.monthDays | (2.1.0) length of the lunar month: 29 or 30 (0 outside 1800–2199) | | lunarDateText | lunar date object (date, month, year) | | lunarDateText.date | the lunar date in ganzhi | | lunarDateText.month | the lunar month in ganzhi | | lunarDateText.year | the lunar year in ganzhi | | firstHour | the ganzhi of first hour of the day | | solarTerms | solar terms of the day (name) | | dayMaster | deprecated — same value as napAm | | napAm | (2.1.0) Nạp âm of the day, e.g. "Thiên Thượng Hỏa" | | element | (2.1.0) element of the Nạp âm: Kim / Mộc / Thủy / Hỏa / Thổ (null if unknown) | | auspiciousHours | list of auspicious hours (string) | | inAuspiciousHours | list of inauspicious hours (string) | | hours | (2.1.0) always 12 items, Tý → Hợi (structured version of the two strings above) | | hours[].chi | hour branch, "Tý" … "Hợi" | | hours[].canChi | ganzhi of the hour on that day, e.g. "Giáp Tý" | | hours[].start / end | start / end hour (start is 23 for Tý) | | hours[].star | the 12-star spirit ruling the hour | | hours[].category | "hoang-dao" \| "hac-dao" \| null, follows starSystem | | dayStar | the day's patron star (12-star system) and its classification | | dayStar.star | name of the day star (e.g. Thanh Long, Bạch Hổ) | | dayStar.isAuspicious | kept for 2.x: true iff category === "hoang-dao". false does not mean hắc đạo — see category | | dayStar.index / category / system / aliases | (2.1.0) 1..12 (Thanh Long = 1), "hoang-dao" \| "hac-dao" \| null, "hiep-ky" \| "ngoc-hap", alternative names | | dayStar.monthBasis | (2.2.0) how the month branch (Nguyệt Kiến) was determined: "solar-term" (default) or "lunar-month" | | solarTerm | (2.1.0) {current, next} | | solarTerm.current / next | {name, index, start, startLocal}; next also has daysUntil | | solarTerm..index | position in SOLAR_TERMS (0 = Xuân Phân) | | solarTerm..start | Date — an absolute instant (UTC when printed) | | solarTerm..startLocal | (2.1.1) {day, month, year, hour, minute} in Vietnam time (UTC+7) | | solarTerm.next.daysUntil | calendar days (UTC+7) until the next term starts, ≥ 1 | | canChi | (2.1.0) numeric Can/Chi indexes: day, month (lunar), year (lunar), hour (first Tý hour) | | canChi. | {can: 0..9, chi: 0..11, text} — index into HEAVENLY_STEMS / EARTHLY_BRANCHES | | clash | (2.1.0) {chi, canChi} — see "Tuổi xung / hợp"; rule changed in 2.1.1 | | clash.chi | the opposite Chi (lục xung), always 1 item | | clash.canChi | tuổi xung of the day, always 2 items from 2.1.1 (empty only if the Nạp âm is unknown → use chi) | | compatible | (2.1.0) {tamHop: string[2], lucHop: string} | | holidays | list of Vietnamese holidays on this date (solar and lunar can both apply) | | holidays[].name | holiday name | | holidays[].calendar | solar or lunar — which calendar defines the holiday | | holidays[].isPublicHoliday | true for statutory days off (Labor Code 2019, Art. 112) | | holidays[].type | (2.1.0) "public" \| "traditional" \| "commemorative" | | holidays[].isDayOff | (2.1.0) same as isPublicHoliday |

lunarDay() returns {date, month, isLeap, date_text, dateText}. date_text (snake_case) is deprecated; dateText has the same value and is the one to use (added in 2.1.1).

Items of getHolidays() / nextHolidays() are events, not the holidays[] entries above: {name, date: {day, month, year}, calendar, lunarDate?: {day, month}, type, isDayOff, isPublicHoliday}, plus endDate and days when groupConsecutive is on.

Note on dayStar: by default the 12-star "Nguyệt Kiến" (month-branch) is derived from solar terms (same method used for solarTerms), per the classical "Thanh Long Hoàng Đạo Ca" (Hiệp Kỷ Biện Phương Thư). Many popular Vietnamese almanac sites key it off the lunar month number instead, which disagrees for about a third of all days — see monthBasis under "New in 2.2.0".

Note on holidays: lunar holidays are only reported in regular (non-leap) months, so they occur once per lunar year. A solar and a lunar holiday can fall on the same day (e.g. 2/9/2020 was also Lễ Vu Lan); both are returned. Solar observances are only reported from the year they were established (e.g. Ngày Văn hóa Việt Nam 24/11 from 2026, per Nghị quyết 28/2026/QH16). isPublicHoliday reflects the current Labor Code, Art. 112. Movable days off (the extra Quốc khánh day on 1/9 or 3/9, and the 5 Tết days chosen each year by the government) are not included.

🆕 New in 2.2.0

monthBasis for dayStar

dayInfo(date, {monthBasis: "solar-term" | "lunar-month"}) — default "solar-term", so existing results do not change. The chosen basis is echoed in dayStar.monthBasis. getDayStarInfo(lunar, system?, monthBasis?) takes it as a third argument.

| | solar-term (default) | lunar-month | |---|---|---| | Month branch (Nguyệt Kiến) | from the current solar term: Lập Xuân → Dần, Kinh Trập → Mão, Thanh Minh → Thìn … | from the lunar month number: tháng 1 → Dần, tháng 2 → Mão, tháng 3 → Thìn … | | Leap month | not applicable (follows the sun) | same branch as the regular month with the same number | | Source | classical rule; same as solarTerms | what many Vietnamese almanac websites show | | Changes when | the Sun crosses a 30° boundary (~every 30 days, around the 4th–8th of each solar month) | on mùng 1 of each lunar month |

The two bases use the same star sequence and the same Hoàng Đạo / Hắc Đạo classification; they only differ in which month branch they start from. On the days when the two month branches agree the results are identical; on the others they differ by exactly one branch, i.e. between a solar term and the next mùng 1 (or the reverse), which is up to ~16 days around each boundary.

| Solar date | Lunar | solar-term (default): month branch → day star | lunar-month: month branch → day star | |---|---|---|---| | 1/1/2025 | 2/12 | tháng Tý → Tư Mệnh (hoang-dao) | tháng Sửu → Thiên Lao (hac-dao) | | 4/1/2025 | 5/12 | tháng Tý → Minh Đường (hoang-dao) | tháng Sửu → Câu Trận (hac-dao) | | 30/1/2025 | 2/1 | tháng Sửu → Minh Đường (hoang-dao) | tháng Dần → Câu Trận (hac-dao) | | 17/10/2025 | 26/8 | tháng Tuất → Chu Tước (hac-dao) | tháng Dậu → Thiên Đức (hoang-dao) |

In 2025 the two bases give a different day star on 118 of 365 days.

dayInfo("1/1/2025", {monthBasis: "lunar-month"}).dayStar
// → {
//     star: "Thiên Lao",
//     isAuspicious: false,
//     index: 9,
//     category: "hac-dao",
//     system: "hiep-ky",
//     monthBasis: "lunar-month",
//     aliases: []
//   }

getDayStarInfo(getLunarDate(1, 1, 2025), "hiep-ky", "lunar-month").monthBasis
// → "lunar-month"

monthBasis only affects dayStar. The hour stars in hours[] depend on the day's Chi alone, not on the month, so hours[] (and auspiciousHours / inAuspiciousHours) are the same for both bases. (The request this release implements asked for hours[].star / category to follow monthBasis; they cannot, because the rule used for hours has no month input.)

🆕 New in 2.1.1

Fixes and clarifications on top of 2.1.0 (the first three bullets change behaviour — see CHANGELOG.md):

  • One DateInput for every function that takes a solar date — dayInfo, lunarDay, getHourInfo, nextHolidays, getLunarDate(date): a Date, {day, month, year}, or a "d/m/yyyy" / "dd/mm/yyyy" string. Bug fix: in 2.1.0, nextHolidays only worked with {day, month, year} and silently returned [] for a Date or a string.
  • Invalid dates throw RangeError ("31/2/2026", "abc", outside 1800–2199) instead of returning an empty array or the string "Invalid date input.". This applies to dayInfo, lunarDay, getHourInfo, nextHolidays, getLunarDate(date). In 2.1.0, dayInfo/lunarDay returned "Invalid date input." and getHourInfo returned null for a bad date.
  • clash.canChi has a new rule and now always has 2 items (see "Tuổi xung / hợp").
  • getSolarTermByIndex(year, index), startLocal on every solar term, and the documented meaning of index and daysUntil (see "Solar terms").
  • nextHolidays(from, count, {groupConsecutive, types, dayOffOnly}) (see "Holidays by range").
  • lunarDay() also returns dateText (camelCase); date_text is deprecated.

🆕 New in 2.1.0

APIs added in 2.1.0. Input handling (DateInput, RangeError) is described under "New in 2.1.1" above: in 2.1.0 dayInfo, lunarDay and getHourInfo accepted a Date, {day, month, year} or "d/m/yyyy", but nextHolidays only accepted {day, month, year}.

The DateInput rules (2.1.1): a Date (local time), {day, month, year}, or a "d/m/yyyy" / "dd/mm/yyyy" string. An invalid date throws a RangeError with a descriptive message. The low-level numeric getLunarDate(day, month, year) and the lunar helpers (getSolarDate, getLunarMonthDays, getLeapMonth, monthInfo) never throw: they return a zeroed LunarDate / null.

1. Hoàng Đạo / Hắc Đạo systems

dayInfo("17/10/2025", {starSystem: "ngoc-hap"}).dayStar
// → {
//     star: "Chu Tước",
//     isAuspicious: false,
//     index: 4,
//     category: "hac-dao",
//     system: "ngoc-hap",
//     monthBasis: "solar-term",
//     aliases: []
//   }

| system | Hoàng đạo | Hắc đạo | Neither (category: null) | |---|---|---|---| | hiep-ky (default) — Hiệp Kỷ Biện Phương Thư | Thanh Long, Minh Đường, Kim Quỹ, Thiên Đức, Ngọc Đường, Tư Mệnh | Thiên Hình, Chu Tước, Bạch Hổ, Thiên Lao, Huyền Vũ, Câu Trận | — | | ngoc-hap — Ngọc Hạp Thông Thư | Thanh Long, Minh Đường, Thiên Đức (Kim Đường), Ngọc Đường | Chu Tước, Bạch Hổ, Huyền Vũ (Nguyên Vũ), Câu Trận (Câu Trần) | Thiên Hình, Kim Quỹ, Thiên Lao, Tư Mệnh |

The star of the day is the same in both systems; only the classification differs. Aliases: Thiên Đức ↔ Bảo Quang ↔ Kim Đường, Huyền Vũ ↔ Nguyên Vũ, Câu Trận ↔ Câu Trần. Sources: Hiệp Kỷ Biện Phương Thư for the 6/6 split and the "Thanh Long Hoàng Đạo Ca" rule for the star of the day; the 4/4 grouping is the Ngọc Hạp Thông Thư convention. Which of the four remaining stars to leave unclassified in ngoc-hap follows that convention (Thiên Hình, Kim Quỹ, Thiên Lao, Tư Mệnh) — verify against your preferred almanac if it matters.

2–3. Lunar → solar, month length

getSolarDate(1, 1, 2027)
// → { day: 6, month: 2, year: 2027, jd: 2461443 }

getSolarDate(30, 3, 2027)       // tháng 3/2027 thiếu
// → null

getSolarDate(1, 5, 2025, true)  // 2025 nhuận tháng 6, không phải 5
// → null

getLeapMonth(2025)
// → 6

getLunarMonthDays(6, 2025, true)
// → 29

getLunarDate(17, 10, 2025).monthDays
// → 29

getSolarDate never throws; years are lunar years 1800–2199 and the result must be within 25/1/1800 – 31/12/2199.

4. Structured hours

dayInfo("17/10/2025").hours[0]
// → { chi: "Tý", canChi: "Giáp Tý", start: 23, end: 1, star: "Thiên Hình", category: "hac-dao" }

getHourInfo("17/10/2025", 14)   // 23 và 0 giờ đều là Tý
// → { chi: "Mùi", canChi: "Tân Mùi", start: 13, end: 15, star: "Huyền Vũ", category: "hac-dao" }

Always 12 entries, Tý → Hợi. category follows starSystem; with hiep-ky the hoang-dao entries are exactly the old auspiciousHours string.

5. Solar terms

dayInfo("17/10/2025").solarTerm
// → {
//     current: {
//       name: "Hàn Lộ",
//       index: 13,
//       start: 2025-10-08T00:37:00.000Z,
//       startLocal: { day: 8, month: 10, year: 2025, hour: 7, minute: 37 }
//     },
//     next: {
//       name: "Sương Giáng",
//       index: 14,
//       start: 2025-10-23T03:47:00.000Z,
//       startLocal: { day: 23, month: 10, year: 2025, hour: 10, minute: 47 },
//       daysUntil: 6
//     }
//   }

getSolarTermByIndex(2026, 14)
// → {
//     name: "Sương Giáng",
//     index: 14,
//     start: 2026-10-23T09:36:00.000Z,
//     startLocal: { day: 23, month: 10, year: 2026, hour: 16, minute: 36 }
//   }

getSolarTerms(2026)[17]         // theo thời gian: phần tử thứ 18 trong năm, nhưng index = 12
// → {
//     name: "Thu Phân",
//     index: 12,
//     start: 2026-09-23T00:05:00.000Z,
//     startLocal: { day: 23, month: 9, year: 2026, hour: 7, minute: 5 }
//   }

getSolarTerms(2026).length
// → 24
  • Numbering: index is the position in SOLAR_TERMS: 0 = Xuân Phân, 1 = Thanh Minh, … 12 = Thu Phân, 14 = Sương Giáng, 18 = Đông Chí, 21 = Lập Xuân, 23 = Kinh Trập. dayInfo().solarTerm.*.index and getSolarTerms()[i].index use the same numbering.
  • Array order ≠ index: getSolarTerms(year) is ordered by time within the solar year (starting at Tiểu Hàn), so getSolarTerms(2026)[17] is Thu Phân with index: 12. Access by index with getSolarTermByIndex(year, index) (returns null for an invalid year/index).
  • Time zone: start is an absolute instant (Date); toISOString() shows it in UTC. Vietnam time is UTC+7: use startLocal — {day, month, year, hour, minute} already in UTC+7, independent of the machine's time zone — or add 7 hours yourself.
  • start comes from the same simplified solar-position formula as the rest of the library; expect an error of up to a few tens of minutes versus published tables.
  • daysUntil is the number of calendar days (UTC+7) from the queried day to the day the next term starts (≥ 1). It does not depend on the time of day or on the time zone of the machine running the code.

6. Holidays by range

getHolidays(2026)[0]
// → {
//     name: "Tết Dương lịch",
//     date: { day: 1, month: 1, year: 2026 },
//     calendar: "solar",
//     type: "public",
//     isDayOff: true,
//     isPublicHoliday: true
//   }

nextHolidays({day: 1, month: 11, year: 2026}, 1)[0]   // lễ âm lịch có lunarDate
// → {
//     name: "Tết Thường Tân",
//     date: { day: 18, month: 11, year: 2026 },
//     calendar: "lunar",
//     type: "traditional",
//     isDayOff: false,
//     isPublicHoliday: false,
//     lunarDate: { day: 10, month: 10 }
//   }

nextHolidays("1/1/2027", 5, {groupConsecutive: true}).map(h => [h.name, h.days])
// → [
//     [ "Tết Dương lịch", 1 ],
//     [ "Lễ cúng Ông Táo", 1 ],
//     [ "Ngày thành lập Đảng Cộng sản Việt Nam", 1 ],
//     [ "Giao thừa", 1 ],
//     [ "Tết Nguyên Đán", 3 ]
//   ]

nextHolidays("1/1/2027", 5, {groupConsecutive: true}).at(-1)
// → {
//     name: "Tết Nguyên Đán",
//     date: { day: 6, month: 2, year: 2027 },
//     calendar: "lunar",
//     type: "public",
//     isDayOff: true,
//     isPublicHoliday: true,
//     lunarDate: { day: 1, month: 1 },
//     endDate: { day: 8, month: 2, year: 2027 },
//     days: 3
//   }

nextHolidays("1/1/2027", 5, {types: ["public"]}).map(h => h.name + " " + h.date.day + "/" + h.date.month)
// → [
//     "Tết Dương lịch 1/1",
//     "Tết Nguyên Đán 6/2",
//     "Tết Nguyên Đán 7/2",
//     "Tết Nguyên Đán 8/2",
//     "Giỗ Tổ Hùng Vương 16/4"
//   ]

nextHolidays("1/1/2027", 3, {dayOffOnly: true}).map(h => h.name)
// → [ "Tết Dương lịch", "Tết Nguyên Đán", "Tết Nguyên Đán" ]

nextHolidays(from, count, options?): count counts the items returned after filtering and grouping. By default each day is its own item (Tết = 3 items). With groupConsecutive, consecutive days with the same name are merged (date = first day, plus endDate and days; single days get days: 1). Invalid from throws RangeError.

type: public (statutory day off), traditional (lunar festivals, Giáng sinh, Giao thừa), commemorative (other solar observances). isDayOff mirrors isPublicHoliday; movable days off are not included.

7. Tuổi xung / hợp

dayInfo().clash and .compatible, computed from the Can Chi and Nạp âm of the day:

  • clash.chi: lục xung — the opposite Chi (6 apart). Always one element.
  • clash.canChi: tuổi xung = the 5 Can Chi with the opposite Chi whose Nạp âm element khắc (overcomes, in either direction) the element of the day's Nạp âm. Because the 5 ages of one Chi carry all 5 elements, this is always exactly 2 entries, sorted by Can. It matches the usual Vietnamese almanac listing, e.g. ngày Giáp Tý → Mậu Ngọ, Nhâm Ngọ; ngày Kỷ Mão → Ất Dậu, Tân Dậu; ngày Quý Dậu → Đinh Mão, Tân Mão. (2.1.1 changed the rule: 2.1.0 used Can xung + opposite Chi and returned one item — or none on Mậu/Kỷ days. E.g. ngày Quý Dậu: 2.1.0 ["Đinh Mão"] → 2.1.1 ["Đinh Mão", "Tân Mão"]; ngày Kỷ Mão: [] → ["Ất Dậu", "Tân Dậu"].) Defensive: if the Nạp âm of the day cannot be determined the list is empty — fall back to chi.
  • compatible.tamHop: the other two Chi of the tam hợp triad (Thân-Tý-Thìn, Hợi-Mão-Mùi, Dần-Ngọ-Tuất, Tỵ-Dậu-Sửu).
  • compatible.lucHop: lục hợp partner (Tý-Sửu, Dần-Hợi, Mão-Tuất, Thìn-Dậu, Tỵ-Thân, Ngọ-Mùi).
dayInfo("26/10/2026").clash   // ngày Quý Dậu
// → { canChi: [ "Đinh Mão", "Tân Mão" ], chi: [ "Mão" ] }

dayInfo("1/11/2026").clash    // ngày Kỷ Mão
// → { canChi: [ "Ất Dậu", "Tân Dậu" ], chi: [ "Dậu" ] }

dayInfo("17/10/2025").compatible
// → { tamHop: [ "Hợi", "Mão" ], lucHop: "Ngọ" }

8–9. Nạp âm and Can Chi indexes

napAm / element replace dayMaster (deprecated, same value; it was always Nạp âm, not Nhật chủ). dayInfo().canChi (example below) gives {can: 0..9, chi: 0..11, text} for day, month (lunar month), year (lunar year) and hour (first Tý hour; chi is always 0). Index into HEAVENLY_STEMS / EARTHLY_BRANCHES.

dayInfo("17/10/2025").canChi
// → {
//     day: { can: 5, chi: 7, text: "Kỷ Mùi" },
//     month: { can: 1, chi: 9, text: "Ất Dậu" },
//     year: { can: 1, chi: 5, text: "Ất Tỵ" },
//     hour: { can: 0, chi: 0, text: "Giáp Tý" }
//   }

11. Whole month

monthInfo(2026, 10).length
// → 31

monthInfo(2026, 10)[0].solarDate
// → "1/10/2026"

Decoded lunar years and solar-term times are cached internally.

Not implemented

Item 10 of the upgrade request (12 Trực, 28 Sao, ngày kỵ, rating) is intentionally not included: each needs an authoritative source and, for rating, agreed weights, and shipping guessed tables would be misleading.

ESM / CDN

<script type="module">
  import {dayInfo} from "https://cdn.jsdelivr.net/npm/[email protected]/lib/esm/index.js";
</script>

📚 API

All functions are exported from the package root:

import {
  dayInfo, lunarDay, monthInfo, getHourInfo,           // high-level
  getLunarDate, getSolarDate, getLeapMonth, getLunarMonthDays, getJulianDayNumber, // conversion
  getSolarTerms, getSolarTermByIndex, getHolidays, nextHolidays, getCanChi,
  getHeavenlyEarthly, getDayStemIndex, getDayBranchIndex, getMonthBranchIndex,
  getSolarTermIndex, getDayStarInfo,
  HEAVENLY_STEMS, EARTHLY_BRANCHES, SOLAR_TERMS,       // name tables
} from "vietnamese-lunar";

High-level

| Function | Returns | | |---|---|---| | dayInfo(date: DateInput, options?) | DayInfo | Full info of a day (see example above). | | lunarDay(date: DateInput) | LunarDayInfo | Lunar date + ganzhi only (lighter). |

  • date is a DateInput: "d/m/yyyy" (e.g. "7/1/2025" or "07/01/2025"), a Date, or {day, month, year}; year 1800–2199.
  • Invalid input (wrong format, 31/2, out of range, extra spaces…) throws RangeError (since 2.1.1 — in 2.1.0 dayInfo/lunarDay returned the string "Invalid date input.", as in 2.0.x):
dayInfo("31/2/2026")
// → `RangeError: dayInfo: invalid date "31/2/2026". Expected a Date, {day, month, year} or a "d/m/yyyy" string that exists on the calendar, within years 1800–2199.`

nextHolidays("abc", 3)
// → `RangeError: nextHolidays: invalid date "abc". Expected a Date, {day, month, year} or a "d/m/yyyy" string that exists on the calendar, within years 1800–2199.`
const info = dayInfo("2/9/2020");
info.holidays;       // see below
info.dayStar.isAuspicious; // Hoàng Đạo? (false does not mean Hắc Đạo — check info.dayStar.category)
dayInfo("2/9/2020").holidays
// → [
//     {
//       name: "Ngày Quốc khánh",
//       calendar: "solar",
//       isPublicHoliday: true,
//       type: "public",
//       isDayOff: true
//     },
//     {
//       name: "Lễ Vu Lan",
//       calendar: "lunar",
//       isPublicHoliday: false,
//       type: "traditional",
//       isDayOff: false
//     }
//   ]

Low-level

Use these when you already have day/month/year as numbers (no string parsing, no day/month validation — you must keep the year in 1800–2199; outside it getLunarDate returns a LunarDate with date: 0).

getLunarDate(day, month, year): LunarDate — solar → lunar.

getLunarDate(17, 10, 2025)
// → { date: 26, month: 8, year: 2025, isLeap: false, julianDay: 2460966, monthDays: 29 }

year is the lunar year (may differ from the solar year in Jan/Feb). julianDay can be passed to the index helpers below.

getJulianDayNumber(day, month, year): number — Julian Day Number of a solar date.

getJulianDayNumber(17, 10, 2025)
// → 2460966

getHeavenlyEarthly(lunar: LunarDate): {date, month, year} — Can Chi names.

getHeavenlyEarthly(getLunarDate(17, 10, 2025))
// → { date: "Kỷ Mùi", month: "Ất Dậu", year: "Ất Tỵ" }

Index helpers (input: Julian Day Number, output: array index):

| Function | Lookup table | Example jd = 2460966 (17/10/2025) | |---|---|---| | getDayStemIndex(jd) | HEAVENLY_STEMS | HEAVENLY_STEMS[5] → "Kỷ" | | getDayBranchIndex(jd) | EARTHLY_BRANCHES | EARTHLY_BRANCHES[7] → "Mùi" | | getMonthBranchIndex(jd) | EARTHLY_BRANCHES | "Tuất" — Nguyệt Kiến by solar term | | getSolarTermIndex(jd) | SOLAR_TERMS | "Hàn Lộ" |

EARTHLY_BRANCHES[getMonthBranchIndex(jd)]; // "Tuất"
SOLAR_TERMS[getSolarTermIndex(jd)];        // "Hàn Lộ"

getMonthBranchIndex (solar-term month, changes at Lập Xuân, Kinh Trập…) is not the same as lunarDateText.month (lunar month, changes on mùng 1). E.g. 17/10/2025 is lunar month Ất Dậu but Nguyệt Kiến Tuất.

getDayStarInfo(lunar: LunarDate, system?: "hiep-ky" | "ngoc-hap", monthBasis?: "solar-term" | "lunar-month"): DayStarInfo — 12-star Hoàng Đạo / Hắc Đạo. system defaults to "hiep-ky", monthBasis to "solar-term".

getDayStarInfo(getLunarDate(17, 10, 2025))            // default system: "hiep-ky"
// → {
//     star: "Chu Tước",
//     isAuspicious: false,
//     index: 4,
//     category: "hac-dao",
//     system: "hiep-ky",
//     monthBasis: "solar-term",
//     aliases: []
//   }

getDayStarInfo(getLunarDate(17, 10, 2025), "ngoc-hap")
// → {
//     star: "Chu Tước",
//     isAuspicious: false,
//     index: 4,
//     category: "hac-dao",
//     system: "ngoc-hap",
//     monthBasis: "solar-term",
//     aliases: []
//   }

getDayStarInfo(getLunarDate(17, 10, 2025), "hiep-ky", "lunar-month")
// → {
//     star: "Thiên Đức",
//     isAuspicious: true,
//     index: 6,
//     category: "hoang-dao",
//     system: "hiep-ky",
//     monthBasis: "lunar-month",
//     aliases: [ "Bảo Quang", "Kim Đường" ]
//   }

The lists of hoàng đạo / hắc đạo stars for each system are in the table under "Hoàng Đạo / Hắc Đạo systems" above. The default "hiep-ky" has Hoàng Đạo: Thanh Long, Minh Đường, Kim Quỹ, Thiên Đức, Ngọc Đường, Tư Mệnh; Hắc Đạo: Thiên Hình, Chu Tước, Bạch Hổ, Thiên Lao, Huyền Vũ, Câu Trận.

lunarDay(date) and date_text: lunarDay returns both date_text (snake_case, deprecated, kept for compatibility) and dateText (same value). getLunarDate(date) also accepts a single DateInput.

Types (TypeScript)

import type {
  DayInfo, LunarDayInfo, LunarDate, DayStarInfo, Holiday, dateFormat,
  DateInput, DayInfoOptions, HourInfo, SolarTermItem, SolarTermInfo, CanChiInfo,
  HolidayEvent, NextHolidaysOptions, StarSystem, StarCategory, MonthBasis, HolidayType, LocalDateTime,
} from "vietnamese-lunar";

| Type | Shape | |---|---| | DateInput | string \| Date \| {day, month, year} | | DayInfoOptions | { starSystem?: "hiep-ky" \| "ngoc-hap", monthBasis?: "solar-term" \| "lunar-month" } | | MonthBasis | "solar-term" \| "lunar-month" | | LunarDate | { date, month, year, isLeap, julianDay, monthDays } | | dateFormat | { date, month, year } — ganzhi names | | DayStarInfo | { star, isAuspicious, index, category, system, monthBasis, aliases } | | Holiday | one entry of dayInfo().holidays: { name, calendar, isPublicHoliday, type, isDayOff } | | HolidayEvent | item of getHolidays / nextHolidays: { name, date, calendar, lunarDate?, type, isDayOff, isPublicHoliday, endDate?, days? } | | NextHolidaysOptions | { groupConsecutive?: boolean, types?: HolidayType[], dayOffOnly?: boolean } | | HourInfo | { chi, canChi, start, end, star, category } | | SolarTermItem | { name, index, start: Date, startLocal: LocalDateTime } | | SolarTermInfo | { current: SolarTermItem, next: SolarTermItem & { daysUntil } } | | LocalDateTime | { day, month, year, hour, minute } | | CanChiInfo | { day, month, year, hour }, each { can, chi, text } | | DayInfo | return type of dayInfo | | LunarDayInfo | return type of lunarDay: { date, month, isLeap, date_text (deprecated), dateText } |

Changelog

See CHANGELOG.md. Upgrading from v1? holiday was renamed to holidays (array) — see the 2.0.0 notes.

Thanks

Hồ Ngọc Đức