1 | # Node Cron
|
2 |
|
3 | [![npm](https://img.shields.io/npm/l/node-cron.svg)](https://github.com/merencia/node-cron/blob/master/LICENSE.md)
|
4 | [![npm](https://img.shields.io/npm/v/node-cron.svg)](https://img.shields.io/npm/v/node-cron.svg)
|
5 | [![Coverage Status](https://coveralls.io/repos/github/merencia/node-cron/badge.svg?branch=master)](https://coveralls.io/github/merencia/node-cron?branch=master)
|
6 | [![Code Climate](https://codeclimate.com/github/merencia/node-cron/badges/gpa.svg)](https://codeclimate.com/github/merencia/node-cron)
|
7 | [![Build Status](https://travis-ci.org/merencia/node-cron.svg?branch=master)](https://travis-ci.org/merencia/node-cron)
|
8 | [![Dependency Status](https://david-dm.org/merencia/node-cron.svg)](https://david-dm.org/merencia/node-cron)
|
9 | [![devDependency Status](https://david-dm.org/merencia/node-cron/dev-status.svg)](https://david-dm.org/merencia/node-cron#info=devDependencies)
|
10 |
|
11 | The node-cron module is tiny task scheduler in pure JavaScript for node.js based on [GNU crontab](https://www.gnu.org/software/mcron/manual/html_node/Crontab-file.html). This module allows you to schedule task in node.js using full crontab syntax.
|
12 |
|
13 | [![NPM](https://nodei.co/npm/node-cron.png?downloads=true&downloadRank=true&stars=false)](https://nodei.co/npm/node-cron/)
|
14 |
|
15 |
|
16 | ## Getting Started
|
17 |
|
18 | Install node-cron using npm:
|
19 |
|
20 | ```console
|
21 | $ npm install --save node-cron
|
22 | ```
|
23 |
|
24 | Import node-cron and schedule a task:
|
25 |
|
26 | ```javascript
|
27 | var cron = require('node-cron');
|
28 |
|
29 | cron.schedule('* * * * *', function(){
|
30 | console.log('running a task every minute');
|
31 | });
|
32 | ```
|
33 |
|
34 | ## Cron Syntax
|
35 |
|
36 | This is a quick reference to cron syntax and also shows the options supported by node-cron.
|
37 |
|
38 | ### Allowed fields
|
39 |
|
40 | ```
|
41 | # ┌────────────── second (optional)
|
42 | # │ ┌──────────── minute
|
43 | # │ │ ┌────────── hour
|
44 | # │ │ │ ┌──────── day of month
|
45 | # │ │ │ │ ┌────── month
|
46 | # │ │ │ │ │ ┌──── day of week
|
47 | # │ │ │ │ │ │
|
48 | # │ │ │ │ │ │
|
49 | # * * * * * *
|
50 | ```
|
51 |
|
52 | ### Allowed values
|
53 |
|
54 | | field | value |
|
55 | |--------------|---------------------|
|
56 | | second | 0-59 |
|
57 | | minute | 0-59 |
|
58 | | hour | 0-23 |
|
59 | | day of month | 1-31 |
|
60 | | month | 1-12 (or names) |
|
61 | | day of week | 0-7 (or names, 0 or 7 are sunday) |
|
62 |
|
63 |
|
64 | #### Using multiples values
|
65 |
|
66 | You may use multiples values separated by comma:
|
67 |
|
68 | ```javascript
|
69 | var cron = require('node-cron');
|
70 |
|
71 | cron.schedule('1,2,4,5 * * * *', function(){
|
72 | console.log('running every minute 1, 2, 4 and 5');
|
73 | });
|
74 | ```
|
75 |
|
76 | #### Using ranges
|
77 |
|
78 | You may also define a range of values:
|
79 |
|
80 | ```javascript
|
81 | var cron = require('node-cron');
|
82 |
|
83 | cron.schedule('1-5 * * * *', function(){
|
84 | console.log('running every minute to 1 from 5');
|
85 | });
|
86 | ```
|
87 |
|
88 | #### Using step values
|
89 |
|
90 | Step values can be used in conjunction with ranges, following a range with '/' and a number. e.g: `1-10/2` that is the same as `2,4,6,8,10`. Steps are also permitted after an asterisk, so if you want to say “every two minutes”, just use `*/2`.
|
91 |
|
92 | ```javascript
|
93 | var cron = require('node-cron');
|
94 |
|
95 | cron.schedule('*/2 * * * *', function(){
|
96 | console.log('running a task every two minutes');
|
97 | });
|
98 | ```
|
99 |
|
100 | #### Using names
|
101 |
|
102 | For month and week day you also may use names or short names. e.g:
|
103 |
|
104 | ```javascript
|
105 | var cron = require('node-cron');
|
106 |
|
107 | cron.schedule('* * * January,September Sunday', function(){
|
108 | console.log('running on Sundays of January and September');
|
109 | });
|
110 | ```
|
111 |
|
112 | Or with short names:
|
113 |
|
114 | ```javascript
|
115 | var cron = require('node-cron');
|
116 |
|
117 | cron.schedule('* * * Jan,Sep Sun', function(){
|
118 | console.log('running on Sundays of January and September');
|
119 | });
|
120 | ```
|
121 |
|
122 | ## Cron methods
|
123 |
|
124 | ### Schedule
|
125 |
|
126 | Schedules given task to be executed whenever the cron expression ticks.
|
127 |
|
128 | Arguments:
|
129 |
|
130 | - !string expression - Cron expression
|
131 | - !Function func - Task to be executed
|
132 | - boolean? immediateStart - Whether to start scheduler immediately after create.
|
133 |
|
134 | ## ScheduledTask methods
|
135 |
|
136 | ### Start
|
137 |
|
138 | Starts the scheduled task.
|
139 |
|
140 | ```javascript
|
141 | var cron = require('node-cron');
|
142 |
|
143 | var task = cron.schedule('* * * * *', function() {
|
144 | console.log('immediately started');
|
145 | }, false);
|
146 |
|
147 | task.start();
|
148 | ```
|
149 |
|
150 | ### Stop
|
151 |
|
152 | The task won't be executed unless re-started.
|
153 |
|
154 | ```javascript
|
155 | var cron = require('node-cron');
|
156 |
|
157 | var task = cron.schedule('* * * * *', function() {
|
158 | console.log('will execute every minute until stopped');
|
159 | });
|
160 |
|
161 | task.stop();
|
162 | ```
|
163 |
|
164 | ### Destroy
|
165 |
|
166 | The task will be stopped and completely destroyed.
|
167 |
|
168 | ```javascript
|
169 | var cron = require('node-cron');
|
170 |
|
171 | var task = cron.schedule('* * * * *', function() {
|
172 | console.log('will not execute anymore, nor be able to restart');
|
173 | });
|
174 |
|
175 | task.destroy();
|
176 | ```
|
177 |
|
178 | ### Validate
|
179 |
|
180 | Validate that the given string is a valid cron expression.
|
181 |
|
182 | ```javascript
|
183 | var cron = require('node-cron');
|
184 |
|
185 | var valid = cron.validate('59 * * * *');
|
186 | var invalid = cron.validate('60 * * * *');
|
187 | ```
|
188 |
|
189 | ## Issues
|
190 |
|
191 | Feel free to submit issues and enhancement requests [here](https://github.com/merencia/node-cron/issues).
|
192 |
|
193 | ## Contributors
|
194 |
|
195 | In general, we follow the "fork-and-pull" Git workflow.
|
196 |
|
197 | - Fork the repo on GitHub;
|
198 | - Commit changes to a branch in your fork;
|
199 | - Pull request "upstream" with your changes;
|
200 |
|
201 | NOTE: Be sure to merge the latest from "upstream" before making a pull request!
|
202 |
|
203 | Please do not contribute code you did not write yourself, unless you are certain you have the legal ability to do so. Also ensure all contributed code can be distributed under the ISC License.
|
204 |
|
205 | ## License
|
206 |
|
207 | node-cron is under [ISC License](https://github.com/merencia/node-cron/blob/master/LICENSE.md).
|