node-schedule 1.3.1 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Master (Unreleased)
+
+# 2.1.0 - 28 November, 2021
+
+### New features:
+
+- Implement support for graceful shutdown #583
+- Emit a success event after a successful job invocation. #643
+
+# 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,59 @@ 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).
+Node 6+ is supported.
 
-```
-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
 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`.
+* A `success` event when a job invocation triggered by a schedule returns successfully or
+  returns a resolved `Promise`. In any case, the `success` event receives the value returned
+  by the callback or in case of a promise, the resolved value.
+
+(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 +85,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 +97,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 +106,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 +125,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 +136,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 +153,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,16 +168,30 @@ 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 (0-59)`
@@ -172,6 +201,8 @@ var j = schedule.scheduleJob(rule, function(){
 - `month (0-11)`
 - `year`
 - `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 +215,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,13 +226,29 @@ 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!');
 });
 ```
 
+### Graceful Shutdown.
+You can shutdown jobs gracefully.  
+`gracefulShutdown()` will cancel all jobs and return Promise.  
+It will wait until all jobs are terminated.  
+```js
+schedule.gracefulShutdown();
+```
+
+You can also gracefully shutdown jobs when a system interrupt occurs.
+```
+process.on('SIGINT', function () { 
+  schedule.gracefulShutdown()
+  .then(() => process.exit(0))
+}
+```
+
 ### Handle Jobs and Job Invocations
 
 There are some function to get information for a Job and to handle the Job and
@@ -231,8 +278,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,14 +291,13 @@ Before jumping in, check out our [Contributing] page guide!
 
 Copyright 2015 Matt Patenaude.
 
-Licensed under the **[MIT License] [license]**.
+Licensed under the **[MIT License](https://github.com/node-schedule/node-schedule/blob/master/LICENSE)**.
 
 
 [cron]: http://unixhelp.ed.ac.uk/CGI/man-cgi?crontab+5
 [Contributing]: https://github.com/node-schedule/node-schedule/blob/master/CONTRIBUTING.md
 [Matt Patenaude]: https://github.com/mattpat
 [Tejas Manohar]: http://tejas.io
-[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
+[Igor Savin]: https://twitter.com/kibertoad
+[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,17 @@
+'use strict';
+
+const { cancelJob, rescheduleJob, scheduledJobs, scheduleJob, gracefulShutdown} = 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,
+  gracefulShutdown,
+}