croner 6.0.0-dev.2 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +86 -84
  2. package/package.json +2 -5
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  Trigger functions or evaluate cron expressions in JavaScript or TypeScript. No dependencies. All features. Node. Deno. Bun. Browser. <br><br>Try it live on <a href="https://jsfiddle.net/hexag0n/hoa8kwsb/">jsfiddle</a>.<br>
4
4
  </p>
5
5
 
6
- # Croner - Cron for JavaScript and TypeScript
6
+ # Cron for JavaScript and TypeScript
7
7
 
8
8
  [![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) [![NPM Downloads](https://img.shields.io/npm/dw/croner.svg)](https://www.npmjs.org/package/croner)
9
9
  ![No dependencies](https://img.shields.io/badge/dependencies-none-brightgreen) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Hexagon/croner/blob/master/LICENSE)
@@ -11,9 +11,9 @@ Trigger functions or evaluate cron expressions in JavaScript or TypeScript. No d
11
11
  * Trigger functions in JavaScript using [Cron](https://en.wikipedia.org/wiki/Cron#CRON_expression) syntax.
12
12
  * Works in Node.js >=7.6 (both require and import), Deno >=1.16 and Bun >=0.2.2.
13
13
  * Works in browsers as standalone, UMD or ES-module.
14
- * Target different [time zones](docs/EXAMPLES.md#time-zone).
15
- * Built in [overrun protection](docs/EXAMPLES.md#overrun-protection) with callback
16
- * Built in [error handling](docs/EXAMPLES.md#error-handling) with callback
14
+ * Target different [time zones](https://github.com/Hexagon/croner/blob/master/docs/EXAMPLES.md#time-zone).
15
+ * Built in [overrun protection](https://github.com/Hexagon/croner/blob/master/docs/EXAMPLES.md#overrun-protection) with callback
16
+ * Built in [error handling](https://github.com/Hexagon/croner/blob/master/docs/EXAMPLES.md#error-handling) with callback
17
17
  * Includes [TypeScript](https://www.typescriptlang.org/) typings.
18
18
  * Find the first date of the next month, the date of the next Tuesday, etc.
19
19
  * Pause, resume, or stop execution after a task is scheduled.
@@ -28,90 +28,25 @@ const job = Cron('*/5 * * * * *', () => {
28
28
  });
29
29
 
30
30
  // Enumeration: What dates do the next 100 sundays occur on?
31
- const nextSundays = Cron('0 0 0 * * 7').enumerate(100);
31
+ const nextSundays = Cron('0 0 0 * * 7').nextRuns(100);
32
32
  console.log(nextSundays);
33
33
 
34
34
  // Days left to a specific date
35
- const msLeft = Cron('59 59 23 24 DEC *').next() - new Date();
35
+ const msLeft = Cron('59 59 23 24 DEC *').nextRun() - new Date();
36
36
  console.log(Math.floor(msLeft/1000/3600/24) + " days left to next christmas eve");
37
37
 
38
38
  // Run a function at a specific date/time using a non-local timezone (time is ISO 8601 local time)
39
- // This will run 2023-01-23 00:00:00 according to the time in Asia/Kolkata
40
- Cron('2023-01-23T00:00:00', { timezone: 'Asia/Kolkata' }, () => { console.log('Yay!') });
39
+ // This will run 2024-01-23 00:00:00 according to the time in Asia/Kolkata
40
+ Cron('2024-01-23T00:00:00', { timezone: 'Asia/Kolkata' }, () => { console.log('Yay!') });
41
41
 
42
42
  ```
43
43
 
44
44
  More [examples](#examples)...
45
45
 
46
- ## Why another JavaScript cron implementation
47
-
48
- Because the existing ones are not good enough. They have serious bugs, use bloated dependencies, do not work in all environments, and/or simply do not work as expected.
49
-
50
- | | croner | cronosjs | node-cron | cron | node-schedule |
51
- |---------------------------|:-------------------:|:-------------------:|:---------:|:-------------------------:|:-------------------:|
52
- | **Platforms** |
53
- | Node.js (CommonJS) | ✓ | ✓ | ✓ | ✓ | ✓ |
54
- | Browser (ESMCommonJS) | ✓ | ✓ | | | |
55
- | Deno (ESM) | ✓ | | | | |
56
- | **Features** |
57
- | Over-run protection | ✓ | | | | |
58
- | Error handling | ✓ | | | | ✓ |
59
- | Typescript typings | ✓ | ✓ | | | |
60
- | Unref timers (optional) | ✓ | | | ✓ | |
61
- | dom-OR-dow | ✓ | ✓ | ✓ | ✓ | ✓ |
62
- | dom-AND-dow (optional) | ✓ | | | | |
63
- | Next run | ✓ | ✓ | | ✓ | ✓ |
64
- | Next n runs | ✓ | ✓ | | ✓ | |
65
- | Timezone | ✓ | ✓ | ✓ | ✓ | ✓ |
66
- | Minimum interval | ✓ | | | | |
67
- | Controls (stop/resume) | ✓ | ✓ | ✓ | ✓ | ✓ |
68
- | Range (0-13) | ✓ | ✓ | ✓ | ✓ | ✓ |
69
- | Stepping (*/5) | ✓ | ✓ | ✓ | ✓ | ✓ |
70
- | Last day of month (L) | ✓ | ✓ | | | |
71
-
72
- <details>
73
- <summary>In depth comparison of various libraries</summary>
74
-
75
- | | croner | cronosjs | node-cron | cron | node-schedule |
76
- |---------------------------|:-------------------:|:-------------------:|:---------:|:-------------------------:|:-------------------:|
77
- | **Size** |
78
- | Minified size (KB) | 15.5 | 16.3 | 16.5 | - | - |
79
- | Bundlephobia minzip (KB) | 3.6 | 5.1 | 5.7 | 23.9 | 32.4 |
80
- | Dependencies | 0 | 0 | 1 | 1 | 3 |
81
- | **Popularity** |
82
- | Downloads/week [^1] | 576K | 31K | 433K | 2239K | 924K |
83
- | **Quality** |
84
- | Issues [^1] | 0 | 2 | 127 :warning: | 43 :warning: | 139 :warning: |
85
- | Code coverage | 99% | 98% | 100% | 81% | 94% |
86
- | **Performance** |
87
- | Ops/s `1 2 3 4 5 6` | 99 952 | 49 308 | N/A :x: | Test failed :x: | 2 299 :warning: |
88
- | Ops/s `0 0 0 29 2 *` | 65 392 | 17 138 | N/A :x: | Test failed :x: | 1 450 :warning: |
89
- | **Tests** | **8/8** | **7/8** | **0/8** [^4] :question: | **1/8** :warning: | **7/8** |
90
- | Test `0 0 23 * * *` | 2022-10-09 00:40 | 2022-10-09 00:40 | N/A | 2022-10-09 00:40 | 2022-10-09 00:40 |
91
- | Test `0 0 0 L 2 *` [^2] | 2023-02-28 00:00 | 2023-02-28 00:00 | N/A | N/A | 2023-02-28 00:00 |
92
- | Test `0 0 0 29 2 *` | 2024-02-29 00:00 | 2024-02-29 00:00 | N/A | 2023-03-29 00:00 :x: | 2024-02-29 00:00 |
93
- | Test `0 0 0 29 2 6` [^3] | 2048-02-09 00:00| N/A | N/A | N/A | N/A |
94
- | Test `0 0 0 15 2 *` | 2023-02-16 00:00 | 2023-02-16 00:00 | N/A | 2023-03-15 00:00 :x: | 2023-02-16 00:00 |
95
- | Test `0 0 0 * 10 1` | 2022-10-10 00:00 | 2022-10-10 00:00 | N/A | 2022-11-07 00:00 :x: | 2022-10-10 00:00 |
96
- | Test `0 0 23 31 3 *` | 2023-03-31 23:00 | 2023-03-31 23:00 | N/A | 2023-04-01 23:00 :x: | 2023-03-31 23:00 |
97
- | Test `1 2 3 4 5 6` | 2023-05-04 03:02 | 2023-05-04 03:02 | N/A | 2023-06-03 03:02 :x: | 2023-05-04 03:02 |
98
-
99
- > **Note**
100
- > * Table last updated at 2022-10-23, issues and downloads updated 2023-02-19
101
- > * node-cron has no interface to predict when the function will run, so tests cannot be carried out.
102
- > * All tests and benchmarks were carried out using [https://github.com/Hexagon/cron-comparison](https://github.com/Hexagon/cron-comparison)
103
-
104
- [^1]: As of 2023-02-19
105
- [^2]: Requires support for L-modifier
106
- [^3]: In dom-AND-dow mode, only supported by croner at the moment.
107
- [^4]: Node-cron has no way of showing next run time.
108
-
109
- </details>
110
-
111
46
  ## Installation
112
47
 
113
48
  > **Note**
114
- > If you are migrating from a different library such as `cron` or `node-cron`, or upgrading from a older version of croner, see [MIGRATION.md](docs/MIGRATION.md).
49
+ > If you are migrating from a different library such as `cron` or `node-cron`, or upgrading from a older version of croner, see [MIGRATION.md](https://github.com/Hexagon/croner/blob/master/docs/MIGRATION.md).
115
50
 
116
51
  Install croner using your favorite package manager or CDN. then include it in you project:
117
52
 
@@ -128,7 +63,7 @@ const Cron = require("croner");
128
63
  Using Deno
129
64
 
130
65
  ```typescript
131
- import { Cron } from "https://deno.land/x/croner@6.0.0-dev.0/dist/croner.js";
66
+ import { Cron } from "https://deno.land/x/croner@6.0.0/dist/croner.js";
132
67
  ```
133
68
 
134
69
  In a webpage using the UMD-module
@@ -139,8 +74,6 @@ In a webpage using the UMD-module
139
74
 
140
75
  ## Documentation
141
76
 
142
- > **Note**: If you are using version `5.x` or earlier, pay special attention to the changelog in [MIGRATION.md](docs/MIGRATION.md).
143
-
144
77
  ### Signature
145
78
 
146
79
  Cron takes three arguments
@@ -150,10 +83,14 @@ Cron takes three arguments
150
83
  * scheduleds function (optional)
151
84
 
152
85
  ```javascript
153
- const job = Cron("* * * * * *" /* Or a date object, or ISO 8601 local time */ , /*optional*/ { maxRuns: 1 } , /*optional*/ () => {} );
86
+ // Parameters
87
+ // - First: Cron pattern, js date object (fire once), or ISO 8601 time string (fire once)
88
+ // - Second: Options (optional)
89
+ // - Third: Function run trigger (optional)
90
+ const job = Cron("* * * * * *", { maxRuns: 1 }, () => {} );
154
91
 
155
92
  // If function is omitted in constructor, it can be scheduled later
156
- job.schedule((/* optional */ job, /* optional */ context) => {});
93
+ job.schedule(job, /* optional */ context) => {});
157
94
  ```
158
95
 
159
96
  The job will be sceduled to run at next matching time unless you supply option `{ paused: true }`. The `Cron(...)` constructor will return a Cron instance, later called `job`, which have a couple of methods and properties listed below.
@@ -161,11 +98,11 @@ The job will be sceduled to run at next matching time unless you supply option `
161
98
  #### Status
162
99
 
163
100
  ```javascript
164
- job.nextRun( /*optional*/ startFromDate ); // Get a Date object representing next run
165
- job.nextRuns(10, /*optional*/ startFromDate ); // Get a array of Dates, containing next n runs according to pattern
101
+ job.nextRun( /*optional*/ startFromDate ); // Get Date object representing next run
102
+ job.nextRuns(10, /*optional*/ startFromDate ); // Get array of Dates, containing next n runs
166
103
  job.msToNext( /*optional*/ startFromDate ); // Milliseconds left to next execution
167
104
  job.currentRun(); // Date object showing when current (or last) run were started
168
- job.previousRun( ); // Date object showing when previous job were started
105
+ job.previousRun( ); // Date object showing when previous job were started
169
106
 
170
107
  job.isRunning(); // Indicates if there is a scheduled job (true or false)
171
108
  job.isBusy(); // Indicates if a job is currenctly doing work (true or false)
@@ -179,7 +116,7 @@ job.getPattern(); // Returns the original pattern string
179
116
  job.trigger(); // Force a trigger instantly
180
117
  job.pause(); // Pause trigger
181
118
  job.resume(); // Resume trigger
182
- job.stop(); // Stop job completely, it isn't possible to resume after this
119
+ job.stop(); // Stop job completely, it isn't possible to resume after this
183
120
  ```
184
121
 
185
122
  #### Properties
@@ -259,6 +196,71 @@ It is also possible to use the following "nicknames" as pattern.
259
196
  | \@daily | Run once a day, ie. "0 0 * * *". |
260
197
  | \@hourly | Run once an hour, ie. "0 * * * *". |
261
198
 
199
+ ## Why another JavaScript cron implementation
200
+
201
+ Because the existing ones are not good enough. They have serious bugs, use bloated dependencies, do not work in all environments, and/or simply do not work as expected.
202
+
203
+ | | croner | cronosjs | node-cron | cron | node-schedule |
204
+ |---------------------------|:-------------------:|:-------------------:|:---------:|:-------------------------:|:-------------------:|
205
+ | **Platforms** |
206
+ | Node.js (CommonJS) | ✓ | ✓ | ✓ | ✓ | ✓ |
207
+ | Browser (ESMCommonJS) | ✓ | ✓ | | | |
208
+ | Deno (ESM) | ✓ | | | | |
209
+ | **Features** |
210
+ | Over-run protection | ✓ | | | | |
211
+ | Error handling | ✓ | | | | ✓ |
212
+ | Typescript typings | ✓ | ✓ | | | |
213
+ | Unref timers (optional) | ✓ | | | ✓ | |
214
+ | dom-OR-dow | ✓ | ✓ | ✓ | ✓ | ✓ |
215
+ | dom-AND-dow (optional) | ✓ | | | | |
216
+ | Next run | ✓ | ✓ | | ✓ | ✓ |
217
+ | Next n runs | ✓ | ✓ | | ✓ | |
218
+ | Timezone | ✓ | ✓ | ✓ | ✓ | ✓ |
219
+ | Minimum interval | ✓ | | | | |
220
+ | Controls (stop/resume) | ✓ | ✓ | ✓ | ✓ | ✓ |
221
+ | Range (0-13) | ✓ | ✓ | ✓ | ✓ | ✓ |
222
+ | Stepping (*/5) | ✓ | ✓ | ✓ | ✓ | ✓ |
223
+ | Last day of month (L) | ✓ | ✓ | | | |
224
+
225
+ <details>
226
+ <summary>In depth comparison of various libraries</summary>
227
+
228
+ | | croner | cronosjs | node-cron | cron | node-schedule |
229
+ |---------------------------|:-------------------:|:-------------------:|:---------:|:-------------------------:|:-------------------:|
230
+ | **Size** |
231
+ | Minified size (KB) | 15.5 | 16.3 | 16.5 | - | - |
232
+ | Bundlephobia minzip (KB) | 3.6 | 5.1 | 5.7 | 23.9 | 32.4 |
233
+ | Dependencies | 0 | 0 | 1 | 1 | 3 |
234
+ | **Popularity** |
235
+ | Downloads/week [^1] | 576K | 31K | 433K | 2239K | 924K |
236
+ | **Quality** |
237
+ | Issues [^1] | 0 | 2 | 127 :warning: | 43 :warning: | 139 :warning: |
238
+ | Code coverage | 99% | 98% | 100% | 81% | 94% |
239
+ | **Performance** |
240
+ | Ops/s `1 2 3 4 5 6` | 99 952 | 49 308 | N/A :x: | Test failed :x: | 2 299 :warning: |
241
+ | Ops/s `0 0 0 29 2 *` | 65 392 | 17 138 | N/A :x: | Test failed :x: | 1 450 :warning: |
242
+ | **Tests** | **8/8** | **7/8** | **0/8** [^4] :question: | **1/8** :warning: | **7/8** |
243
+ | Test `0 0 23 * * *` | 2022-10-09 00:40 | 2022-10-09 00:40 | N/A | 2022-10-09 00:40 | 2022-10-09 00:40 |
244
+ | Test `0 0 0 L 2 *` [^2] | 2023-02-28 00:00 | 2023-02-28 00:00 | N/A | N/A | 2023-02-28 00:00 |
245
+ | Test `0 0 0 29 2 *` | 2024-02-29 00:00 | 2024-02-29 00:00 | N/A | 2023-03-29 00:00 :x: | 2024-02-29 00:00 |
246
+ | Test `0 0 0 29 2 6` [^3] | 2048-02-09 00:00| N/A | N/A | N/A | N/A |
247
+ | Test `0 0 0 15 2 *` | 2023-02-16 00:00 | 2023-02-16 00:00 | N/A | 2023-03-15 00:00 :x: | 2023-02-16 00:00 |
248
+ | Test `0 0 0 * 10 1` | 2022-10-10 00:00 | 2022-10-10 00:00 | N/A | 2022-11-07 00:00 :x: | 2022-10-10 00:00 |
249
+ | Test `0 0 23 31 3 *` | 2023-03-31 23:00 | 2023-03-31 23:00 | N/A | 2023-04-01 23:00 :x: | 2023-03-31 23:00 |
250
+ | Test `1 2 3 4 5 6` | 2023-05-04 03:02 | 2023-05-04 03:02 | N/A | 2023-06-03 03:02 :x: | 2023-05-04 03:02 |
251
+
252
+ > **Note**
253
+ > * Table last updated at 2022-10-23, issues and downloads updated 2023-02-19
254
+ > * node-cron has no interface to predict when the function will run, so tests cannot be carried out.
255
+ > * All tests and benchmarks were carried out using [https://github.com/Hexagon/cron-comparison](https://github.com/Hexagon/cron-comparison)
256
+
257
+ [^1]: As of 2023-02-19
258
+ [^2]: Requires support for L-modifier
259
+ [^3]: In dom-AND-dow mode, only supported by croner at the moment.
260
+ [^4]: Node-cron has no way of showing next run time.
261
+
262
+ </details>
263
+
262
264
  ## Development
263
265
 
264
266
  ### Master branch
@@ -288,7 +290,7 @@ A list of fixes and features currently released in the `dev` branch is available
288
290
 
289
291
  ### Contributing
290
292
 
291
- See [Contribution Guide](docs/CONTRIBUTING.md)
293
+ See [Contribution Guide](https://github.com/Hexagon/croner/blob/master/docs/CONTRIBUTING.md)
292
294
 
293
295
  ... or ...
294
296
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "croner",
3
- "version": "6.0.0-dev.2",
3
+ "version": "6.0.0",
4
4
  "description": "Trigger functions and/or evaluate cron expressions in JavaScript. No dependencies. Most features. All environments.",
5
5
  "author": "Hexagon <github.com/hexagon>",
6
6
  "homepage": "https://hexagon.github.io/croner",
@@ -82,8 +82,5 @@
82
82
  "uglify-js": "^3.17.1",
83
83
  "uvu": "^0.5.6"
84
84
  },
85
- "license": "MIT",
86
- "dependencies": {
87
- "taffydb": "^2.7.3"
88
- }
85
+ "license": "MIT"
89
86
  }