node-schedule 1.2.5 → 1.3.3

package/README.md

@@ -2,7 +2,8 @@
 
 [![NPM version](http://img.shields.io/npm/v/node-schedule.svg)](https://www.npmjs.com/package/node-schedule)
 [![Downloads](https://img.shields.io/npm/dm/node-schedule.svg)](https://www.npmjs.com/package/node-schedule)
-[![Build Status](https://travis-ci.org/node-schedule/node-schedule.svg?branch=master)](https://travis-ci.org/node-schedule/node-schedule)
+[![Build Status](https://github.com/node-schedule/node-schedule/workflows/ci/badge.svg)](https://github.com/node-schedule/node-schedule/actions)
+[![Coverage Status](https://coveralls.io/repos/node-schedule/node-schedule/badge.svg?branch=master)](https://coveralls.io/r/node-schedule/node-schedule?branch=master)
 [![Join the chat at https://gitter.im/node-schedule/node-schedule](https://img.shields.io/badge/gitter-chat-green.svg)](https://gitter.im/node-schedule/node-schedule?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 [![NPM](https://nodei.co/npm/node-schedule.png?downloads=true)](https://nodei.co/npm/node-schedule/)
@@ -43,14 +44,19 @@ Every scheduled job in Node Schedule is represented by a `Job` object. You can
 create jobs manually, then execute the `schedule()` method to apply a schedule,
 or use the convenience function `scheduleJob()` as demonstrated below.
 
-`Job` objects are `EventEmitter`'s, and emit a `run` event after each execution.
-They also emit a `scheduled` event each time they're scheduled to run, and a
-`canceled` event when an invocation is canceled before it's executed (both events
-receive a JavaScript date object as a parameter). Note that jobs are scheduled the
-first time immediately, so if you create a job using the `scheduleJob()`
-convenience method, you'll miss the first `scheduled` event, but you can query the
-invocation manually (see below). Also note that `canceled` is the single-L American
-spelling.
+`Job` objects are `EventEmitter`s, and emit the following events:
+* A `run` event after each execution.
+* A `scheduled` event each time they're scheduled to run.
+* A `canceled` event when an invocation is canceled before it's executed.  
+  Note that `canceled` is the single-L American spelling.
+* An `error` event when a job invocation triggered by a schedule throws or returns
+  a rejected `Promise`.
+
+(Both the `scheduled` and `canceled` events receive a JavaScript date object as
+a parameter).  
+Note that jobs are scheduled the first time immediately, so if you create a job
+using the `scheduleJob()` convenience method, you'll miss the first `scheduled`
+event, but you can query the invocation manually (see below).
 
 ### Cron-style Scheduling
 
@@ -58,7 +64,7 @@ The cron format consists of:
 ```
 *    *    *    *    *    *
 ┬    ┬    ┬    ┬    ┬    ┬
-│    │    │    │    │    |
+│    │    │    │    │    │
 │    │    │    │    │    └ day of week (0 - 7) (0 or 7 is Sun)
 │    │    │    │    └───── month (1 - 12)
 │    │    │    └────────── day of month (1 - 31)
@@ -89,11 +95,18 @@ var j = schedule.scheduleJob('0 17 ? * 0,4-6', function(){
 
 Execute a cron job every 5 Minutes = */5 * * * *
 
+You can also get when it is scheduled to run for every invocation of the job:
+```js
+var j = schedule.scheduleJob('0 1 * * *', function(fireDate){
+  console.log('This job was supposed to run at ' + fireDate + ', but actually ran at ' + new Date());
+});
+```
+This is useful when you need to check if there is a delay of the job invocation when the system is busy, or save a record of all invocations of a job for audit purpose.
 #### Unsupported Cron Features
 
-Currently, `W` (nearest weekday), `L` (last day of month/week), and `#` (nth weekday
-of the month) are not supported. Most other features supported by popular cron
-implementations should work just fine.
+Currently, `W` (nearest weekday) and `L` (last day of month/week) are not supported. 
+Most other features supported by popular cron implementations should work just fine, 
+including `#` (nth weekday of the month).
 
 [cron-parser] is used to parse crontab instructions.
 
@@ -156,15 +169,31 @@ var j = schedule.scheduleJob(rule, function(){
 });
 ```
 
+Timezones are also supported. Here is an example of executing at the start of every day in the UTC timezone.
+
+```js
+var rule = new schedule.RecurrenceRule();
+rule.hour = 0;
+rule.tz = 'Etc/UTC';
+
+var j = schedule.scheduleJob(rule, function(){
+  console.log('A new day has begun in the UTC timezone!');
+});
+```
+
+A list of acceptable tz (timezone) values can be found at <https://en.wikipedia.org/wiki/List_of_tz_database_time_zones>
+
 #### RecurrenceRule properties
 
-- `second`
-- `minute`
-- `hour`
-- `date`
-- `month`
+- `second (0-59)`
+- `minute (0-59)`
+- `hour  (0-23)`
+- `date  (1-31)`
+- `month (0-11)`
 - `year`
-- `dayOfWeek`
+- `dayOfWeek (0-6) Starting with Sunday`
+- `tz`
+
 
 > **Note**: It's worth noting that the default value of a component of a recurrence rule is
 > `null` (except for second, which is 0 for familiarity with cron). *If we did not
@@ -197,11 +226,11 @@ var j = schedule.scheduleJob({ start: startTime, end: endTime, rule: '*/1 * * *
 
 ### Handle Jobs and Job Invocations
 
-There are some function to get informations for a Job and to handle the Job and
+There are some function to get information for a Job and to handle the Job and
 Invocations.
 
 
-#### job.cancel(reshedule)
+#### job.cancel(reschedule)
 You can invalidate any job with the `cancel()` method:
 
 ```js
@@ -210,7 +239,7 @@ j.cancel();
 All planned invocations will be canceled. When you set the parameter ***reschedule***
 to true then the Job is newly scheduled afterwards.
 
-#### job.cancelNext(reshedule)
+#### job.cancelNext(reschedule)
 This method invalidates the next planned invocation or the job.
 When you set the parameter ***reschedule*** to true then the Job is newly scheduled
 afterwards.
@@ -224,8 +253,9 @@ This method returns a Date object for the planned next Invocation for this Job.
 
 ## Contributing
 
-This module was originally developed by [Matt Patenaude], and is now maintained by
-[Tejas Manohar] and [other wonderful contributors].
+This module was originally developed by [Matt Patenaude] who eventually passed over maintainer's mantle over to [Tejas Manohar].   
+
+Currently it is being maintained by [Igor Savin] and [our amazing community].
 
 We'd love to get your contributions. Individuals making significant and valuable
 contributions are given commit-access to the project to contribute as they see fit.
@@ -243,7 +273,8 @@ Licensed under the **[MIT License] [license]**.
 [Contributing]: https://github.com/node-schedule/node-schedule/blob/master/CONTRIBUTING.md
 [Matt Patenaude]: https://github.com/mattpat
 [Tejas Manohar]: http://tejas.io
+[Igor Savin]: https://twitter.com/kibertoad
 [license]: https://github.com/node-schedule/node-schedule/blob/master/LICENSE
 [Tejas Manohar]: https://github.com/tejasmanohar
-[other wonderful contributors]: https://github.com/node-schedule/node-schedule/graphs/contributors
+[our amazing community]: https://github.com/node-schedule/node-schedule/graphs/contributors
 [cron-parser]: https://github.com/harrisiirak/cron-parser

package/lib/nodeVersionUtils.js

@@ -0,0 +1,30 @@
+'use strict'
+
+var nodeVersionString = process.versions.node
+
+function getNodeVersion(nodeVersionString) {
+  var versionSplit = nodeVersionString.split('.')
+  return {
+    majorVersion: Number(versionSplit[0]),
+    minorVersion: Number(versionSplit[1])
+  }
+}
+
+function arePromisesSupported(nodeVersion) {
+  var majorVersion = nodeVersion.majorVersion
+  var minorVersion = nodeVersion.minorVersion
+
+  if (majorVersion > 0) {
+    return true
+  }
+
+  if (minorVersion < 12) {
+    return false
+  }
+
+  return true
+}
+
+module.exports.nodeVersionString = nodeVersionString;
+module.exports.arePromisesSupported = arePromisesSupported;
+module.exports.getNodeVersion = getNodeVersion;

package/lib/schedule.js

@@ -11,11 +11,13 @@ var events = require('events'),
   cronParser = require('cron-parser'),
   CronDate = require('cron-parser/lib/date'),
   lt = require('long-timeout'),
-  sorted = require('sorted-array-functions');
+  sorted = require('sorted-array-functions'),
+  nodeVersionUtils = require('./nodeVersionUtils')
 
 /* Job object */
 var anonJobCounter = 0;
 var scheduledJobs = {};
+var promisesSupported = nodeVersionUtils.arePromisesSupported(nodeVersionUtils.getNodeVersion(nodeVersionUtils.nodeVersionString))
 
 function isValidDate(date) {
   // Taken from http://stackoverflow.com/a/12372720/1562178
@@ -90,7 +92,7 @@ function Job(name, job, callback) {
 
       cancelInvocation(inv);
 
-      if (reschedule && inv.recurrenceRule.recurs) {
+      if (reschedule && (inv.recurrenceRule.recurs || inv.recurrenceRule.next)) {
         newInv = scheduleNextRecurrence(inv.recurrenceRule, this, inv.fireDate, inv.endDate);
         if (newInv !== null) {
           newInvs.push(newInv);
@@ -125,7 +127,7 @@ function Job(name, job, callback) {
 
     cancelInvocation(nextInv);
 
-    if (reschedule && nextInv.recurrenceRule.recurs) {
+    if (reschedule && (nextInv.recurrenceRule.recurs || nextInv.recurrenceRule.next)) {
       newInv = scheduleNextRecurrence(nextInv.recurrenceRule, this, nextInv.fireDate, nextInv.endDate);
       if (newInv !== null) {
         this.trackInvocation(newInv);
@@ -167,12 +169,12 @@ function Job(name, job, callback) {
 
 util.inherits(Job, events.EventEmitter);
 
-Job.prototype.invoke = function() {
+Job.prototype.invoke = function(fireDate) {
   if (typeof this.job == 'function') {
     this.setTriggeredJobs(this.triggeredJobs() + 1);
-    this.job();
+    return this.job(fireDate);
   } else {
-    this.job.execute();
+    this.job.execute(fireDate);
   }
 };
 
@@ -188,10 +190,14 @@ Job.prototype.schedule = function(spec) {
   var end;
   var tz;
 
+  // save passed-in value before 'spec' is replaced
+  if (typeof spec === 'object' && 'tz' in spec) {
+    tz = spec.tz;
+  }
+
   if (typeof spec === 'object' && spec.rule) {
     start = spec.start || undefined;
     end = spec.end || undefined;
-    tz = spec.tz;
     spec = spec.rule;
 
     if (start) {
@@ -398,6 +404,11 @@ RecurrenceRule.prototype.isValid = function() {
 };
 
 RecurrenceRule.prototype.nextInvocationDate = function(base) {
+  var next = this._nextInvocationDate(base);
+  return next ? next.toDate() : null;
+};
+
+RecurrenceRule.prototype._nextInvocationDate = function(base) {
   base = ((base instanceof CronDate) || (base instanceof Date)) ? base : (new Date());
   if (!this.recurs) {
     return null;
@@ -464,7 +475,7 @@ RecurrenceRule.prototype.nextInvocationDate = function(base) {
     break;
   }
 
-  return next ? next.toDate() : null;
+  return next;
 };
 
 function recurMatch(val, matcher) {
@@ -491,10 +502,15 @@ function recurMatch(val, matcher) {
 
 /* Date-based scheduler */
 function runOnDate(date, job) {
-  var now = (new Date()).getTime();
+  var now = Date.now();
   var then = date.getTime();
-  
-  return lt.setTimeout(job, (then < now ? 0 : then - now));
+
+  return lt.setTimeout(function() {
+    if (then > Date.now())
+      runOnDate(date, job);
+    else
+      job();
+  }, (then < now ? 0 : then - now));
 }
 
 var invocations = [];
@@ -535,8 +551,18 @@ function prepareNextInvocation() {
 
       job.stopTrackingInvocation(cinv);
 
-      job.invoke();
-      job.emit('run');
+      try {
+        var result = job.invoke(cinv.fireDate instanceof CronDate ? cinv.fireDate.toDate() : cinv.fireDate);
+        job.emit('run');
+
+        if (promisesSupported && result instanceof Promise) {
+          result.catch(function (err) {
+            job.emit('error', err);
+          });
+        }
+      } catch (err) {
+        job.emit('error', err);
+      }
     });
   }
 }
@@ -569,7 +595,7 @@ function scheduleNextRecurrence(rule, job, prevDate, endDate) {
 
   prevDate = (prevDate instanceof CronDate) ? prevDate : new CronDate();
 
-  var date = (rule instanceof RecurrenceRule) ? rule.nextInvocationDate(prevDate) : rule.next();
+  var date = (rule instanceof RecurrenceRule) ? rule._nextInvocationDate(prevDate) : rule.next();
   if (date === null) {
     return null;
   }

package/package.json

@@ -1,38 +1,52 @@
 {
   "name": "node-schedule",
-  "version": "1.2.5",
+  "version": "1.3.3",
   "description": "A cron-like and not-cron-like job scheduler for Node.",
   "keywords": [
     "schedule",
     "task",
     "job",
-    "cron"
+    "cron",
+    "in-memory"
   ],
   "license": "MIT",
   "main": "./lib/schedule.js",
   "scripts": {
     "test": "nodeunit",
-    "lint": "eslint lib test"
+    "test:coverage": "istanbul cover ./node_modules/.bin/nodeunit test",
+    "test:coverage-win": "istanbul cover ./node_modules/nodeunit/bin/nodeunit test",
+    "lint": "eslint lib test",
+    "lint:fix": "eslint --fix lib test"
   },
   "author": {
     "name": "Matt Patenaude",
     "email": "matt@mattpatenaude.com",
     "url": "http://mattpatenaude.com"
   },
+  "contributors": [
+    {
+      "name": "Igor Savin",
+      "email": "kibertoad@gmail.com"
+    }
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/node-schedule/node-schedule.git"
   },
   "dependencies": {
-    "cron-parser": "^2.4.0",
+    "cron-parser": "^2.18.0",
     "long-timeout": "0.1.1",
-    "sorted-array-functions": "^1.0.0"
+    "sorted-array-functions": "^1.3.0"
   },
   "devDependencies": {
-    "coveralls": "^2.11.2",
-    "eslint": "^3.19.0",
+    "eslint": "^7.18.0",
     "istanbul": "^0.4.5",
-    "nodeunit": "^0.10.2",
-    "sinon": "^1.14.1"
-  }
+    "nodeunit": "~0.10.2",
+    "sinon": "^2.4.1"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "lib/*"
+  ]
 }

package/.eslintrc

@@ -1,17 +0,0 @@
-{
-  "env": {
-    "node": true,
-    "es6": true
-  },
-  "rules": {
-    "eqeqeq": ["error", "smart"],
-    "indent": ["error", 2, { "SwitchCase": 1 }],
-    "no-constant-condition": "off",
-    "no-redeclare": "warn",
-    "no-underscore-dangle": "off",
-    "no-use-before-define": ["warn","nofunc"],
-    "quotes": ["error", "single"],
-    "space-before-blocks": "error",
-    "strict": "error"
-  }
-}

package/.travis.yml

@@ -1,15 +0,0 @@
-language: node_js
-node_js:
-  - "0.12"
-  - "0.10"
-  - "4"
-  - "6"
-  - "7"
-before_script: >
-  if nvm ls-remote --lts | grep "$(nvm current)"; then
-    echo "running on a LTS node version, linting"
-    npm test
-  else
-    echo "running on a non-LTS node version, skipping linting"
-  fi
-script: ./node_modules/.bin/istanbul cover ./node_modules/.bin/nodeunit test && cat ./coverage/lcov.info | ./node_modules/.bin/coveralls && rm -rf ./coverage

package/CONTRIBUTING.md

@@ -1,31 +0,0 @@
-## Rules
-1. **No `--force` pushes** or modifying the git history in any way
-2. Follow existing code style
-3. Pull requests with tests are much more likely to be accepted
-4. Follow the guidelines below
-
-## Bugfix or Feature?
-
-This project uses the [gitflow workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow). Simply put, you need to decide if your contribution will be a bug fix that could be released as a patch, or a feature that will end up being a minor or major release.
-
-### Found a bug that can be fixed without affecting the API?
-
-1. **Fork** this repo
-2. Create a new branch from `master` to work in
-3. **Add tests** if needed
-4. Make sure your code **lints** by running `npm run lint`
-5. Make sure your code **passes tests** by running `npm test`
-6. Submit a **pull request** against the `master` branch
-
-### New feature or anything that would result in a change to the API?
-
-1. **Fork** this repo
-2. Create a new branch from `develop` to work in
-3. **Add tests** to as needed
-4. Make sure your code **lints** by running `npm run lint`
-5. Make sure your code **passes tests** by running `npm test`
-6. Submit a **pull request** against the `develop` branch
-
-## Releases
-
-Declaring formal releases remains the prerogative of the project maintainer.