cron vs agenda vs later vs bree vs bull vs node-cron vs node-schedule
Node.js 定时任务与作业调度库深度对比
搜索包...
cronagendalaterbreebullnode-cronnode-schedule类似的npm包:

Node.js 定时任务与作业调度库深度对比

agenda、bree、bull、cron、later、node-cron 和 node-schedule 都是用于在 Node.js 环境中执行定时任务或延迟作业的库，但它们的架构理念、依赖环境和适用场景截然不同。cron、node-cron 和 node-schedule 专注于基于 Cron 表达式的内存级定时触发，适合简单的周期性任务；later 提供更灵活的自然语言式调度逻辑但已停止维护；agenda 和 bull 是基于数据库（MongoDB 和 Redis）的重型作业队列，支持持久化、重试和分布式处理；bree 则是一个现代化的轻量级包装器，旨在简化原生 worker_threads 和 Cron 的使用，强调隔离性和易用性。

npm下载趋势

3 年

GitHub Stars 排名

统计详情

npm包名称
下载量
Stars
大小
Issues
发布时间
License
cron3,919,3978,952161 kB3910 个月前MIT
agenda82,6969,709301 kB443 个月前MIT
later16,8492,407-9811 年前MIT
bree03,29692 kB298 个月前MIT
bull016,254309 kB1482 年前MIT
node-cron03,282328 kB93 个月前ISC
node-schedule09,19835 kB1734 年前MIT

Node.js 定时任务与作业调度库深度对比：从内存 Cron 到分布式队列

在 Node.js 生态中，处理定时任务（Scheduled Jobs）和背景作业（Background Jobs）有多种方案。开发者常面临的选择困境是：究竟该用简单的内存定时器，还是引入沉重的数据库依赖？本文将深入对比 agenda、bree、bull、cron、later、node-cron 和 node-schedule，帮助你根据实际工程需求做出架构决策。

🕒 核心机制：内存计时 vs 持久化队列

这是选择库时的第一个分水岭。cron、node-cron、node-schedule 和 later 将调度信息保存在内存中。这意味着如果 Node.js 进程重启，所有待执行的任务都会丢失。相反，agenda 和 bull 将任务存储在数据库（MongoDB 或 Redis）中，确保即使服务崩溃，任务也能在恢复后继续执行。

node-cron 是典型的内存型库，它解析 Cron 表达式并在内存中设置定时器。

// node-cron: 内存级定时，进程重启后任务丢失
const cron = require('node-cron');

cron.schedule('*/5 * * * *', () => {
  console.log('每 5 分钟运行一次，重启后需重新注册');
});

bull 则将作业推入 Redis 队列，即使进程挂掉，作业依然安全存储在 Redis 中。

// bull: 持久化队列，进程重启后作业仍可处理
const Queue = require('bull');
const myQueue = new Queue('my-tasks', 'redis://127.0.0.1:6379');

myQueue.add({ foo: 'bar' }, { repeat: { cron: '*/5 * * * *' } });
// 作业定义存储在 Redis 中，Worker 可随时拉取

agenda 使用 MongoDB 存储作业定义和状态，支持复杂的查询和锁定机制。

// agenda: 基于 MongoDB 的持久化作业
const Agenda = require('agenda');
const agenda = new Agenda({ db: { address: 'mongodb://localhost/agenda' } });

agenda.define('send email', async (job) => {
  console.log('发送电子邮件');
});

await agenda.every('5 minutes', 'send email');
// 调度规则存入 MongoDB，支持多实例竞争锁

bree 虽然主要作为包装器，但它支持将作业配置持久化到文件系统或数据库，并结合了 worker_threads。

// bree: 配置文件驱动，支持持久化配置
const Bree = require('bree');

const bree = new Bree({
  root: './jobs',
  jobs: [
    { name: 'daily-report', interval: '0 0 * * *' } // 支持 cron 字符串
  ]
});

bree.start();

🧵 执行模型：阻塞主线程 vs 线程隔离

在单线程的 Node.js 中，长时间运行的任务会阻塞事件循环，导致 API 响应变慢。传统的 node-cron 和 node-schedule 默认在主线程执行回调。而 bree 和 bull 提供了更好的隔离方案。

