Extreme 16-bit binary compressed lunar calendar library.
npm install tinylunar!Node Support !Browser Support !TypeScript !License
本库采用 16 位位字段打包（Bit-packing）协议，将 1901 年至 2100 年的农历数据存储为 143KB 的二进制格式（经 Deflate 压缩嵌入代码后约 50KB）。数据内置于包内，提供同步查询接口，具备 O(1)时间复杂度的检索性能。
- 数据压缩：采用二进制位域编码，显著减小数据体积。
- 零运行时依赖：自包含解压逻辑，无需安装额外的运行库。
- 同步 API：数据随代码加载，无需执行异步网络请求，引入即可调用。
- 原始数据：历法原始数据来源于 香港天文台 (Hong Kong Observatory)。
- 数据解析：本项目采用了由 traditional-chinese-calendar-database 项目提供的 JSON 数据作为构建源，在此表示感谢。
- 使用规范：请在遵守香港天文台相关数据公开使用协议的前提下使用本库。
``bash`
npm install tinylunar或
pnpm add tinylunar
`html`
---
本库默认导出单例对象 lunisolar，所有查询均为同步操作。
#### lunisolar.query()
查询指定日期的详细农历信息。
方法签名
`typescript`
query(date?: Date | string | number, lang?: 'SC' | 'TC'): LunarInfo | null
参数说明
| 参数名 | 是否必选 | 说明 |
| ------ | -------- | ------------------------------------------------------------ |
| date | 否 | 支持 Date 对象、ISO 字符串（YYYY-MM-DD）或时间戳，默认为当前系统时间 |
| lang | 否 | 输出语言：SC（简体），TC（繁体），默认 SC |
------
#### lunisolar.queryMonth()
批量查询指定公历月份的整月数据。
方法签名
`typescript`
queryMonth(year: number, month: number, lang?: 'SC' | 'TC'): (LunarInfo | null)[]
参数说明
| 参数名 | 是否必选 | 说明 |
| ------ | -------- | ----------------------- |
| year | 是 | 公历年份（1901 - 2100） |
| month | 是 | 公历月份（1 - 12） |
| lang | 否 | 输出语言，默认 SC |
返回值说明
- 返回数组长度等于当月天数
- 数组索引 i 对应公历 i + 1 日
------
#### lunisolar.queryYear()
批量查询指定公历年份的整年数据。
方法签名
`typescript`
queryYear(year: number, lang?: 'SC' | 'TC'): (LunarInfo | null)[]
参数说明
| 参数名 | 是否必选 | 说明 |
| ------ | -------- | ----------------------- |
| year | 是 | 公历年份（1901 - 2100） |
| lang | 否 | 输出语言，默认 SC |
------
#### lunisolar.getSolarTerms()
获取指定公历年份全年的 24 节气列表。
方法签名
`typescript`
getSolarTerms(year: number, lang?: 'SC' | 'TC'): SolarTermItem[]
SolarTermItem 结构
`typescript`
{
name: string;
date: { year: number; month: number; day: number };
lunar: string;
}
------
#### lunisolar.getSupportRange()
获取当前数据文件支持的公历年份范围。
方法签名
`typescript`
getSupportRange(): { start: number; end: number }
#### 单日查询
`typescript
import { lunisolar } from 'tinylunar';
const info = lunisolar.query('2026-02-17', 'TC');
console.log(info?.lunar.month); // "正月"
`
#### 月度批量查询
`typescript
import { lunisolar } from 'tinylunar';
const days = lunisolar.queryMonth(2026, 1);
console.log(days[0]?.lunar.date); // "十三" (对应 1月1日)
`
#### 获取节气列表
`typescript`
const terms = lunisolar.getSolarTerms(2025);
const lichun = terms.find(t => t.name === '立春');
// lichun.date -> { year: 2025, month: 2, day: 3 }
---
`typescript`
interface LunarInfo {
day: string; // 星期。例："星期五"
gregorian: {
year: number; // 公历年
month: number; // 公历月 (1-12)
date: number; // 公历日
};
lunar: {
year: string; // 农历干支年。例："戊寅"
month: string; // 农历月。例："正月" 或 "闰六月"
date: string; // 农历日。例："初八"
leapMonth: boolean; // 是否为闰月
};
zodiac: string; // 生肖。例："虎"
solarTerm: string; // 24节气。无节气则为空字符串 ""
}
数据由 12 字节 Header 开头，随后是每单元 2 字节（16-bit）的每日数据块。
`text``
Bit | 15 | 14 13 12 11 10 | 9 | 8 7 6 5 4 | 3 2 1 0 |
+----+----------------+---+----------------+-------------+
| R | Solar | L | Date | Month |
+----+----------------+---+----------------+-------------+
| 位段 (Bits) | 缩写 | 含义 | 说明 |
| :---------- | :---- | :-------- | :------------------------------- |
| 15 | R | Reserved | 预留位，固定填充 0。 |
| 14 - 10 | Solar | 节气索引 | 取值 0-24。0 代表当天无节气。 |
| 9 | L | Leap Flag | 闰月标志。1 为闰月，0 为正常月。 |
| 8 - 4 | Date | 农历日期 | 取值 1-30。对应初一至三十。 |
| 3 - 0 | Month | 农历月份 | 取值 1-12。对应正月至腊月。 |