{"_id":"@baostudio/viet-lunar","_rev":"2-e4c2d028226fdb1aa998b0539bae5578","name":"@baostudio/viet-lunar","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@baostudio/viet-lunar","version":"0.1.0","keywords":["vietnamese","lunar","calendar","can-chi","hoang-dao","viet-nam","am-lich","tet"],"author":{"name":"Bao Studio"},"license":"MIT","_id":"@baostudio/viet-lunar@0.1.0","maintainers":[{"name":"b_kun","email":"ddquangbao@gmail.com"}],"homepage":"https://github.com/baostudio/viet-lunar#readme","bugs":{"url":"https://github.com/baostudio/viet-lunar/issues"},"dist":{"shasum":"9855fd9217428bf498dc15c03ade2735de59cf72","tarball":"https://registry.npmjs.org/@baostudio/viet-lunar/-/viet-lunar-0.1.0.tgz","fileCount":31,"integrity":"sha512-3CJcoaH9g2p9TezDuQ6zsdc9qAD4rnRY2R4KvXYfU1wiOk+qgtLhE80nBn6FXQ1M/xLF1IlV1NS5fabNHPu+jg==","signatures":[{"sig":"MEYCIQDVVRG4eAwBXoo/Pzg0GnQSps8LDOAGt706Tg83p7H6ZAIhANDvZHv1jjdJF6VKDAT+Se+QqXwHEhdbiaoUbJ/4+jfO","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":143597},"main":"./dist/cjs/index.cjs","type":"module","types":"./dist/types/index.d.ts","module":"./dist/esm/index.js","exports":{".":{"types":"./dist/types/index.d.ts","import":"./dist/esm/index.js","require":"./dist/cjs/index.cjs"}},"gitHead":"10f4973f3bae0ffa312c346e2aa2ec86e6df911f","scripts":{"lint":"eslint . --ext .ts","test":"bun test","build":"bun run build:esm && bun run build:cjs && bun run build:types","build:cjs":"bun build ./src/index.ts --outfile=dist/cjs/index.cjs --target=node --format=cjs","build:esm":"bun build ./src/index.ts --outfile=dist/esm/index.js --target=node --format=esm","test:watch":"bun test --watch","build:types":"tsc -p tsconfig.json --emitDeclarationOnly --declarationDir dist/types","prepublishOnly":"bun run build && bun test"},"_npmUser":{"name":"b_kun","email":"ddquangbao@gmail.com"},"repository":{"url":"git+https://github.com/baostudio/viet-lunar.git","type":"git"},"_npmVersion":"10.8.2","description":"Vietnamese Lunar Calendar library for TypeScript - Convert between Solar ↔ Lunar calendar, compute Can-Chi, Solar Terms, and Vietnamese auspicious/inauspicious rules","directories":{},"_nodeVersion":"20.19.3","_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/viet-lunar_0.1.0_1762332389181_0.08970383757946943","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@baostudio/viet-lunar","version":"0.1.1","description":"Vietnamese Lunar Calendar library for TypeScript - Convert between Solar ↔ Lunar calendar, compute Can-Chi, Solar Terms, and Vietnamese auspicious/inauspicious rules","keywords":["vietnamese","lunar","calendar","can-chi","hoang-dao","viet-nam","am-lich","tet"],"author":{"name":"Bao Studio"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/baostudio/viet-lunar.git"},"type":"module","main":"./dist/cjs/index.cjs","module":"./dist/esm/index.js","types":"./dist/types/index.d.ts","exports":{".":{"import":"./dist/esm/index.js","require":"./dist/cjs/index.cjs","types":"./dist/types/index.d.ts"}},"scripts":{"build":"bun run build:esm && bun run build:cjs && bun run build:types","build:esm":"bun build ./src/index.ts --outfile=dist/esm/index.js --target=node --format=esm","build:cjs":"bun build ./src/index.ts --outfile=dist/cjs/index.cjs --target=node --format=cjs","build:types":"tsc -p tsconfig.json --emitDeclarationOnly --declarationDir dist/types","test":"bun test","test:watch":"bun test --watch","lint":"eslint . --ext .ts","prepublishOnly":"bun run build && bun test"},"devDependencies":{"@types/bun":"latest","typescript":"^5.0.0"},"_id":"@baostudio/viet-lunar@0.1.1","gitHead":"b9904c2219414538dd65c2ee763ebd6a3d224d76","bugs":{"url":"https://github.com/baostudio/viet-lunar/issues"},"homepage":"https://github.com/baostudio/viet-lunar#readme","_nodeVersion":"20.19.3","_npmVersion":"10.8.2","dist":{"integrity":"sha512-RiLKjtxoPfvNYvBr9ueHXlWPPFixYjxpGuY+XJBYXoCW7OENBXCOxAAY55N/Qt8iEbfW+wqSN6Kx9mHB9SX1jg==","shasum":"8796f569b2edd62132bbcc539697eabde0ec476d","tarball":"https://registry.npmjs.org/@baostudio/viet-lunar/-/viet-lunar-0.1.1.tgz","fileCount":31,"unpackedSize":147084,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDOYEdk4deSUAJZ1KRUOs9lnt0SWHfMYlB8RpagypJlxgIhAPNN8fkgwhrRxP/xFyJV2UhzTr7++yZZ3ZltvlbhJb4O"}]},"_npmUser":{"name":"b_kun","email":"ddquangbao@gmail.com"},"directories":{},"maintainers":[{"name":"b_kun","email":"ddquangbao@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/viet-lunar_0.1.1_1762400173097_0.11481510896621838"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-05T08:46:29.023Z","modified":"2025-11-06T03:36:13.510Z","0.1.0":"2025-11-05T08:46:29.365Z","0.1.1":"2025-11-06T03:36:13.293Z"},"bugs":{"url":"https://github.com/baostudio/viet-lunar/issues"},"author":{"name":"Bao Studio"},"license":"MIT","homepage":"https://github.com/baostudio/viet-lunar#readme","keywords":["vietnamese","lunar","calendar","can-chi","hoang-dao","viet-nam","am-lich","tet"],"repository":{"type":"git","url":"git+https://github.com/baostudio/viet-lunar.git"},"description":"Vietnamese Lunar Calendar library for TypeScript - Convert between Solar ↔ Lunar calendar, compute Can-Chi, Solar Terms, and Vietnamese auspicious/inauspicious rules","maintainers":[{"name":"b_kun","email":"ddquangbao@gmail.com"}],"readme":"# 🌙 Vietnamese Lunar Calendar (`viet-lunar`)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)\n[![Bun](https://img.shields.io/badge/Bun-1.0+-black.svg)](https://bun.sh/)\n\nA comprehensive, deterministic TypeScript library for the **Vietnamese Lunar Calendar** (Âm Lịch Việt Nam). Convert between Solar ↔ Lunar dates, compute Can-Chi (Sexagenary cycles), Solar Terms (24 Tiết Khí), Hoàng Đạo hours, and Vietnamese auspicious/inauspicious day rules.\n\n---\n\n## ✨ Features\n\n- ✅ **Accurate Solar ↔ Lunar Conversion** with Vietnamese timezone (UTC+7)\n- ✅ **Can-Chi (干支) Calculations** for year, month, day, and hour\n- ✅ **24 Solar Terms (Tiết Khí)** computation\n- ✅ **Hoàng Đạo Hours** (Auspicious hours for daily activities)\n- ✅ **Vietnamese Day Analysis** (Nên/Kiêng - Should Do/Avoid)\n- ✅ **12 Trực (建除十二客)** and 28 Lunar Mansions (Nhị Thập Bát Tú)\n- ✅ **Vietnamese Holidays** detection (Tết, Giỗ Tổ, Trung Thu, etc.)\n- ✅ **Leap Month** handling\n- ✅ **Dual Localization** (Vietnamese & English)\n- ✅ **Pure Functions** - deterministic and testable\n- ✅ **ESM + CJS** exports\n\n---\n\n## 📦 Installation\n\n```bash\n# Using npm\nnpm install @baostudio/viet-lunar\n\n# Using bun\nbun add @baostudio/viet-lunar\n\n# Using yarn\nyarn add @baostudio/viet-lunar\n```\n\n---\n\n## 🚀 Quick Start\n\n```typescript\nimport { solarToLunar, analyzeDay } from '@baostudio/viet-lunar';\n\n// Convert solar to lunar date\nconst lunar = solarToLunar({ year: 2024, month: 2, day: 10 });\nconsole.log(lunar); \n// { year: 2024, month: 1, day: 1, leapMonth: false } - Tết 2024!\n\n// Analyze a day\nconst analysis = analyzeDay({ year: 2025, month: 11, day: 4 });\nconsole.log(analysis.lunar);      // Lunar date\nconsole.log(analysis.canChi);     // Can-Chi for year, month, day\nconsole.log(analysis.nen);        // Activities recommended\nconsole.log(analysis.kieng);      // Activities to avoid\nconsole.log(analysis.quality);    // Day quality: excellent/good/neutral/poor/bad\n```\n\n---\n\n## 📖 API Documentation\n\n### Core Conversions\n\n#### `solarToLunar(solar: SolarDate): LunarDate`\n\nConvert a Gregorian (solar) date to Vietnamese lunar date.\n\n```typescript\nimport { solarToLunar } from '@baostudio/viet-lunar';\n\nconst lunar = solarToLunar({ year: 2024, month: 2, day: 10 });\n// Returns: { year: 2024, month: 1, day: 1, leapMonth: false }\n```\n\n#### `lunarToSolar(lunar: LunarDate): SolarDate`\n\nConvert a Vietnamese lunar date to Gregorian date.\n\n```typescript\nimport { lunarToSolar } from '@baostudio/viet-lunar';\n\nconst solar = lunarToSolar({ year: 2025, month: 1, day: 1, leapMonth: false });\n// Returns: { year: 2025, month: 1, day: 29 } - Tết 2025\n```\n\n---\n\n### Can-Chi (Sexagenary) Calculations\n\n#### `getCanChiYear(year: number): Sexagenary`\n\nGet the Can-Chi for a year.\n\n```typescript\nimport { getCanChiYear } from '@baostudio/viet-lunar';\n\nconst yearCanChi = getCanChiYear(2024);\n// Returns: { stem: \"Giáp\", branch: \"Thìn\", code: 40 }\n```\n\n#### `getCanChiDay(solar: SolarDate): Sexagenary`\n\nGet the Can-Chi for a specific day.\n\n```typescript\nimport { getCanChiDay } from '@baostudio/viet-lunar';\n\nconst dayCanChi = getCanChiDay({ year: 2025, month: 11, day: 4 });\n// Returns: { stem: \"Bính\", branch: \"Tý\", code: 12 }\n```\n\n#### `getAllCanChi(solar: SolarDate, hour?: number): CanChiInfo`\n\nGet all Can-Chi (year, month, day, hour) for a date.\n\n```typescript\nimport { getAllCanChi } from '@baostudio/viet-lunar';\n\nconst canChi = getAllCanChi({ year: 2025, month: 11, day: 4 }, 9);\nconsole.log(canChi.year);   // Year Can-Chi\nconsole.log(canChi.month);  // Month Can-Chi\nconsole.log(canChi.day);    // Day Can-Chi\nconsole.log(canChi.hour);   // Hour Can-Chi\n```\n\n---\n\n### Day Analysis\n\n#### `analyzeDay(solar: SolarDate, options?: AnalysisOptions): DayAnalysis`\n\nComprehensive analysis of a day including:\n- Lunar date\n- Can-Chi for year, month, day, hour\n- Solar term\n- Hoàng Đạo hours\n- Trực (12 Positions)\n- Nên (recommended activities)\n- Kiêng (activities to avoid)\n- Holidays\n- Overall quality\n\n```typescript\nimport { analyzeDay } from '@baostudio/viet-lunar';\n\nconst analysis = analyzeDay(\n  { year: 2025, month: 11, day: 4 },\n  { hour: 9, locale: 'vi' }\n);\n\nconsole.log(analysis.lunar);           // { year: 2025, month: 9, day: 15, leapMonth: false }\nconsole.log(analysis.canChi.day);      // Day's Can-Chi\nconsole.log(analysis.hoangDao.hours);  // [\"Tý\", \"Sửu\", \"Mão\", ...]\nconsole.log(analysis.nen);             // [\"cưới hỏi\", \"khai trương\", ...]\nconsole.log(analysis.kieng);           // [\"động thổ\", ...]\nconsole.log(analysis.quality);         // \"good\"\n```\n\n#### `findGoodDays(startDate, endDate, criteria?): DayAnalysis[]`\n\nFind good days within a date range.\n\n```typescript\nimport { findGoodDays } from '@baostudio/viet-lunar';\n\nconst goodDays = findGoodDays(\n  { year: 2025, month: 11, day: 1 },\n  { year: 2025, month: 11, day: 30 },\n  'excellent'\n);\n\nconsole.log(`Found ${goodDays.length} excellent days`);\n```\n\n---\n\n### Solar Terms\n\n#### `getSolarTerm(solar: SolarDate): SolarTerm | undefined`\n\nGet the solar term if the date falls on one.\n\n```typescript\nimport { getSolarTerm } from '@baostudio/viet-lunar';\n\nconst term = getSolarTerm({ year: 2024, month: 2, day: 4 });\n// Returns solar term if date is Lập Xuân, Vũ Thủy, etc.\n```\n\n---\n\n### Formatting\n\n#### `toRichText(analysis: DayAnalysis, locale?: 'vi' | 'en'): string`\n\nFormat analysis result as rich text.\n\n```typescript\nimport { toRichText, analyzeDay } from '@baostudio/viet-lunar';\n\nconst analysis = analyzeDay({ year: 2025, month: 11, day: 4 });\nconst text = toRichText(analysis, 'vi');\nconsole.log(text);\n```\n\n---\n\n## 🎯 Use Cases\n\n### 1. Wedding Date Selection\n\n```typescript\nimport { findDaysForActivity } from '@baostudio/viet-lunar';\n\nconst weddingDays = findDaysForActivity(\n  { year: 2025, month: 12, day: 1 },\n  { year: 2026, month: 2, day: 28 },\n  'cưới hỏi'\n);\n\nconsole.log(`Found ${weddingDays.length} suitable days for weddings`);\n```\n\n### 2. Business Opening\n\n```typescript\nimport { analyzeDay } from '@baostudio/viet-lunar';\n\nconst analysis = analyzeDay({ year: 2025, month: 11, day: 4 });\n\nif (analysis.nen.includes('khai trương')) {\n  console.log('Good day to open business!');\n  console.log('Auspicious hours:', analysis.hoangDao.hours);\n}\n```\n\n### 3. Calendar Widget\n\n```typescript\nimport { analyzeDay, toDisplayObject } from '@baostudio/viet-lunar';\n\nconst today = { year: 2025, month: 11, day: 4 };\nconst analysis = analyzeDay(today);\nconst display = toDisplayObject(analysis, 'vi');\n\n// Use display object in your UI\n// display.date.lunar, display.canChi, display.recommendations, etc.\n```\n\n---\n\n## 🧪 Testing\n\n```bash\n# Run tests\nbun test\n\n# Run with watch mode\nbun test --watch\n```\n\n---\n\n## 🏗️ Building\n\n```bash\n# Build all formats (ESM + CJS + Types)\nbun run build\n\n# Build individual formats\nbun run build:esm\nbun run build:cjs\nbun run build:types\n```\n\n---\n\n## 📚 Documentation\n\nFor detailed documentation on algorithms and Vietnamese lunar calendar rules, see:\n\n- [01-chuyen-doi-duong-lich-sang-am-lich.md](./docs/01-chuyen-doi-duong-lich-sang-am-lich.md) - Solar↔Lunar conversion\n- [02-cach-tinh-can-chi.md](./docs/02-cach-tinh-can-chi.md) - Can-Chi calculations\n- [03-gio-hoang-dao.md](./docs/03-gio-hoang-dao.md) - Hoàng Đạo hours\n- [04-luan-ngay-tot-xau.md](./docs/04-luan-ngay-tot-xau.md) - Day quality rules\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n---\n\n## 📄 License\n\nMIT License - see [LICENSE](./LICENSE) for details\n\n---\n\n## 🙏 Acknowledgments\n\n- Based on Vietnamese astronomical calculations and traditional calendar rules\n- Algorithms adapted from Jean Meeus' \"Astronomical Algorithms\"\n- Vietnamese calendar research by Prof. Hoàng Xuân Hãn\n\n---\n\n## 📮 Contact\n\nCreated by **Bao Studio**\n\nFor issues or questions, please open an issue on GitHub.\n\n---\n\n**Built with ❤️ using [Bun](https://bun.sh/) and TypeScript**\n","readmeFilename":"README.md"}