@sanguo-dev/calendar 0.0.0-stage → 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,269 @@
+/**
+ * 返回农历 y 年一整年的总天数
+ * @param y 农历年（1900-2100）
+ * @return 348-385
+ */
+declare const lYearDays: (y: number) => number;
+/**
+ * 返回农历 y 年闰月是哪个月；没有闰月返回 0
+ * @param y 农历年（1900-2100）
+ */
+declare const leapMonth: (y: number) => number;
+/**
+ * 返回农历 y 年闰月的天数；没有闰月返回 0
+ * @param y 农历年（1900-2100）
+ */
+declare const leapDays: (y: number) => number;
+/**
+ * 返回农历 y 年 m 月（非闰月）的天数，闰月天数请用 leapDays
+ * @param y 农历年（1900-2100）
+ * @param m 农历月（1-12）
+ */
+declare const lMonthDays: (y: number, m: number) => number;
+/**
+ * 农历年转换为干支纪年
+ * @param lYear 农历年，允许 1899 这类边界年（只做算术，不查表）
+ */
+declare const toGanZhiYear: (lYear: number) => string;
+/**
+ * 传入相对甲子的偏移量返回干支
+ * @param offset 可以为负数
+ */
+declare const toGanZhi: (offset: number) => string;
+/**
+ * 传入当天的干支偏移量，返回当天十二个时辰的干支
+ * @param offset 相对甲子的偏移量（与 gzDay 用同一个偏移量）
+ */
+declare const toHourGanZhi: (offset: number) => string[];
+/**
+ * 农历数字月份转中文，例如 1 -> "正月"、12 -> "腊月"
+ * @param m 农历月（1-12）
+ */
+declare const toChinaMonth: (m: number) => string;
+/**
+ * 农历日期数字转中文，例如 1 -> "初一"、21 -> "廿一"
+ * @param d 农历日（1-30）
+ */
+declare const toChinaDay: (d: number) => string;
+/**
+ * 取第 n 个节气名（n 从 0 开始，0 为小寒）
+ * @param n 0-23
+ */
+declare const getSolarTerm: (n: number) => string;
+/**
+ * 返回公历 y 年 m 月的天数（会自动处理闰年）
+ * @param y 公历年
+ * @param m 公历月（1-12）
+ * @return 28-31
+ */
+declare const solarDays: (y: number, m: number) => number;
+/**
+ * 返回公历 y 年 m 月 1 日是星期几
+ * @param y 公历年
+ * @param m 公历月（1-12）
+ * @return 0-6，0 为周日
+ */
+declare const solarFirstWeek: (y: number, m: number) => number;
+/**
+ * 返回公历 y 年 m 月第 nth 个星期 weekday 是几号
+ * @param y 公历年
+ * @param m 公历月（1-12）
+ * @param weekday 0-6，0 为周日
+ * @param nth 第几个，从 1 开始
+ * @example nthWeekdayOfMonth(2026, 5, 0, 2) // 10，2026 年母亲节是 5 月 10 日
+ */
+declare const nthWeekdayOfMonth: (y: number, m: number, weekday: number, nth: number) => number;
+/**
+ * 公历月、日判断所属星座
+ * @param m 公历月（1-12）
+ * @param d 公历日
+ * @example toAstro(4, 19) // "白羊座"
+ */
+declare const toAstro: (m: number, d: number) => string;
+/**
+ * 传入公历年获得该年第 n 个节气所在公历月的日期
+ * @param y 公历年（1900-2100）
+ * @param n 第几个节气（1-24），1 为小寒
+ * @return 日期数字
+ * @example getTerm(1987, 3) // 4，1987 年 2 月 4 日立春
+ */
+declare const getTerm: (y: number, n: number) => number;
+/**
+ * 年份转生肖，以农历年为准
+ * @param y 年份
+ * @example getAnimal(1987) // "兔"
+ */
+declare const getAnimal: (y: number) => string;
+/**
+ * 数字转中文，0-10
+ * @param num 0-10
+ * @example toChinaNum(3) // "三"
+ */
+declare const toChinaNum: (num: number) => string;
+/**
+ * 公历节日 / 农历节日的映射表
+ * key 为四位 "MMDD"，value 为节日名称数组
+ */
+type FestivalMap = Record<string, string[]>;
+/**
+ * 节日配置，sFtv 为公历节日，lFtv 为农历节日
+ */
+interface FestivalConfig {
+  /** 公历节日，key 为 MMDD，例如 { "0101": ["元旦"] } */
+  sFtv?: FestivalMap;
+  /** 农历节日，key 为 MMDD，例如 { "0101": ["春节"] } */
+  lFtv?: FestivalMap;
+}
+/**
+ * 单年的放假与调休配置（用户注入时的形态，两个数组都可省略）
+ */
+interface RestEntry {
+  /** 该年放假日（MMDD），不含普通周末 */
+  xiu?: string[];
+  /** 该年调休补班日（MMDD），一般是周末上班 */
+  ban?: string[];
+}
+/**
+ * 归一化之后的单年配置：两个数组一定存在，内部查询用
+ */
+interface NormalizedRestEntry {
+  xiu: string[];
+  ban: string[];
+}
+/**
+ * 调休配置，key 为年份，value 为该年的放假/补班日
+ */
+type RestConfig = Record<string | number, RestEntry>;
+/**
+ * getHolidays() 的返回值：结构完整，可直接再传给 createCalendar()
+ */
+interface HolidaySnapshot {
+  setFestival: {
+    sFtv: FestivalMap;
+    lFtv: FestivalMap;
+  };
+  setRest: Record<string, NormalizedRestEntry>;
+}
+/**
+ * createCalendar 的入参
+ */
+interface HolidayConfig {
+  setFestival?: FestivalConfig;
+  setRest?: RestConfig;
+}
+/**
+ * createCalendar 的选项
+ */
+interface SetHolidayOptions {
+  /** 为 true 时丢弃内置节日/调休数据，只使用传入的数据 */
+  replace?: boolean;
+}
+/**
+ * 公历转农历 / 农历转公历的完整结果
+ */
+interface LunarResult {
+  /** 是否在 rest.json 的放假日列表（xiu）中；与周末无关 */
+  xiu: boolean;
+  /** 是否在 rest.json 的调休补班日列表（ban）中 */
+  ban: boolean;
+  /** 公历节日，例如 ["元旦"]；没有节日时是共享的只读空数组 */
+  gljr: readonly string[];
+  /** 农历节日，例如 ["春节"]；没有节日时是共享的只读空数组 */
+  nljr: readonly string[];
+  /** 农历年 */
+  lYear: number;
+  /** 农历月，1-12 */
+  lMonth: number;
+  /** 农历日，1-30 */
+  lDay: number;
+  /** 生肖，以农历年为准 */
+  animal: string;
+  /** 农历月中文名，例如 "正月"、"闰四月" */
+  lMonthCn: string;
+  /** 农历日中文名，例如 "初一" */
+  lDayCn: string;
+  /** 公历年 */
+  cYear: number;
+  /** 公历月，1-12 */
+  cMonth: number;
+  /** 公历日 */
+  cDay: number;
+  /** 干支年，以立春为界，与 gzMonth 口径一致 */
+  gzYear: string;
+  /** 干支年，以正月初一为界，与 animal 口径一致 */
+  gzYearLunar: string;
+  /** 干支月，以节气为界 */
+  gzMonth: string;
+  /** 干支日 */
+  gzDay: string;
+  /** 当天十二个时辰的干支 */
+  gzHour: string[];
+  /** 是否今天（按本地时区） */
+  isToday: boolean;
+  /** 是否闰月 */
+  isLeap: boolean;
+  /** 星期数字，1-7，周一为 1、周日为 7 */
+  nWeek: number;
+  /** 星期数字，0-6，周日为 0，与 solarFirstWeek 口径一致 */
+  dayOfWeek: number;
+  /** 星期中文，例如 "星期日" */
+  ncWeek: string;
+  /** 节气名，当天不是节气时为 null */
+  term: string | null;
+  /** 星座，例如 "摩羯座" */
+  astro: string;
+}
+/**
+ * getHolidays 的选项
+ */
+interface GetHolidaysOptions {
+  /** 默认 true：返回合并内置数据后的完整配置；false：只返回创建实例时传入的那部分 */
+  merged?: boolean;
+}
+/**
+ * 固定了一份节假日配置的日历实例
+ *
+ * 由 createCalendar() 创建，配置在创建时固定，实例之间互不影响。
+ */
+interface Calendar {
+  /** 公历转农历，不传参返回今天 */
+  solarToLunar(this: void, y?: number, m?: number, d?: number): LunarResult;
+  /** 农历转公历 */
+  lunarToSolar(this: void, y: number, m: number, d: number, isLeapMonth?: boolean): LunarResult;
+  /** 该实例当前配置的深拷贝，可再次用于 createCalendar() */
+  getHolidays(this: void, options?: GetHolidaysOptions): HolidaySnapshot;
+}
+/**
+ * 创建固定节假日配置的日历实例
+ *
+ * 不读取也不修改任何全局状态；配置在创建时校验并冻结，
+ * 多个实例之间互不影响。不传配置时使用内置数据。
+ *
+ * @param config 节假日 / 调休配置
+ * @param options replace 为 true 时忽略内置数据
+ * @throws TypeError 配置格式不合法（含具体字段路径）
+ * @example
+ * const cc = createCalendar({ setRest: { 2027: { xiu: ["0101"] } } });
+ * cc.solarToLunar(2027, 1, 1).xiu; // true
+ */
+declare const createCalendar: (config?: HolidayConfig, options?: SetHolidayOptions) => Calendar;
+declare const utils: {
+  lYearDays: typeof lYearDays;
+  leapMonth: typeof leapMonth;
+  leapDays: typeof leapDays;
+  lMonthDays: typeof lMonthDays;
+  toChinaMonth: typeof toChinaMonth;
+  toChinaDay: typeof toChinaDay;
+  toChinaNum: typeof toChinaNum;
+  solarDays: typeof solarDays;
+  solarFirstWeek: typeof solarFirstWeek;
+  nthWeekdayOfMonth: typeof nthWeekdayOfMonth;
+  toAstro: typeof toAstro;
+  getAnimal: typeof getAnimal;
+  getTerm: typeof getTerm;
+  getSolarTerm: typeof getSolarTerm;
+  toGanZhi: typeof toGanZhi;
+  toGanZhiYear: typeof toGanZhiYear;
+  toHourGanZhi: typeof toHourGanZhi;
+};
+export { type Calendar, type FestivalConfig, type FestivalMap, type GetHolidaysOptions, type HolidayConfig, type HolidaySnapshot, type LunarResult, type RestConfig, type RestEntry, type SetHolidayOptions, createCalendar, createCalendar as default, utils };

