# π SolarLunar
**Professional Solar-Lunar Calendar Conversion Library**
[](https://www.npmjs.com/package/solarlunar)
[](LICENSE)
[](https://www.npmjs.com/package/solarlunar)
[](https://github.com/yize/solarlunar/actions)
[](https://bundlephobia.com/package/solarlunar)
_High-performance solar-lunar calendar conversion with倩干ε°ζ―, ηθ, and 24 solar terms support_
---
## π Features
- ** blazing Fast**: >340,000 conversions per second
- **Accurate**: Precise calculations for 1900-2100 period
- **Complete**: Full support for 倩干ε°ζ―, ηθ, and 24 solar terms
- **Modern**: ESM, CJS, and UMD module support
- **Typed**: Full TypeScript support
- **Lightweight**: Zero dependencies
- **Reliable**: 100% test coverage
## π¦ Installation
```bash
npm install solarlunar
```
> **Note**: Use lowercase `solarlunar` (not `solarLunar`) when importing. Some case-sensitive file systems may fail to resolve the package with uppercase letters.
## π οΈ Quick Start
### ES6 Modules
```javascript
import solarLunar from 'solarlunar';
// Solar to Lunar
const lunar = solarLunar.solar2lunar(2023, 10, 15);
console.log(lunar.lYear, lunar.lMonth, lunar.lDay); // 2023 8 30
// Lunar to Solar
const solar = solarLunar.lunar2solar(2023, 8, 30);
console.log(solar.cYear, solar.cMonth, solar.cDay); // 2023 10 15
```
### CommonJS
```javascript
const solarLunar = require('solarlunar');
```
### Browser
```html
```
## π API Reference
### solarLunar.solar2lunar(year, month, day)
Convert solar date to lunar date.
**Parameters:**
- `year` (Number): Solar year (1900-2100)
- `month` (Number): Solar month (1-12)
- `day` (Number): Solar day (1-31)
**Returns:** Object with lunar date information
### solarLunar.lunar2solar(year, month, day, isLeapMonth?)
Convert lunar date to solar date.
**Parameters:**
- `year` (Number): Lunar year (1900-2100)
- `month` (Number): Lunar month (1-12)
- `day` (Number): Lunar day (1-30)
- `isLeapMonth` (Boolean, optional): Whether it's a leap month
**Returns:** Object with solar date information
## π― Returned Object Structure
```javascript
{
// Basic lunar info
lYear: 2023, // Lunar year
lMonth: 8, // Lunar month
lDay: 30, // Lunar day
isLeap: false, // Whether leap month
// Basic solar info
cYear: 2023, // Solar year
cMonth: 10, // Solar month
cDay: 15, // Solar day
isToday: false, // Whether today
// Chinese representations
yearCn: 'δΊιΆδΊδΈεΉ΄', // Chinese year
monthCn: 'ε
«ζ', // Chinese month
dayCn: 'δΈε', // Chinese day
ncWeek: 'ζζζ₯', // Chinese weekday
// Stems and Branches
gzYear: 'ηΈε―', // Year stem-branch
gzMonth: 'θΎι
', // Month stem-branch
gzDay: 'η²ε', // Day stem-branch
// Zodiac and terms
animal: 'ε
', // Zodiac animal
isTerm: false, // Whether solar term day
term: '', // Solar term name if applicable
// Weekday info
nWeek: 7 // Weekday number (1-7 for Mon-Sun)
}
```
## π§ͺ Examples
### Complete Conversion
```javascript
const result = solarLunar.solar2lunar(2023, 12, 22); // Winter Solstice day
console.log(result);
/*
{
lYear: 2023, lMonth: 11, lDay: 10,
yearCn: 'δΊιΆδΊδΈεΉ΄', monthCn: 'ε¬ζ', dayCn: 'εε',
gzYear: 'ηΈε―', gzMonth: 'ηΈδΈ', gzDay: 'η²ζ',
animal: 'ε
',
isTerm: true, term: 'ε¬θ³',
cYear: 2023, cMonth: 12, cDay: 22,
isToday: false, isLeap: false,
nWeek: 5, ncWeek: 'ζζδΊ'
}
*/
```
### Zodiac Calculation
```javascript
// Precise zodiac based on Spring Festival
const animal = solarLunar.getAnimal(2023, 2, 5); // Accurate based on η«ζ₯
```
### Solar Term Detection
```javascript
const hasTerm = solarLunar.solar2lunar(2023, 12, 22);
if (hasTerm.isTerm) {
console.log(`Today is ${hasTerm.term} solar term!`);
}
```
## ποΈ Architecture
### Modern Build System
- **Rollup 4**: Optimized builds with tree-shaking
- **Vitest**: Fast, modern testing framework
- **ESLint + Prettier**: Code quality and formatting
- **TypeScript**: Complete type definitions
### Performance Optimizations
- Optimized algorithms for date calculations
- Precomputed data structures
- Efficient memory usage
- Fast lookup mechanisms
## π Performance
| Operation | Average Time | Throughput |
| ------------------ | ------------ | ------------------- |
| Solar to Lunar | < 0.003ms | >340,000 ops/sec |
| Lunar to Solar | < 0.004ms | >270,000 ops/sec |
| Zodiac Calculation | < 0.001ms | >41,000,000 ops/sec |
## π‘οΈ Reliability
- **57 Test Cases**: 100% pass rate
- **1900-2100 Support**: Full century range coverage
- **Boundary Testing**: Extensive edge case validation
- **Security Audited**: Clean dependency tree
## π Documentation
- [Quick Start Guide](QUICKSTART.md)
- [API Documentation](API.md)
- [Usage Examples](EXAMPLES.md)
- [Development Guide](DEVELOPMENT.md)
- [Release Notes](RELEASE-NOTES.md)
## π€ Contributing
We welcome contributions! Please see our [Development Guide](DEVELOPMENT.md) for how to get started.
### Development Commands
```bash
npm install # Install dependencies
npm test # Run tests
npm run test:watch # Watch mode for tests
npm run dev # Development build watch
npm run build # Production build
npm run lint # Code quality check
npm run format # Code formatting
npm run perf # Performance benchmark
npm run typecheck # Type checking
npm run security # Security audit
```
## π License
ISC License - Free and open source.
## π Acknowledgments
Based on the original work by [JJonline](http://blog.jjonline.cn/userInterFace/173.html), modernized and enhanced for contemporary JavaScript environments.
---
**Made with β€οΈ for the JavaScript Community**
[Get Started](#-quick-start) β’ [API Docs](API.md) β’ [Examples](EXAMPLES.md) β’ [Report Issue](https://github.com/yize/solarlunar/issues)