node-schedule 直接在主线程执行回调函数，若任务耗时过长，会阻塞其他请求。

// node-schedule: 主线程执行，耗时任务会阻塞事件循环
const schedule = require('node-schedule');

schedule.scheduleJob('*/10 * * * *', async () => {
  await heavyComputation(); // 阻塞主线程！
});

bree 的核心优势在于默认使用 worker_threads，将任务放在独立的线程中运行，彻底解耦主线程。

// bree: 自动使用 worker_threads 隔离任务
// jobs/daily-report.js (独立文件)
module.exports = async () => {
  await heavyComputation(); // 在独立线程运行，不阻塞主进程
};

// 主进程配置
const bree = new Bree({ root: './jobs', jobs: ['daily-report'] });

bull 通过定义独立的 Worker 进程来处理作业，天然支持分布式和进程隔离。

// bull: 独立的 Worker 进程处理作业
// worker.js
const worker = queue.process(async (job) => {
  await heavyComputation(); // 在独立进程/线程中运行
});

📝 调度语法：标准 Cron vs 灵活规则

对于调度频率的定义，不同库提供了不同粒度的控制。

cron 提供最基础的 Cron 解析，严格遵循标准，不支持秒级或非标准表达式。

// cron: 基础解析，通常用于底层
const { CronJob } = require('cron');

new CronJob('0 0 12 * * *', () => {
  console.log('中午 12 点执行');
});

node-schedule 扩展了 Cron 语法，支持直接传入 Date 对象或递归规则（RecurrenceRule），灵活性更高。

// node-schedule: 支持 Date 对象和复杂规则
const schedule = require('node-schedule');

// 一次性任务：特定时间点
schedule.scheduleJob(new Date(2023, 11, 31, 23, 59, 59), () => {
  console.log('新年快乐');
});

// 递归规则：每周五下午 3 点
const rule = new schedule.RecurrenceRule();
rule.dayOfWeek = 5;
rule.hour = 15;
schedule.scheduleJob(rule, () => {
  console.log('周五下午茶时间');
});

later (已弃用) 曾提供极具可读性的自然语言式调度，但现在不再推荐。

// later: 自然语言风格 (已不推荐在新项目使用)
const later = require('later');

const schedule = later.parse.text('every 5 mins on weekdays');
later.setInterval(() => {
  console.log('工作日每 5 分钟');
}, schedule);

bree 和 bull 均支持标准的 Cron 字符串，同时也支持人类可读的时间间隔（如 5 seconds）。

// bree: 支持人类可读间隔
const bree = new Bree({
  jobs: [
    { name: 'task1', interval: '5 seconds' },
    { name: 'task2', cron: '0 0 * * *' }
  ]
});

// bull: 重复作业配置
queue.add('task', {}, {
  repeat: { cron: '*/5 * * * *' } // 标准 Cron
  // 或 repeat: { every: 5000 } // 毫秒间隔
});

⚠️ 维护状态与风险提示

在选型时，库的活跃程度至关重要。

  • later: 已弃用。该库已多年未更新，存在潜在的安全风险和兼容性问题。强烈建议不要在新项目中使用。如果需要灵活的调度语法，请迁移至 node-schedule 或使用 cronstrue 辅助生成表达式。
  • cron: 维护状态一般，功能较为基础，通常作为其他库的依赖存在。除非你需要极小的包体积且只需最基础的功能，否则推荐功能更完善的 node-cron。
  • agenda / bull: 两者都非常活跃，但架构较重。agenda 依赖 MongoDB，bull 依赖 Redis。如果你的基础设施中没有这些数据库，引入它们仅为了定时任务可能得不偿失。
  • bree: 现代、轻量且积极维护。它是目前替代老旧 node-cron + child_process 组合的最佳实践方案。

🌐 真实场景决策指南

场景 1：简单的日志清理或健康检查

需求：每天凌晨运行一次，无需持久化，代码简单。

  • ✅ 推荐: node-cron 或 bree
  • 理由：轻量级，零配置。bree 更能防止阻塞主线程。
// 使用 node-cron
cron.schedule('0 0 * * *', () => cleanupLogs());

场景 2：发送营销邮件或生成大型报表

