🕉️ Brahma Muhurat Calculator

The most auspicious time for your spiritual practice

A high-precision JavaScript library for calculating Brahma Muhurat with NASA-grade astronomical accuracy

Calculate the sacred time period occurring approximately 96 minutes before sunrise - the most auspicious time in Hindu tradition for meditation, yoga, and spiritual practices.

✨ Why Choose Brahma Muhurat Calculator?

🎯 Precision • NASA-grade astronomical accuracy with multiple precision levels
🌍 Global • Works anywhere on Earth with proper timezone handling
⚡ Fast • Sub-100ms calculations optimized for performance
🧪 Tested • 83 comprehensive test cases with 60%+ coverage
📱 Universal • Works in Node.js and modern browsers
🔮 Spiritual • Respects Hindu traditions while embracing modern science
📦 Optimized • Minimal 24KB package size for lightning-fast installation

🚀 Quick Start

npm install brahma-muhurat

JavaScript Usage

const BrahmaMuhuratCalculator = require('brahma-muhurat');

// 🎯 Simple calculation
const calculator = new BrahmaMuhuratCalculator();

const result = calculator.calculate({
  latitude: 25.317644,    // 📍 Varanasi, India
  longitude: 83.005495,
  date: '2024-02-18',
  timezone: 'Asia/Kolkata'
});

console.log(`🌅 Brahma Muhurat: ${result.brahmaMuhurat.start.localTime} - ${result.brahmaMuhurat.end.localTime}`);
console.log(`☀️ Sunrise: ${result.sunrise.localTime}`);
console.log(`⏰ Duration: ${result.brahmaMuhurat.duration.formatted}`);

TypeScript Usage

import { CalculationParams, CalculationResult } from 'brahma-muhurat';
const BrahmaMuhuratCalculator = require('brahma-muhurat');

// 🎯 Type-safe calculation
const calculator = new BrahmaMuhuratCalculator({
  precision: 'high',
  traditionType: 'standard',
  refractionModel: 'bennett'
});

const params: CalculationParams = {
  latitude: 25.317644,
  longitude: 83.005495,
  date: '2024-02-18',
  timezone: 'Asia/Kolkata'
};

const result: CalculationResult = calculator.calculate(params);
console.log(`🕉️ Brahma Muhurat: ${result.brahmaMuhurat.start.localTime} - ${result.brahmaMuhurat.end.localTime}`);

🌟 Key Features

🎯 Precision Levels

| Level | Accuracy | Best For | |-------|----------|----------| | basic | ±2-5 minutes | Quick calculations | | high | ±30 seconds | Daily practice (recommended) | | maximum | ±10-30 seconds | Precise ceremonies |

🏛️ Tradition Types

| Type | Duration | Description | |------|----------|-------------| | standard | 96 minutes | Traditional calculation | | extended | 120 minutes | Intensive spiritual practice | | smarta | 96 minutes exact | Orthodox Vedic calculation | | dynamic | Variable | Seasonal day-length based |

🌍 Global Capabilities

• ✅ International locations with timezone intelligence
• ✅ Polar regions handling for extreme latitudes
• ✅ High altitude corrections up to mountain peaks
• ✅ Batch processing for multiple dates/locations
• ✅ Seasonal variations with spiritual significance

🔬 Scientific Accuracy

• 🛰️ NASA-grade algorithms from astronomy-engine
• 🌡️ Atmospheric corrections for pressure, temperature, humidity
• 📐 3 refraction models: Bennett, Sæmundsson, Rigorous
• 🔄 Cross-validation against traditional Panchang (±10min accuracy)
• 🌙 Moon phase calculations with spiritual significance

📁 Project Architecture

🕉️ brahma-muhurat/
├── 📁 src/                          # Source code
│   ├── 📁 core/                     # Core astronomical calculations
│   │   ├── 🧮 astronomical.js       # NASA-grade solar calculations
│   │   ├── 🌫️ refraction.js         # Atmospheric refraction models
│   │   └── 🕉️ muhurat.js            # Brahma Muhurat calculation logic
│   ├── 📁 utils/                    # Utility functions
│   │   ├── ⏰ time.js               # Time utilities and formatting
│   │   └── 🌍 geo.js               # Geographic utilities and validation
│   └── 🎯 index.js                 # Main library entry point
├── 📁 test/                        # Comprehensive test suite
│   ├── 🧪 calculations.test.js     # Core functionality tests
│   ├── 📊 coverage-enhancement.test.js # Coverage improvement tests
│   └── 🔧 utilities-coverage.test.js   # Utility function tests
├── 📁 examples/                    # Working examples
│   ├── 🌱 simple.js               # Basic usage demonstration
│   └── 🚀 advanced.js             # Advanced features showcase
├── 📁 scripts/                    # Automation scripts
│   ├── 🔄 update-dependencies.js  # Automated dependency management
│   ├── 🔧 build.js               # Build verification
│   ├── ✅ check-node-version.js   # Node.js compatibility check
│   └── 🔍 validate-compatibility.js # Environment validation
├── 📁 types/                      # TypeScript definitions
│   └── 📝 index.d.ts             # Complete type definitions
├── 📁 docs/                       # Documentation
│   ├── 📋 AI_PROJECT_PROMPT.md    # Original development specifications
│   ├── 🧮 BRAHMA_MUHURAT_CALCULATION.md # Mathematical documentation
│   ├── 📊 DEVELOPMENT_SUMMARY.md  # Project overview
│   ├── 🧪 TEST_COVERAGE_TYPESCRIPT_SUMMARY.md # Testing details
│   └── 📝 FINAL_DEVELOPMENT_NOTES.md # Complete development notes
├── 📄 package.json               # Package configuration
├── 📖 README.md                  # This beautiful documentation
└── 🔒 .gitignore                # Git ignore patterns

