@sanguo-dev/calendar 0.0.0-stage → 1.0.0

package/src/data/festival.json

@@ -0,0 +1,195 @@
+{
+  "sFtv": {
+    "1001": ["国庆节", "国际音乐日", "国际老人节"],
+    "1002": ["国际和平与民主自由斗争日"],
+    "1004": ["世界动物日", "世界住房日", "国际建筑日"],
+    "1005": ["世界教师日"],
+    "1008": ["世界视觉日", "全国高血压日", "世界视力日"],
+    "1009": ["世界邮政日"],
+    "1010": ["世界精神卫生日", "辛亥革命纪念日"],
+    "1011": ["萝莉节"],
+    "1012": ["世界关节炎日"],
+    "1013": ["国际减轻自然灾害日", "世界保健日", "国际标准时间日", "中国少年先锋队诞辰日"],
+    "1014": ["世界标准日"],
+    "1015": ["国际盲人节", "全球洗手日", "世界农村妇女日"],
+    "1016": ["世界粮食节"],
+    "1017": ["国际消除贫困日", "国家扶贫日"],
+    "1019": ["世界镇痛日"],
+    "1020": ["世界骨质疏松日", "世界厨师日"],
+    "1022": ["世界传统医药日"],
+    "1024": ["联合国日", "世界发展信息日"],
+    "1025": ["人类天花绝迹日", "抗美援朝纪念日", "台湾光复纪念日"],
+    "1028": ["世界男性健康日"],
+    "1029": ["圣纪节"],
+    "1031": ["世界勤俭日"],
+    "1101": ["万圣节"],
+    "1108": ["中国记者日", "记者节"],
+    "1109": ["消防宣传日"],
+    "1111": ["光棍节", "双十一购物狂欢节"],
+    "1112": ["吉尼斯世界纪录日"],
+    "1114": ["联合国糖尿病日", "屌丝节"],
+    "1116": ["国际宽容日"],
+    "1117": ["国际大学生节"],
+    "1119": ["世界厕所日"],
+    "1120": ["世界儿童日"],
+    "1121": ["世界电视日", "世界问候日"],
+    "1125": ["国际消除对妇女的暴力日"],
+    "1129": ["国际声援巴勒斯坦人民日"],
+    "1201": ["世界艾滋病日"],
+    "1202": ["全国交通安全日"],
+    "1203": ["国际残疾人日"],
+    "1204": ["全国法制宣传日", "国家宪法日"],
+    "1205": ["国际志愿人员日"],
+    "1207": ["国际民航日"],
+    "1209": ["世界足球日", "国际反腐败日"],
+    "1210": ["世界人权日"],
+    "1212": ["双十二购物狂欢节", "国际儿童电视广播日"],
+    "1213": ["国家公祭日"],
+    "1215": ["世界强化免疫日"],
+    "1218": ["国际移徙者日"],
+    "1219": ["联合国南南合作日"],
+    "1220": ["澳门回归纪念"],
+    "1221": ["国际篮球日"],
+    "1224": ["平安夜", "长津湖战役胜利纪念日"],
+    "1225": ["圣诞节"],
+    "1226": ["毛泽东诞辰日"],
+    "0101": ["元旦"],
+    "0110": ["中国人民警察节"],
+    "0131": ["国际麻风节"],
+    "0126": ["国际海关日"],
+    "0127": ["国际大屠杀纪念日"],
+    "0202": ["世界湿地日"],
+    "0207": ["国际声援南非日"],
+    "0210": ["国际气象节"],
+    "0214": ["情人节"],
+    "0224": ["第三世界青年日"],
+    "0204": ["世界抗癌症日", "世界癌症日"],
+    "0221": ["国际母语日"],
+    "0228": ["国际罕见病日", "世界居住条件调查日"],
+    "0301": ["国际海豹日", "国际民防日"],
+    "0303": ["全国爱耳日"],
+    "0305": ["学雷锋纪念日", "中国青年志愿者服务日"],
+    "0308": ["妇女节"],
+    "0312": ["植树节", "世界肾脏日"],
+    "0314": ["白色情人节", "国际警察日"],
+    "0315": ["消费者权益日"],
+    "0317": ["国际航海日", "中国国医节"],
+    "0320": ["世界无肉日"],
+    "0321": ["世界睡眠日", "世界森林日", "世界儿歌日", "国际消除种族歧视日", "世界诗歌日"],
+    "0322": ["世界水日"],
+    "0323": ["世界气象日"],
+    "0311": ["国际尊严尊敬日"],
+    "0316": ["手拉手情系贫困小伙伴全国统一行动日", "世界社会工作日"],
+    "0324": ["世界防治结核病日"],
+    "0307": ["女生节"],
+    "0306": ["世界青光眼日"],
+    "0327": ["世界戏剧日"],
+    "0309": ["保护母亲河日"],
+    "0318": ["全国科技人才活动日"],
+    "0329": ["全国中小学生安全教育日"],
+    "0410": ["耶稣受难日", "非洲环境保护日"],
+    "0401": ["愚人节"],
+    "0402": ["国际儿童图书日", "世界自闭症日"],
+    "0407": ["世界卫生日"],
+    "0411": ["世界帕金森病日"],
+    "0422": ["世界地球日"],
+    "0423": ["世界读书日", "中国海军建军节"],
+    "0426": ["世界知识产权日", "世界防治疟疾日"],
+    "0404": ["复活节", "清明节"],
+    "0417": ["世界血友病日"],
+    "0418": ["国际古迹遗址日"],
+    "0421": ["秘书节"],
+    "0425": ["全国儿童预防接种宣传日"],
+    "0428": ["世界安全生产与健康日"],
+    "0429": ["化学战受害者纪念日"],
+    "0415": ["全民国家安全教育日"],
+    "0424": ["中国航天日"],
+    "0430": ["全国交通安全反思日"],
+    "0501": ["劳动节"],
+    "0504": ["青年节", "五四运动纪念日"],
+    "0505": ["世界哮喘日", "碘缺乏病防治日"],
+    "0508": ["世界红十字日", "世界微笑日"],
+    "0512": ["国际护士节", "全国防灾减灾日"],
+    "0510": ["中国品牌日"],
+    "0515": ["国际家庭日", "防治碘缺乏病日"],
+    "0517": ["世界电信日", "全国助残日", "世界高血压日"],
+    "0518": ["国际博物馆日"],
+    "0520": ["全国学生营养日", "全国母乳喂养宣传日", "世界计量日"],
+    "0522": ["国际生物多样性日"],
+    "0531": ["世界无烟日"],
+    "0513": ["开斋节"],
+    "0503": ["世界新闻自由日"],
+    "0521": ["世界文化发展日"],
+    "0526": ["世界向人体条件挑战日"],
+    "0529": ["国际维和人员日"],
+    "0509": ["救助贫困母亲日"],
+    "0519": ["中国旅游日"],
+    "0606": ["全国爱眼日"],
+    "0601": ["国际儿童节", "世界牛奶日"],
+    "0605": ["世界环境日"],
+    "0612": ["中国文化遗产日", "世界无童工日"],
+    "0620": ["世界难民日"],
+    "0617": ["世界防治荒漠化和干旱日"],
+    "0623": ["国际奥林匹克日"],
+    "0625": ["全国土地日"],
+    "0626": ["国际禁毒日", "联合国宪章日"],
+    "0604": ["受侵略戕害的无辜儿童国际日"],
+    "0608": ["世界海洋日"],
+    "0614": ["世界献血日"],
+    "0630": ["世界青年联欢节"],
+    "0622": ["中国儿童慈善活动日"],
+    "0701": ["香港回归纪念日", "建党节", "世界建筑日"],
+    "0703": ["国际合作节"],
+    "0711": ["世界人口日", "中国航海日"],
+    "0720": ["古尔邦节", "人类月球日"],
+    "0702": ["国际体育记者日"],
+    "0706": ["国际接吻日"],
+    "0707": ["七七事变纪念日"],
+    "0708": ["世界过敏性疾病日"],
+    "0718": ["纳尔逊·曼德拉国际日"],
+    "0728": ["世界肝炎日"],
+    "0731": ["非洲妇女节"],
+    "0801": ["建军节"],
+    "0803": ["男人节"],
+    "0808": ["八卦节", "全民健身日"],
+    "0809": ["国际土著人日"],
+    "0826": ["纳米比亚日", "全国律师咨询日"],
+    "0815": ["日本无条件投降日"],
+    "0819": ["中国医师节"],
+    "0903": ["中国人民抗日战争纪念日", "中国人民抗日战争胜利纪念日"],
+    "0908": ["国际扫盲日"],
+    "0910": ["教师节", "世界预防自杀日"],
+    "0916": ["国际臭氧层保护日"],
+    "0918": ["中国国耻日", "世界清洁地球日", "九一八事变", "全民国防教育日"],
+    "0920": ["国际爱牙日", "公民道德宣传日"],
+    "0921": ["国际和平日", "世界停火日", "世界阿尔茨海默病日"],
+    "0927": ["国际聋人节", "世界旅游日", "国际聋人日"],
+    "0928": ["孔子诞辰"],
+    "0911": ["世界急救日"],
+    "0915": ["国际民主日"],
+    "0922": ["世界无车日"],
+    "0926": ["世界避孕日"],
+    "0930": ["国际翻译日", "烈士纪念日"],
+    "0905": ["中华慈善日"]
+  },
+  "lFtv": {
+    "0101": ["春节"],
+    "0107": ["人日"],
+    "0115": ["元宵节"],
+    "0202": ["龙抬头", "中和节"],
+    "0303": ["上巳节"],
+    "0505": ["端午节"],
+    "0520": ["分龙节"],
+    "0616": ["鲁班节"],
+    "0707": ["七夕情人节"],
+    "0714": ["鬼节(南方)"],
+    "0715": ["中元节", "盂兰节"],
+    "0815": ["中秋节"],
+    "0909": ["重阳节"],
+    "1001": ["寒衣节"],
+    "1015": ["下元节"],
+    "1208": ["腊八节"],
+    "1223": ["小年", "祭灶节"],
+    "1230": ["除夕"]
+  }
+}