需求：任务耗时久，不能阻塞 API 响应，失败需重试。

  • ✅ 推荐: bull 或 agenda
  • 理由：需要持久化保证不丢失，需要重试机制，需要独立进程处理耗时逻辑。
// 使用 bull
queue.add('generate-report', { userId: 123 }, { attempts: 3, backoff: { type: 'exponential', delay: 2000 } });

场景 3：复杂的动态调度系统

需求：用户可在界面动态设置任意时间的提醒，支持单次和循环。

  • ✅ 推荐: node-schedule (小规模) 或 agenda (大规模)
  • 理由：node-schedule 支持 Date 对象，适合动态添加一次性任务。若需集群支持，则选 agenda。
// 使用 node-schedule 动态添加
schedule.scheduleJob(userSelectedDate, () => sendReminder());

📊 总结对比表

特性node-cronnode-schedulebreebullagendalater
存储方式内存内存配置/内存RedisMongoDB内存
进程重启存活❌❌✅ (配置持久化)✅✅❌
执行隔离主线程主线程Worker Threads独立 Worker主线程/Worker主线程
调度语法CronCron + Date + RuleCron + IntervalCron + IntervalCron + HumanNatural Language
重试机制❌❌✅ (基础)✅ (高级)✅ (高级)❌
分布式支持❌❌❌✅✅❌
维护状态✅✅✅✅✅❌ (弃用)

💡 架构师建议

对于大多数现代 Node.js 应用，bree 是最平衡的选择：它既解决了主线程阻塞问题，又提供了简单的 Cron 支持，且没有重型数据库依赖。

如果你的业务涉及关键数据流（如支付回调、重要通知），必须保证任务绝对不丢失且支持横向扩展，那么 bull (配合 Redis) 是工业界的标准答案。

尽量避免使用 later，并在需要复杂调度逻辑时优先考虑 node-schedule 而非原始的 cron 包。记住，简单的工具解决简单的问题，复杂的工具解决可靠性的问题 —— 不要为了杀鸡而用牛刀，也不要为了盖楼而只用积木。

如何选择: cron vs agenda vs later vs bree vs bull vs node-cron vs node-schedule

  • cron:

    仅在对性能有极致要求且不需要人类可读的 Cron 表达式时选择基础的 cron 包。它提供了最底层的 Cron 解析能力，通常作为其他库的底层依赖，对于大多数应用层开发来说，直接使用更上层的封装（如 node-cron）通常是更好的选择。

  • agenda:

    如果你的项目已经使用 MongoDB 且需要强大的作业持久化、重试机制和分布式处理能力，选择 agenda。它适合需要确保任务不丢失、支持复杂查询筛选作业以及需要管理后台任务队列的企业级应用，但需注意其依赖 MongoDB 带来的运维成本。

  • later:

    避免在新项目中使用 later，因为它已不再积极维护。虽然它曾提供比标准 Cron 更灵活的调度语法（如自然语言解析），但在现代 Node.js 生态中，其功能已被 node-schedule 或更专业的作业队列库所取代，继续使用可能带来兼容性风险。

  • bree:

    选择 bree 如果你希望以最小的配置快速启动定时任务，同时利用 Node.js 原生的 worker_threads 实现任务隔离以防止主线程阻塞。它非常适合现代 Node.js 项目，特别是那些希望避免重型依赖（如 Redis/MongoDB）且需要简单 Cron 调度或脚本定期执行的场景。

  • bull:

    当你的系统需要高吞吐量、极高的可靠性以及复杂的作业流控制（如优先级、延迟、重复、沙箱处理）时，bull 是最佳选择。基于 Redis 的特性使其在分布式环境和微服务架构中表现卓越，适合处理关键业务逻辑的背景作业，但需承担 Redis 的维护成本。

  • node-cron:

    如果你需要一个零依赖、轻量级且仅用于在单进程中执行简单周期性任务的库，node-cron 是理想选择。它完美兼容标准 Cron 语法，适合日志轮转、健康检查等不需要持久化或分布式的简单场景，但不适合长运行或关键任务。

  • node-schedule:

    选择 node-schedule 如果你需要比标准 Cron 更丰富的调度规则（如支持 Date 对象、递归规则）且希望保持代码简洁。它在内存中运行，适合中等复杂度的定时任务，但在进程重启后会丢失任务状态，因此不适用于需要严格保证执行的关键作业。