Precision Levels

• basic: ±2-5 minutes accuracy, fastest performance
• high: ±30 seconds to 2 minutes, recommended for most uses
• maximum: ±10-30 seconds, highest accuracy with atmospheric corrections

Tradition Types

• standard: 96 minutes before sunrise (traditional)
• extended: 120 minutes before sunrise (intensive practice)
• smarta: 96 minutes exact (orthodox calculation)
• dynamic: Variable duration based on seasonal day length

Refraction Models

• bennett: Most commonly used, good general accuracy
• saemundsson: More accurate for low altitudes
• rigorous: Highest accuracy with humidity effects

💻 Advanced Usage

const locations = [
  { name: '🇮🇳 Varanasi', lat: 25.317644, lon: 83.005495, tz: 'Asia/Kolkata' },
  { name: '🇺🇸 New York', lat: 40.7128, lon: -74.0060, tz: 'America/New_York' },
  { name: '🇬🇧 London', lat: 51.5074, lon: -0.1278, tz: 'Europe/London' }
];

locations.forEach(loc => {
  const result = calculator.calculate({
    latitude: loc.lat,
    longitude: loc.lon,
    date: '2024-02-18',
    timezone: loc.tz
  });
  console.log(`${loc.name}: ${result.brahmaMuhurat.start.localTime}`);
});

const dates = ['2024-02-18', '2024-02-19', '2024-02-20'];
const batchResults = calculator.calculateBatch({
  latitude: 25.317644,
  longitude: 83.005495,
  timezone: 'Asia/Kolkata'
}, dates);

batchResults.forEach((result, index) => {
  console.log(`Day ${index + 1}: ${result.brahmaMuhurat.start.localTime}`);
});

// Calculate for Mount Kailash (high altitude)
const result = calculator.calculate({
  latitude: 31.0688,      // Mount Kailash
  longitude: 81.3108,
  elevation: 6638,        // High altitude in meters
  pressure: 360,          // Reduced atmospheric pressure
  temperature: -10,       // Cold temperature
  humidity: 0.1,          // Low humidity
  date: '2024-02-18',
  timezone: 'Asia/Kolkata'
});

const precisions = ['basic', 'high', 'maximum'];
const location = { lat: 25.317644, lon: 83.005495, tz: 'Asia/Kolkata' };

precisions.forEach(precision => {
  const calc = new BrahmaMuhuratCalculator({ precision });
  const result = calc.calculate({
    ...location,
    date: '2024-02-18',
    timezone: location.tz
  });
  console.log(`${precision}: ${result.brahmaMuhurat.start.localTime}`);
});

📚 API Reference

const calculator = new BrahmaMuhuratCalculator({
  precision: 'high',           // 'basic' | 'high' | 'maximum'
  traditionType: 'standard',   // 'standard' | 'extended' | 'smarta' | 'dynamic'
  refractionModel: 'bennett'   // 'bennett' | 'saemundsson' | 'rigorous'
});

Full TypeScript integration with comprehensive type definitions:

import { CalculationParams, CalculationResult, CalculatorOptions } from 'brahma-muhurat';
const BrahmaMuhuratCalculator = require('brahma-muhurat');

// Type-safe calculator creation
const calculator = new BrahmaMuhuratCalculator({
  precision: 'high',
  traditionType: 'standard',
  refractionModel: 'bennett'
});

// Type-safe parameters
const params: CalculationParams = {
  latitude: 25.317644,
  longitude: 83.005495,
  date: '2024-02-18',
  timezone: 'Asia/Kolkata'
};

// Type-safe result
const result: CalculationResult = calculator.calculate(params);

TypeScript Examples:

npm run example:typescript        # All TypeScript examples
npm run example:ts-simple        # Basic usage
npm run example:ts-advanced      # Advanced features
npm run example:ts-integration   # Service patterns

📖 Full TypeScript Guide: docs/TYPESCRIPT_GUIDE.md

calculate(params) - Main calculation method

const result = calculator.calculate({
  latitude: 25.317644,         // Decimal degrees (-90 to 90)
  longitude: 83.005495,        // Decimal degrees (-180 to 180)
  elevation: 80,               // Meters above sea level (optional)
  date: '2024-02-18',         // YYYY-MM-DD format
  timezone: 'Asia/Kolkata',    // IANA timezone name
  pressure: 1013.25,          // Atmospheric pressure in mbar (optional)
  temperature: 15,            // Temperature in Celsius (optional)
  humidity: 0.5               // Relative humidity 0-1 (optional)
});