package/src/data/rest.json

@@ -0,0 +1,74 @@
+{
+  "2026": {
+    "xiu": [
+      "0101",
+      "0102",
+      "0103",
+      "0215",
+      "0216",
+      "0217",
+      "0218",
+      "0219",
+      "0220",
+      "0221",
+      "0222",
+      "0223",
+      "0404",
+      "0405",
+      "0406",
+      "0501",
+      "0502",
+      "0503",
+      "0504",
+      "0505",
+      "0619",
+      "0620",
+      "0621",
+      "0925",
+      "0926",
+      "0927",
+      "1001",
+      "1002",
+      "1003",
+      "1004",
+      "1005",
+      "1006",
+      "1007"
+    ],
+    "ban": ["0104", "0214", "0228", "0509", "0920", "1010"]
+  },
+  "2027": {
+    "xiu": [
+      "0101",
+      "0102",
+      "0103",
+      "0205",
+      "0206",
+      "0207",
+      "0208",
+      "0209",
+      "0210",
+      "0211",
+      "0212",
+      "0213",
+      "0403",
+      "0404",
+      "0405",
+      "0501",
+      "0502",
+      "0503",
+      "0504",
+      "0505",
+      "0609",
+      "0915",
+      "1001",
+      "1002",
+      "1003",
+      "1004",
+      "1005",
+      "1006",
+      "1007"
+    ],
+    "ban": ["0131", "0214", "0508", "0926", "1009"]
+  }
+}

