# ๐๏ธ Brahma Muhurat Calculator
### *The most auspicious time for your spiritual practice*
[](https://www.npmjs.com/package/brahma-muhurat)
[](https://www.npmjs.com/package/brahma-muhurat)
[](https://github.com/rakshitbharat/brahma-muhurat/blob/main/LICENSE)
[](https://github.com/rakshitbharat/brahma-muhurat)
**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
```bash
npm install brahma-muhurat
```
### JavaScript Usage
```javascript
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
```typescript
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
๐๏ธ View Project Structure
```
๐๏ธ 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
๐ Multiple Locations
```javascript
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}`);
});
```
๐
Batch Processing
```javascript
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}`);
});
```
๐๏ธ High Altitude & Atmospheric Conditions
```javascript
// 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'
});
```
๐ฏ Precision Comparison
```javascript
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
๐๏ธ Constructor Options
```javascript
const calculator = new BrahmaMuhuratCalculator({
precision: 'high', // 'basic' | 'high' | 'maximum'
traditionType: 'standard', // 'standard' | 'extended' | 'smarta' | 'dynamic'
refractionModel: 'bennett' // 'bennett' | 'saemundsson' | 'rigorous'
});
```
๐ TypeScript Support
Full TypeScript integration with comprehensive type definitions:
```typescript
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:**
```bash
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](docs/TYPESCRIPT_GUIDE.md)
๐ฏ Main Methods
### `calculate(params)` - Main calculation method
```javascript
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
```javascript
const results = calculator.calculateBatch(baseParams, ['2024-02-18', '2024-02-19']);
```
### `calculateSunrise(params)` - Sunrise only
```javascript
const sunrise = calculator.calculateSunrise(params);
```
๐ง Static Utility Methods
```javascript
// 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
```bash
# ๐งช 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
```bash
# ๐ 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](https://github.com/rakshitbharat/brahma-muhurat/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"*
[](https://www.npmjs.com/package/brahma-muhurat)
[](https://github.com/rakshitbharat/brahma-muhurat)
**Made with ๐ง Human Wisdom + ๐ค AI Innovation + ๐ Spiritual Devotion**