calculateBatch(baseParams, dates) - Multiple dates

const results = calculator.calculateBatch(baseParams, ['2024-02-18', '2024-02-19']);

calculateSunrise(params) - Sunrise only

const sunrise = calculator.calculateSunrise(params);

// Get supported timezones
const timezones = BrahmaMuhuratCalculator.getSupportedTimezones();

// Format coordinates
const formatted = BrahmaMuhuratCalculator.formatCoordinates(25.317644, 83.005495);

// Validate coordinates
const isValid = BrahmaMuhuratCalculator.validateCoordinates(25.317644, 83.005495);

// Get library information
const info = BrahmaMuhuratCalculator.getLibraryInfo();

🧪 Testing & Quality

# 🧪 Run comprehensive test suite (83 tests)
npm test

# 📊 Run with coverage report
npm run test:coverage

# 🔍 Code linting
npm run lint

# 🚀 Try examples
npm run example          # Simple usage
npm run example:advanced # Advanced features

# 📝 TypeScript examples
npm run example:typescript        # All TypeScript examples
npm run example:ts-simple        # Simple TypeScript example
npm run example:ts-advanced      # Advanced TypeScript features
npm run example:ts-integration   # TypeScript integration patterns

Quality Metrics:

• ✅ 83 tests passing with comprehensive edge cases
• ✅ 60.52% test coverage across all modules
• ✅ Zero ESLint issues - clean, maintainable code
• ✅ Cross-validated against traditional Panchang calculations
• ✅ Performance tested - all calculations under 100ms

🌍 Spiritual Context & Cultural Significance

"Brahma Muhurat is the time of Brahma - the creator. It is the most auspicious time for spiritual practices, when the mind is naturally calm and conducive to meditation."

🙏 Perfect for:

• 🧘 Meditation and Pranayama - Enhanced focus and awareness
• 📿 Mantra Recitation - Amplified spiritual vibrations
• 📖 Scripture Study - Improved comprehension and retention
• 🕉️ Yoga Practice - Optimal mind-body harmony
• 🪔 Religious Ceremonies - Maximum spiritual benefit

🌅 Traditional Significance:

• Sattvic Period: Time when Sattva (purity) dominates
• Divine Connection: Easier access to higher consciousness
• Mental Clarity: Natural state of alertness and focus
• Spiritual Progress: Accelerated spiritual development
• Energy Alignment: Optimal cosmic energy for transformation

🛠️ Development Scripts

# 🔄 Check for dependency updates
npm run check-latest

# ⬆️ Update dependencies automatically  
npm run update-deps

# ✅ Validate environment compatibility
npm run validate-deps

# 🔧 Build verification
npm run build

🤝 Human-AI Partnership

This library is a product of collaborative innovation between human wisdom and AI assistance.

Developed through the synergy of traditional spiritual knowledge, modern astronomical science, and cutting-edge AI technology.

👥 The Collaboration:

• 🧠 Human Vision: Spiritual understanding, cultural authenticity, and practical requirements
• 🤖 AI Assistance: Code optimization, testing strategies, and technical implementation
• 🔬 Scientific Accuracy: NASA-grade algorithms with traditional validation
• 🙏 Cultural Respect: Honoring Hindu traditions while embracing modern technology

This partnership demonstrates how AI can augment human creativity and domain expertise to create tools that serve both technical excellence and spiritual practice.

🌐 Compatibility & Requirements

| Environment | Version | Status | |-------------|---------|--------| | Node.js | 12.0.0+ | ✅ Fully Supported | | Browser | ES6+ | ✅ Fully Supported | | TypeScript | 4.0+ | ✅ Full Type Definitions | | React/Vue/Angular | Any | ✅ Framework Agnostic |

📄 License & Contributing

📜 License

MIT License - Free for personal and commercial use

🤝 Contributing

We welcome contributions! Please:

1. 🍴 Fork the repository
2. 🌿 Create a feature branch
3. ✅ Ensure all tests pass
4. 📝 Add documentation for new features
5. 🚀 Submit a pull request

💬 Support & Community

• 🐛 Issues: GitHub Issues
• 📖 Documentation: Comprehensive guides and examples
• 💡 Feature Requests: We'd love to hear your ideas!

🙏 Acknowledgments

🌟 Special Thanks:

• Vedic Astronomers for the foundational mathematical principles
• Modern Astronomers for precise celestial mechanics
• Open Source Community for the astronomical libraries
• Spiritual Practitioners for validation and feedback
• AI Technology for enhancing development capabilities

📚 Based on:

• Traditional Hindu astronomical calculations (Jyotisha)
• Modern astronomical algorithms and NASA data
• Atmospheric science research
• Cross-cultural spiritual practices

🕉️ May your spiritual journey be blessed with perfect timing!

"Time is the most precious gift - use it wisely for spiritual growth"

Made with 🧠 Human Wisdom + 🤖 AI Innovation + 🙏 Spiritual Devotion