🌌 QiMenDunJia (奇门遁甲)

A modern, highly optimized, and modular TypeScript Qi Men Dun Jia (奇门遁甲) chart calculation library.

This project decouples calendar/astronomical implementations from core Qimen logic. All calendar abilities are encapsulated in a unified adapter layer. The core chart engine consumes only a standardized CalendarSnapshot object, allowing the library to be distributed in three distinct packages to balance accuracy, bundle size, and dependency strategies.

---

📦 Packages & Distribution

We distribute the library in three flavors on NPM. Every package compiles to a zero-dependency (or minimal-dependency) bundle supporting both ES Module (ESM) and CommonJS (CJS), complete with rich TypeScript declarations (.d.ts).

NPM Package	Solar Term Engine	Runtime Dependencies	Bundle Size	Best For
qimendunjia-lite	Lightweight analytical solar position	Zero	~12 KB	Bundle-size sensitive environments, web apps, apps needing approximate solar terms.
qimendunjia-standalone	Ported ShouXing Astronomical Calendar	Zero	~68 KB	Production applications needing accurate solar term boundary times without heavy deps.
qimendunjia-tyme4ts	Backed by tyme4ts library	tyme4ts	~6 KB (+ dep)	Projects already using tyme4ts or needing bit-perfect calendar alignment.

Installation

Choose the package that fits your use case and install it via your package manager:

# To install the standalone version (Recommended for most apps):
npm install qimendunjia-standalone

# Or install the lite or tyme4ts variant:
npm install qimendunjia-lite
npm install qimendunjia-tyme4ts

---

🚀 Quick Start

All three packages expose an identical public API surface. You can seamlessly switch between variants by simply changing the import package name.

import { calculate, calculateBrief } from "qimendunjia-standalone";

// Initialize date (e.g. Summer Solstice, June 22, 2026 at 03:00:15 AM)
const date = new Date("2026-06-22T03:00:15+08:00");

// 1. Calculate the complete Qimen Dunjia Chart
const chart = calculate(date);
if ("error" in chart) {
  console.error("Failed to calculate chart:", chart.message);
} else {
  console.log("--- Si Zhu (四柱) ---");
  console.log(chart.info.siZhu); // { year: '丙午', month: '甲午', day: '丁卯', time: '壬寅' }

  console.log("\n--- Ju Shu (局数) ---");
  console.log(chart.info.ju); // "阴遁九局 (上元)"

  console.log("\n--- Zhi Fu & Zhi Shi (值符/值使) ---");
  console.log(chart.info.fu); // "值符：天心"
  console.log(chart.info.shi); // "值使：开门"
}

// 2. Get a quick summary brief (lightweight & fast)
const brief = calculateBrief(date);
console.log(brief.info);
/*
{
  jieqi: '节气：夏至',
  ju: '阴遁九局 (上元)',
  fu: '值符：天心',
  shi: '值使：开门'
}
*/

---

🛠️ Advanced Configuration

🌖 Late Zi Hour Mode (晚子时)

Standard Qimen rules differentiate between "Early Zi Hour" (早子时, 00:00 - 01:00) and "Late Zi Hour" (晚子时, 23:00 - 24:00). You can customize whether Late Zi Hour is calculated as the same day or the next day using lateZiHourMode:

// Same Day Mode (Default) - 23:00 is grouped as the same calendar day
const sameDayChart = calculate(new Date("2026-05-27T23:30:00+08:00"), {
  lateZiHourMode: "same-day", // day: '辛丑', time: '庚子'
});

// Next Day Mode - 23:00 advances the day pillar (日柱) to the next day
const nextDayChart = calculate(new Date("2026-05-27T23:30:00+08:00"), {
  lateZiHourMode: "next-day", // day: '壬寅', time: '庚子'
});

📅 Custom Calendar Snapshot

If you want to plug in your own custom astronomical calculations, high-precision ephemerides, or local timezone/apparent solar time corrections, you can bypass the built-in calendar adapter entirely:

import { calculateFromSnapshot } from "qimendunjia-standalone";
import type { CalendarSnapshot } from "qimendunjia-standalone";

