Traditional East Asian calendar systems—such as the 60-term Sexagenary Cycle (Ganzhi), 24 Solar Terms, and 64-hexagram Jingfang Najia (Six-Line I Ching)—are often treated as fuzzy folklore, yet underneath they are pure deterministic state machines rooted in spherical astronomy and binary combinatorics.
When building a zero-registration, edge-delivered charting workspace, we ran into four subtle engineering problems that cause web calculators to disagree on edge cases. Here is how we modeled them cleanly in TypeScript.
1. Solar Longitude vs. Civil Calendar Boundaries
In the classical Four Pillars (BaZi) calendar, months do not switch on the 1st of a Gregorian or Lunar month. Each month begins at an exact 15° increment of apparent ecliptic solar longitude (the 12 major Solar Terms, starting with Lichun at 315°).
interface SolarTermBoundary { termName: string; eclipticDeg: number; // multiples of 15° utcMillis: number; // minute/second precision } If an implementation only stores whole-day dates for solar terms, anyone born within a few hours of a boundary gets the wrong Year or Month Pillar.
2. Apparent True Solar Time (Longitude + Equation of Time)
Civil clock time uses regional meridians (e.g., UTC+8 = 120°E). True Solar Time applies two deterministic corrections:
- Longitude offset:
(birthLongitude - standardMeridian) * 4minutes. - Equation of Time (EoT): up to roughly
±16minutes across the year due to Earth's orbital eccentricity and axial tilt.
Combining both shifts boundary births cleanly into the right two-hour Earthly Branch (Shichen), and lets you emit an auditable calendar boundary receipt showing the exact offset applied.
3. Binary Encoding of 64 Hexagrams & Jingfang Najia Assignment
A Six-Line I Ching (Liuyao) cast is a 6-bit vector with two moving-line states (6 old yin, 7 young yang, 8 young yin, 9 old yang):
- Bits
0..2form the lower trigram (8states); bits3..5form the upper trigram (8states), yielding8 × 8 = 64base hexagrams. - Applying a bitwise mask on moving lines (
6→ yang,9→ yin) deterministically yields the Transformed Hexagram (Zhi Gua). - Jingfang Najia maps each of the 6 lines to an Earthly Branch and Five-Element stem based on its Palace (Ba Gong) and trigram polarity, attaching the Six Relatives (Liu Qin) relative to the Palace element.
You can test the full three-coin cast and Najia state table live in our free, no-login I Ching online workspace.
4. Stateless Privacy & Sub-10ms Edge Delivery
Birth timestamps and relationship queries are personal. Rather than storing user birth profiles in a central database, core charting runs deterministically with zero sign-up required—making it easy to cross-check a BaZi calculator chart or run a two-chart Chinese astrology compatibility comparison while keeping local drafts ephemeral.
Everything above runs deterministically from classical rulesets—and exposing exact solar-term and True Solar Time boundaries makes debugging edge cases transparent for both developers and readers.
