0
# Node Schedule
1
2
Node Schedule is a flexible cron-like and not-cron-like job scheduler for Node.js that enables precise time-based scheduling. It allows you to schedule jobs (arbitrary functions) for execution at specific dates with optional recurrence rules, using a single timer architecture for efficiency.
3
4
## Package Information
5
6
- **Package Name**: node-schedule
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install node-schedule`
10
11
## Core Imports
12
13
```javascript
14
const schedule = require('node-schedule');
15
```
16
17
For ES modules:
18
19
```javascript
20
import * as schedule from 'node-schedule';
21
```
22
23
Individual imports:
24
25
```javascript
26
const { scheduleJob, cancelJob, rescheduleJob, gracefulShutdown, Job, RecurrenceRule, Range, Invocation } = require('node-schedule');
27
```
28
29
## Basic Usage
30
31
```javascript
32
const schedule = require('node-schedule');
33
34
// Schedule with cron syntax
35
const job = schedule.scheduleJob("42 * * * *", function() {
36
console.log('The answer to life, the universe, and everything!');
37
});
38
39
// Schedule for specific date
40
const date = new Date(2024, 11, 21, 5, 30, 0);
41
const job2 = schedule.scheduleJob(date, function() {
42
console.log('This will run on December 21st 2024 at 5:30am');
43
});
44
45
// Cancel a job
46
schedule.cancelJob(job);
47
48
// Access all scheduled jobs
49
console.log('Scheduled jobs:', Object.keys(schedule.scheduledJobs));
50
51
// Graceful shutdown (cancels all jobs and waits for completion)
52
await schedule.gracefulShutdown();
53
```
54
55
## Architecture
56
57
Node Schedule is built around several key components:
58
59
- **Job Scheduling**: Core `scheduleJob()` function and `Job` class for creating and managing scheduled tasks
60
- **Timing Specifications**: Multiple formats including cron strings, Date objects, and RecurrenceRule objects
61
- **Single Timer System**: Efficient architecture that uses only one timer at any given time
62
- **Event-Driven Model**: Jobs extend EventEmitter and emit lifecycle events (run, scheduled, canceled, error, success)
63
- **Promise Support**: Automatic handling of job functions that return Promises with proper success/error events
64
- **Generator Function Support**: Automatic detection and handling of JavaScript generator functions
65
- **Timezone Support**: Full timezone support for scheduling across different time zones
66
- **Graceful Shutdown**: Built-in support for cleanly stopping all jobs and waiting for running tasks to complete
67
68
## Capabilities
69
70
### Job Scheduling
71
72
Core job scheduling functionality for creating, managing, and executing time-based tasks with multiple scheduling formats.
73
74
```javascript { .api }
75
/**
76
* Schedule a job to run at specified times
77
* @param {string|Date|object} spec - Schedule specification (cron, date, or recurrence rule)
78
* @param {function} method - Function to execute
79
* @returns {Job|null} Job instance or null if scheduling failed
80
*/
81
function scheduleJob(spec, method);
82
83
/**
84
* Schedule a named job to run at specified times
85
* @param {string} name - Job name for later reference
86
* @param {string|Date|object} spec - Schedule specification
87
* @param {function} method - Function to execute
88
* @param {function} [callback] - Optional callback function
89
* @returns {Job|null} Job instance or null if scheduling failed
90
*/
91
function scheduleJob(name, spec, method, callback);
92
93
/**
94
* Reschedule an existing job with new timing
95
* @param {Job|string} job - Job instance or job name
96
* @param {string|Date|object} spec - New schedule specification
97
* @returns {Job|null} Job instance or null if rescheduling failed
98
*/
99
function rescheduleJob(job, spec);
100
101
/**
102
* Cancel a scheduled job
103
* @param {Job|string} job - Job instance or job name
104
* @returns {boolean} True if job was successfully canceled
105
*/
106
function cancelJob(job);
107
108
/**
109
* Gracefully shutdown all jobs and wait for completion
110
* @returns {Promise<void>} Promise that resolves when all jobs are stopped
111
*/
112
function gracefulShutdown();
113
```
114
115
### Job Management
116
117
Advanced job management capabilities including manual execution, lifecycle control, and state inspection.
118
119
```javascript { .api }
120
class Job extends EventEmitter {
121
constructor(name, job, callback);
122
123
/** Job name (readonly) */
124
readonly name: string;
125
/** Job function to execute */
126
job: function;
127
/** Optional callback function */
128
callback: function | false;
129
/** Number of currently running invocations */
130
running: number;
131
/** Array of pending invocation objects */
132
pendingInvocations: Invocation[];
133
/** Whether this is a one-time job */
134
isOneTimeJob: boolean;
135
}
136
```
137
138
[Job Management](./job-management.md)
139
140
### Recurrence Rules
141
142
Flexible recurrence rule system for defining complex scheduling patterns with precise control over timing components.
143
144
```javascript { .api }
145
/**
146
* Create a recurrence rule for complex scheduling patterns
147
* @param {number|number[]|Range} [year] - Year specification
148
* @param {number|number[]|Range} [month] - Month specification (0-11)
149
* @param {number|number[]|Range} [date] - Day of month specification (1-31)
150
* @param {number|number[]|Range} [dayOfWeek] - Day of week specification (0-6, Sunday=0)
151
* @param {number|number[]|Range} [hour] - Hour specification (0-23)
152
* @param {number|number[]|Range} [minute] - Minute specification (0-59)
153
* @param {number|number[]|Range} [second] - Second specification (0-59, defaults to 0)
154
*/
155
function RecurrenceRule(year?, month?, date?, dayOfWeek?, hour?, minute?, second?);
156
157
/**
158
* Create a range for use in recurrence rules
159
* @param {number} [start=0] - Range start value
160
* @param {number} [end=60] - Range end value
161
* @param {number} [step=1] - Range step value
162
*/
163
function Range(start?, end?, step?);
164
```
165
166
[Recurrence Rules](./recurrence-rules.md)
167
168
### Scheduled Jobs Registry
169
170
Global registry for accessing and managing named scheduled jobs.
171
172
```javascript { .api }
173
/**
174
* Global object containing all named scheduled jobs
175
* Key is the job name, value is the Job instance
176
*/
177
const scheduledJobs: {[key: string]: Job};
178
```
179
180
## Types
181
182
```javascript { .api }
183
184
/** Schedule specification object with timing constraints */
185
interface ScheduleSpec {
186
/** Recurrence rule or cron string */
187
rule: RecurrenceRule | string;
188
/** Optional start date */
189
start?: Date;
190
/** Optional end date */
191
end?: Date;
192
/** Optional timezone identifier */
193
tz?: string;
194
}
195
196
/** Object-literal recurrence specification */
197
interface RecurrenceSpec {
198
/** Year specification */
199
year?: number | number[] | Range;
200
/** Month specification (0-11) */
201
month?: number | number[] | Range;
202
/** Day of month specification (1-31) */
203
date?: number | number[] | Range;
204
/** Day of week specification (0-6, Sunday=0) */
205
dayOfWeek?: number | number[] | Range;
206
/** Hour specification (0-23) */
207
hour?: number | number[] | Range;
208
/** Minute specification (0-59) */
209
minute?: number | number[] | Range;
210
/** Second specification (0-59) */
211
second?: number | number[] | Range;
212
}
213
214
/** Internal invocation object (primarily for internal use) */
215
class Invocation {
216
constructor(job, fireDate, recurrenceRule, endDate);
217
218
/** Associated job instance */
219
job: Job;
220
/** When invocation should fire */
221
fireDate: Date;
222
/** Associated recurrence rule */
223
recurrenceRule: RecurrenceRule;
224
/** Optional end date for recurring jobs */
225
endDate?: Date;
226
/** Internal timer identifier */
227
timerID: number | null;
228
}
229
```