npm package: @olemop/scheduler
Description: @olemop/scheduler is a schedule tool for nodejs, it's purpose is to provide a product level schedule module which is high efficient and can support large number job schedule.You can
Latest version: 0.0.54

# @olemop/scheduler

@olemop/scheduler is a schedule tool for nodejs, it's purpose is to provide a product level schedule module which is high efficient and can support large number job schedule.You can

As a schedule tool, it support two kinds of trigger: A simple trigger which use a js object and  a Cron time trigger which use a Cron time string.

## Installation

```bash
npm install @olemop/scheduler
```

## Schedule simple Job

Simple job will receive a object as a trigger, which take three attributes, a JS function as object, and an object as the parameters in the job.

### Simple trigge example

```javascript
// Fire 10000ms after now, and run 10 times with a 1000ms interval.
const trigger1 = {
  // Start time, use the time in date object
  start: Date.now() + 10000, 
  // Fire interval, the precision is millisecond
  period: 1000,      
  // Fire times, in this case the trigger will fire 10 times.
  count: 10          
}

// Fire right now, and run 10 times with 1000ms interval.
const trigger2 = {
  period: 1000,
  count: 10
}

// Fire right now, and run forever with 1000ms interval.
const trigger3 = {
  period: 1000
}

// Fire 3000ms after right now, run only once.
const trigger4 = {
  start: Date.now() + 3000
}

// The job will fire right now, run only once.
const trigger5 = {}

// Illegal! The 'count' attribute cannot used alone without 'period'.
const trigger6 = {
  count: 10
}
```

### Simple job example

```javascript
const schedule = require('../lib/schedule')

const simpleJob = function (data) {
  console.log(`run Job: ${data.name}`)
}

schedule.scheduleJob({ start: Date.now(), period: 3000, count: 10 }, simpleJob, { name: 'simpleJobExample' })
```

## Schedule cron Job

Cron job is the job that use cron trigger, it is just like the simple job, only use the cron trigger instead of simple trigger.

### Cron job example

```javascript
const schedule = require('../lib/schedule')

const cronJob = function (data) {
  console.log(`run Job: ${data.name}`)
}

schedule.scheduleJob('0 0/15 8 * * *', cronJob, { name:'cronJobExample' })
```

### Cron Trigger syntax

Cron trigger has 7 fiels, the format is very like the cronTab in linux, only add a second field in the head. The fields and the boundary is as follow:

<pre style="bgcolor='#dbdbdb'">
*     *     *     *   *    *        command to be executed
-     -     -     -   -    -
|     |     |     |   |    |
|     |     |     |   |    +----- day of week (0 - 6) (Sunday=0)
|     |     |     |   +------- month (1 - 12)
|     |     |     +--------- day of month (1 - 31)
|     |     +----------- hour (0 - 23)
|     +------------- min (0 - 59)
+------------- second (0 - 59)
</pre>

### Exampe of cron tirggers

"0/2 0 8 * * 6"    Fire at every Satuaday at every even seconds of 08:00

"0 30 10 1 4 *"      Fire at 10:30 on 1st of March

"15 15 15 10 10 *"   Fire at Octorber 10th, at 15:15:15.

### Special characters

@olemop/schedule allow three kinds of spechial characters:

- -: '-' means range. For example, 1-3 in the second field means the seconds 1, 2 and 3
- /: means increasement. For exapmle, 1/20 in the second field means 1, 21 and 41 second, and 1/2 means for every odd seconds as 1, 3, 5 ... ...
- ,: means additional values. For example, 1, 10, 15 in the second field means 1, 10 and 15 second. You can use '-', and '/' with ',', for example, 11,20-22,0/2 in the second filed means 11, 21 and all the even seconds.

## Cancel Job

```javascript
const schedule = require('../lib/schedule')

const simpleJob = function () {
  console.log('run simple Job')
}

// Add a simple job and save the id
const id = schedule.scheduleJob({ period: 1000 }, simpleJob, {})

// CancelJob
schedule.cancelJob(id)
```

When you cancel a job, it will stop schedule immidiatelly, and delete the job.