// Create a custom snapshot representing the time state
const mySnapshot: CalendarSnapshot = {
  solarDate: "2026年6月22日",
  lunarDate: "农历丙午年五月初八",
  solarYear: 2026,
  julianDay: 2461213.29184,
  winterSolsticeJulianDay: 2461031.543,
  summerSolsticeJulianDay: 2461213.183,
  nextWinterSolsticeJulianDay: 2461396.701,
  solarTermName: "夏至",
  yearGanZhi: "丙午",
  monthGanZhi: "甲午",
  dayGanZhi: "丁卯",
  dayXun: "甲子",
  monthXun: "甲辰",
  yearXun: "甲辰",
  hours: [
    { ganZhi: "庚子", xun: "甲午" },
    { ganZhi: "辛丑", xun: "甲午" },
    { ganZhi: "壬寅", xun: "甲午" },
    // ... all 13 double-hours (including late Zi)
  ],
};

// Pass the snapshot directly to the Qimen calculator
const chart = calculateFromSnapshot(
  mySnapshot,
  new Date("2026-06-22T03:00:15+08:00"),
);
console.log(chart.info.ju); // "阴遁九局 (上元)"

---

📖 Public API Signature Reference

Every package exports the following robust API methods:

/** Core Calculation **/
function calculate(
  date: Date,
  options?: QimenOptions,
): QimenResult | QimenErrorResult;
function calculateBrief(
  date: Date,
  options?: QimenOptions,
): QimenBriefResult | QimenErrorResult;

/** Snapshot Calculators **/
function createCalendarSnapshot(
  date: Date,
  options?: CalendarOptions,
): CalendarSnapshot;
function calculateFromSnapshot(
  snapshot: CalendarSnapshot,
  date: Date,
  options?: QimenOptions,
): QimenResult;
function calculateBriefFromSnapshot(
  snapshot: CalendarSnapshot,
  date: Date,
  options?: QimenOptions,
): QimenBriefResult;

/** Helper Functions **/
function calculateJuShu(
  snapshot: CalendarSnapshot,
  method?: QimenMethod,
  hourIndex?: number,
): JuShu;
function getSolarTerms(
  year: number,
  options?: CalendarOptions,
): SolarTermInfo[];
function getSolarTermName(date: Date, options?: CalendarOptions): string;
function getHourIndex(hour?: number, options?: CalendarOptions): number;
function getJulianDay(date: Date): number;
function isIntlChineseCalendarSupported(): boolean;

/** Distribution Utilities **/
function getDiPan(type: DunType, num: number): PalaceMap;
function distributeJiuXing(
  diPan: PalaceMap,
  xunShou: string,
  shiGan?: string,
  type?: DunType,
): unknown;
function distributeBaMen(
  zhiFuGong: Palace,
  shiGan: string,
  diPan: PalaceMap,
  type?: DunType,
): unknown;
function distributeBaShen(zhiFuGong: Palace, type?: DunType): PalaceMap;

---

📡 Runtime Lunar Formatting & ICU support

For lite and standalone packages, the library relies on the runtime environment's native Intl APIs (Intl.DateTimeFormat('zh-CN-u-ca-chinese')) to format traditional Chinese lunar dates (e.g. 农历丙午年五月初八).

• Supported Environments: Modern browsers (Chrome, Safari, Firefox, Edge) and Node.js instances compiled with complete ICU support.
• Fallbacks: If you are deploying to a constrained environment (such as WeChat Mini-Programs, thin Docker containers, or old webviews lacking Chinese ICU data), you can check support using isIntlChineseCalendarSupported(). When unsupported, lunarDate defaults to an empty string "" without affecting any Qimen stems, branches, terms, or chart distributions.
• Forced Consistency: If you require strict, multi-platform runtime parity for traditional lunar dates, we highly recommend using qimendunjia-tyme4ts which bundles tyme4ts calendar structures.

---

💻 Developer Guide & Scripts

This library is structured as an extremely neat TypeScript monorepo workspace.

Core Scripts

# 1. Install all monorepo dependencies
pnpm install

# 2. Run TypeScript compile and verify type safety
pnpm typecheck

# 3. Execute the full Jest/Node automated test suite
pnpm test

# 4. Compile and bundle lite, standalone, and tyme4ts packages
pnpm build:packages

---

📄 License & Attribution

• This project is open-source and licensed under the MIT License.
• The high-precision astronomical algorithms inside the standalone adapter are ported and adapted from ShouXing Astronomical Calendar (寿星天文历), with structures aligned to tyme4ts (Copyright (c) 2024 6tail, MIT License). We extend our deepest gratitude to 6tail and the contributors of tyme4ts for their excellent architectural designs.