lunaris

lunaris 是零依赖 TypeScript 日期库，提供公历、农历、二十四节气、四柱八字、命盘、大运流年流月流日、黄历宜忌、纳音、胎神、节日标记和多语言输出。

核心目标是把传统历法能力放进一个稳定的包入口。默认导出 lunaris() 创建日期实例，具名导出提供全部类、工具函数、常量和类型。

特性

• 公历与农历互转，覆盖农历主数据区间 1901-02-19 至 2101-01-28，并兼容 1901 年春节前的 1900 年农历尾段。
• 二十四节气使用寿星天文算法，提供日精度节气表和精确时刻。
• 四柱八字支持年柱换岁节气、正月初一换岁和早晚子时配置，并支持由四柱干支反查匹配的公历日期。
• 命盘提供十神、四柱神煞、胎元、胎息、命宫、身宫、空亡和长生十二宫。
• 运势系统提供起运、大运、小运、流年、流月和流日。
• 黄历提供宜忌。
• 干支体系提供天干、地支、六十甲子、藏干、三会、三合、六合、刑冲破害、五行和八卦。
• Markers 提供公历节日、农历节日、周序节日和函数式日期标记。
• 内建 zh、zh-cn、en、ja 语言包，支持注册自定义语言包。
• format、diff、add 支持公历单位和农历单位。

安装

pnpm add lunaris

npm install lunaris

快速上手

import lunaris, { Markers, festivalsZh } from 'lunaris'

const d = lunaris('2025-10-07 14:30')

// 公历、农历、格式化
d.format('YYYY-MM-DD HH:mm:ss')         // 2025-10-07 14:30:00
d.format('lY年 lM(lL)lD lH時')          // 二〇二五年 八月(小)十六 未時
d.lunar.toString()                      // 二〇二五年八月十六未時

// 四柱、纳音、胎神、节气
d.fourPillars.toString()                // 乙巳 乙酉 己酉 辛未
d.takeSound                             // 大驛土
d.fetalGod                              // 占大門外東北
d.recentSolarTerm(0)[0].name            // 白露

// 四柱反查公历日期（可能多解，如时柱地支为子时跨早晚子时两解）
lunaris.fromFourPillars(['癸卯', '甲子', '甲子', '甲子'])
  .map(r => r.format('YYYY-MM-DD HH:mm:ss'))  // ['2023-12-31 23:00:00', '2024-01-01 00:00:00']

// 命盘与运势
const chart = d.natalChart(1)            // 1 男/乾造，0 女/坤造
chart.genderName                         // 乾造
chart.year.stemTenGod.name               // 年柱天干十神
chart.year.stemTenGod.shortName          // 十神单字简称（如 官/殺/財）
chart.gods.year.map(String)              // 年柱神煞

const fortune = chart.fortune({ precision: 'minute' })
const major = fortune.getMajorFortunes()[1]
major.stemBranch?.name                   // 大运干支
major.getYearlyFortunes()[0]
  .getMonthlyFortunes()[0]
  .getDailyFortunes()[0]
  .stemBranch.name                       // 流日干支

// 黄历
d.almanac.getGoodActs()                  // 今日宜
d.almanac.getBadActs()                   // 今日忌

// 节日标记
Markers.add(festivalsZh)
lunaris('2024-02-10').markers.list.map(m => m.name) // ['國際氣象節', '春節']

常用入口

| 入口 | 说明 | | --- | --- | | lunaris(date?, config?) | 创建 Lunaris 实例。 | | lunaris.utc(date?, config?) | 按 UTC 语义创建实例。 | | lunaris.fromLunar(param, config?) | 由农历参数反查公历并创建实例。 | | lunaris.fromFourPillars(pillars, options?) | 由四柱干支反查匹配的公历日期并创建实例列表（可能多解）。 | | lunaris.config(config) | 更新全局配置。 | | lunaris.locale(localeData, unChangeLang?) | 注册语言包。 | | d.lunar | 农历对象 Lunar。 | | d.fourPillars | 四柱对象 FourPillars。 | | d.natalChart(gender) | 八字命盘 NatalChart。 | | d.almanac | 黄历对象 Almanac。 | | d.markers | 节日标记对象 Markers。 | | d.format(fmt) | 格式化输出。 | | d.diff(date, unit?, float?) | 日期差值，支持农历单位。 | | d.add(value, unit?) | 日期加法。 |

文档

完整文档位于 docs。

| 文档 | 内容 | | --- | --- | | 快速开始 | 安装、导入、创建实例、配置和典型流程。 | | 核心日期 API | lunaris()、Lunaris、日期属性、时区、差值和加法。 | | 农历与节气 | Lunar、农历反查、二十四节气、胎神和天文工具。 | | 干支与四柱 | 天干、地支、六十甲子、五行、八卦和四柱。 | | 命盘与运势 | NatalChart、Pillar、十神、神煞、起运、大运、小运、流年、流月、流日。 | | 黄历 | 宜忌 API。 | | 节日标记 | 全局标记、实例标记、内置节日和标记工具函数。 | | 格式化与语言包 | 格式化令牌、语言包结构、自定义语言包和翻译工具。 | | 工具函数与类型 | 从包入口导出的工具函数、常量、类型和完整导出清单。 |

配置

import lunaris from 'lunaris'

lunaris.config({
  lang: 'zh-cn',
  changeAgeTerm: 2,
  ziHourSplit: true,
})

const d = lunaris('2024-03-01 23:30', {
  lang: 'en',
  ziHourSplit: false,
})

| 配置项 | 类型 | 说明 | | --- | --- | --- | | lang | string | 语言包名称，内建 zh、zh-cn、en、ja。 | | isUTC | boolean | 是否使用 UTC 字段读取。 | | offset | number | UTC 偏移分钟数。 | | changeAgeTerm | number \| null | 年柱换岁节气索引，默认 2 表示立春，null 表示正月初一换岁。 | | ziHourSplit | boolean | true 表示晚子时 23:00-24:00 的日柱按次日计。 |

开发

pnpm test
pnpm test:coverage
pnpm typecheck
pnpm build
pnpm typecheck:dist   # 对打包后的 dist/index.d.mts 做消费者视角类型检查，随 prepublishOnly 自动执行
pnpm gen:golden

测试覆盖公历农历换算、节气、格式化、四柱、命盘、运势、黄历、节日标记和语言包。

License

MIT