与cron类似的npm包

cron 是一个用于 Node.js 的时间调度库，允许开发者根据 cron 表达式安排任务的执行。它提供了一种简单而强大的方式来定期执行任务，适用于需要定时执行的场景，比如定期发送电子邮件、清理数据库或执行数据备份等。虽然 cron 提供了强大的调度功能，但在 Node.js 生态系统中还有其他一些替代库可以实现类似的功能。以下是几个替代方案：

  • agenda 是一个轻量级的任务调度库，基于 MongoDB。它允许开发者使用简单的 API 定义和调度任务，并支持任务的重复执行、延迟执行和优先级管理。由于 agenda 使用 MongoDB 存储任务信息，因此它非常适合需要持久化任务的应用程序。如果你的应用需要复杂的任务调度和持久化功能，agenda 是一个不错的选择。
  • later 是一个灵活的调度库，支持多种时间格式和调度规则。它允许开发者使用简单的 JavaScript 对象定义复杂的调度规则，并提供了强大的解析和格式化功能。later 适合需要灵活调度的应用程序，尤其是当任务的执行时间不规则时。如果你需要一个可以处理复杂调度逻辑的库，later 是一个值得考虑的选项。
  • node-cron 是一个简单的任务调度库，灵感来自于 UNIX 的 cron。它允许开发者使用 cron 表达式轻松地安排任务，并支持定时执行和重复执行。node-cron 的 API 简单易用，适合需要基本调度功能的应用程序。如果你只需要一个简单的调度解决方案，node-cron 是一个理想的选择。

要查看 cron 与其他库的比较，请访问：比较 agenda vs cron vs later vs node-cron。

与agenda类似的npm包

agenda 是一个用于 Node.js 的轻量级任务调度库。它允许开发者使用 MongoDB 来存储和调度任务，提供了一种简单而灵活的方式来处理定时任务和后台作业。虽然 agenda 提供了强大的任务调度功能，但在 Node.js 生态系统中还有其他库可以作为替代方案。以下是一些替代库：

  • bull 是一个功能强大的任务和消息队列库，基于 Redis 构建。它支持优先级、延迟和重复任务等高级功能，非常适合需要处理大量任务的应用程序。Bull 的设计旨在提供高性能和可靠性，尤其适合需要处理复杂工作流和任务调度的场景。如果你的应用需要高吞吐量和强大的任务管理功能，Bull 是一个理想的选择。
  • node-schedule 是一个基于 cron 表达式的任务调度库，允许开发者在 Node.js 中轻松地安排定时任务。它的 API 简单易用，适合需要在特定时间或间隔执行任务的应用。与 agenda 和 bull 不同，node-schedule 更加专注于简单的定时任务调度，而不是任务队列或后台作业处理。如果你的需求主要是定时执行任务，node-schedule 是一个不错的选择。

要查看 agenda 与 bull 和 node-schedule 的比较，请访问：比较 agenda vs bull vs node-schedule。

与later类似的npm包

later 是一个用于在 Node.js 应用程序中处理定时任务的库。它提供了一种灵活的方式来安排和执行定时任务，支持多种时间格式和调度选项。虽然 later 提供了强大的定时任务调度功能，但在 Node.js 生态系统中还有其他类似的库可以选择。以下是一些替代方案：

  • agenda 是一个基于 MongoDB 的轻量级任务调度库，适用于 Node.js 应用程序。它允许开发者使用简单的 API 来安排和执行任务，支持重复任务和延迟任务。由于其与 MongoDB 的紧密集成，agenda 特别适合需要持久化任务和调度的应用程序。如果你的应用需要一个强大的任务调度解决方案，并且你已经在使用 MongoDB，agenda 是一个不错的选择。
  • cron 是一个经典的定时任务调度库，模仿了 Unix 系统中的 cron 功能。它允许开发者使用 cron 表达式来定义任务的调度规则。由于其简单易用和广泛的社区支持，cron 是许多 Node.js 应用程序的首选定时任务解决方案。如果你熟悉 cron 表达式并希望快速设置定时任务，cron 是一个理想的选择。
  • node-schedule 是一个灵活的任务调度库，允许开发者使用 JavaScript 对象来定义任务的调度。它支持 cron 表达式和日期对象，提供了丰富的调度选项。node-schedule 适合需要灵活调度和简单 API 的应用程序。如果你希望在 Node.js 中使用简单的调度方法，node-schedule 是一个不错的选择。

