@sanguo-dev/calendar 0.0.0-stage → 1.0.1

package/src/types.ts

@@ -0,0 +1,146 @@
+/**
+ * 公历节日 / 农历节日的映射表
+ * key 为四位 "MMDD"，value 为节日名称数组
+ */
+export type FestivalMap = Record<string, string[]>;
+
+/**
+ * 节日配置，sFtv 为公历节日，lFtv 为农历节日
+ */
+export interface FestivalConfig {
+  /** 公历节日，key 为 MMDD，例如 { "0101": ["元旦"] } */
+  sFtv?: FestivalMap;
+  /** 农历节日，key 为 MMDD，例如 { "0101": ["春节"] } */
+  lFtv?: FestivalMap;
+}
+
+/**
+ * 单年的放假与调休配置（用户注入时的形态，两个数组都可省略）
+ */
+export interface RestEntry {
+  /** 该年放假日（MMDD），不含普通周末 */
+  xiu?: string[];
+  /** 该年调休补班日（MMDD），一般是周末上班 */
+  ban?: string[];
+}
+
+/**
+ * 归一化之后的单年配置：两个数组一定存在，内部查询用
+ */
+export interface NormalizedRestEntry {
+  xiu: string[];
+  ban: string[];
+}
+
+/** 规范化后的调休表，key 为年份 */
+export type RestMap = Record<string, NormalizedRestEntry>;
+
+/**
+ * 调休配置，key 为年份，value 为该年的放假/补班日
+ */
+export type RestConfig = Record<string | number, RestEntry>;
+
+/**
+ * getHolidays() 的返回值：结构完整，可直接再传给 createCalendar()
+ */
+export interface HolidaySnapshot {
+  setFestival: {
+    sFtv: FestivalMap;
+    lFtv: FestivalMap;
+  };
+  setRest: Record<string, NormalizedRestEntry>;
+}
+
+/**
+ * createCalendar 的入参
+ */
+export interface HolidayConfig {
+  setFestival?: FestivalConfig;
+  setRest?: RestConfig;
+}
+
+/**
+ * createCalendar 的选项
+ */
+export interface SetHolidayOptions {
+  /** 为 true 时丢弃内置节日/调休数据，只使用传入的数据 */
+  replace?: boolean;
+}
+
+/**
+ * 公历转农历 / 农历转公历的完整结果
+ */
+export 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 的选项
+ */
+export interface GetHolidaysOptions {
+  /** 默认 true：返回合并内置数据后的完整配置；false：只返回创建实例时传入的那部分 */
+  merged?: boolean;
+}
+
+/**
+ * 固定了一份节假日配置的日历实例
+ *
+ * 由 createCalendar() 创建，配置在创建时固定，实例之间互不影响。
+ */
+export 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;
+}

package/src/utils/Assert.ts

