baziflow-core

Accurate BaZi (八字 / Four Pillars of Destiny) chart engine for JavaScript & TypeScript.

Give it a birth date, time and place — it returns the four pillars, true solar time, the Five Elements (五行) distribution, the Ten Gods (十神), hidden stems (藏干), NaYin (纳音) and the Luck Pillars (大运). Fully typed, tree-shakeable, one runtime dependency.

Maintained by the team behind BaziFlow — a free online BaZi calculator.

Install

npm install baziflow-core

Usage

import { computeChart } from "baziflow-core";

const chart = computeChart({
  year: 1990,
  month: 6,
  day: 15,
  hour: 14,
  minute: 30,
  gender: "male",
  longitude: 116.4, // Beijing — enables true-solar-time correction
});

console.log(chart.day.gan, chart.day.zhi); // Day pillar, e.g. 丁 巳
console.log(chart.dayMaster, chart.dayMasterElement); // 丁 "fire"
console.log(chart.trueSolarTime); // "14:16"
console.log(chart.elementStrength); // { wood: 12, fire: 40, earth: 18, metal: 15, water: 15 }
console.log(chart.luckCycles[0]); // first Luck Pillar (大运)

Lunar dates

computeChart({ year: 1990, month: 5, day: 22, hour: 8, gender: "female", calendar: "lunar" });

Just the primitives

Everything the engine uses is exported for building your own tools:

import {
  calcTrueSolarTime, // true solar time from longitude
  getTenGod,         // Ten God between two stems
  getNayin,          // NaYin for a stem/branch pair
  calcElementStrength,
  GAN_ELEMENT, ZHI_HIDDEN_GAN, GAN_COMBINE,
  romanizeGan, zodiacEn,
} from "baziflow-core";

What it returns

computeChart returns a BaziChart:

| Field | Meaning | | --- | --- | | year / month / day / hour | The four Pillars (stem, branch, elements, Ten God, hidden stems, NaYin) | | dayMaster / dayMasterElement | The Day Master stem (日主) and its element | | elementStrength | Five Elements distribution, percentages summing to ~100 | | luckCycles / currentLuckCycleIndex | Luck Pillars (大运) and the active decade | | trueSolarTime | Time used for the hour pillar after longitude correction | | solarDate / lunarDate / zodiac | Gregorian date, Chinese lunar date, zodiac animal (CN + EN) |

Scope

This package computes the chart, not a reading. It deliberately ships no fortune-telling judgements — no favourable/unfavourable elements, no strength verdict, no interpretation. Those are opinionated and belong to your product. For a full interpreted reading, try the hosted BaziFlow calculator.

Labels for NaYin ship in English, Simplified Chinese, Traditional Chinese and Japanese via formatNayin(value, locale).

License

MIT © BaziFlow