Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/node-cron/node-cron
A simple cron-like job scheduler for Node.js
https://github.com/node-cron/node-cron
cron cron-syntax node-cron scheduled-jobs scheduled-tasks
Last synced: 3 days ago
JSON representation
A simple cron-like job scheduler for Node.js
- Host: GitHub
- URL: https://github.com/node-cron/node-cron
- Owner: node-cron
- License: isc
- Created: 2016-02-03T17:55:47.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2024-06-25T20:41:17.000Z (6 months ago)
- Last Synced: 2024-11-21T09:16:46.221Z (22 days ago)
- Topics: cron, cron-syntax, node-cron, scheduled-jobs, scheduled-tasks
- Language: JavaScript
- Homepage:
- Size: 409 KB
- Stars: 2,984
- Watchers: 23
- Forks: 257
- Open Issues: 166
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome - node-cron/node-cron - A simple cron-like job scheduler for Node.js (JavaScript)
- awesome - node-cron - like job scheduler for Node.js (Node.js)
- awesome-made-by-brazilians - Node Cron
README
# Node Cron
[](https://github.com/merencia/node-cron/blob/master/LICENSE.md)
[](https://img.shields.io/npm/v/node-cron.svg)
[](https://coveralls.io/github/node-cron/node-cron?branch=master)
[](https://codeclimate.com/github/merencia/node-cron)
[](https://travis-ci.org/merencia/node-cron)
[](https://david-dm.org/merencia/node-cron)
[](https://david-dm.org/merencia/node-cron#info=devDependencies)
[](#backers)
[](#sponsors)
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.
**Need a job scheduler with support for worker threads and cron syntax?** Try out the [Bree](https://github.com/breejs/bree) job scheduler!
[](https://nodei.co/npm/node-cron/)
## Getting Started
Install node-cron using npm:
```console
npm install --save node-cron
```
Import node-cron and schedule a task:
- commonjs
```javascript
const cron = require('node-cron');
cron.schedule('* * * * *', () => {
console.log('running a task every minute');
});
```
- es6 (module)
```javascript
import cron from 'node-cron';
cron.schedule('* * * * *', () => {
console.log('running a task every minute');
});
```
## Cron Syntax
This is a quick reference to cron syntax and also shows the options supported by node-cron.
### Allowed fields
```
# ┌────────────── second (optional)
# │ ┌──────────── minute
# │ │ ┌────────── hour
# │ │ │ ┌──────── day of month
# │ │ │ │ ┌────── month
# │ │ │ │ │ ┌──── day of week
# │ │ │ │ │ │
# │ │ │ │ │ │
# * * * * * *
```
### Allowed values
| field | value |
| ------------ | --------------------------------- |
| second | 0-59 |
| minute | 0-59 |
| hour | 0-23 |
| day of month | 1-31 |
| month | 1-12 (or names) |
| day of week | 0-7 (or names, 0 or 7 are sunday) |
#### Using multiples values
You may use multiples values separated by comma:
```javascript
import cron from 'node-cron';
cron.schedule('1,2,4,5 * * * *', () => {
console.log('running every minute 1, 2, 4 and 5');
});
```
#### Using ranges
You may also define a range of values:
```javascript
import cron from 'node-cron';
cron.schedule('1-5 * * * *', () => {
console.log('running every minute to 1 from 5');
});
```
#### Using step values
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`.
```javascript
import cron from 'node-cron';
cron.schedule('*/2 * * * *', () => {
console.log('running a task every two minutes');
});
```
#### Using names
For month and week day you also may use names or short names. e.g:
```javascript
import cron from 'node-cron';
cron.schedule('* * * January,September Sunday', () => {
console.log('running on Sundays of January and September');
});
```
Or with short names:
```javascript
import cron from 'node-cron';
cron.schedule('* * * Jan,Sep Sun', () => {
console.log('running on Sundays of January and September');
});
```
## Cron methods
### Schedule
Schedules given task to be executed whenever the cron expression ticks.
Arguments:
- **expression** `string`: Cron expression
- **function** `Function`: Task to be executed
- **options** `Object`: Optional configuration for job scheduling.
#### Options
- **scheduled**: A `boolean` to set if the created task is scheduled. Default `true`;
- **recoverMissedExecutions**: A `boolean` to set if the created task should be able to recover missed executions. Default `false`;
- **timezone**: The timezone that is used for job scheduling. See [IANA time zone database](https://www.iana.org/time-zones) for valid values, such as `Asia/Shanghai`, `Asia/Kolkata`, `America/Sao_Paulo`.
**Example**:
```js
import cron from 'node-cron';
cron.schedule('0 1 * * *', () => {
console.log('Running a job at 01:00 at America/Sao_Paulo timezone');
}, {
scheduled: true,
timezone: "America/Sao_Paulo"
});
```
## ScheduledTask methods
### Start
Starts the scheduled task.
```javascript
import cron from 'node-cron';
const task = cron.schedule('* * * * *', () => {
console.log('stopped task');
}, {
scheduled: false
});
task.start();
```
### Stop
The task won't be executed unless re-started.
```javascript
import cron from 'node-cron';
const task = cron.schedule('* * * * *', () => {
console.log('will execute every minute until stopped');
});
task.stop();
```
### Validate
Validate that the given string is a valid cron expression.
```javascript
import cron from 'node-cron';
const valid = cron.validate('59 * * * *');
const invalid = cron.validate('60 * * * *');
```
### Naming tasks
You can name your tasks to make it easier to identify them in the logs.
```javascript
import cron from 'node-cron';
const task = cron.schedule('* * * * *', () => {
console.log('will execute every minute until stopped');
}, {
name: 'my-task'
});
```
### List tasks
You can list all the tasks that are currently running.
```javascript
import cron from 'node-cron';
const tasks = cron.getTasks();
for (let [key, value] of tasks.entries()) {
console.log("key", key)
console.log("value", value)
}
```
value is an object with the following properties:
- _events
- _eventsCount
- _maxListeners
- options
- _task
- etc...
## Issues
Feel free to submit issues and enhancement requests [here](https://github.com/merencia/node-cron/issues).
## Contributing
In general, we follow the "fork-and-pull" Git workflow.
- Fork the repo on GitHub;
- Commit changes to a branch in your fork;
- Pull request "upstream" with your changes;
NOTE: Be sure to merge the latest from "upstream" before making a pull request!
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.
## Contributors
This project exists thanks to all the people who contribute.
## Backers
Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/node-cron#backer)]
## Sponsors
Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/node-cron#sponsor)]
## License
node-cron is under [ISC License](https://github.com/merencia/node-cron/blob/master/LICENSE.md).