node-cron

name	node-cron
description	Node.js cron job scheduling with the `cron` npm package. Use when the user needs to schedule recurring tasks, create cron jobs, validate cron expressions, set up timed callbacks, or work with cron syntax in a Node.js/TypeScript project.

Node Cron

Use the cron npm package (npm install cron) for second-precision scheduled tasks in Node.js.

Triggers

cron job, node-cron, schedule task, cron expression, cron pattern, scheduled job, npm install cron, CronJob, CronTime.

Quick Start

import { CronJob } from 'cron';

const job = new CronJob(
  '0 */5 * * * *',  // every 5 minutes
  () => console.log('Running every 5 minutes'),
  null,             // onComplete
  true,             // start immediately
  'Asia/Shanghai'   // timeZone
);

Or use the object form:

const job = CronJob.from({
  cronTime: '0 0 9 * * 1',    // 9am every Monday
  onTick: () => sendReport(),
  start: true,
  timeZone: 'Asia/Shanghai'
});

job.stop();   // halt
job.start();  // resume

Cron Patterns

The library uses 6 fields (second-precision), unlike standard 5-field Unix cron:

second  minute  hour  day-of-month  month  day-of-week
  0-59   0-59   0-23     1-31       1-12     0-7

Syntax

Token	Meaning
*	Any value (every second/minute/etc.)
1,3,5	List of values
1-5	Range (inclusive)
*/5	Every N steps

Names

Use first 3 letters for month/day-of-week (case-insensitive): "jan,mar,dec", "mon,wed,fri"

Day-of-week: 0 or 7 is Sunday.

Common Examples

Expression	Meaning
*/10 * * * * *	Every 10 seconds
0 * * * * *	Every minute on the second
0 0 * * * *	Every hour
0 0 9 * * *	Daily at 9:00 AM
0 30 9 * * 1-5	9:30 AM Mon-Fri
0 0 0 1 * *	Midnight on the 1st of every month

CronJob Class

Constructor Parameters

Param	Required	Description
cronTime	[OK]	Cron pattern string, Date, or Luxon DateTime
onTick	[OK]	Callback function
onComplete		Called when job stops via job.stop()
start		Auto-start. Default false
timeZone		IANA zone string (e.g. 'Asia/Shanghai')
context		this context for onTick
runOnInit		Fire onTick immediately on init
waitForCompletion		If true, skip ticks while callback is still running
errorHandler		Catch exceptions in onTick
name		Job identifier for debugging
threshold		Missed-deadline tolerance in ms. Default 250

Do NOT pass utcOffset together with timeZone -- they conflict.

Key Methods

• CronJob.from(obj) (static) -- Create with named params
• job.start() / job.stop() -- Start/stop
• job.nextDate() -- Next execution as Luxon DateTime
• job.nextDates(n) -- Array of next N dates
• job.lastDate() -- Last execution date
• job.setTime(cronTime) -- Change schedule
• job.addCallback(fn) -- Add another onTick callback

Read-Only Properties

• job.isActive -- Whether job is running
• job.isCallbackRunning -- Whether onTick is currently executing

Standalone Utilities

import * as cron from 'cron';

// When will this cron expression fire next?
const dt = cron.sendAt('0 0 * * *');
console.log(dt.toISO());

// How many ms until next execution?
const ms = cron.timeout('0 0 * * *');

// Validate an expression
const { valid, error } = cron.validateCronExpression('0 0 * * *');

Gotchas

• Month is 1-12, not 0-11. Upgrade from v2 needs +1 on all month values.
• Day-of-week 0 = Sunday (7 also works).
• 6 fields (with seconds) -- unlike standard 5-field Unix cron.
• Use waitForCompletion: true for async callbacks to prevent overlap.

Async onTick

Wrap async work directly -- waitForCompletion prevents overlapping runs:

const job = CronJob.from({
  cronTime: '*/30 * * * * *',
  onTick: async () => {
    await fetchData();
    await processData();
  },
  waitForCompletion: true,
  start: true
});

Full API Reference

See references/api_reference.md for the complete API documentation including CronTime class, all method signatures, and migration notes.