查看比较：比较 agenda vs cron vs later vs node-schedule。

与bree类似的npm包

bree 是一个用于 Node.js 的任务调度库，旨在简化定时任务的管理和执行。它支持使用 JavaScript 和 TypeScript 编写的任务，并提供了易于使用的 API，允许开发者轻松地调度和管理后台任务。虽然 bree 提供了强大的任务调度功能，但在 Node.js 生态系统中还有其他一些替代库。以下是一些替代方案：

  • agenda 是一个轻量级的任务调度库，基于 MongoDB。它允许开发者使用简单的语法来定义和调度任务，并支持重复任务、延迟任务和优先级设置。对于需要持久化任务和复杂调度的应用，agenda 是一个不错的选择。
  • bull 是一个功能强大的任务和消息队列库，基于 Redis。它支持复杂的任务调度、并发处理和失败重试机制。bull 非常适合需要高性能和可靠性的任务处理场景，尤其是在处理大量并发任务时。
  • cron 是一个简单的任务调度库，允许开发者使用 cron 表达式来定义任务的执行时间。它非常适合需要定期执行的任务，如每天、每周或每月的任务。cron 的使用非常直观，适合简单的调度需求。
  • later 是一个灵活的任务调度库，支持复杂的时间表达式和调度规则。它允许开发者使用自然语言来定义任务的执行时间，适合需要灵活调度的场景。
  • node-cron 是一个轻量级的 cron 任务调度库，允许开发者使用 cron 表达式来调度任务。它非常简单易用，适合需要基本调度功能的应用。
  • node-schedule 是一个功能强大的任务调度库，支持使用 cron 表达式和 JavaScript Date 对象来定义任务的执行时间。它适合需要灵活调度和复杂时间规则的应用。

要查看 bree 与其他库的比较，请访问：比较 agenda vs bree vs bull vs cron vs later vs node-cron vs node-schedule。

与bull类似的npm包

bull 是一个用于 Node.js 的高性能任务和消息队列库。它基于 Redis 构建，能够处理大量的任务和作业，适合需要高并发和高可靠性的应用程序。Bull 提供了丰富的功能，包括任务重试、延迟任务、优先级队列等，使得开发者能够轻松管理和调度任务。尽管 Bull 是一个强大的选择，但在 Node.js 生态系统中，还有其他一些替代库可供选择。以下是几个替代方案：

  • agenda 是一个轻量级的任务调度库，使用 MongoDB 作为数据存储。它允许开发者使用简单的 API 定义和调度任务，适合需要定时任务或周期性任务的应用。Agenda 的灵活性和易用性使其成为小型到中型项目的理想选择。
  • bee-queue 是一个简单且高效的任务队列库，专为处理大量短任务而设计。与 Bull 类似，bee-queue 也基于 Redis，但它的重点是提供更简单的 API 和更快的性能，适合需要快速处理任务的场景。
  • bullmq 是 Bull 的下一代版本，提供了更强大的功能和更好的性能。它支持更复杂的任务管理和调度，适合需要更高灵活性和可扩展性的应用程序。BullMQ 还引入了更好的类型支持和更丰富的 API，使得开发者能够更轻松地管理任务。
  • kue 是一个基于 Redis 的优先级任务队列库，提供了丰富的功能，包括任务重试、优先级管理和实时监控。虽然 Kue 的功能强大，但它的维护更新相对较少，可能不如 Bull 和其他库那么活跃。
  • node-resque 是一个用于 Node.js 的任务队列库，支持多种后端存储，包括 Redis 和 MongoDB。它提供了灵活的任务调度和处理机制，适合需要多种存储选项和复杂任务管理的应用。

要查看这些库之间的比较，请访问：Comparing agenda vs bee-queue vs bull vs bullmq vs kue vs node-resque。

