node-schedule 1.3.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Master (Unreleased)
+
+# 2.0.0 - 01 February, 2021
+
+### Breaking changes:
+
+- Drop support for Node < 6
+- Remove support for job objects. See `UPGRADING.md` for more details. #557
+
+### New features:
+
+- Introduce compatibility with browsers and Electron #553
+
+### Bug fixes:
+
+- Avoid leaking memory on one-off jobs #581
+- Address anonymous job id collision problem to ensure that node-schedule could run with the unlimited uptime #582
+
+### Internal changes:
+
+- Bump cron-parser from 2.18.0 to 3.1.0 #562
+- Bump sinon from 1.17.7 to 9.2.4 #566  
+- Switch to nyc from istanbul #574
+- Convert tests from nodeunit to Tape #575
+- Replace var with let/const #577
+- Execute airtap tests on a headless Chromium #578
+- Make structure more modular #579

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/)
@@ -12,45 +13,56 @@ It allows you to schedule jobs (arbitrary functions) for execution at
 specific dates, with optional recurrence rules. It only uses a single timer
 at any given time (rather than reevaluating upcoming jobs every second/minute).
 
-## Usage
-
-### Installation
-
-You can install using [npm](https://www.npmjs.com/package/node-schedule).
-
-```
-npm install node-schedule
-```
+Node 6+ is supported.
 
-### Overview
+## Overview
 
 Node Schedule is for time-based scheduling, not interval-based scheduling.
+
 While you can easily bend it to your will, if you only want to do something like
-"run this function every 5 minutes", you'll find `setInterval` much easier to use,
-and far more appropriate. But if you want to, say, "run this function at the :20
+"run this function every 5 minutes", [toad-scheduler](https://github.com/kibertoad/toad-scheduler) would be a better choice. But if you want to, say, "run this function at the :20
 and :50 of every hour on the third Tuesday of every month," you'll find that
 Node Schedule suits your needs better. Additionally, Node Schedule has Windows
-support unlike true cron since the node runtime is now fully supported.
+support, unlike true `cron`, since the node runtime is now fully supported.
 
 Note that Node Schedule is designed for in-process scheduling, i.e. scheduled jobs
 will only fire as long as your script is running, and the schedule will disappear
 when execution completes. If you need to schedule jobs that will persist even when
 your script *isn't* running, consider using actual [cron].
 
+In case you need durable jobs that persist across restarts and lock system compatible with multi-node deployments,
+try [agenda](https://github.com/agenda/agenda) or [bree](https://github.com/breejs/bree).
+
+## Usage
+
+### Installation
+
+You can install using [npm](https://www.npmjs.com/package/node-schedule).
+
+```
+npm install node-schedule
+```
+
+
 ### Jobs and Scheduling
 
 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
 
@@ -70,9 +82,9 @@ The cron format consists of:
 Examples with the cron format:
 
 ```js
-var schedule = require('node-schedule');
+const schedule = require('node-schedule');
 
-var j = schedule.scheduleJob('42 * * * *', function(){
+const job = schedule.scheduleJob('42 * * * *', function(){
   console.log('The answer to life, the universe, and everything!');
 });
 ```
@@ -82,7 +94,7 @@ Execute a cron job when the minute is 42 (e.g. 19:42, 20:42, etc.).
 And:
 
 ```js
-var j = schedule.scheduleJob('0 17 ? * 0,4-6', function(){
+const job = schedule.scheduleJob('0 17 ? * 0,4-6', function(){
   console.log('Today is recognized by Rebecca Black!');
 });
 ```
@@ -91,16 +103,16 @@ 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){
+const job = 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.
 
@@ -110,10 +122,10 @@ Say you very specifically want a function to execute at 5:30am on December 21, 2
 Remember - in JavaScript - 0 - January, 11 - December.
 
 ```js
-var schedule = require('node-schedule');
-var date = new Date(2012, 11, 21, 5, 30, 0);
+const schedule = require('node-schedule');
+const date = new Date(2012, 11, 21, 5, 30, 0);
 
-var j = schedule.scheduleJob(date, function(){
+const job = schedule.scheduleJob(date, function(){
   console.log('The world is going to end today.');
 });
 ```
@@ -121,10 +133,10 @@ var j = schedule.scheduleJob(date, function(){
 To use current data in the future you can use binding:
 
 ```js
-var schedule = require('node-schedule');
-var date = new Date(2012, 11, 21, 5, 30, 0);
-var x = 'Tada!';
-var j = schedule.scheduleJob(date, function(y){
+const schedule = require('node-schedule');
+const date = new Date(2012, 11, 21, 5, 30, 0);
+const x = 'Tada!';
+const job = schedule.scheduleJob(date, function(y){
   console.log(y);
 }.bind(null,x));
 x = 'Changing Data';
@@ -138,12 +150,12 @@ You can build recurrence rules to specify when a job should recur. For instance,
 consider this rule, which executes the function every hour at 42 minutes after the hour:
 
 ```js
-var schedule = require('node-schedule');
+const schedule = require('node-schedule');
 
-var rule = new schedule.RecurrenceRule();
+const rule = new schedule.RecurrenceRule();
 rule.minute = 42;
 
-var j = schedule.scheduleJob(rule, function(){
+const job = schedule.scheduleJob(rule, function(){
   console.log('The answer to life, the universe, and everything!');
 });
 ```
@@ -153,25 +165,41 @@ object to specify a range of start and end values, with an optional step paramet
 For instance, this will print a message on Thursday, Friday, Saturday, and Sunday at 5pm:
 
 ```js
-var rule = new schedule.RecurrenceRule();
+const rule = new schedule.RecurrenceRule();
 rule.dayOfWeek = [0, new schedule.Range(4, 6)];
 rule.hour = 17;
 rule.minute = 0;
 
-var j = schedule.scheduleJob(rule, function(){
+const job = schedule.scheduleJob(rule, function(){
   console.log('Today is recognized by Rebecca Black!');
 });
 ```
 
+Timezones are also supported. Here is an example of executing at the start of every day in the UTC timezone.
+
+```js
+const rule = new schedule.RecurrenceRule();
+rule.hour = 0;
+rule.tz = 'Etc/UTC';
+
+const job = 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
@@ -184,7 +212,7 @@ To make things a little easier, an object literal syntax is also supported, like
 in this example which will log a message every Sunday at 2:30pm:
 
 ```js
-var j = schedule.scheduleJob({hour: 14, minute: 30, dayOfWeek: 0}, function(){
+const job = schedule.scheduleJob({hour: 14, minute: 30, dayOfWeek: 0}, function(){
   console.log('Time for tea!');
 });
 ```
@@ -195,20 +223,20 @@ It will run after 5 seconds and stop after 10 seconds in this example.
 The ruledat supports the above.
 
 ```js
-let startTime = new Date(Date.now() + 5000);
-let endTime = new Date(startTime.getTime() + 5000);
-var j = schedule.scheduleJob({ start: startTime, end: endTime, rule: '*/1 * * * * *' }, function(){
+const startTime = new Date(Date.now() + 5000);
+const endTime = new Date(startTime.getTime() + 5000);
+const job = schedule.scheduleJob({ start: startTime, end: endTime, rule: '*/1 * * * * *' }, function(){
   console.log('Time for tea!');
 });
 ```
 
 ### 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
@@ -217,7 +245,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.
@@ -231,8 +259,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.
@@ -250,7 +279,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/UPGRADING.md

@@ -0,0 +1,20 @@
+## Upgrading to new node-schedule versions
+
+### Upgrading to version 2.0.0+
+
+* Node.js versions older than 6 are no longer supported, please update your environment before upgrading.
+* In order to prevent memory leaks, one-off jobs (targeted to be executed at an exact date) cannot be rescheduled by name, as reference to them is no longer stored indefinitely. If you want to keep rescheduling them, make sure to store reference to the initial job.
+* The `scheduleJob()` method no longer supports passing an object with the job method. If you were using an object, pass the job method directly.  
+
+  E.g. code that previously looked like this:
+  ```javascript
+  const obj = {
+   execute() {}
+  };
+  Scheduler.scheduleJob(obj);
+  ```
+  should be changed to something like this:
+  ```javascript
+  function execute() {}
+  Scheduler.scheduleJob(execute);
+  ```

package/index.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const { cancelJob, rescheduleJob, scheduledJobs, scheduleJob} = require('./lib/schedule')
+const { Invocation, RecurrenceRule, Range} = require('./lib/Invocation')
+const { Job } = require('./lib/Job')
+
+module.exports = {
+  Job,
+  Invocation,
+  Range,
+  RecurrenceRule,
+  cancelJob,
+  rescheduleJob,
+  scheduledJobs,
+  scheduleJob
+}

package/lib/Invocation.js

@@ -0,0 +1,339 @@
+'use strict';
+
+const lt = require('long-timeout')
+const CronDate = require('cron-parser/lib/date')
+const sorted = require('sorted-array-functions')
+
+const invocations = [];
+let currentInvocation = null;
+
+/* DoesntRecur rule */
+const DoesntRecur = new RecurrenceRule();
+DoesntRecur.recurs = false;
+
+/* Invocation object */
+function Invocation(job, fireDate, recurrenceRule, endDate) {
+  this.job = job;
+  this.fireDate = fireDate;
+  this.endDate = endDate;
+  this.recurrenceRule = recurrenceRule || DoesntRecur;
+
+  this.timerID = null;
+}
+
+function sorter(a, b) {
+  return (a.fireDate.getTime() - b.fireDate.getTime());
+}
+
+/* Range object */
+function Range(start, end, step) {
+  this.start = start || 0;
+  this.end = end || 60;
+  this.step = step || 1;
+}
+
+Range.prototype.contains = function(val) {
+  if (this.step === null || this.step === 1) {
+    return (val >= this.start && val <= this.end);
+  } else {
+    for (let i = this.start; i < this.end; i += this.step) {
+      if (i === val) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+};
+
+/* RecurrenceRule object */
+/*
+  Interpreting each property:
+  null - any value is valid
+  number - fixed value
+  Range - value must fall in range
+  array - value must validate against any item in list
+
+  NOTE: Cron months are 1-based, but RecurrenceRule months are 0-based.
+*/
+function RecurrenceRule(year, month, date, dayOfWeek, hour, minute, second) {
+  this.recurs = true;
+
+  this.year = (year == null) ? null : year;
+  this.month = (month == null) ? null : month;
+  this.date = (date == null) ? null : date;
+  this.dayOfWeek = (dayOfWeek == null) ? null : dayOfWeek;
+  this.hour = (hour == null) ? null : hour;
+  this.minute = (minute == null) ? null : minute;
+  this.second = (second == null) ? 0 : second;
+}
+
+RecurrenceRule.prototype.isValid = function() {
+  function isValidType(num) {
+    if (Array.isArray(num) || (num instanceof Array)) {
+      return num.every(function(e) {
+        return isValidType(e);
+      });
+    }
+    return !(Number.isNaN(Number(num)) && !(num instanceof Range));
+  }
+  if (this.month !== null && (this.month < 0 || this.month > 11 || !isValidType(this.month))) {
+    return false;
+  }
+  if (this.dayOfWeek !== null && (this.dayOfWeek < 0 || this.dayOfWeek > 6 || !isValidType(this.dayOfWeek))) {
+    return false;
+  }
+  if (this.hour !== null && (this.hour < 0 || this.hour > 23 || !isValidType(this.hour))) {
+    return false;
+  }
+  if (this.minute !== null && (this.minute < 0 || this.minute > 59 || !isValidType(this.minute))) {
+    return false;
+  }
+  if (this.second !== null && (this.second < 0 || this.second > 59 || !isValidType(this.second))) {
+    return false;
+  }
+  if (this.date !== null) {
+    if(!isValidType(this.date)) {
+      return false;
+    }
+    switch (this.month) {
+      case 3:
+      case 5:
+      case 8:
+      case 10:
+        if (this.date < 1 || this. date > 30) {
+          return false;
+        }
+        break;
+      case 1:
+        if (this.date < 1 || this. date > 29) {
+          return false;
+        }
+        break;
+      default:
+        if (this.date < 1 || this. date > 31) {
+          return false;
+        }
+    }
+  }
+  return true;
+};
+
+RecurrenceRule.prototype.nextInvocationDate = function(base) {
+  const 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;
+  }
+
+  if(!this.isValid()) {
+    return null;
+  }
+
+  const now = new CronDate(Date.now(), this.tz);
+  let fullYear = now.getFullYear();
+  if ((this.year !== null) &&
+    (typeof this.year == 'number') &&
+    (this.year < fullYear)) {
+    return null;
+  }
+
+  let next = new CronDate(base.getTime(), this.tz);
+  next.addSecond();
+
+  while (true) {
+    if (this.year !== null) {
+      fullYear = next.getFullYear();
+      if ((typeof this.year == 'number') && (this.year < fullYear)) {
+        next = null;
+        break;
+      }
+
+      if (!recurMatch(fullYear, this.year)) {
+        next.addYear();
+        next.setMonth(0);
+        next.setDate(1);
+        next.setHours(0);
+        next.setMinutes(0);
+        next.setSeconds(0);
+        continue;
+      }
+    }
+    if (this.month != null && !recurMatch(next.getMonth(), this.month)) {
+      next.addMonth();
+      continue;
+    }
+    if (this.date != null && !recurMatch(next.getDate(), this.date)) {
+      next.addDay();
+      continue;
+    }
+    if (this.dayOfWeek != null && !recurMatch(next.getDay(), this.dayOfWeek)) {
+      next.addDay();
+      continue;
+    }
+    if (this.hour != null && !recurMatch(next.getHours(), this.hour)) {
+      next.addHour();
+      continue;
+    }
+    if (this.minute != null && !recurMatch(next.getMinutes(), this.minute)) {
+      next.addMinute();
+      continue;
+    }
+    if (this.second != null && !recurMatch(next.getSeconds(), this.second)) {
+      next.addSecond();
+      continue;
+    }
+
+    break;
+  }
+
+  return next;
+};
+
+function recurMatch(val, matcher) {
+  if (matcher == null) {
+    return true;
+  }
+
+  if (typeof matcher === 'number') {
+    return (val === matcher);
+  } else if(typeof matcher === 'string') {
+    return (val === Number(matcher));
+  } else if (matcher instanceof Range) {
+    return matcher.contains(val);
+  } else if (Array.isArray(matcher) || (matcher instanceof Array)) {
+    for (let i = 0; i < matcher.length; i++) {
+      if (recurMatch(val, matcher[i])) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/* Date-based scheduler */
+function runOnDate(date, job) {
+  const now = Date.now();
+  const then = date.getTime();
+
+  return lt.setTimeout(function() {
+    if (then > Date.now())
+      runOnDate(date, job);
+    else
+      job();
+  }, (then < now ? 0 : then - now));
+}
+
+function scheduleInvocation(invocation) {
+  sorted.add(invocations, invocation, sorter);
+  prepareNextInvocation();
+  const date = invocation.fireDate instanceof CronDate ? invocation.fireDate.toDate() : invocation.fireDate;
+  invocation.job.emit('scheduled', date);
+}
+
+function prepareNextInvocation() {
+  if (invocations.length > 0 && currentInvocation !== invocations[0]) {
+    if (currentInvocation !== null) {
+      lt.clearTimeout(currentInvocation.timerID);
+      currentInvocation.timerID = null;
+      currentInvocation = null;
+    }
+
+    currentInvocation = invocations[0];
+
+    const job = currentInvocation.job;
+    const cinv = currentInvocation;
+    currentInvocation.timerID = runOnDate(currentInvocation.fireDate, function() {
+      currentInvocationFinished();
+
+      if (job.callback) {
+        job.callback();
+      }
+
+      if (cinv.recurrenceRule.recurs || cinv.recurrenceRule._endDate === null) {
+        const inv = scheduleNextRecurrence(cinv.recurrenceRule, cinv.job, cinv.fireDate, cinv.endDate);
+        if (inv !== null) {
+          inv.job.trackInvocation(inv);
+        }
+      }
+
+      job.stopTrackingInvocation(cinv);
+
+      try {
+        const result = job.invoke(cinv.fireDate instanceof CronDate ? cinv.fireDate.toDate() : cinv.fireDate);
+        job.emit('run');
+
+        if (result instanceof Promise) {
+          result.catch(function (err) {
+            job.emit('error', err);
+          });
+        }
+      } catch (err) {
+        job.emit('error', err);
+      }
+
+      if (job.isOneTimeJob) {
+        job.deleteFromSchedule();
+      }
+    });
+  }
+}
+
+function currentInvocationFinished() {
+  invocations.shift();
+  currentInvocation = null;
+  prepareNextInvocation();
+}
+
+function cancelInvocation(invocation) {
+  const idx = invocations.indexOf(invocation);
+  if (idx > -1) {
+    invocations.splice(idx, 1);
+    if (invocation.timerID !== null) {
+      lt.clearTimeout(invocation.timerID);
+    }
+
+    if (currentInvocation === invocation) {
+      currentInvocation = null;
+    }
+
+    invocation.job.emit('canceled', invocation.fireDate);
+    prepareNextInvocation();
+  }
+}
+
+/* Recurrence scheduler */
+function scheduleNextRecurrence(rule, job, prevDate, endDate) {
+
+  prevDate = (prevDate instanceof CronDate) ? prevDate : new CronDate();
+
+  const date = (rule instanceof RecurrenceRule) ? rule._nextInvocationDate(prevDate) : rule.next();
+  if (date === null) {
+    return null;
+  }
+
+  if ((endDate instanceof CronDate) && date.getTime() > endDate.getTime()) {
+    return null;
+  }
+
+  const inv = new Invocation(job, date, rule, endDate);
+  scheduleInvocation(inv);
+
+  return inv;
+}
+
+module.exports = {
+  Range,
+  RecurrenceRule,
+  Invocation,
+  cancelInvocation,
+  scheduleInvocation,
+  scheduleNextRecurrence,
+  sorter,
+  _invocations: invocations
+}