dsh-cron-parse

dsh-cron-parse

DSH 插件：解析 5 段标准 cron 表达式，提供校验、中文人性化描述、各字段展开值，以及未来若干次运行时间预览。纯 ESM、零依赖、无构建。

安装

dsh plugin --profile <name> add file:./plugins/dsh-cron-parse
# 或 npm 发布后：dsh plugin --profile <name> add dsh-cron-parse

安装后组合层会挂载 cron_parse 工具（cron-parse 层 id）。

工具：cron_parse

参数：

参数	类型	必填	说明
expression	string	是	5 段标准 cron：minute hour dayOfMonth month dayOfWeek
count	number	否	未来运行次数（1–10），默认 5
tz	string	否	IANA 时区名（如 Asia/Shanghai、UTC），默认本地时区
now	string	否	ISO 8601 基准时间，默认当前时间

返回规范值：{ ok, valid, description, fields: { minute, hour, dom, month, dow }, nextRuns, timezone, errors }。

支持语法表

语法	示例	含义
*	*	全部取值
*/n	*/15（分钟）	每 n（自最小值起）
a-b	1-5（星期）	闭区间
a-b/n	0-30/10	区间内步进
列表	1,15,30	多值并集
名称	jan-dec、sun-sat	月名/星期名，大小写不敏感
周日	0 或 7	0/7 都表示周日，展开后归一为 0

各字段取值范围：分钟 0-59，小时 0-23，日 1-31，月 1-12，星期 0-7。

语义说明

• dow / dom 并集（经典 Vixie 语义）：当「日（dayOfMonth）」与「星期（dayOfWeek）」都受限（字段不是纯 *）时，某天只要满足其一即触发（OR）；仅一个受限时用它；都不受限时每天触发。例如 0 0 1,15 * 1 表示每月 1 日、15 日以及每个周一触发。
• 受限判定：字段只有为纯 * 时才视为“不受限”；*/n、a-b、列表均视为受限。
• 下次运行计算：从 now 的下一分钟边界起，逐日扫描（日内按 hour×minute 枚举匹配时刻），最多迭代 100000 天（仅兜底，可满足表达式 + count≤10 永不触顶）。可满足性预判会提前拦截“日/月无可行组合”的永不触发表达式（如 0 0 30 2 *，2 月没有 30 日）并返回 ok:false。
• 所有结果按 tz（默认本地）时区解释；nextRuns 为带时区偏移的 ISO 8601 字符串。

人性化描述示例

表达式	描述
0 9 * * *	每天 09:00
30 8 * * 1-5	每周一至五 08:30
15 * * * *	每小时的第 15 分钟
*/15 * * * *	每 15 分钟
0 0 1 jan *	每年1月1日 00:00

复杂表达式（如 dow/dom 并集、多字段组合）退化为「字段原文 + 各字段展开值」。

局限

• 仅支持 5 段标准 cron，不支持秒段，也不支持 L、W、#、? 等特殊字符。
• 「永不触发」通过“日/月可行组合”预判 + 100000 天迭代上限双重判定；闰年 2 月 29 日 会被正确识别为可触发（约每 4 年一次）。
• 计算按目标时区墙钟逐日推进，夏令时切换瞬间的歧义/重复墙钟时刻按定点迭代的某一侧解释。

自检

挂载时自动执行 5 条自检（工作日 9 点 / 每 15 分钟 / 每年 1 月 1 日 / 非法值 / 2 月 30 日永不触发），证据行输出到日志，前缀 [dsh-cron-parse]。

License

MIT