与node-cron类似的npm包

node-cron 是一个用于 Node.js 的定时任务调度库。它允许开发者使用类似于 Unix cron 的语法来设置和管理定时任务，能够在特定的时间间隔或特定的时间点执行函数。这个库非常适合需要定期执行某些操作的场景，比如定时备份、数据抓取或发送定期报告等。

虽然 node-cron 提供了强大的定时任务调度功能，但在 Node.js 生态系统中还有其他一些库可以作为替代方案。以下是几个常见的替代库：

  • cron 是一个功能强大的定时任务调度库，提供了类似于 Unix cron 的功能。与 node-cron 类似，cron 允许开发者使用 cron 表达式来定义任务的执行时间。它的灵活性和强大功能使其适合于需要复杂调度的应用程序。如果你需要更高级的调度功能，cron 是一个不错的选择。
  • node-schedule 是另一个用于 Node.js 的定时任务调度库。与 node-cron 和 cron 不同，node-schedule 提供了一种更灵活的调度方式，允许开发者使用 JavaScript 的 Date 对象来设置任务的执行时间。它适合于需要在特定时间点或特定条件下执行任务的场景。如果你的调度需求比较复杂，node-schedule 可能会更符合你的需求。

要查看 node-cron 与 cron 和 node-schedule 的比较，请访问：比较 cron vs node-cron vs node-schedule。

与node-schedule类似的npm包

node-schedule 是一个用于 Node.js 的定时任务调度库。它允许开发者轻松地安排和管理定时任务，支持使用 cron 表达式或 JavaScript Date 对象来定义任务的执行时间。虽然 node-schedule 提供了强大的调度功能，但在 Node.js 生态系统中还有其他一些库可以作为替代方案。以下是几个替代库：

  • agenda 是一个轻量级的任务调度库，基于 MongoDB。它允许开发者使用简单的 API 来定义和管理任务，并提供了持久化存储的能力。Agenda 适合需要持久化任务调度的应用程序，尤其是在需要跨服务器或重启后保持任务状态的情况下。
  • cron 是一个经典的定时任务调度库，允许开发者使用 cron 表达式来定义任务的执行时间。它提供了简单的 API 来创建和管理任务，适合需要精确控制任务调度的场景。Cron 是一个成熟的解决方案，适合于各种 Node.js 应用程序。
  • later 是一个灵活的定时任务调度库，支持复杂的调度需求。它允许开发者使用自然语言或对象来定义任务的执行时间，并提供了丰富的功能来处理不同的时间间隔和规则。Later 适合需要高度自定义调度的应用程序。
  • node-cron 是一个简单的 cron 任务调度库，允许开发者使用 cron 表达式来定义任务的执行时间。它的 API 直观易用，适合需要简单定时任务调度的场景。Node-cron 是一个轻量级的解决方案，适合小型项目或简单的定时任务需求。

要查看 node-schedule 与其他库的比较，请访问：比较 agenda vs cron vs later vs node-cron vs node-schedule。

cron的README

cron for Node.js logo
cron is a robust tool for running jobs (functions or commands) on schedules defined using the cron syntax.
Perfect for tasks like data backups, notifications, and many more!

Cron for Node.js

Version Monthly Downloads Build Status CodeQL Status Coverage Renovate OpenSSF Scorecard Discord

🌟 Features

  • execute a function whenever your scheduled job triggers
  • execute a job external to the javascript process (like a system command) using child_process
  • use a Date or Luxon DateTime object instead of cron syntax as the trigger for your callback
  • use an additional slot for seconds (leaving it off will default to 0 and match the Unix behavior)

🚀 Installation

npm install cron

Table of Contents

  1. Features
  2. Installation
  3. Migrating
  4. Basic Usage
  5. Cron Patterns
  6. API
  7. Gotchas
  8. Community
  9. Contributing
  10. Acknowledgements
  11. License

⬆ Migrating

v4 dropped Node v16 and renamed the job.running property:

Migrating from v3 to v4

Dropped Node version

Node v16 is no longer supported. Upgrade your Node installation to Node v18 or above

Property renamed and now read-only

You can no longer set the running property (now isActive). It is read-only. To start or stop a cron job, use job.start() and job.stop().