package/dist/index.d.mts

@@ -0,0 +1,269 @@
+/**
+ * 返回农历 y 年一整年的总天数
+ * @param y 农历年（1900-2100）
+ * @return 348-385
+ */
+declare const lYearDays: (y: number) => number;
+/**
+ * 返回农历 y 年闰月是哪个月；没有闰月返回 0
+ * @param y 农历年（1900-2100）
+ */
+declare const leapMonth: (y: number) => number;
+/**
+ * 返回农历 y 年闰月的天数；没有闰月返回 0
+ * @param y 农历年（1900-2100）
+ */
+declare const leapDays: (y: number) => number;
+/**
+ * 返回农历 y 年 m 月（非闰月）的天数，闰月天数请用 leapDays
+ * @param y 农历年（1900-2100）
+ * @param m 农历月（1-12）
+ */
+declare const lMonthDays: (y: number, m: number) => number;
+/**
+ * 农历年转换为干支纪年
+ * @param lYear 农历年，允许 1899 这类边界年（只做算术，不查表）
+ */
+declare const toGanZhiYear: (lYear: number) => string;
+/**
+ * 传入相对甲子的偏移量返回干支
+ * @param offset 可以为负数
+ */
+declare const toGanZhi: (offset: number) => string;
+/**
+ * 传入当天的干支偏移量，返回当天十二个时辰的干支
+ * @param offset 相对甲子的偏移量（与 gzDay 用同一个偏移量）
+ */
+declare const toHourGanZhi: (offset: number) => string[];
+/**
+ * 农历数字月份转中文，例如 1 -> "正月"、12 -> "腊月"
+ * @param m 农历月（1-12）
+ */
+declare const toChinaMonth: (m: number) => string;
+/**
+ * 农历日期数字转中文，例如 1 -> "初一"、21 -> "廿一"
+ * @param d 农历日（1-30）
+ */
+declare const toChinaDay: (d: number) => string;
+/**
+ * 取第 n 个节气名（n 从 0 开始，0 为小寒）
+ * @param n 0-23
+ */
+declare const getSolarTerm: (n: number) => string;
+/**
+ * 返回公历 y 年 m 月的天数（会自动处理闰年）
+ * @param y 公历年
+ * @param m 公历月（1-12）
+ * @return 28-31
+ */
+declare const solarDays: (y: number, m: number) => number;
+/**
+ * 返回公历 y 年 m 月 1 日是星期几
+ * @param y 公历年
+ * @param m 公历月（1-12）
+ * @return 0-6，0 为周日
+ */
+declare const solarFirstWeek: (y: number, m: number) => number;
+/**
+ * 返回公历 y 年 m 月第 nth 个星期 weekday 是几号
+ * @param y 公历年
+ * @param m 公历月（1-12）
+ * @param weekday 0-6，0 为周日
+ * @param nth 第几个，从 1 开始
+ * @example nthWeekdayOfMonth(2026, 5, 0, 2) // 10，2026 年母亲节是 5 月 10 日
+ */
+declare const nthWeekdayOfMonth: (y: number, m: number, weekday: number, nth: number) => number;
+/**
+ * 公历月、日判断所属星座
+ * @param m 公历月（1-12）
+ * @param d 公历日
+ * @example toAstro(4, 19) // "白羊座"
+ */
+declare const toAstro: (m: number, d: number) => string;
+/**
+ * 传入公历年获得该年第 n 个节气所在公历月的日期
+ * @param y 公历年（1900-2100）
+ * @param n 第几个节气（1-24），1 为小寒
+ * @return 日期数字
+ * @example getTerm(1987, 3) // 4，1987 年 2 月 4 日立春
+ */
+declare const getTerm: (y: number, n: number) => number;
+/**
+ * 年份转生肖，以农历年为准
+ * @param y 年份
+ * @example getAnimal(1987) // "兔"
+ */
+declare const getAnimal: (y: number) => string;
+/**
+ * 数字转中文，0-10
+ * @param num 0-10
+ * @example toChinaNum(3) // "三"
+ */
+declare const toChinaNum: (num: number) => string;
+/**
+ * 公历节日 / 农历节日的映射表
+ * key 为四位 "MMDD"，value 为节日名称数组
+ */
+type FestivalMap = Record<string, string[]>;
+/**
+ * 节日配置，sFtv 为公历节日，lFtv 为农历节日
+ */
+interface FestivalConfig {
+  /** 公历节日，key 为 MMDD，例如 { "0101": ["元旦"] } */
+  sFtv?: FestivalMap;
+  /** 农历节日，key 为 MMDD，例如 { "0101": ["春节"] } */
+  lFtv?: FestivalMap;
+}
+/**
+ * 单年的放假与调休配置（用户注入时的形态，两个数组都可省略）
+ */
+interface RestEntry {
+  /** 该年放假日（MMDD），不含普通周末 */
+  xiu?: string[];
+  /** 该年调休补班日（MMDD），一般是周末上班 */
+  ban?: string[];
+}
+/**
+ * 归一化之后的单年配置：两个数组一定存在，内部查询用
+ */
+interface NormalizedRestEntry {
+  xiu: string[];
+  ban: string[];
+}
+/**
+ * 调休配置，key 为年份，value 为该年的放假/补班日
+ */
+type RestConfig = Record<string | number, RestEntry>;
+/**
+ * getHolidays() 的返回值：结构完整，可直接再传给 createCalendar()
+ */
+interface HolidaySnapshot {
+  setFestival: {
+    sFtv: FestivalMap;
+    lFtv: FestivalMap;
+  };
+  setRest: Record<string, NormalizedRestEntry>;
+}
+/**
+ * createCalendar 的入参
+ */
+interface HolidayConfig {
+  setFestival?: FestivalConfig;
+  setRest?: RestConfig;
+}
+/**
+ * createCalendar 的选项
+ */
+interface SetHolidayOptions {
+  /** 为 true 时丢弃内置节日/调休数据，只使用传入的数据 */
+  replace?: boolean;
+}
+/**
+ * 公历转农历 / 农历转公历的完整结果
+ */
+interface LunarResult {
+  /** 是否在 rest.json 的放假日列表（xiu）中；与周末无关 */
+  xiu: boolean;
+  /** 是否在 rest.json 的调休补班日列表（ban）中 */
+  ban: boolean;
+  /** 公历节日，例如 ["元旦"]；没有节日时是共享的只读空数组 */
+  gljr: readonly string[];
+  /** 农历节日，例如 ["春节"]；没有节日时是共享的只读空数组 */
+  nljr: readonly string[];
+  /** 农历年 */
+  lYear: number;
+  /** 农历月，1-12 */
+  lMonth: number;
+  /** 农历日，1-30 */
+  lDay: number;
+  /** 生肖，以农历年为准 */
+  animal: string;
+  /** 农历月中文名，例如 "正月"、"闰四月" */
+  lMonthCn: string;
+  /** 农历日中文名，例如 "初一" */
+  lDayCn: string;
+  /** 公历年 */
+  cYear: number;
+  /** 公历月，1-12 */
+  cMonth: number;
+  /** 公历日 */
+  cDay: number;
+  /** 干支年，以立春为界，与 gzMonth 口径一致 */
+  gzYear: string;
+  /** 干支年，以正月初一为界，与 animal 口径一致 */
+  gzYearLunar: string;
+  /** 干支月，以节气为界 */
+  gzMonth: string;
+  /** 干支日 */
+  gzDay: string;
+  /** 当天十二个时辰的干支 */
+  gzHour: string[];
+  /** 是否今天（按本地时区） */
+  isToday: boolean;
+  /** 是否闰月 */
+  isLeap: boolean;
+  /** 星期数字，1-7，周一为 1、周日为 7 */
+  nWeek: number;
+  /** 星期数字，0-6，周日为 0，与 solarFirstWeek 口径一致 */
+  dayOfWeek: number;
+  /** 星期中文，例如 "星期日" */
+  ncWeek: string;
+  /** 节气名，当天不是节气时为 null */
+  term: string | null;
+  /** 星座，例如 "摩羯座" */
+  astro: string;
+}
+/**
+ * getHolidays 的选项
+ */
+interface GetHolidaysOptions {
+  /** 默认 true：返回合并内置数据后的完整配置；false：只返回创建实例时传入的那部分 */
+  merged?: boolean;
+}
+/**
+ * 固定了一份节假日配置的日历实例
+ *
+ * 由 createCalendar() 创建，配置在创建时固定，实例之间互不影响。
+ */
+interface Calendar {
+  /** 公历转农历，不传参返回今天 */
+  solarToLunar(this: void, y?: number, m?: number, d?: number): LunarResult;
+  /** 农历转公历 */
+  lunarToSolar(this: void, y: number, m: number, d: number, isLeapMonth?: boolean): LunarResult;
+  /** 该实例当前配置的深拷贝，可再次用于 createCalendar() */
+  getHolidays(this: void, options?: GetHolidaysOptions): HolidaySnapshot;
+}
+/**
+ * 创建固定节假日配置的日历实例
+ *
+ * 不读取也不修改任何全局状态；配置在创建时校验并冻结，
+ * 多个实例之间互不影响。不传配置时使用内置数据。
+ *
+ * @param config 节假日 / 调休配置
+ * @param options replace 为 true 时忽略内置数据
+ * @throws TypeError 配置格式不合法（含具体字段路径）
+ * @example
+ * const cc = createCalendar({ setRest: { 2027: { xiu: ["0101"] } } });
+ * cc.solarToLunar(2027, 1, 1).xiu; // true
+ */
+declare const createCalendar: (config?: HolidayConfig, options?: SetHolidayOptions) => Calendar;
+declare const utils: {
+  lYearDays: typeof lYearDays;
+  leapMonth: typeof leapMonth;
+  leapDays: typeof leapDays;
+  lMonthDays: typeof lMonthDays;
+  toChinaMonth: typeof toChinaMonth;
+  toChinaDay: typeof toChinaDay;
+  toChinaNum: typeof toChinaNum;
+  solarDays: typeof solarDays;
+  solarFirstWeek: typeof solarFirstWeek;
+  nthWeekdayOfMonth: typeof nthWeekdayOfMonth;
+  toAstro: typeof toAstro;
+  getAnimal: typeof getAnimal;
+  getTerm: typeof getTerm;
+  getSolarTerm: typeof getSolarTerm;
+  toGanZhi: typeof toGanZhi;
+  toGanZhiYear: typeof toGanZhiYear;
+  toHourGanZhi: typeof toHourGanZhi;
+};
+export { type Calendar, type FestivalConfig, type FestivalMap, type GetHolidaysOptions, type HolidayConfig, type HolidaySnapshot, type LunarResult, type RestConfig, type RestEntry, type SetHolidayOptions, createCalendar, createCalendar as default, utils };