Four Pillars
Year, month, day, and hour pillars with typed stems, branches, hidden stems, polarity, and Ten God relationships.
calculateFourPillars()
Open-source · TypeScript · MIT
BaZi calculation,
made inspectable.
Reliable primitives for Four Pillars, true solar time, Five Element profiles, and Da Yun—built for applications that need explicit rules instead of a black box.
$
pnpm add @mingora/bazi
import { calculateBaziChart }
from "@mingora/bazi";
const chart = calculateBaziChart({
date: { year: 1998, month: 12, day: 13 },
time: { hour: 12, minute: 0 },
location: {
timeZone: "Asia/Shanghai",
longitude: 116.39
},
options: { solarTime: "true" }
});Year戊寅Wu Yin
Month甲子Jia Zi
Day甲午Jia Wu
Hour庚午Geng Wu
500randomized chart checks
97.9%statement coverage
100%function coverage
1800–2100documented date range
What it computes
A small surface.
A complete calculation path.
The library separates calendar facts, time correction, and interpretive policy so every output can be traced back to an explicit stage.
True solar time
IANA history, DST transitions, standard meridians, equation of time, and safe date rollover in one transparent result.
calculateTrueSolarTime()
Da Yun timing
Direction, precise Sect 2 starting offset, start date, and typed ten-year cycles without calculating it for every chart.
calculateDaYun()
Five Elements
Versioned hidden-stem weights, seasonal adjustment, normalized percentages, Day Master support, and role mapping.
analyzeElements()
Transparent by design
One input. Five explicit stages.
- 01Validate
Gregorian date, exact or unknown time, IANA zone, coordinates, and policy options.
- 02Resolve civil time
Historical offsets and DST ambiguity are resolved before astronomical correction.
- 03Correct solar time
Longitude and equation-of-time corrections can move the calculation across a day boundary.
- 04Generate pillars
The calendar engine applies the selected midnight or Zi-hour day boundary.
- 05Analyze
Versioned Mingora models produce auditable element scores and relationship signals.
Boundary-aware
The edge cases are
part of the API.
Birth-time software fails at boundaries, not at noon. These cases are modeled, returned, and tested instead of hidden behind defaults.
America/New_York · 2023-11-05 · 01:30
One clock time. Two real instants.
Fall-back creates two valid 01:30 timestamps. Choose earlier, later, compatible, or reject ambiguity explicitly.
earlierUTC−04:00laterUTC−05:00
Public API
Focused primitives.
Serializable output.
No calendar-library objects leak through the public contract. Upgrade the internals without rewriting your application.
Read the complete API on GitHubcalculateBaziChart(input)Primary entry
Returns pillars, Day Master, element profile, role mapping, confidence, warnings, and calculation metadata.
calculateTrueSolarTime(input)Time
Returns civil and solar timestamps, offsets, standard meridian, each correction component, and rollover status.
calculateDaYun(input)Timing
Returns direction, direction basis, precise start offset, start datetime, and up to twelve typed cycles.
analyzeRelationship(a, b)Signals
Returns deterministic Day Master, polarity, element exchange, role rhythm, and branch-interaction evidence.
Engineering principles
Useful defaults.
No invisible assumptions.
Uncertainty is output
An unknown birth time produces a null hour pillar and explicit warnings—not a fabricated noon chart presented as fact.
Policy is versioned
Seasonal weights and hidden-stem proportions belong to named models, separate from calendar calculations.
Boundaries are selectable
Midnight and Zi-hour day boundaries are first-class options, preserved in calculation metadata.
From engine to experience
See the calculation
in a human interface.
This library powers the production BaZi experience at Mingora—turning structured calculation into clear, plain-English reflection.