v3 introduced TypeScript and tighter Unix cron pattern alignment:

Migrating from v2 to v3

Month & day-of-week indexing changes

  • Month Indexing: Changed from 0-11 to 1-12. So you need to increment all numeric months by 1.

  • Day-of-Week Indexing: Support added for 7 as Sunday.

Adjustments in CronJob

  • The constructor no longer accepts an object as its first and only params. Use CronJob.from(argsObject) instead.
  • Callbacks are now called in the order they were registered.
  • nextDates(count?: number) now always returns an array (empty if no argument is provided). Use nextDate() instead for a single date.

Removed methods

  • removed job() method in favor of new CronJob(...args) / CronJob.from(argsObject)

  • removed time() method in favor of new CronTime()

🛠 Basic Usage

import { CronJob } from 'cron';

const job = new CronJob(
	'* * * * * *', // cronTime
	function () {
		console.log('You will see this message every second');
	}, // onTick
	null, // onComplete
	true, // start
	'America/Los_Angeles' // timeZone
);
// job.start() is optional here because of the fourth parameter set to true.

// equivalent job using the "from" static method, providing parameters as an object
const job = CronJob.from({
	cronTime: '* * * * * *',
	onTick: function () {
		console.log('You will see this message every second');
	},
	start: true,
	timeZone: 'America/Los_Angeles'
});

Note: In the first example above, the fourth parameter to CronJob() starts the job automatically. If not provided or set to falsy, you must explicitly start the job using job.start().

For more advanced examples, check the examples directory.

⏰ Cron Patterns

Cron patterns are the backbone of this library. Familiarize yourself with the syntax:

- `*` Asterisks: Any value
- `1-3,5` Ranges: Ranges and individual values
- `*/2` Steps: Every two units

Detailed patterns and explanations are available at crontab.org. The examples in the link have five fields, and 1 minute as the finest granularity, but our cron scheduling supports an enhanced format with six fields, allowing for second-level precision. Tools like crontab.guru can help in constructing patterns but remember to account for the seconds field.

Supported Ranges

Here's a quick reference to the UNIX Cron format this library uses, plus an added second field:

field          allowed values
-----          --------------
second         0-59
minute         0-59
hour           0-23
day of month   1-31
month          1-12 (or names, see below)
day of week    0-7 (0 or 7 is Sunday, or use names)

Names can also be used for the 'month' and 'day of week' fields. Use the first three letters of the particular day or month (case does not matter). Ranges and lists of names are allowed.
Examples: "mon,wed,fri", "jan-mar".

📖 API

Standalone Functions

  • sendAt: Indicates when a CronTime will execute (returns a Luxon DateTime object).

    import * as cron from 'cron';

const dt = cron.sendAt('0 0 * * *');
console.log(`The job would run at: ${dt.toISO()}`);

  • timeout: Indicates the number of milliseconds in the future at which a CronTime will execute (returns a number).

    import * as cron from 'cron';

const timeout = cron.timeout('0 0 * * *');
console.log(`The job would run in ${timeout}ms`);

  • validateCronExpression: Validates if a given cron expression is valid (returns an object with valid and error properties).

    import * as cron from 'cron';

const validation = cron.validateCronExpression('0 0 * * *');
console.log(`Is the cron expression valid? ${validation.valid}`);
if (!validation.valid) {
	console.error(`Validation error: ${validation.error}`);
}

CronJob Class

Constructor