package/src/index.ts

@@ -0,0 +1,317 @@
+import {
+  lYearDays,
+  leapMonth,
+  leapDays,
+  lMonthDays,
+  yearStartOf,
+  monthSegmentsOf,
+  resolveLunarYear,
+  toGanZhiYear,
+  toGanZhi,
+  toHourGanZhi,
+  toChinaMonth,
+  toChinaDay,
+  getSolarTerm,
+} from "./utils/LunarFunction";
+import type { LunarMonthSegment } from "./utils/LunarFunction";
+
+import {
+  toAstro,
+  getTerm,
+  getAnimal,
+  solarDays,
+  solarFirstWeek,
+  weekdayOf,
+  toChinaNum,
+  nthWeekdayOfMonth,
+} from "./utils/SolarFunction";
+
+import { assertInteger, assertPlainObject, describe, failRange, failType } from "./utils/Assert";
+import { festivalList, NO_FESTIVAL } from "./utils/SetFestival";
+import { restOf } from "./utils/SetRest";
+import { createCalendarConfig, snapshotOf } from "./config";
+import type { ResolvedConfig } from "./config";
+import type { Calendar, HolidayConfig, LunarResult, SetHolidayOptions } from "./types";
+
+export type {
+  LunarResult,
+  Calendar,
+  FestivalMap,
+  FestivalConfig,
+  RestEntry,
+  RestConfig,
+  HolidayConfig,
+  HolidaySnapshot,
+  GetHolidaysOptions,
+  SetHolidayOptions,
+} from "./types";
+
+/** 支持的公历 / 农历年份范围 */
+const MIN_YEAR = 1900;
+const MAX_YEAR = 2100;
+const DAY_MS = 86400000;
+/** 农历数据起点：1900-01-31，即农历 1900 年正月初一 */
+const MIN_SOLAR_UTC = Date.UTC(MIN_YEAR, 0, 31);
+/** 支持的最后一个公历日 */
+const MAX_SOLAR_UTC = Date.UTC(MAX_YEAR, 11, 31);
+
+/** 把公历年月日校验成合法的、在支持范围内的日期 */
+const validateSolar = function (
+  y: unknown,
+  m: unknown,
+  d: unknown,
+): { year: number; month: number; day: number } {
+  const year = assertInteger("solarToLunar(year)", y, MIN_YEAR, MAX_YEAR);
+  const month = assertInteger("solarToLunar(month)", m, 1, 12);
+  const day = assertInteger("solarToLunar(day)", d, 1, solarDays(year, month));
+  const utc = Date.UTC(year, month - 1, day);
+  if (utc < MIN_SOLAR_UTC) {
+    failRange("solarToLunar", `${year}-${month}-${day} 早于 1900-01-31，超出农历数据范围`);
+  }
+  if (utc > MAX_SOLAR_UTC) {
+    failRange("solarToLunar", `${year}-${month}-${day} 晚于 2100-12-31，超出农历数据范围`);
+  }
+  return { year, month, day };
+};
+
+/** 某一天的公历节日，包含按规则计算的浮动节日 */
+const solarFestivals = function (
+  y: number,
+  m: number,
+  d: number,
+  sFtv: Record<string, string[]>,
+): readonly string[] {
+  const base = festivalList(sFtv, m, d);
+  const extra: string[] = [];
+
+  const add = function (name: string) {
+    if (base.indexOf(name) === -1 && extra.indexOf(name) === -1) extra.push(name);
+  };
+
+  if (m === 5 && d === nthWeekdayOfMonth(y, 5, 0, 2)) add("母亲节");
+  if (m === 6 && d === nthWeekdayOfMonth(y, 6, 0, 3)) add("父亲节");
+  if (m === 11 && d === nthWeekdayOfMonth(y, 11, 4, 4)) add("感恩节");
+
+  // 没有浮动节日时直接返回配置里的只读数组，省掉一次拷贝
+  return extra.length === 0 ? base : Object.freeze(base.concat(extra));
+};
+
+/**
+ * 某一天的农历节日，除夕按“腊月最后一天”计算，不写死 12-30
+ *
+ * 闰月不过节：闰五月初五不算端午、闰八月十五不算中秋。
+ */
+const lunarFestivals = function (
+  lYear: number,
+  lMonth: number,
+  lDay: number,
+  isLeap: boolean,
+  lFtv: Record<string, string[]>,
+): readonly string[] {
+  if (isLeap) return NO_FESTIVAL;
+
+  const base = festivalList(lFtv, lMonth, lDay);
+  if (lMonth === 12 && lDay === lMonthDays(lYear, 12) && base.indexOf("除夕") === -1) {
+    return Object.freeze(base.concat("除夕"));
+  }
+  return base;
+};
+
+/**
+ * 核心换算，入参必须是已经校验过、且在支持范围内的公历日期
+ */
+const computeLunar = function (
+  config: ResolvedConfig,
+  sy: number,
+  sm: number,
+  sd: number,
+): LunarResult {
+  const utc = Date.UTC(sy, sm - 1, sd);
+  const offset = Math.round((utc - MIN_SOLAR_UTC) / DAY_MS);
+  const { year, offsetInYear } = resolveLunarYear(offset);
+
+  // 月份段（闰月单独一段）按顺序扫描，最多 13 段
+  const segments = monthSegmentsOf(year);
+  let segment = segments[0] as LunarMonthSegment;
+  for (const item of segments) {
+    if (item.start > offsetInYear) break;
+    segment = item;
+  }
+
+  const month = segment.month;
+  const day = offsetInYear - segment.start + 1;
+  const isLeap = segment.isLeap;
+
+  const dayOfWeek = weekdayOf(sy, sm, sd);
+  const firstTermDay = getTerm(sy, sm * 2 - 1);
+  const secondTermDay = getTerm(sy, sm * 2);
+
+  let term: string | null = null;
+  if (firstTermDay === sd) term = getSolarTerm(sm * 2 - 2);
+  if (secondTermDay === sd) term = getSolarTerm(sm * 2 - 1);
+
+  // xiu / ban 只由 rest.json 决定，与周末无关；同一天不会既放假又补班，两种状态互斥
+  const restState = restOf(config.restIndex, sy, sm, sd);
+  const isXiu = restState === "xiu";
+  const isBan = restState === "ban";
+
+  const dayCyclical = utc / DAY_MS - (sd - 1) + 25567 + 10;
+  const gzDayOffset = dayCyclical + sd - 1;
+  // 只有 2 月才需要立春当天的日期，其它月份不去查节气表
+  const ganzhiYear = sm > 2 || (sm === 2 && sd >= getTerm(sy, 3)) ? sy : sy - 1;
+
+  return {
+    xiu: isXiu,
+    ban: isBan,
+    gljr: solarFestivals(sy, sm, sd, config.sFtv),
+    nljr: lunarFestivals(year, month, day, isLeap, config.lFtv),
+    lYear: year,
+    lMonth: month,
+    lDay: day,
+    animal: getAnimal(year),
+    lMonthCn: (isLeap ? "闰" : "") + toChinaMonth(month),
+    lDayCn: toChinaDay(day),
+    cYear: sy,
+    cMonth: sm,
+    cDay: sd,
+    gzYear: toGanZhiYear(ganzhiYear),
+    gzYearLunar: toGanZhiYear(year),
+    gzMonth: toGanZhi((sy - 1900) * 12 + sm + (sd >= firstTermDay ? 12 : 11)),
+    gzDay: toGanZhi(gzDayOffset),
+    gzHour: toHourGanZhi(gzDayOffset),
+    isToday: (function () {
+      const now = new Date();
+      return now.getFullYear() === sy && now.getMonth() + 1 === sm && now.getDate() === sd;
+    })(),
+    isLeap,
+    nWeek: dayOfWeek === 0 ? 7 : dayOfWeek,
+    dayOfWeek,
+    ncWeek: "星期" + toChinaNum(dayOfWeek),
+    term,
+    astro: toAstro(sm, sd),
+  };
+};
+
+/** 公历转农历的内部实现，节假日配置由调用方固定 */
+const solarToLunarWith = function (
+  config: ResolvedConfig,
+  y?: number,
+  m?: number,
+  d?: number,
+): LunarResult {
+  if (y === undefined && m === undefined && d === undefined) {
+    const now = new Date();
+    const today = validateSolar(now.getFullYear(), now.getMonth() + 1, now.getDate());
+    return computeLunar(config, today.year, today.month, today.day);
+  }
+  if (y === undefined || m === undefined || d === undefined) {
+    failRange(
+      "solarToLunar",
+      `年、月、日必须同时传入，或全部不传以取今天（收到 year=${String(y)}, month=${String(m)}, day=${String(d)}）`,
+    );
+  }
+  const date = validateSolar(y, m, d);
+  return computeLunar(config, date.year, date.month, date.day);
+};
+
+/** 农历转公历的内部实现，节假日配置由调用方固定 */
+const lunarToSolarWith = function (
+  config: ResolvedConfig,
+  y: number,
+  m: number,
+  d: number,
+  isLeapMonth?: boolean,
+): LunarResult {
+  const year = assertInteger("lunarToSolar(year)", y, MIN_YEAR, MAX_YEAR);
+  const month = assertInteger("lunarToSolar(month)", m, 1, 12);
+  if (isLeapMonth !== undefined && typeof isLeapMonth !== "boolean") {
+    throw failType("lunarToSolar(isLeapMonth)", `必须是布尔值，收到 ${describe(isLeapMonth)}`);
+  }
+  const leap = leapMonth(year);
+  const wantLeap = isLeapMonth === true;
+  if (wantLeap && leap !== month) {
+    failRange(
+      "lunarToSolar(isLeapMonth)",
+      `${year} 年${leap === 0 ? "没有闰月" : `的闰月是闰${leap}月`}，不能按闰${month}月换算`,
+    );
+  }
+  const maxDay = wantLeap ? leapDays(year) : lMonthDays(year, month);
+  const day = assertInteger("lunarToSolar(day)", d, 1, maxDay);
+
+  // 直接查表定位到该月第一天的绝对偏移，不再逐年逐月累加
+  const segments = monthSegmentsOf(year);
+  const segment = segments.find((item) => item.month === month && item.isLeap === wantLeap);
+  if (!segment) {
+    return failRange("lunarToSolar", `${year} 年${wantLeap ? "闰" : ""}${month}月不存在`);
+  }
+  const offset = yearStartOf(year) + segment.start;
+
+  const utc = MIN_SOLAR_UTC + (offset + day - 1) * DAY_MS;
+  if (utc > MAX_SOLAR_UTC) {
+    failRange("lunarToSolar", `农历 ${year}-${month}-${day} 换算后晚于 2100-12-31，超出支持范围`);
+  }
+  const date = new Date(utc);
+  return computeLunar(config, date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate());
+};
+
+/**
+ * 创建固定节假日配置的日历实例
+ *
+ * 不读取也不修改任何全局状态；配置在创建时校验并冻结，
+ * 多个实例之间互不影响。不传配置时使用内置数据。
+ *
+ * @param config 节假日 / 调休配置
+ * @param options replace 为 true 时忽略内置数据
+ * @throws TypeError 配置格式不合法（含具体字段路径）
+ * @example
+ * const cc = createCalendar({ setRest: { 2027: { xiu: ["0101"] } } });
+ * cc.solarToLunar(2027, 1, 1).xiu; // true
+ */
+const createCalendar = function (
+  config: HolidayConfig = {},
+  options: SetHolidayOptions = {},
+): Calendar {
+  // 用户配置只校验一次；只有一份可查询的配置，own 只在 getHolidays 需要时生成快照
+  const { merged, snapshotOwn } = createCalendarConfig(config, options);
+
+  return {
+    /** 公历转农历，不传参返回今天 */
+    solarToLunar: (y, m, d) => solarToLunarWith(merged, y, m, d),
+    /** 农历转公历 */
+    lunarToSolar: (y, m, d, isLeapMonth) => lunarToSolarWith(merged, y, m, d, isLeapMonth),
+    /** 当前配置的深拷贝；merged 为 false 时只导出用户传入的部分 */
+    getHolidays: (getOptions) => {
+      if (getOptions !== undefined) assertPlainObject(getOptions, "getHolidays(options)");
+      if (getOptions?.merged !== undefined && typeof getOptions.merged !== "boolean") {
+        throw failType(
+          "getHolidays(options).merged",
+          `必须是布尔值，收到 ${describe(getOptions.merged)}`,
+        );
+      }
+      return getOptions?.merged === false ? snapshotOwn() : snapshotOf(merged);
+    },
+  };
+};
+
+const utils = {
+  lYearDays,
+  leapMonth,
+  leapDays,
+  lMonthDays,
+  toChinaMonth,
+  toChinaDay,
+  toChinaNum,
+  solarDays,
+  solarFirstWeek,
+  nthWeekdayOfMonth,
+  toAstro,
+  getAnimal,
+  getTerm,
+  getSolarTerm,
+  toGanZhi,
+  toGanZhiYear,
+  toHourGanZhi,
+};
+
+export { createCalendar, utils };
+export default createCalendar;