@@ -0,0 +1,230 @@
+/**
+ * 统一的参数错误、类型守卫，以及节日 / 调休配置的校验与规范化
+ */
+import type { FestivalMap, RestMap } from "../types";
+
+/** 四位 "MMDD"，月份 01-12、日期 01-31 */
+const MMDD_RE = /^(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$/;
+
+/** 预生成的 MMDD 查表键（12 × 31），避免每次查节日 / 调休都拼字符串 */
+const MMDD: string[][] = Array.from({ length: 13 }, () => Array.from({ length: 32 }, () => ""));
+
+for (let m = 1; m <= 12; m++) {
+  for (let d = 1; d <= 31; d++) {
+    (MMDD[m] as string[])[d] = (m < 10 ? "0" + m : String(m)) + (d < 10 ? "0" + d : String(d));
+  }
+}
+
+/** 取四位 MMDD 字符串，例如 mmddOf(1, 1) → "0101" */
+export const mmddOf = function (m: number, d: number): string {
+  return (MMDD[m] as string[])[d] as string;
+};
+
+/** 调休年份：1900-2100 */
+const YEAR_RE = /^(19\d{2}|20\d{2}|2100)$/;
+
+/** 公历每个月的最大天数，2 月按闰年放宽到 29 */
+const SOLAR_MAX_DAY = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+/** 调休表每年的字段 */
+const REST_FIELDS = ["xiu", "ban"];
+
+/** 抛出带位置信息的 TypeError，用于配置格式错误 */
+export function failType(path: string, message: string): never {
+  throw new TypeError(`[calendar] ${path} ${message}`);
+}
+
+/** 抛出带位置信息的 RangeError，用于数值越界 */
+export function failRange(path: string, message: string): never {
+  throw new RangeError(`[calendar] ${path} ${message}`);
+}
+
+/** 是否为普通对象（非 null、非数组） */
+export const isPlainObject = function (value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+
+/** 校验是普通对象，否则按 path 抛 TypeError；断言之后可以直接当字典用 */
+export function assertPlainObject(
+  value: unknown,
+  path: string,
+  message = "必须是对象",
+): asserts value is Record<string, unknown> {
+  if (!isPlainObject(value)) failType(path, `${message}，收到 ${describe(value)}`);
+}
+
+/** 校验对象里没有白名单之外的字段 */
+export const assertKnownKeys = function (
+  value: object,
+  allowed: readonly string[],
+  path: string,
+): void {
+  Object.keys(value).forEach(function (key) {
+    if (allowed.indexOf(key) === -1) {
+      failType(`${path}.${key}`, `不认识的字段，只支持 ${allowed.join(" 与 ")}`);
+    }
+  });
+};
+
+/** 把任意值格式化成便于排查的短字符串 */
+export const describe = function (value: unknown): string {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (
+    typeof value === "number" ||
+    typeof value === "boolean" ||
+    value === null ||
+    value === undefined
+  ) {
+    return String(value);
+  }
+  if (Array.isArray(value)) return `Array(${value.length})`;
+  if (typeof value === "object") {
+    const keys = Object.keys(value as Record<string, unknown>);
+    return `Object(keys: ${keys.slice(0, 5).join(", ")}${keys.length > 5 ? ", …" : ""})`;
+  }
+  return typeof value;
+};
+
+/** 校验一个整数并返回它 */
+export const assertInteger = function (
+  path: string,
+  value: unknown,
+  min: number,
+  max: number,
+): number {
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    return failRange(path, `必须是整数，收到 ${describe(value)}`);
+  }
+  if (value < min || value > max) {
+    return failRange(path, `必须在 ${min}-${max} 之间，收到 ${value}`);
+  }
+  return value;
+};
+
+/** 公历 MMDD 是否对应真实存在的日期（例如 0231、0431 为 false） */
+const isSolarMonthDay = function (m: number, d: number): boolean {
+  return d >= 1 && d <= (SOLAR_MAX_DAY[m - 1] ?? 0);
+};
+
+/** 农历 MMDD：每个月最多 30 天 */
+const isLunarMonthDay = function (m: number, d: number): boolean {
+  return d >= 1 && d <= 30;
+};
+
+/**
+ * 校验并解析四位 MMDD：节日 key 与调休日期共用同一套格式和日期检查
+ *
+ * @param value 待校验值，必须是 "MMDD" 字符串
+ * @param path 出错时用于定位的路径
+ * @param options.lunar 按农历校验（每月最多 30 天），默认公历
+ * @param options.label 报错信息里的主语，例如 "节日 key"
+ */
+export function assertMMDD(
+  value: unknown,
+  path: string,
+  options: { lunar?: boolean; label?: string } = {},
+): { month: number; day: number; text: string } {
+  const { lunar = false, label } = options;
+  const prefix = label === undefined ? "" : `${label} `;
+  const parsed =
+    typeof value === "string" && MMDD_RE.test(value)
+      ? { month: Number(value.slice(0, 2)), day: Number(value.slice(2)), text: value }
+      : null;
+
+  if (parsed === null) {
+    failType(path, `${prefix}必须是四位 "MMDD"（如 "0101"），收到 ${describe(value)}`);
+  }
+  const valid = lunar
+    ? isLunarMonthDay(parsed.month, parsed.day)
+    : isSolarMonthDay(parsed.month, parsed.day);
+  if (!valid) {
+    failType(path, `${lunar ? "农历" : "公历"}不存在 ${parsed.month} 月 ${parsed.day} 日`);
+  }
+  return parsed;
+}
+
+/**
+ * 校验并规范化节日表
+ *
+ * @param input 待校验的节日表
+ * @param path 出错时用于定位的路径，例如 "createCalendar.setFestival.sFtv"
+ * @param lunar 农历节日（true）还是公历节日（false）
+ */
+const normalizeFestivalMap = function (input: unknown, path: string, lunar = false): FestivalMap {
+  assertPlainObject(input, path);
+  const result: FestivalMap = {};
+  Object.keys(input).forEach(function (key) {
+    assertMMDD(key, `${path}.${key}`, { lunar, label: "节日 key" });
+    const value = input[key];
+    if (!Array.isArray(value)) {
+      throw failType(`${path}.${key}`, `节日名称必须是字符串数组，收到 ${describe(value)}`);
+    }
+    const names: string[] = [];
+    value.forEach(function (name: unknown, index: number) {
+      if (typeof name !== "string" || name.trim() === "") {
+        throw failType(
+          `${path}.${key}[${index}]`,
+          `节日名称必须是非空字符串，收到 ${describe(name)}`,
+        );
+      }
+      names.push(name);
+    });
+    result[key] = names;
+  });
+  return result;
+};
+
+/** 校验并去重一组调休日期（MMDD 字符串） */
+const normalizeDayList = function (input: unknown, path: string): string[] {
+  if (!Array.isArray(input)) {
+    throw failType(path, `必须是 "MMDD" 字符串数组，收到 ${describe(input)}`);
+  }
+  const days: string[] = [];
+  input.forEach(function (day: unknown, index: number) {
+    days.push(assertMMDD(day, `${path}[${index}]`).text);
+  });
+  return Array.from(new Set(days));
+};
+
+/**
+ * 校验并规范化调休表，key 为年份
+ *
+ * @param input 待校验的调休表
+ * @param path 出错时用于定位的路径
+ */
+const normalizeRestMap = function (input: unknown, path: string): RestMap {
+  assertPlainObject(input, path);
+  const result: RestMap = {};
+  Object.keys(input).forEach(function (yearKey) {
+    if (!YEAR_RE.test(yearKey)) {
+      throw failType(
+        `${path}.${yearKey}`,
+        `年份必须是 1900-2100 的四位数字，收到 ${describe(yearKey)}`,
+      );
+    }
+    const entry = input[yearKey];
+    assertPlainObject(entry, `${path}.${yearKey}`, "必须是 { xiu: [], ban: [] }");
+    assertKnownKeys(entry, REST_FIELDS, `${path}.${yearKey}`);
+
+    const xiu =
+      entry.xiu === undefined ? [] : normalizeDayList(entry.xiu, `${path}.${yearKey}.xiu`);
+    const ban =
+      entry.ban === undefined ? [] : normalizeDayList(entry.ban, `${path}.${yearKey}.ban`);
+
+    // 放假和补班来自同一份法定节假日安排，同一天不可能既放假又补班
+    const conflict = xiu.filter(function (day) {
+      return ban.indexOf(day) !== -1;
+    });
+    if (conflict.length > 0) {
+      throw failType(
+        `${path}.${yearKey}`,
+        `同一天不能既是放假日又是补班日：${conflict.join("、")}`,
+      );
+    }
+
+    result[yearKey] = { xiu, ban };
+  });
+  return result;
+};
+
+export { normalizeFestivalMap, normalizeRestMap };

package/src/utils/LunarFunction.ts

@@ -0,0 +1,215 @@
+import { LunarInfo, Gan, Zhi, GanZhiHour, SolarTerm, nStr3, nStr2, nStr1 } from "../data/Calendar";
+import { assertInteger, failRange } from "./Assert";
+
+/** 农历数据表覆盖的年份 */
+const LUNAR_YEAR_MIN = 1900;
+const LUNAR_YEAR_MAX = 2100;
+
+/**
+ * 校验农历年份是否在数据表范围内，越界直接抛 RangeError
+ */
+const assertLunarYear = function (y: number, path: string): number {
+  return assertInteger(path, y, LUNAR_YEAR_MIN, LUNAR_YEAR_MAX);
+};
+
+/**
+ * 返回农历 y 年一整年的总天数
+ * @param y 农历年（1900-2100）
+ * @return 348-385
+ */
+const lYearDays = function (y: number): number {
+  assertLunarYear(y, "lYearDays(year)");
+  let sum = 348;
+  for (let i = 0x8000; i > 0x8; i >>= 1) {
+    sum += LunarInfo[y - 1900] & i ? 1 : 0;
+  }
+  return sum + leapDays(y);
+};
+
+/**
+ * 返回农历 y 年闰月是哪个月；没有闰月返回 0
+ * @param y 农历年（1900-2100）
+ */
+const leapMonth = function (y: number): number {
+  assertLunarYear(y, "leapMonth(year)");
+  return LunarInfo[y - 1900] & 0xf;
+};
+
+/**
+ * 返回农历 y 年闰月的天数；没有闰月返回 0
+ * @param y 农历年（1900-2100）
+ */
+const leapDays = function (y: number): number {
+  if (leapMonth(y)) {
+    return LunarInfo[y - 1900] & 0x10000 ? 30 : 29;
+  }
+  return 0;
+};
+
+/**
+ * 返回农历 y 年 m 月（非闰月）的天数，闰月天数请用 leapDays
+ * @param y 农历年（1900-2100）
+ * @param m 农历月（1-12）
+ */
+const lMonthDays = function (y: number, m: number): number {
+  assertLunarYear(y, "lMonthDays(year)");
+  assertInteger("lMonthDays(month)", m, 1, 12);
+  return LunarInfo[y - 1900] & (0x10000 >> m) ? 30 : 29;
+};
+
+/** 农历每年正月初一距 1900-01-31 的天数；长度 202，最后一项是 2101 正月初一 */
+const YEAR_START: number[] = (function () {
+  const starts: number[] = [0];
+  for (let y = LUNAR_YEAR_MIN; y <= LUNAR_YEAR_MAX; y++) {
+    starts.push((starts[starts.length - 1] as number) + lYearDays(y));
+  }
+  return starts;
+})();
+
+/** 某年正月初一距 1900-01-31 的天数 */
+const yearStartOf = function (year: number): number {
+  assertLunarYear(year, "yearStartOf(year)");
+  return YEAR_START[year - LUNAR_YEAR_MIN] as number;
+};
+
+/** 农历某年的一个“月份段”，闰月算独立一段 */
+export interface LunarMonthSegment {
+  month: number;
+  isLeap: boolean;
+  /** 该段 1 号距当年正月初一的天数 */
+  start: number;
+}
+
+const segmentCache = new Map<number, LunarMonthSegment[]>();
+
+/** 某年的月份段表（按时间顺序），第一次构建后缓存 */
+const monthSegmentsOf = function (year: number): LunarMonthSegment[] {
+  const cached = segmentCache.get(year);
+  if (cached) return cached;
+
+  const leap = leapMonth(year);
+  const segments: LunarMonthSegment[] = [];
+  let start = 0;
+
+  for (let m = 1; m <= 12; m++) {
+    segments.push({ month: m, isLeap: false, start });
+    start += lMonthDays(year, m);
+    if (leap === m) {
+      segments.push({ month: m, isLeap: true, start });
+      start += leapDays(year);
+    }
+  }
+
+  segmentCache.set(year, segments);
+  return segments;
+};
+
+/** 把“距 1900-01-31 的天数”换算成农历年与当年第几天（二分查找，替代逐年累减） */
+const resolveLunarYear = function (offset: number): { year: number; offsetInYear: number } {
+  let low = 0;
+  let high = LUNAR_YEAR_MAX - LUNAR_YEAR_MIN;
+
+  while (low < high) {
+    const mid = (low + high + 1) >>> 1;
+    if ((YEAR_START[mid] as number) <= offset) low = mid;
+    else high = mid - 1;
+  }
+
+  return {
+    year: LUNAR_YEAR_MIN + low,
+    offsetInYear: offset - (YEAR_START[low] as number),
+  };
+};
+
+/**
+ * 农历年转换为干支纪年
+ * @param lYear 农历年，允许 1899 这类边界年（只做算术，不查表）
+ */
+const toGanZhiYear = function (lYear: number): string {
+  if (typeof lYear !== "number" || !Number.isInteger(lYear)) {
+    failRange("toGanZhiYear(year)", `必须是整数，收到 ${lYear}`);
+  }
+  let ganKey = (lYear - 3) % 10;
+  let zhiKey = (lYear - 3) % 12;
+  if (ganKey <= 0) ganKey += 10;
+  if (zhiKey <= 0) zhiKey += 12;
+  return Gan[ganKey - 1] + Zhi[zhiKey - 1];
+};
+
+/**
+ * 传入相对甲子的偏移量返回干支
+ * @param offset 可以为负数
+ */
+const toGanZhi = function (offset: number): string {
+  if (typeof offset !== "number" || !Number.isInteger(offset)) {
+    failRange("toGanZhi(offset)", `必须是整数，收到 ${offset}`);
+  }
+  const gan = ((offset % 10) + 10) % 10;
+  const zhi = ((offset % 12) + 12) % 12;
+  return Gan[gan] + Zhi[zhi];
+};
+
+/**
+ * 传入当天的干支偏移量，返回当天十二个时辰的干支
+ * @param offset 相对甲子的偏移量（与 gzDay 用同一个偏移量）
+ */
+const toHourGanZhi = function (offset: number): string[] {
+  if (typeof offset !== "number" || !Number.isInteger(offset)) {
+    failRange("toHourGanZhi(offset)", `必须是整数，收到 ${offset}`);
+  }
+  const index = ((offset % 10) + 10) % 10;
+  return GanZhiHour[index].split("-");
+};
+
+/**
+ * 农历数字月份转中文，例如 1 -> "正月"、12 -> "腊月"
+ * @param m 农历月（1-12）
+ */
+const toChinaMonth = function (m: number): string {
+  assertInteger("toChinaMonth(month)", m, 1, 12);
+  return nStr3[m - 1] + "月";
+};
+
+/**
+ * 农历日期数字转中文，例如 1 -> "初一"、21 -> "廿一"
+ * @param d 农历日（1-30）
+ */
+const toChinaDay = function (d: number): string {
+  assertInteger("toChinaDay(day)", d, 1, 30);
+  switch (d) {
+    case 10:
+      return "\u521d\u5341";
+    case 20:
+      return "\u4e8c\u5341";
+    case 30:
+      return "\u4e09\u5341";
+    default:
+      return nStr2[Math.floor(d / 10)] + nStr1[d % 10];
+  }
+};
+
+/**
+ * 取第 n 个节气名（n 从 0 开始，0 为小寒）
+ * @param n 0-23
+ */
+const getSolarTerm = function (n: number): string {
+  assertInteger("getSolarTerm(n)", n, 0, 23);
+  return SolarTerm[n];
+};
+
+export {
+  lYearDays,
+  leapMonth,
+  leapDays,
+  lMonthDays,
+  yearStartOf,
+  monthSegmentsOf,
+  resolveLunarYear,
+  toGanZhiYear,
+  toGanZhi,
+  toHourGanZhi,
+  toChinaMonth,
+  toChinaDay,
+  getSolarTerm,
+  assertLunarYear,
+};

package/src/utils/SetFestival.ts

@@ -0,0 +1,40 @@
+import { mmddOf } from "./Assert";
+import type { FestivalMap } from "../types";
+
+/** 没有节日时共用的空数组，冻结后不怕调用方误改 */
+const NO_FESTIVAL: readonly string[] = Object.freeze([]) as readonly string[];
+
+/**
+ * 把两份节日表按 key 合并并去重，不修改入参
+ */
+const mergeFestivalMap = function (base: FestivalMap, extra?: FestivalMap): FestivalMap {
+  if (!extra) return base;
+  const result: FestivalMap = { ...base };
+  Object.keys(extra).forEach(function (key) {
+    const merged = result[key] ? result[key].concat(extra[key]) : extra[key];
+    result[key] = Array.from(new Set(merged));
+  });
+  return result;
+};
+
+/**
+ * 冻结节日表，防止调用方后续误改
+ */
+const freezeFestivalMap = function (map: FestivalMap): FestivalMap {
+  Object.keys(map).forEach(function (key) {
+    Object.freeze(map[key]);
+  });
+  return Object.freeze(map);
+};
+
+/**
+ * 取某一天（MMDD）的节日名称，没有则返回共享的空数组。
+ *
+ * 返回的是只读数组：配置里的数组已被冻结，调用方要追加节日必须自己 copy。
+ */
+const festivalList = function (map: FestivalMap, m: number, d: number): readonly string[] {
+  return map[mmddOf(m, d)] ?? NO_FESTIVAL;
+};
+
+export { mergeFestivalMap, freezeFestivalMap, festivalList, NO_FESTIVAL };
+export type { FestivalMap };