croner 4.0.74 → 4.0.79

package/README.md

@@ -1,47 +1,100 @@
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/gh/hexagon/croner@master/croner.png" alt="Croner" width="150" height="108"><br>
-  Trigger functions in javascript using Cron syntax.<br><br>Try it live on <a href="https://jsfiddle.net/hexag0n/hoa8kwsb/">jsfiddle</a>.<br>
+  <img src="/croner.png" alt="Croner" width="150" height="150"><br>
+  Trigger functions in JavaScript using Cron syntax.<br><br>Try it live on <a href="https://jsfiddle.net/hexag0n/hoa8kwsb/">jsfiddle</a>.<br>
 </p>
 
 # Croner
 
 ![Node.js CI](https://github.com/Hexagon/croner/workflows/Node.js%20CI/badge.svg?branch=master) [![npm version](https://badge.fury.io/js/croner.svg)](https://badge.fury.io/js/croner) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/4978bdbf495941c087ecb32b120f28ff)](https://www.codacy.com/gh/Hexagon/croner/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=Hexagon/croner&amp;utm_campaign=Badge_Grade)
-[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Hexagon/croner/blob/master/LICENSE) [![jsdelivr](https://data.jsdelivr.com/v1/package/npm/croner/badge?style=rounded)](https://www.jsdelivr.com/package/npm/croner)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Hexagon/croner/blob/master/LICENSE) [![jsdelivr](https://data.jsdelivr.com/v1/package/gh/hexagon/croner/badge?style=rounded)](https://www.jsdelivr.com/package/gh/hexagon/croner)
+[![Support Server](https://img.shields.io/discord/912830749948915713.svg?color=7289da&label=Croner&logo=discord&style=flat-square)](https://discord.gg/VgpuJ48K8K)
 
-*   Trigger functions in JavaScript using [Cron](https://en.wikipedia.org/wiki/Cron#CRON_expression) syntax
-*   Pause, resume or stop execution efter a task is scheduled
+*   Trigger functions in JavaScript using [Cron](https://en.wikipedia.org/wiki/Cron#CRON_expression) syntax.
+*   Pause, resume or stop execution after a task is scheduled.
 *   Find first date of next month, find date of next tuesday, etc.
-*   Works in Node.js >=4.0 (both require and import)
-*   Works in Deno >=1.16
+*   Works in Node.js >=4.0 (both require and import).
+*   Works in Deno >=1.16.
 *   Works in browsers as standalone, UMD or ES-module.
-*   **Experimental feature:** Schedule in specific target timezones
-*   Includes [TypeScript](https://www.typescriptlang.org/) typings
+*   **Experimental feature:** Schedule in specific target timezones.
+*   Includes [TypeScript](https://www.typescriptlang.org/) typings.
 
 Quick examples:
 
 ```javascript
-// Run a function at the interval set by a cron expression
-let job = Cron('* * * * * *', () => {
+// Run a function at the interval defined by a cron expression
+const job = Cron('* * * * * *', () => {
 	console.log('This will run every second');
 });
 
 // What date is next sunday?
-let nextSunday = Cron('0 0 0 * * 7').next();
+const nextSunday = Cron('0 0 0 * * 7').next();
 console.log(nextSunday.toLocaleDateString());
 
 // How many days left to christmas eve?
-let msLeft = Cron('59 59 23 24 DEC *').next() - new Date();
+const msLeft = Cron('59 59 23 24 DEC *').next() - new Date();
 console.log(Math.floor(msLeft/1000/3600/24) + " days left to next christmas eve");
 ```
 
 More [examples](#examples)...
 
+## Why another javascript cron implementation?
+
+Because the existing ones isn't good enough. They have serious bugs, use bloated dependencies, does not work in all environments and/or just doesn't work as expected.
+
+Benchmark at 2021-11-26:
+
+```
+> node cron-implementation-test.js
+
+Test: When is next saturday 29th of february, pattern '0 0 0 29 2 6'
+
+node-schedule: 2022-02-05 00:00:00 in 37.77ms
+node-cron:     ???                 in 6.746ms
+cron:          2022-03-05 00:00:00 in 8.282ms
+croner:        2048-02-29 00:00:00 in 2.676ms
+
+> node cron-implementation-test.js
+
+Test: When is next 15th of february, pattern '0 0 0 15 2 *'
+
+node-schedule: 2022-02-15 00:00:00 in 91.834ms
+node-cron:     ???                 in 7.69ms
+cron:          2022-03-15 00:00:00 in 12.354ms
+croner:        2022-02-15 00:00:00 in 4.398ms
+
+Test: When is next monday in october, pattern '0 0 0 * 10 1'
+
+node-schedule: 2022-10-03 00:00:00 in 244.057ms
+node-cron:     ???                 in 12.001ms
+cron:          2021-11-29 00:00:00 in 19.322ms
+croner:        2022-10-03 00:00:00 in 5.394ms
+
+Test: When is next monday the 1st of any month, pattern '0 0 0 1 * 1'
+
+node-schedule: 2021-11-29 00:00:00 in 39.591ms
+node-cron:     ???                 in 7.078ms
+cron:          2021-11-29 00:00:00 in 10.107ms
+croner:        2022-08-01 00:00:00 in 9.473ms
+
+Test: When is 23:00 next 31st march, pattern '0 0 23 31 3 *'
+
+node-schedule: 2022-03-31 23:00:00 in 87.661ms
+node-cron:     ???                 in 10.299ms
+Month '3' is limited to '30' days.
+cron:          2022-04-01 23:00:00 in 25.756ms
+croner:        2022-03-31 23:00:00 in 5.569ms
+
+```
+  https://gist.github.com/Hexagon/703f85f2dd86443cc17eef8f5cc6cb70
+
 ## Installation
 
 ### Node.js
 
 ```npm install croner --save```
 
+JavaScript
+
 ```javascript
 // ESM Import ...
 import Cron from "croner";
@@ -50,6 +103,18 @@ import Cron from "croner";
 const Cron = require("croner");
 ```
 
+TypeScript
+
+*Note that only default export is available in Node.js TypeScript, as the commonjs module is used internally.*
+
+```typescript
+import Cron from "croner";
+
+const scheduler : Cron = new Cron("* * * * * *", () => {
+    console.log("This will run every second.");
+});
+```
+
 ### Deno
 
 JavaScript
@@ -67,7 +132,7 @@ TypeScript
 ```typescript
 import { Cron } from "https://cdn.jsdelivr.net/gh/hexagon/croner@4/src/croner.js";
 
-let scheduler : Cron = new Cron("* * * * * *", () => {
+const _scheduler : Cron = new Cron("* * * * * *", () => {
     console.log("This will run every second.");
 });
 ```
@@ -112,16 +177,16 @@ Cron takes three arguments
 *   scheduled function (optional)
 
 ```javascript
-var job = Cron("* * * * * *" , /*optional*/ { maxRuns: 1 } , /*optional*/ () => {} );
+const job = Cron("* * * * * *" , /*optional*/ { maxRuns: 1 } , /*optional*/ () => {} );
 
 // If function is omitted in constructor, it can be scheduled later
-job.schedule(() => {});		
+job.schedule((/* optional */ job, /* optional */ context) => {});		
 
 // States
-let nextRun = job.next( /*optional*/ previousRun );	// Get a Date object representing next run
-let prevRun = job.previous( );	
-let msToNext = job.msToNext( /*optional*/ previosRun ); // Milliseconds left to next execution
-let isRunning = job.running();
+const nextRun = job.next( /*optional*/ previousRun );	// Get a Date object representing next run
+const prevRun = job.previous( );	
+const msToNext = job.msToNext( /*optional*/ previousRun ); // Milliseconds left to next execution
+const isRunning = job.running();
 
 // Control scheduled execution
 job.pause();				
@@ -140,6 +205,7 @@ job.stop();
 | startAt      | undefined      | String         | ISO 8601 formatted datetime (2021-10-17T23:43:00)<br>in local or specified timezone |
 | stopAt       | undefined      | String         | ISO 8601 formatted datetime (2021-10-17T23:43:00)<br>in local or specified timezone |
 | paused       | false          | Boolean        | If the job should be paused from start. |
+| context      | undefined      | Any            | Passed as the second parameter to triggered function |
 
 #### Pattern
 
@@ -171,16 +237,17 @@ job.stop();
 #### Expressions
 ```javascript
 // Run a function according to pattern
-Cron('0-4 */5 1,2,3 * JAN-MAR SAT', function () {
-	console.log('This will run the first five seconds every fifth minute');
-	console.log('of hour 1,2 and 3 every saturday in January to March.');
+Cron('15-45/10 */5 1,2,3 * JAN-MAR SAT', function () {
+	console.log('This will run every tenth second between second 15-45');
+	console.log('every fifth minute of hour 1,2 and 3');
+	console.log('every saturday in January to March.');
 });
 ```
 
 #### Find dates
 ```javascript
 // Find next month
-let nextMonth = Cron('0 0 0 1 * *').next(),
+const nextMonth = Cron('0 0 0 1 * *').next(),
 	nextSunday = Cron('0 0 0 * * 7').next(),
 	nextSat29feb = Cron("0 0 0 29 2 6").next();
 
@@ -192,7 +259,7 @@ console.log("Next saturday at 29th of february: " +  nextSat29feb.toLocaleDateSt
 #### With options
 ```javascript
 
-var job = Cron(
+const job = Cron(
 	'* * * * *', 
 	{ 
 		maxRuns: Infinity, 
@@ -208,7 +275,7 @@ var job = Cron(
 
 #### Job controls
 ```javascript
-let job = Cron('* * * * * *', (self) => {
+const job = Cron('* * * * * *', (self) => {
 	console.log('This will run every second. Pause on second 10. Resume on second 15. And quit on second 20.');
 	console.log('Current second: ', new Date().getSeconds());
 	console.log('Previous run: ' + self.previous());
@@ -220,6 +287,27 @@ Cron('15 * * * * *', {maxRuns: 1}, () => job.resume());
 Cron('20 * * * * *', {maxRuns: 1}, () => job.stop());
 ```
 
+#### Passing a context
+```javascript
+const data = {
+	what: "stuff"
+};
+
+Cron('* * * * * *', { context: data }, (_self, context) => {
+	console.log('This will print stuff: ' + context.what);
+});
+
+Cron('*/5 * * * * *', { context: data }, (self, context) => {
+	console.log('After this, other stuff will be printed instead');
+	context.what = "other stuff";
+	self.stop();
+});
+```
+
+## Contributing
+
+See [Contribution Guide](/CONTRIBUTING.md)
+
 ## License
 
 MIT