Bazi Calculator (Forked from Alvamind)

⚠️ This is a fork of the original bazi-calculator-by-alvamind, published under the @aharris02 scope for compatibility with modern TypeScript builds and deployment environments (e.g. Vercel).

📢 Disclaimer

This package is provided for educational and research purposes only. The calculations and interpretations should not be used as the sole basis for making important life decisions. Chinese Metaphysics and Bazi analysis require professional expertise and years of study.

✨ Features

Core Calculations

• Four Pillars (四柱)
  • Year Pillar (年柱)
  • Month Pillar (月柱)
  • Day Pillar (日柱)
  • Hour Pillar (時柱)
• Solar/Lunar Calendar Conversions
• Precise Time Calculations

Analysis Components

• Five Elements (五行) Analysis
  • Element Distribution
  • Element Relationships
  • Element Strength Calculations
• Day Master (日主) Analysis
  • Yin/Yang Nature
  • Element Properties
  • Stem Relationships
• Eight Mansions (八宅) Feng Shui
  • Life Gua Calculation
  • Direction Analysis
  • Lucky/Unlucky Sectors
• Destiny Indicators
  • Nobleman (貴人)
  • Intelligence Star (文昌)
  • Sky Horse (天馬)
  • Peach Blossom (桃花)

Technical Features

• 🔒 Type-safe with TypeScript
• 📦 ES Module Support
• 🏗️ SOLID Architecture
• 🔄 JSON-based Date Mapping
• 📝 Comprehensive Type Definitions
• ⚡ Optimized Performance

🚀 Installation

# Using npm
npm install @aharris02/bazi-calculator-by-alvamind

# Using yarn
yarn add bazi-calculator-by-alvamind

# Using pnpm
pnpm add bazi-calculator-by-alvamind

🎯 Quick Start

import { BaziCalculator } from '@aharris02/bazi-calculator-by-alvamind';

// Initialize calculator
const calculator = new BaziCalculator(
  1990,    // Year
  5,       // Month
  10,      // Day
  12,      // Hour (24-hour format)
  'male'   // Gender
);

// Get complete analysis
const analysis = calculator.getCompleteAnalysis();

// Display Chinese characters
console.log(calculator.toString()); // 庚午年辛巳月乙酉日壬午時

📖 Detailed Documentation

Basic Usage

Getting Basic Analysis

const basicAnalysis = calculator.calculateBasicAnalysis();

Calculating Pillars Only

const pillars = calculator.calculatePillars();

Example Output

{
  "mainPillars": {
    "year": {
      "chinese": "庚午",
      "element": "METAL",
      "animal": "Horse",
      "branch": { "element": "FIRE" }
    },
    "month": {
      "chinese": "辛巳",
      "element": "METAL",
      "animal": "Snake",
      "branch": { "element": "FIRE" }
    },
    "day": {
      "chinese": "乙酉",
      "element": "WOOD",
      "animal": "Rooster",
      "branch": { "element": "METAL" }
    },
    "time": {
      "chinese": "壬午",
      "element": "WATER",
      "animal": "Horse",
      "branch": { "element": "FIRE" }
    }
  },
  "basicAnalysis": {
    "lifeGua": 1,
    "dayMaster": {
      "stem": "乙",
      "nature": "Yin",
      "element": "WOOD"
    },
    "nobleman": ["子", "申"],
    "intelligence": "巳",
    "skyHorse": "卯",
    "peachBlossom": "酉",
    "fiveFactors": {
      "WOOD": 13,
      "FIRE": 38,
      "EARTH": 0,
      "METAL": 38,
      "WATER": 12
    },
    "eightMansions": {
      "group": "East",
      "lucky": {
        "wealth": "SE",
        "health": "E",
        "romance": "S",
        "career": "N"
      },
      "unlucky": {
        "obstacles": "NW",
        "quarrels": "W",
        "setbacks": "SW",
        "totalLoss": "NE"
      }
    }
  }
}

API Reference

BaziCalculator Class

class BaziCalculator {
  constructor(
    year: number,     // Gregorian year
    month: number,    // Month (1-12)
    day: number,      // Day (1-31)
    hour: number,     // Hour (0-23)
    gender?: GenderType // 'male' | 'female'
  )

  // Main methods
  calculatePillars(): Pillars
  calculateBasicAnalysis(): BasicAnalysis
  getCompleteAnalysis(): CompleteAnalysis
  toString(): string
}

🤝 Contributing

We welcome contributions! See our Contributing Guidelines for details.

Development Setup

# Clone repository
git clone https://github.com/yourusername/bazi-calculator-by-alvamind.git

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

📝 Important Notes

Calculation Methods

• Solar calendar based calculations
• Traditional Chinese time system (12 two-hour periods)
• Standard Stem-Branch (干支) system
• Eight Mansions Feng Shui principles

Limitations

• Time zone considerations
• Lunar calendar approximations
• Regional variations in interpretations

🙏 Acknowledgements

• Traditional Chinese Metaphysics texts and masters
• Modern Bazi research and practitioners
• Open source community contributors
• Chinese calendar conversion references

📄 License

MIT License - see the LICENSE file for details.

💬 Support

• 📧 Email: support@alvamind.com
• 🐛 Issues: GitHub Issues
• 📚 Wiki: Documentation

🌟 References

1. Chinese Metaphysics Classics
2. Modern Bazi Analysis Methods
3. Traditional Calendar Systems
4. Stem-Branch Theory