node-schedule 1.3.3 → 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

@@ -13,31 +13,37 @@ 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
+Node 6+ is supported.
 
-You can install using [npm](https://www.npmjs.com/package/node-schedule).
-
-```
-npm install node-schedule
-```
-
-### 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
@@ -76,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!');
 });
 ```
@@ -88,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!');
 });
 ```
@@ -97,7 +103,7 @@ 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());
 });
 ```
@@ -116,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.');
 });
 ```
@@ -127,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';
@@ -144,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!');
 });
 ```
@@ -159,12 +165,12 @@ 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!');
 });
 ```
@@ -172,11 +178,11 @@ 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();
+const rule = new schedule.RecurrenceRule();
 rule.hour = 0;
 rule.tz = 'Etc/UTC';
 
-var j = schedule.scheduleJob(rule, function(){
+const job = schedule.scheduleJob(rule, function(){
   console.log('A new day has begun in the UTC timezone!');
 });
 ```
@@ -206,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!');
 });
 ```
@@ -217,9 +223,9 @@ 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!');
 });
 ```

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
+}