constructor(cronTime, onTick, onComplete, start, timeZone, context, runOnInit, utcOffset, unrefTimeout, waitForCompletion, errorHandler, name, threshold):

  • cronTime: [REQUIRED] - The time to fire off your job. Can be cron syntax, a JS Date object or a Luxon DateTime object.

  • onTick: [REQUIRED] - Function to execute at the specified time. If an onComplete callback was provided, onTick will receive it as an argument.

  • onComplete: [OPTIONAL] - Invoked when the job is halted with job.stop(). It might also be triggered by onTick post its run.

  • start: [OPTIONAL] - Determines if the job should commence before constructor exit. Default is false.

  • timeZone: [OPTIONAL] - Sets the execution time zone. Default is local time. Check valid formats in the Luxon documentation.

  • context: [OPTIONAL] - Execution context for the onTick method.

  • runOnInit: [OPTIONAL] - Instantly triggers the onTick function post initialization. Default is false.

  • utcOffset: [OPTIONAL] - Specifies time zone offset in minutes. Cannot co-exist with timeZone.

  • unrefTimeout: [OPTIONAL] - Useful for controlling event loop behavior. More details here.

  • waitForCompletion: [OPTIONAL] - If true, no additional instances of the onTick callback function will run until the current onTick callback has completed. Any new scheduled executions that occur while the current callback is running will be skipped entirely. Default is false.

  • errorHandler: [OPTIONAL] - Function to handle any exceptions that occur in the onTick method.

  • name: [OPTIONAL] - Name of the job. Useful for identifying jobs in logs.

  • threshold: [OPTIONAL] - Threshold in ms to control whether to execute or skip missed execution deadlines caused by slow or busy hardware. Execution delays within threshold will be executed immediately, and otherwise will be skipped. In both cases a warning will be printed to the console with the job name and cron expression. See issue #962 for more information. Default is 250.

Methods

  • from (static): Create a new CronJob object providing arguments as an object. See argument names and descriptions above.

  • start: Initiates the job.

  • stop: Halts the job.

  • setTime: Modifies the time for the CronJob. Parameter must be a CronTime.

  • lastDate: Provides the last execution date.

  • nextDate: Indicates the subsequent date that will activate an onTick.

  • nextDates(count): Supplies an array of upcoming dates that will initiate an onTick.

  • fireOnTick: Allows modification of the onTick calling behavior.

  • addCallback: Permits addition of onTick callbacks.

Properties

  • isActive: [READ-ONLY] Indicates if a job is active (checking to see if the callback needs to be called).

  • isCallbackRunning: [READ-ONLY] Indicates if a callback is currently executing.

    const job = new CronJob('* * * * * *', async () => {
	console.log(job.isCallbackRunning); // true during callback execution
	await someAsyncTask();
	console.log(job.isCallbackRunning); // still true until callback completes
});

console.log(job.isCallbackRunning); // false
job.start();
console.log(job.isActive); // true
console.log(job.isCallbackRunning); // false

CronTime Class

Constructor

constructor(time, zone, utcOffset):

  • time: [REQUIRED] - The time to initiate your job. Accepts cron syntax or a JS Date object.

  • zone: [OPTIONAL] - Equivalent to timeZone from CronJob parameters.

  • utcOffset: [OPTIONAL] - Analogous to utcOffset from CronJob parameters.

💢 Gotchas

  • Both JS Date and Luxon DateTime objects don't guarantee millisecond precision due to computation delays. This module excludes millisecond precision for standard cron syntax but allows execution date specification through JS Date or Luxon DateTime objects. However, specifying a precise future execution time, such as adding a millisecond to the current time, may not always work due to these computation delays. It's observed that delays less than 4-5 ms might lead to inconsistencies. While we could limit all date granularity to seconds, we've chosen to allow greater precision but advise users of potential issues.

  • Using arrow functions for onTick binds them to the parent's this context. As a result, they won't have access to the cronjob's this context. You can read a little more in issue #47 (comment).

🤝 Community

Join the Discord server! Here you can discuss issues and get help in a more casual forum than GitHub.

🌍 Contributing

This project is looking for help! If you're interested in helping with the project, please take a look at our contributing documentation.

🐛 Submitting Bugs/Issues

Please have a look at our contributing documentation, it contains all the information you need to know before submitting an issue.

🙏 Acknowledgements

This is a community effort project. In the truest sense, this project started as an open source project from cron.js and grew into something else. Other people have contributed code, time, and oversight to the project. At this point there are too many to name here so we'll just say thanks.

Special thanks to Hiroki Horiuchi, Lundarl Gholoi and koooge for their work on the DefinitelyTyped typings before they were imported in v2.4.0.

⚖ License

MIT

npm-compare.com is an independent website designed to help developers choose the most suitable npm packages. We are not affiliated with npm, Inc, the official website for the npm registry. Note that npm is a registered trademark of npm, Inc. For more details, please refer to our Terms & Privacy.