Nhat Nguyet : Open-source for the Lunar calendar, Zi Wei Dou Shu, BaZi and numerology

by•



Hi Product Hunt 👋

Most lunar calendar libraries follow the Chinese calendar. Vietnam uses the same rules but counts the day in Vietnam time (UTC+7), not Beijing time (UTC+8). That one hour moves the new moon to a different day often enough to matter: between 1900 and 2100, a popular JavaScript lunar library gives 2,724 dates that differ from the Vietnamese calendar, including 9 Lunar New Years. The next one is 2030.

So we built Nhat Nguyet Open Source: the engine behind , released as libraries anyone can use.

What's inside

• Vietnamese lunar calendar and the 24 solar terms, also for China, Korea, Japan and other countries (country: "CN", "KR", "JP"...)

• Zi Wei Dou Shu (Tử Vi) and BaZi (Four Pillars) charts, numerology, auspicious hours, 206 Vietnamese festivals with iCalendar export

• Named "school" options where the classical books disagree, each with its source

• An iztro-compatible layer if you already use iztro

• SVG chart renderers, a CLI (npx /cli), an MCP server for AI assistants, and 5 web components that need no server

Why you can trust the numbers

• Solar terms within 0.27 minutes of IMCCE (Paris Observatory) on average, never more than 0.9 minutes, over 4,824 instants

• TypeScript and Python give byte-identical output, checked by 17,291 shared test vectors you can use to port it to any language

• A technical paper with every number reproducible from the repo

Open data on Hugging Face

• 3.6 million pre-computed charts with readings that quote classical texts by book and chapter

• Knowledge datasets, a 428-term glossary in English, Chinese and Vietnamese, and a 1,520-question evaluation set for AI models

These are rules of traditional schools, presented with their sources, not predictions.

npm i /ziwei

pip install nhatnguyet

I'd love your feedback, and ports to other languages are very welcome: the test vectors make it a well-defined challenge. 🙏

4 views

Add a comment

Replies

Be the first to reply

Have a question or a thought to share? Add a comment above to start the conversation.