@weiensong/chinese-calendar 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 weiensong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# chinese-calendar
+
+[![npm version](https://img.shields.io/npm/v/@weiensong/chinese-calendar)](https://www.npmjs.com/package/@weiensong/chinese-calendar)
+[![license](https://img.shields.io/npm/l/@weiensong/chinese-calendar)](./LICENSE)
+
+A zero-dependency ESM package that determines whether a given date is a workday in mainland China. It respects the State Council's official holiday and adjusted-workday (调休) schedules, with optional support for Guangxi Sanyuesan (广西三月三).
+
+[中文文档](./README.zh-CN.md)
+
+---
+
+## Installation
+
+```bash
+npm install @weiensong/chinese-calendar
+```
+
+## Usage
+
+```js
+import { isWorkday, getDayInfo } from "@weiensong/chinese-calendar";
+```
+
+### `isWorkday(input, options?)`
+
+Returns `true` if the date is a workday, `false` otherwise.
+
+```js
+isWorkday(new Date(2026, 0, 5));   // true  — Monday
+isWorkday("2026-01-01");           // false — New Year holiday
+isWorkday("2026-01-04");           // true  — adjusted workday for New Year
+```
+
+### `getDayInfo(input, options?)`
+
+Returns a detailed result object explaining the classification.
+
+```js
+getDayInfo("2026-01-04");
+// {
+//   date: "2026-01-04",
+//   isWorkday: true,
+//   type: "adjusted-workday",
+//   holidayName: "元旦",
+//   scheduleYear: 2026,
+//   scheduleStatus: "official",
+//   sourceUrl: "https://www.gov.cn/..."
+// }
+```
+
+| `type`             | Meaning                 |
+| ------------------ | ----------------------- |
+| `regular-workday`  | Regular weekday         |
+| `weekend`          | Regular weekend         |
+| `holiday`          | Official holiday        |
+| `adjusted-workday` | Adjusted workday (调休) |
+
+### Options
+
+```ts
+interface Options {
+  requireOfficialSchedule?: boolean;  // throw if no data for the year
+  enableGuangxiSanyuesan?: boolean;   // enable Guangxi Sanyuesan holidays
+}
+```
+
+#### Strict mode
+
+```js
+import { isWorkday, ScheduleNotFoundError } from "@weiensong/chinese-calendar";
+
+try {
+  isWorkday("2027-01-04", { requireOfficialSchedule: true });
+} catch (error) {
+  console.log(error instanceof ScheduleNotFoundError); // true
+}
+```
+
+#### Guangxi Sanyuesan
+
+Disabled by default. When enabled, any date falling within the Sanyuesan period is resolved solely by Guangxi rules — national adjusted-workday schedules do not apply during this window.
+
+```js
+isWorkday("2025-03-31");                                   // true  — national workday
+isWorkday("2025-03-31", { enableGuangxiSanyuesan: true }); // false — Guangxi Sanyuesan
+```
+
+## Date input
+
+`isWorkday` and `getDayInfo` accept a `Date` object or a string. Strings in `YYYY-MM-DD` format are parsed as local calendar dates (no timezone offset). Other strings are parsed via `new Date()` and interpreted in the runtime's local timezone. Invalid input throws a `TypeError`.
+
+## Coverage
+
+Built-in data covers **2014–2026**, including subsequent adjustments such as the 2015 Victory Day holiday, 2019 Labor Day revision, and 2020 Spring Festival extension.
+
+When no schedule data exists for a year, the package falls back to simple weekday/weekend rules. Set `requireOfficialSchedule: true` to throw a `ScheduleNotFoundError` instead.
+
+## Adding a new year
+
+1. Create `data/YYYY.js` following the schema below.
+2. Register it in `data/index.js`.
+
+```js
+export default {
+  year: 2026,
+  source: {
+    title: "国务院办公厅关于2026年部分节假日安排的通知",
+    documentNumber: "国办发明电〔2025〕7号",
+    publishedAt: "2025-11-04",
+    url: "https://www.gov.cn/...",
+  },
+  holidays: [
+    { name: "春节", start: "2026-02-15", end: "2026-02-23" },
+  ],
+  adjustedWorkdays: [
+    { date: "2026-02-14", relatedHoliday: "春节" },
+  ],
+  guangxiSanyuesan: {
+    name: "广西三月三",
+    daysOff: [],
+    adjustedWorkdays: [],
+  },
+};
+```
+
+The `guangxiSanyuesan` block is required; leave arrays empty if unused.
+
+## Testing
+
+```bash
+npm test
+```
+
+Uses Node.js built-in test runner. No additional dependencies required.
+
+## License
+
+[MIT](./LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,138 @@
+# chinese-calendar
+
+[![npm version](https://img.shields.io/npm/v/@weiensong/chinese-calendar)](https://www.npmjs.com/package/@weiensong/chinese-calendar)
+[![license](https://img.shields.io/npm/l/@weiensong/chinese-calendar)](./LICENSE)
+
+零依赖的 ESM npm 包，判断中国大陆指定日期是否需要上班，遵循国务院官方节假日和调休安排，可选支持广西三月三。
+
+[English Documentation](./README.md)
+
+---
+
+## 安装
+
+```bash
+npm install @weiensong/chinese-calendar
+```
+
+## 使用
+
+```js
+import { isWorkday, getDayInfo } from "@weiensong/chinese-calendar";
+```
+
+### `isWorkday(input, options?)`
+
+返回 `true` 表示上班日，`false` 表示休息日。
+
+```js
+isWorkday(new Date(2026, 0, 5));   // true  — 星期一
+isWorkday("2026-01-01");           // false — 元旦假期
+isWorkday("2026-01-04");           // true  — 元旦调休上班
+```
+
+### `getDayInfo(input, options?)`
+
+返回包含判断依据的详细对象。
+
+```js
+getDayInfo("2026-01-04");
+// {
+//   date: "2026-01-04",
+//   isWorkday: true,
+//   type: "adjusted-workday",
+//   holidayName: "元旦",
+//   scheduleYear: 2026,
+//   scheduleStatus: "official",
+//   sourceUrl: "https://www.gov.cn/..."
+// }
+```
+
+| `type`             | 含义         |
+| ------------------ | ------------ |
+| `regular-workday`  | 普通工作日   |
+| `weekend`          | 普通周末     |
+| `holiday`          | 法定节假日   |
+| `adjusted-workday` | 调休上班日   |
+
+### 选项
+
+```ts
+interface Options {
+  requireOfficialSchedule?: boolean;  // 无年度数据时抛出错误
+  enableGuangxiSanyuesan?: boolean;   // 启用广西三月三
+}
+```
+
+#### 严格模式
+
+```js
+import { isWorkday, ScheduleNotFoundError } from "@weiensong/chinese-calendar";
+
+try {
+  isWorkday("2027-01-04", { requireOfficialSchedule: true });
+} catch (error) {
+  console.log(error instanceof ScheduleNotFoundError); // true
+}
+```
+
+#### 广西三月三
+
+默认不启用。启用后，三月三日期区间内的日期全部按广西规则判断，全国调休不覆盖该区间。
+
+```js
+isWorkday("2025-03-31");                                   // true  — 全国工作日
+isWorkday("2025-03-31", { enableGuangxiSanyuesan: true }); // false — 广西三月三放假
+```
+
+## 日期输入
+
+接受 `Date` 对象或字符串。`YYYY-MM-DD` 格式按本地日历日期解析（无时区偏移），其他字符串通过 `new Date()` 解析并按运行环境本地时区判断。无效输入抛出 `TypeError`。
+
+## 覆盖范围
+
+内置 **2014—2026** 年国务院节假日安排，包含历史上的后续调整（2015 年抗战胜利纪念日、2019 年劳动节调整、2020 年春节延长）。
+
+缺少年度数据时默认退回普通星期规则，可启用严格模式抛出 `ScheduleNotFoundError`。
+
+## 添加新年份
+
+1. 按以下结构创建 `data/YYYY.js`。
+2. 在 `data/index.js` 中注册。
+
+```js
+export default {
+  year: 2026,
+  source: {
+    title: "国务院办公厅关于2026年部分节假日安排的通知",
+    documentNumber: "国办发明电〔2025〕7号",
+    publishedAt: "2025-11-04",
+    url: "https://www.gov.cn/...",
+  },
+  holidays: [
+    { name: "春节", start: "2026-02-15", end: "2026-02-23" },
+  ],
+  adjustedWorkdays: [
+    { date: "2026-02-14", relatedHoliday: "春节" },
+  ],
+  guangxiSanyuesan: {
+    name: "广西三月三",
+    daysOff: [],
+    adjustedWorkdays: [],
+  },
+};
+```
+
+`guangxiSanyuesan` 字段为必填，没有假期时保留空数组。
+
+## 测试
+
+```bash
+npm test
+```
+
+使用 Node.js 原生测试运行器，无需安装额外依赖。
+
+## 许可证
+
+[MIT](./LICENSE)

package/data/2014.js

@@ -0,0 +1,30 @@
+export default {
+  year: 2014,
+  source: {
+    title: "国务院办公厅关于2014年部分节假日安排的通知",
+    documentNumber: "国办发明电〔2013〕28号",
+    publishedAt: "2013-12-11",
+    url: "https://www.yueyang.gov.cn/gggs/szbm/content_230742.html",
+  },
+  holidays: [
+    { name: "元旦", start: "2014-01-01", end: "2014-01-01" },
+    { name: "春节", start: "2014-01-31", end: "2014-02-06" },
+    { name: "清明节", start: "2014-04-05", end: "2014-04-07" },
+    { name: "劳动节", start: "2014-05-01", end: "2014-05-03" },
+    { name: "端午节", start: "2014-05-31", end: "2014-06-02" },
+    { name: "中秋节", start: "2014-09-06", end: "2014-09-08" },
+    { name: "国庆节", start: "2014-10-01", end: "2014-10-07" },
+  ],
+  adjustedWorkdays: [
+    { date: "2014-01-26", relatedHoliday: "春节" },
+    { date: "2014-02-08", relatedHoliday: "春节" },
+    { date: "2014-05-04", relatedHoliday: "劳动节" },
+    { date: "2014-09-28", relatedHoliday: "国庆节" },
+    { date: "2014-10-11", relatedHoliday: "国庆节" },
+  ],
+  guangxiSanyuesan: {
+    name: "广西三月三",
+    daysOff: ["2014-04-02", "2014-04-03"],
+    adjustedWorkdays: [],
+  },
+};

package/data/2015.js

@@ -0,0 +1,42 @@
+export default {
+  year: 2015,
+  source: {
+    title: "国务院办公厅关于2015年部分节假日安排的通知",
+    documentNumber: "国办发明电〔2014〕28号",
+    publishedAt: "2014-12-16",
+    url: "https://www.nea.gov.cn/2015-01/08/c_133904166.htm",
+  },
+  holidays: [
+    { name: "元旦", start: "2015-01-01", end: "2015-01-03" },
+    { name: "春节", start: "2015-02-18", end: "2015-02-24" },
+    { name: "清明节", start: "2015-04-04", end: "2015-04-06" },
+    { name: "劳动节", start: "2015-05-01", end: "2015-05-03" },
+    { name: "端午节", start: "2015-06-20", end: "2015-06-22" },
+    {
+      name: "抗战胜利纪念日",
+      start: "2015-09-03",
+      end: "2015-09-05",
+      sourceUrl:
+        "https://www.ndrc.gov.cn/xxgk/zcfb/qt/201505/t20150513_967883.html",
+    },
+    { name: "中秋节", start: "2015-09-26", end: "2015-09-27" },
+    { name: "国庆节", start: "2015-10-01", end: "2015-10-07" },
+  ],
+  adjustedWorkdays: [
+    { date: "2015-01-04", relatedHoliday: "元旦" },
+    { date: "2015-02-15", relatedHoliday: "春节" },
+    { date: "2015-02-28", relatedHoliday: "春节" },
+    {
+      date: "2015-09-06",
+      relatedHoliday: "抗战胜利纪念日",
+      sourceUrl:
+        "https://www.ndrc.gov.cn/xxgk/zcfb/qt/201505/t20150513_967883.html",
+    },
+    { date: "2015-10-10", relatedHoliday: "国庆节" },
+  ],
+  guangxiSanyuesan: {
+    name: "广西三月三",
+    daysOff: ["2015-04-20", "2015-04-21"],
+    adjustedWorkdays: [],
+  },
+};

package/data/2016.js

@@ -0,0 +1,36 @@
+export default {
+  year: 2016,
+  source: {
+    title: "国务院办公厅关于2016年部分节假日安排的通知",
+    documentNumber: "国办发明电〔2015〕18号",
+    publishedAt: "2015-12-11",
+    url: "https://www.nea.gov.cn/2015-12/11/c_134905936.htm",
+  },
+  holidays: [
+    { name: "元旦", start: "2016-01-01", end: "2016-01-03" },
+    { name: "春节", start: "2016-02-07", end: "2016-02-13" },
+    { name: "清明节", start: "2016-04-02", end: "2016-04-04" },
+    { name: "劳动节", start: "2016-04-30", end: "2016-05-02" },
+    { name: "端午节", start: "2016-06-09", end: "2016-06-11" },
+    { name: "中秋节", start: "2016-09-15", end: "2016-09-17" },
+    { name: "国庆节", start: "2016-10-01", end: "2016-10-07" },
+  ],
+  adjustedWorkdays: [
+    { date: "2016-02-06", relatedHoliday: "春节" },
+    { date: "2016-02-14", relatedHoliday: "春节" },
+    { date: "2016-06-12", relatedHoliday: "端午节" },
+    { date: "2016-09-18", relatedHoliday: "中秋节" },
+    { date: "2016-10-08", relatedHoliday: "国庆节" },
+    { date: "2016-10-09", relatedHoliday: "国庆节" },
+  ],
+  guangxiSanyuesan: {
+    name: "广西三月三",
+    daysOff: [
+      "2016-04-08",
+      "2016-04-09",
+      "2016-04-10",
+      "2016-04-11",
+    ],
+    adjustedWorkdays: [],
+  },
+};

package/data/2017.js

@@ -0,0 +1,33 @@
+export default {
+  year: 2017,
+  source: {
+    title: "国务院办公厅关于2017年部分节假日安排的通知",
+    documentNumber: "国办发明电〔2016〕17号",
+    publishedAt: "2016-12-02",
+    url: "https://app.www.gov.cn/govdata/gov/201612/01/394246/article.html",
+  },
+  holidays: [
+    { name: "元旦", start: "2016-12-31", end: "2017-01-02" },
+    { name: "春节", start: "2017-01-27", end: "2017-02-02" },
+    { name: "清明节", start: "2017-04-02", end: "2017-04-04" },
+    { name: "劳动节", start: "2017-04-29", end: "2017-05-01" },
+    { name: "端午节", start: "2017-05-28", end: "2017-05-30" },
+    {
+      name: "国庆节、中秋节",
+      start: "2017-10-01",
+      end: "2017-10-08",
+    },
+  ],
+  adjustedWorkdays: [
+    { date: "2017-01-22", relatedHoliday: "春节" },
+    { date: "2017-02-04", relatedHoliday: "春节" },
+    { date: "2017-04-01", relatedHoliday: "清明节" },
+    { date: "2017-05-27", relatedHoliday: "端午节" },
+    { date: "2017-09-30", relatedHoliday: "国庆节、中秋节" },
+  ],
+  guangxiSanyuesan: {
+    name: "广西三月三",
+    daysOff: ["2017-03-30", "2017-03-31", "2017-04-01"],
+    adjustedWorkdays: ["2017-04-08"],
+  },
+};

package/data/2018.js

@@ -0,0 +1,31 @@
+export default {
+  year: 2018,
+  source: {
+    title: "国务院办公厅关于2018年部分节假日安排的通知",
+    documentNumber: "国办发明电〔2017〕12号",
+    publishedAt: "2017-11-30",
+    url: "https://app.www.gov.cn/govdata/gov/201711/30/415918/article.html",
+  },
+  holidays: [
+    { name: "元旦", start: "2017-12-30", end: "2018-01-01" },
+    { name: "春节", start: "2018-02-15", end: "2018-02-21" },
+    { name: "清明节", start: "2018-04-05", end: "2018-04-07" },
+    { name: "劳动节", start: "2018-04-29", end: "2018-05-01" },
+    { name: "端午节", start: "2018-06-16", end: "2018-06-18" },
+    { name: "中秋节", start: "2018-09-22", end: "2018-09-24" },
+    { name: "国庆节", start: "2018-10-01", end: "2018-10-07" },
+  ],
+  adjustedWorkdays: [
+    { date: "2018-02-11", relatedHoliday: "春节" },
+    { date: "2018-02-24", relatedHoliday: "春节" },
+    { date: "2018-04-08", relatedHoliday: "清明节" },
+    { date: "2018-04-28", relatedHoliday: "劳动节" },
+    { date: "2018-09-29", relatedHoliday: "国庆节" },
+    { date: "2018-09-30", relatedHoliday: "国庆节" },
+  ],
+  guangxiSanyuesan: {
+    name: "广西三月三",
+    daysOff: ["2018-04-18", "2018-04-19", "2018-04-20"],
+    adjustedWorkdays: ["2018-04-15"],
+  },
+};

package/data/2019.js

@@ -0,0 +1,48 @@
+export default {
+  year: 2019,
+  source: {
+    title: "国务院办公厅关于2019年部分节假日安排的通知",
+    documentNumber: "国办发明电〔2018〕15号",
+    publishedAt: "2018-12-06",
+    url: "https://app.www.gov.cn/govdata/gov/201812/06/432792/article.html",
+  },
+  holidays: [
+    { name: "元旦", start: "2018-12-30", end: "2019-01-01" },
+    { name: "春节", start: "2019-02-04", end: "2019-02-10" },
+    { name: "清明节", start: "2019-04-05", end: "2019-04-07" },
+    {
+      name: "劳动节",
+      start: "2019-05-01",
+      end: "2019-05-04",
+      sourceUrl:
+        "https://app.www.gov.cn/govdata/gov/201903/22/436883/article.html",
+    },
+    { name: "端午节", start: "2019-06-07", end: "2019-06-09" },
+    { name: "中秋节", start: "2019-09-13", end: "2019-09-15" },
+    { name: "国庆节", start: "2019-10-01", end: "2019-10-07" },
+  ],
+  adjustedWorkdays: [
+    { date: "2018-12-29", relatedHoliday: "元旦" },
+    { date: "2019-02-02", relatedHoliday: "春节" },
+    { date: "2019-02-03", relatedHoliday: "春节" },
+    {
+      date: "2019-04-28",
+      relatedHoliday: "劳动节",
+      sourceUrl:
+        "https://app.www.gov.cn/govdata/gov/201903/22/436883/article.html",
+    },
+    {
+      date: "2019-05-05",
+      relatedHoliday: "劳动节",
+      sourceUrl:
+        "https://app.www.gov.cn/govdata/gov/201903/22/436883/article.html",
+    },
+    { date: "2019-09-29", relatedHoliday: "国庆节" },
+    { date: "2019-10-12", relatedHoliday: "国庆节" },
+  ],
+  guangxiSanyuesan: {
+    name: "广西三月三",
+    daysOff: ["2019-04-04", "2019-04-08"],
+    adjustedWorkdays: [],
+  },
+};

package/data/2020.js

@@ -0,0 +1,40 @@
+export default {
+  year: 2020,
+  source: {
+    title: "国务院办公厅关于2020年部分节假日安排的通知",
+    documentNumber: "国办发明电〔2019〕16号",
+    publishedAt: "2019-11-21",
+    url: "https://big5.www.gov.cn/gate/big5/www.gov.cn/zhengce/content/2019-11/21/content_5454164.htm",
+  },
+  holidays: [
+    { name: "元旦", start: "2020-01-01", end: "2020-01-01" },
+    {
+      name: "春节",
+      start: "2020-01-24",
+      end: "2020-02-02",
+      sourceUrl:
+        "https://app.www.gov.cn/govdata/gov/202001/27/453442/article.html",
+    },
+    { name: "清明节", start: "2020-04-04", end: "2020-04-06" },
+    { name: "劳动节", start: "2020-05-01", end: "2020-05-05" },
+    { name: "端午节", start: "2020-06-25", end: "2020-06-27" },
+    {
+      name: "国庆节、中秋节",
+      start: "2020-10-01",
+      end: "2020-10-08",
+    },
+  ],
+  adjustedWorkdays: [
+    { date: "2020-01-19", relatedHoliday: "春节" },
+    { date: "2020-04-26", relatedHoliday: "劳动节" },
+    { date: "2020-05-09", relatedHoliday: "劳动节" },
+    { date: "2020-06-28", relatedHoliday: "端午节" },
+    { date: "2020-09-27", relatedHoliday: "国庆节、中秋节" },
+    { date: "2020-10-10", relatedHoliday: "国庆节、中秋节" },
+  ],
+  guangxiSanyuesan: {
+    name: "广西三月三",
+    daysOff: [],
+    adjustedWorkdays: [],
+  },
+};

package/data/2021.js

@@ -0,0 +1,32 @@
+export default {
+  year: 2021,
+  source: {
+    title: "国务院办公厅关于2021年部分节假日安排的通知",
+    documentNumber: "国办发明电〔2020〕27号",
+    publishedAt: "2020-11-25",
+    url: "https://app.www.gov.cn/govdata/gov/202011/26/465359/article.html",
+  },
+  holidays: [
+    { name: "元旦", start: "2021-01-01", end: "2021-01-03" },
+    { name: "春节", start: "2021-02-11", end: "2021-02-17" },
+    { name: "清明节", start: "2021-04-03", end: "2021-04-05" },
+    { name: "劳动节", start: "2021-05-01", end: "2021-05-05" },
+    { name: "端午节", start: "2021-06-12", end: "2021-06-14" },
+    { name: "中秋节", start: "2021-09-19", end: "2021-09-21" },
+    { name: "国庆节", start: "2021-10-01", end: "2021-10-07" },
+  ],
+  adjustedWorkdays: [
+    { date: "2021-02-07", relatedHoliday: "春节" },
+    { date: "2021-02-20", relatedHoliday: "春节" },
+    { date: "2021-04-25", relatedHoliday: "劳动节" },
+    { date: "2021-05-08", relatedHoliday: "劳动节" },
+    { date: "2021-09-18", relatedHoliday: "中秋节" },
+    { date: "2021-09-26", relatedHoliday: "国庆节" },
+    { date: "2021-10-09", relatedHoliday: "国庆节" },
+  ],
+  guangxiSanyuesan: {
+    name: "广西三月三",
+    daysOff: ["2021-04-14", "2021-04-15", "2021-04-16"],
+    adjustedWorkdays: ["2021-04-18"],
+  },
+};

package/data/2022.js

@@ -0,0 +1,32 @@
+export default {
+  year: 2022,
+  source: {
+    title: "国务院办公厅关于2022年部分节假日安排的通知",
+    documentNumber: "国办发明电〔2021〕11号",
+    publishedAt: "2021-10-25",
+    url: "https://app.www.gov.cn/govdata/gov/202110/25/477428/article.html",
+  },
+  holidays: [
+    { name: "元旦", start: "2022-01-01", end: "2022-01-03" },
+    { name: "春节", start: "2022-01-31", end: "2022-02-06" },
+    { name: "清明节", start: "2022-04-03", end: "2022-04-05" },
+    { name: "劳动节", start: "2022-04-30", end: "2022-05-04" },
+    { name: "端午节", start: "2022-06-03", end: "2022-06-05" },
+    { name: "中秋节", start: "2022-09-10", end: "2022-09-12" },
+    { name: "国庆节", start: "2022-10-01", end: "2022-10-07" },
+  ],
+  adjustedWorkdays: [
+    { date: "2022-01-29", relatedHoliday: "春节" },
+    { date: "2022-01-30", relatedHoliday: "春节" },
+    { date: "2022-04-02", relatedHoliday: "清明节" },
+    { date: "2022-04-24", relatedHoliday: "劳动节" },
+    { date: "2022-05-07", relatedHoliday: "劳动节" },
+    { date: "2022-10-08", relatedHoliday: "国庆节" },
+    { date: "2022-10-09", relatedHoliday: "国庆节" },
+  ],
+  guangxiSanyuesan: {
+    name: "广西三月三",
+    daysOff: ["2022-04-02", "2022-04-06"],
+    adjustedWorkdays: [],
+  },
+};

package/data/2023.js

@@ -0,0 +1,35 @@
+export default {
+  year: 2023,
+  source: {
+    title: "国务院办公厅关于2023年部分节假日安排的通知",
+    documentNumber: "国办发明电〔2022〕16号",
+    publishedAt: "2022-12-08",
+    url: "https://app.www.gov.cn/govdata/gov/202212/08/495070/article.html",
+  },
+  holidays: [
+    { name: "元旦", start: "2022-12-31", end: "2023-01-02" },
+    { name: "春节", start: "2023-01-21", end: "2023-01-27" },
+    { name: "清明节", start: "2023-04-05", end: "2023-04-05" },
+    { name: "劳动节", start: "2023-04-29", end: "2023-05-03" },
+    { name: "端午节", start: "2023-06-22", end: "2023-06-24" },
+    {
+      name: "中秋节、国庆节",
+      start: "2023-09-29",
+      end: "2023-10-06",
+    },
+  ],
+  adjustedWorkdays: [
+    { date: "2023-01-28", relatedHoliday: "春节" },
+    { date: "2023-01-29", relatedHoliday: "春节" },
+    { date: "2023-04-23", relatedHoliday: "劳动节" },
+    { date: "2023-05-06", relatedHoliday: "劳动节" },
+    { date: "2023-06-25", relatedHoliday: "端午节" },
+    { date: "2023-10-07", relatedHoliday: "中秋节、国庆节" },
+    { date: "2023-10-08", relatedHoliday: "中秋节、国庆节" },
+  ],
+  guangxiSanyuesan: {
+    name: "广西三月三",
+    daysOff: ["2023-04-21", "2023-04-22", "2023-04-23"],
+    adjustedWorkdays: [],
+  },
+};

package/data/2024.js

@@ -0,0 +1,33 @@
+export default {
+  year: 2024,
+  source: {
+    title: "国务院办公厅关于2024年部分节假日安排的通知",
+    documentNumber: "国办发明电〔2023〕7号",
+    publishedAt: "2023-10-25",
+    url: "https://www.gov.cn/zhengce/content/202310/content_6911527.htm",
+  },
+  holidays: [
+    { name: "元旦", start: "2024-01-01", end: "2024-01-01" },
+    { name: "春节", start: "2024-02-10", end: "2024-02-17" },
+    { name: "清明节", start: "2024-04-04", end: "2024-04-06" },
+    { name: "劳动节", start: "2024-05-01", end: "2024-05-05" },
+    { name: "端午节", start: "2024-06-10", end: "2024-06-10" },
+    { name: "中秋节", start: "2024-09-15", end: "2024-09-17" },
+    { name: "国庆节", start: "2024-10-01", end: "2024-10-07" },
+  ],
+  adjustedWorkdays: [
+    { date: "2024-02-04", relatedHoliday: "春节" },
+    { date: "2024-02-18", relatedHoliday: "春节" },
+    { date: "2024-04-07", relatedHoliday: "清明节" },
+    { date: "2024-04-28", relatedHoliday: "劳动节" },
+    { date: "2024-05-11", relatedHoliday: "劳动节" },
+    { date: "2024-09-14", relatedHoliday: "中秋节" },
+    { date: "2024-09-29", relatedHoliday: "国庆节" },
+    { date: "2024-10-12", relatedHoliday: "国庆节" },
+  ],
+  guangxiSanyuesan: {
+    name: "广西三月三",
+    daysOff: ["2024-04-11", "2024-04-12"],
+    adjustedWorkdays: [],
+  },
+};

package/data/2025.js

@@ -0,0 +1,33 @@
+export default {
+  year: 2025,
+  source: {
+    title: "国务院办公厅关于2025年部分节假日安排的通知",
+    documentNumber: "国办发明电〔2024〕12号",
+    publishedAt: "2024-11-12",
+    url: "https://www.gov.cn/zhengce/zhengceku/202411/content_6986383.htm",
+  },
+  holidays: [
+    { name: "元旦", start: "2025-01-01", end: "2025-01-01" },
+    { name: "春节", start: "2025-01-28", end: "2025-02-04" },
+    { name: "清明节", start: "2025-04-04", end: "2025-04-06" },
+    { name: "劳动节", start: "2025-05-01", end: "2025-05-05" },
+    { name: "端午节", start: "2025-05-31", end: "2025-06-02" },
+    {
+      name: "国庆节、中秋节",
+      start: "2025-10-01",
+      end: "2025-10-08",
+    },
+  ],
+  adjustedWorkdays: [
+    { date: "2025-01-26", relatedHoliday: "春节" },
+    { date: "2025-02-08", relatedHoliday: "春节" },
+    { date: "2025-04-27", relatedHoliday: "劳动节" },
+    { date: "2025-09-28", relatedHoliday: "国庆节、中秋节" },
+    { date: "2025-10-11", relatedHoliday: "国庆节、中秋节" },
+  ],
+  guangxiSanyuesan: {
+    name: "广西三月三",
+    daysOff: ["2025-03-31", "2025-04-01"],
+    adjustedWorkdays: [],
+  },
+};

package/data/2026.js

@@ -0,0 +1,36 @@
+export default {
+  year: 2026,
+  source: {
+    title: "国务院办公厅关于2026年部分节假日安排的通知",
+    documentNumber: "国办发明电〔2025〕7号",
+    publishedAt: "2025-11-04",
+    url: "https://www.gov.cn/zhengce/zhengceku/202511/content_7047091.htm",
+  },
+  holidays: [
+    { name: "元旦", start: "2026-01-01", end: "2026-01-03" },
+    { name: "春节", start: "2026-02-15", end: "2026-02-23" },
+    { name: "清明节", start: "2026-04-04", end: "2026-04-06" },
+    { name: "劳动节", start: "2026-05-01", end: "2026-05-05" },
+    { name: "端午节", start: "2026-06-19", end: "2026-06-21" },
+    { name: "中秋节", start: "2026-09-25", end: "2026-09-27" },
+    { name: "国庆节", start: "2026-10-01", end: "2026-10-07" },
+  ],
+  adjustedWorkdays: [
+    { date: "2026-01-04", relatedHoliday: "元旦" },
+    { date: "2026-02-14", relatedHoliday: "春节" },
+    { date: "2026-02-28", relatedHoliday: "春节" },
+    { date: "2026-05-09", relatedHoliday: "劳动节" },
+    { date: "2026-09-20", relatedHoliday: "国庆节" },
+    { date: "2026-10-10", relatedHoliday: "国庆节" },
+  ],
+  guangxiSanyuesan: {
+    name: "广西三月三",
+    daysOff: [
+      "2026-04-17",
+      "2026-04-18",
+      "2026-04-19",
+      "2026-04-20",
+    ],
+    adjustedWorkdays: [],
+  },
+};

package/data/index.js

@@ -0,0 +1,29 @@
+import schedule2014 from "./2014.js";
+import schedule2015 from "./2015.js";
+import schedule2016 from "./2016.js";
+import schedule2017 from "./2017.js";
+import schedule2018 from "./2018.js";
+import schedule2019 from "./2019.js";
+import schedule2020 from "./2020.js";
+import schedule2021 from "./2021.js";
+import schedule2022 from "./2022.js";
+import schedule2023 from "./2023.js";
+import schedule2024 from "./2024.js";
+import schedule2025 from "./2025.js";
+import schedule2026 from "./2026.js";
+
+export const schedules = [
+  schedule2014,
+  schedule2015,
+  schedule2016,
+  schedule2017,
+  schedule2018,
+  schedule2019,
+  schedule2020,
+  schedule2021,
+  schedule2022,
+  schedule2023,
+  schedule2024,
+  schedule2025,
+  schedule2026,
+];

package/index.js

@@ -0,0 +1,5 @@
+export {
+  getDayInfo,
+  isWorkday,
+  ScheduleNotFoundError,
+} from "./lib/schedule.js";

package/lib/date.js

@@ -0,0 +1,86 @@
+const INVALID_DATE_MESSAGE =
+  "date must be a valid Date object or date string";
+
+/**
+ * Parse and validate a YYYY-MM-DD calendar date.
+ *
+ * @param {string} value
+ * @returns {{ year: number, month: number, day: number, timestamp: number }}
+ */
+export function parseDateKey(value) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+
+  if (!match) {
+    throw new TypeError(`invalid calendar date: ${value}`);
+  }
+
+  const [, year, month, day] = match.map(Number);
+  const timestamp = Date.UTC(year, month - 1, day);
+  const parsed = new Date(timestamp);
+
+  if (
+    parsed.getUTCFullYear() !== year ||
+    parsed.getUTCMonth() !== month - 1 ||
+    parsed.getUTCDate() !== day
+  ) {
+    throw new TypeError(`invalid calendar date: ${value}`);
+  }
+
+  return { year, month, day, timestamp };
+}
+
+/**
+ * Parse a public Date or string input using local calendar semantics.
+ *
+ * @param {Date|string} input
+ * @returns {Date}
+ */
+export function parseDateInput(input) {
+  let date;
+
+  if (input instanceof Date) {
+    date = input;
+  } else if (typeof input === "string" && input.trim() !== "") {
+    const value = input.trim();
+
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+      const { year, month, day } = parseDateKey(value);
+      date = new Date(0);
+      date.setHours(0, 0, 0, 0);
+      date.setFullYear(year, month - 1, day);
+    } else {
+      date = new Date(value);
+    }
+  } else {
+    throw new TypeError(INVALID_DATE_MESSAGE);
+  }
+
+  if (Number.isNaN(date.getTime())) {
+    throw new TypeError(INVALID_DATE_MESSAGE);
+  }
+
+  return date;
+}
+
+/**
+ * Format a Date as a local YYYY-MM-DD calendar key.
+ *
+ * @param {Date} date
+ * @returns {string}
+ */
+export function toDateKey(date) {
+  const year = String(date.getFullYear()).padStart(4, "0");
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+/**
+ * Format a UTC timestamp as YYYY-MM-DD.
+ *
+ * @param {number} timestamp
+ * @returns {string}
+ */
+export function utcTimestampToDateKey(timestamp) {
+  return new Date(timestamp).toISOString().slice(0, 10);
+}

package/lib/schedule.js

@@ -0,0 +1,322 @@
+import { schedules } from "../data/index.js";
+import {
+  parseDateInput,
+  parseDateKey,
+  toDateKey,
+  utcTimestampToDateKey,
+} from "./date.js";
+
+const ONE_DAY_IN_MILLISECONDS = 24 * 60 * 60 * 1000;
+const schedulesByYear = new Map();
+const exceptionsByDate = new Map();
+const guangxiSanyuesanByDate = new Map();
+const guangxiSanyuesanWorkdaysByDate = new Map();
+const guangxiSanyuesanPeriodDates = new Set();
+
+export class ScheduleNotFoundError extends Error {
+  /** @param {number} year */
+  constructor(year) {
+    super(`official workday schedule is not available for ${year}`);
+    this.name = "ScheduleNotFoundError";
+    this.year = year;
+  }
+}
+
+function assertNonEmptyString(value, field) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError(`${field} must be a non-empty string`);
+  }
+}
+
+function registerSchedule(schedule) {
+  if (!Number.isInteger(schedule.year)) {
+    throw new TypeError("schedule year must be an integer");
+  }
+
+  if (schedulesByYear.has(schedule.year)) {
+    throw new TypeError(`duplicate schedule year: ${schedule.year}`);
+  }
+
+  assertNonEmptyString(schedule.source?.title, "schedule source title");
+  assertNonEmptyString(schedule.source?.documentNumber, "schedule document number");
+  parseDateKey(schedule.source?.publishedAt);
+  assertNonEmptyString(schedule.source?.url, "schedule source URL");
+
+  schedulesByYear.set(schedule.year, schedule);
+
+  for (const holiday of schedule.holidays) {
+    assertNonEmptyString(holiday.name, "holiday name");
+    const start = parseDateKey(holiday.start);
+    const end = parseDateKey(holiday.end);
+
+    if (
+      Math.abs(start.year - schedule.year) > 1 ||
+      Math.abs(end.year - schedule.year) > 1
+    ) {
+      throw new TypeError(`holiday is too far from ${schedule.year}`);
+    }
+
+    if (end.timestamp < start.timestamp) {
+      throw new TypeError(`holiday starts after it ends: ${holiday.name}`);
+    }
+
+    for (
+      let timestamp = start.timestamp;
+      timestamp <= end.timestamp;
+      timestamp += ONE_DAY_IN_MILLISECONDS
+    ) {
+      const date = utcTimestampToDateKey(timestamp);
+
+      if (exceptionsByDate.has(date)) {
+        throw new TypeError(`conflicting schedule entry: ${date}`);
+      }
+
+      exceptionsByDate.set(date, {
+        type: "holiday",
+        isWorkday: false,
+        holidayName: holiday.name,
+        sourceUrl: holiday.sourceUrl ?? schedule.source.url,
+        schedule,
+      });
+    }
+  }
+
+  for (const adjustedWorkday of schedule.adjustedWorkdays) {
+    assertNonEmptyString(
+      adjustedWorkday.relatedHoliday,
+      "adjusted workday related holiday",
+    );
+    const { year } = parseDateKey(adjustedWorkday.date);
+
+    if (Math.abs(year - schedule.year) > 1) {
+      throw new TypeError(
+        `adjusted workday is too far from ${schedule.year}`,
+      );
+    }
+
+    if (exceptionsByDate.has(adjustedWorkday.date)) {
+      throw new TypeError(`conflicting schedule entry: ${adjustedWorkday.date}`);
+    }
+
+    exceptionsByDate.set(adjustedWorkday.date, {
+      type: "adjusted-workday",
+      isWorkday: true,
+      holidayName: adjustedWorkday.relatedHoliday,
+      sourceUrl: adjustedWorkday.sourceUrl ?? schedule.source.url,
+      schedule,
+    });
+  }
+
+  assertNonEmptyString(
+    schedule.guangxiSanyuesan?.name,
+    "Guangxi Sanyuesan name",
+  );
+
+  if (!Array.isArray(schedule.guangxiSanyuesan?.daysOff)) {
+    throw new TypeError("Guangxi Sanyuesan daysOff must be an array");
+  }
+
+  if (!Array.isArray(schedule.guangxiSanyuesan?.adjustedWorkdays)) {
+    throw new TypeError(
+      "Guangxi Sanyuesan adjustedWorkdays must be an array",
+    );
+  }
+
+  for (const date of schedule.guangxiSanyuesan.daysOff) {
+    const { year } = parseDateKey(date);
+
+    if (year !== schedule.year) {
+      throw new TypeError(
+        `Guangxi Sanyuesan day off must be within ${schedule.year}`,
+      );
+    }
+
+    if (guangxiSanyuesanByDate.has(date)) {
+      throw new TypeError(`duplicate Guangxi Sanyuesan day off: ${date}`);
+    }
+
+    guangxiSanyuesanByDate.set(date, {
+      holidayName: schedule.guangxiSanyuesan.name,
+      schedule,
+    });
+  }
+
+  for (const date of schedule.guangxiSanyuesan.adjustedWorkdays) {
+    const { year } = parseDateKey(date);
+
+    if (year !== schedule.year) {
+      throw new TypeError(
+        `Guangxi Sanyuesan adjusted workday must be within ${schedule.year}`,
+      );
+    }
+
+    if (
+      guangxiSanyuesanByDate.has(date) ||
+      guangxiSanyuesanWorkdaysByDate.has(date)
+    ) {
+      throw new TypeError(`conflicting Guangxi Sanyuesan entry: ${date}`);
+    }
+
+    guangxiSanyuesanWorkdaysByDate.set(date, {
+      holidayName: schedule.guangxiSanyuesan.name,
+      schedule,
+    });
+  }
+
+  const allSanyuesanDates = [
+    ...schedule.guangxiSanyuesan.daysOff,
+    ...schedule.guangxiSanyuesan.adjustedWorkdays,
+  ];
+
+  if (allSanyuesanDates.length > 0) {
+    const timestamps = allSanyuesanDates.map((d) => parseDateKey(d).timestamp);
+    const minTs = Math.min(...timestamps);
+    const maxTs = Math.max(...timestamps);
+
+    for (
+      let ts = minTs;
+      ts <= maxTs;
+      ts += ONE_DAY_IN_MILLISECONDS
+    ) {
+      guangxiSanyuesanPeriodDates.add(utcTimestampToDateKey(ts));
+    }
+  }
+}
+
+for (const schedule of schedules) {
+  registerSchedule(schedule);
+}
+
+function normalizeOptions(options) {
+  if (options === undefined) {
+    return {
+      requireOfficialSchedule: false,
+      enableGuangxiSanyuesan: false,
+    };
+  }
+
+  if (options === null || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("options must be an object");
+  }
+
+  const requireOfficialSchedule = options.requireOfficialSchedule ?? false;
+  const enableGuangxiSanyuesan = options.enableGuangxiSanyuesan ?? false;
+
+  if (typeof requireOfficialSchedule !== "boolean") {
+    throw new TypeError("requireOfficialSchedule must be a boolean");
+  }
+
+  if (typeof enableGuangxiSanyuesan !== "boolean") {
+    throw new TypeError("enableGuangxiSanyuesan must be a boolean");
+  }
+
+  return { requireOfficialSchedule, enableGuangxiSanyuesan };
+}
+
+/**
+ * Return an explainable workday classification for a date.
+ *
+ * @param {Date|string} input
+ * @param {{
+ *   requireOfficialSchedule?: boolean,
+ *   enableGuangxiSanyuesan?: boolean
+ * }} [options]
+ * @returns {{
+ *   date: string,
+ *   isWorkday: boolean,
+ *   type: "regular-workday"|"weekend"|"holiday"|"adjusted-workday",
+ *   holidayName: string|null,
+ *   scheduleYear: number|null,
+ *   scheduleStatus: "official"|"weekday-fallback",
+ *   sourceUrl: string|null
+ * }}
+ */
+export function getDayInfo(input, options) {
+  const date = parseDateInput(input);
+  const normalizedOptions = normalizeOptions(options);
+  const dateKey = toDateKey(date);
+  const year = date.getFullYear();
+  const schedule = schedulesByYear.get(year);
+
+  if (!schedule && normalizedOptions.requireOfficialSchedule) {
+    throw new ScheduleNotFoundError(year);
+  }
+
+  const guangxiSanyuesanWorkday = normalizedOptions.enableGuangxiSanyuesan
+    ? guangxiSanyuesanWorkdaysByDate.get(dateKey)
+    : undefined;
+
+  if (guangxiSanyuesanWorkday) {
+    return {
+      date: dateKey,
+      isWorkday: true,
+      type: "adjusted-workday",
+      holidayName: guangxiSanyuesanWorkday.holidayName,
+      scheduleYear: guangxiSanyuesanWorkday.schedule.year,
+      scheduleStatus: "official",
+      sourceUrl: null,
+    };
+  }
+
+  const guangxiSanyuesan = normalizedOptions.enableGuangxiSanyuesan
+    ? guangxiSanyuesanByDate.get(dateKey)
+    : undefined;
+
+  if (guangxiSanyuesan) {
+    return {
+      date: dateKey,
+      isWorkday: false,
+      type: "holiday",
+      holidayName: guangxiSanyuesan.holidayName,
+      scheduleYear: guangxiSanyuesan.schedule.year,
+      scheduleStatus: "official",
+      sourceUrl: null,
+    };
+  }
+
+  const inSanyuesanPeriod =
+    normalizedOptions.enableGuangxiSanyuesan &&
+    guangxiSanyuesanPeriodDates.has(dateKey);
+
+  if (!inSanyuesanPeriod) {
+    const exception = exceptionsByDate.get(dateKey);
+
+    if (exception) {
+      return {
+        date: dateKey,
+        isWorkday: exception.isWorkday,
+        type: exception.type,
+        holidayName: exception.holidayName,
+        scheduleYear: exception.schedule.year,
+        scheduleStatus: "official",
+        sourceUrl: exception.sourceUrl,
+      };
+    }
+  }
+
+  const isWorkday = date.getDay() >= 1 && date.getDay() <= 5;
+
+  return {
+    date: dateKey,
+    isWorkday,
+    type: isWorkday ? "regular-workday" : "weekend",
+    holidayName: null,
+    scheduleYear: schedule?.year ?? null,
+    scheduleStatus: schedule ? "official" : "weekday-fallback",
+    sourceUrl: schedule?.source.url ?? null,
+  };
+}
+
+/**
+ * Determine whether a date is a workday in mainland China's official schedule.
+ *
+ * @param {Date|string} input
+ * @param {{
+ *   requireOfficialSchedule?: boolean,
+ *   enableGuangxiSanyuesan?: boolean
+ * }} [options]
+ * @returns {boolean}
+ */
+export function isWorkday(input, options) {
+  return getDayInfo(input, options).isWorkday;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@weiensong/chinese-calendar",
+  "version": "0.0.2",
+  "description": "Determine whether a date is a workday in mainland China, respecting State Council holiday and adjusted-workday schedules",
+  "author": "weiensong",
+  "type": "module",
+  "sideEffects": false,
+  "exports": "./index.js",
+  "files": [
+    "index.js",
+    "lib",
+    "data"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/touero/chinese-calendar.git"
+  },
+  "homepage": "https://github.com/touero/chinese-calendar#readme",
+  "bugs": {
+    "url": "https://github.com/touero/chinese-calendar/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": [
+    "chinese-calendar",
+    "workday",
+    "holiday",
+    "china",
+    "中国节假日",
+    "工作日",
+    "调休"
+  ],
+  "license": "MIT"
+}