cron-build 3.2.0 → 3.2.1
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.
- package/README.md +107 -0
- package/package.json +3 -3
package/README.md
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# ⚡ Cron Builder & Async Guard
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
A lightweight, strictly typed utility library for generating **Cron expressions** programmatically and handling **exclusive asynchronous task execution**.
|
|
8
|
+
|
|
9
|
+
Built to make scheduling tasks in TypeScript readable, maintainable, and safe.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## ✨ Features
|
|
14
|
+
|
|
15
|
+
* **Type-Safe Cron Generation**: Forget about manually typing `*/5 * * * *`. Use readable objects instead.
|
|
16
|
+
* **Flexible Syntax**: Supports exact numbers, steps (`*/5`), ranges (`10-20`), and lists.
|
|
17
|
+
* **Concurrency Control**: Prevent overlapping executions of async tasks (e.g., cron jobs that take longer than their interval).
|
|
18
|
+
* **Zero Dependencies**: Just pure TypeScript logic.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 🚀 Usage
|
|
23
|
+
|
|
24
|
+
### 1. Building Cron Strings
|
|
25
|
+
The `buildCron` function converts a configuration object into a standard 6-field Cron string (`sec min hour day mon week`).
|
|
26
|
+
|
|
27
|
+
```typescript
|
|
28
|
+
import { buildCron } from './cron-utils';
|
|
29
|
+
|
|
30
|
+
// Simple: Run every 5th minute
|
|
31
|
+
const cron1 = buildCron({
|
|
32
|
+
minute: { step: 5 }
|
|
33
|
+
});
|
|
34
|
+
// Output: "* */5 * * * *"
|
|
35
|
+
|
|
36
|
+
// Advanced: Complex Schedule
|
|
37
|
+
const cron2 = buildCron({
|
|
38
|
+
second: 0,
|
|
39
|
+
minute: [0, 30], // At minute 0 and 30
|
|
40
|
+
hour: { start: 9, end: 18 }, // Between 09:00 and 18:00
|
|
41
|
+
dayOfWeek: 'every' // Every day
|
|
42
|
+
});
|
|
43
|
+
// Output: "0 0,30 9-18 * * *"
|
|
44
|
+
|
|
45
|
+
// Hybrid: Start at 10, then every 20
|
|
46
|
+
const cron3 = buildCron({
|
|
47
|
+
second: { start: 10, step: 20 }
|
|
48
|
+
});
|
|
49
|
+
// Output: "10/20 * * * * *"
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### 2. Preventing Overlapping Tasks
|
|
53
|
+
Use `runExclusive` to wrap an asynchronous function. If the function is called while a previous execution is still running, the new call is **ignored**.
|
|
54
|
+
|
|
55
|
+
Perfect for high-frequency cron jobs where you don't want race conditions.
|
|
56
|
+
|
|
57
|
+
```typescript
|
|
58
|
+
import { runExclusive } from './cron-utils';
|
|
59
|
+
|
|
60
|
+
const longRunningTask = async (id: number) => {
|
|
61
|
+
console.log(`Job ${id} started...`);
|
|
62
|
+
await new Promise(r => setTimeout(r, 5000)); // Simulate work
|
|
63
|
+
console.log(`Job ${id} finished!`);
|
|
64
|
+
};
|
|
65
|
+
|
|
66
|
+
// Wrap the function
|
|
67
|
+
const safeTask = runExclusive(longRunningTask);
|
|
68
|
+
|
|
69
|
+
// trigger multiple times rapidly
|
|
70
|
+
safeTask(1); // ✅ Runs immediately
|
|
71
|
+
safeTask(2); // ❌ Ignored (locked)
|
|
72
|
+
safeTask(3); // ❌ Ignored (locked)
|
|
73
|
+
|
|
74
|
+
// After 5 seconds, safeTask(4) will work again.
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## 📚 API Documentation
|
|
80
|
+
|
|
81
|
+
### `CronOptions`
|
|
82
|
+
The configuration object passed to `buildCron`. All fields are optional and default to `*`.
|
|
83
|
+
|
|
84
|
+
| Property | Type | Description |
|
|
85
|
+
| :--- | :--- | :--- |
|
|
86
|
+
| `second` | `CronValue` | Seconds (0-59) |
|
|
87
|
+
| `minute` | `CronValue` | Minutes (0-59) |
|
|
88
|
+
| `hour` | `CronValue` | Hours (0-23) |
|
|
89
|
+
| `dayOfMonth` | `CronValue` | Day of the Month (1-31) |
|
|
90
|
+
| `month` | `CronValue` | Month (1-12) |
|
|
91
|
+
| `dayOfWeek` | `CronValue` | Day of the Week (0-7) |
|
|
92
|
+
|
|
93
|
+
### `CronValue` Types
|
|
94
|
+
| Value Example | Meaning |
|
|
95
|
+
| :--- | :--- |
|
|
96
|
+
| `'*'` or `'every'` | Matches any value (Wildcard) |
|
|
97
|
+
| `5` | Exact match (At value 5) |
|
|
98
|
+
| `[5, 10, 15]` | List of values |
|
|
99
|
+
| `{ step: 5 }` | Every 5th value (`*/5`) |
|
|
100
|
+
| `{ start: 10, end: 20 }` | Range (`10-20`) |
|
|
101
|
+
| `{ start: 5, step: 10 }` | Start at 5, then every 10 (`5/10`) |
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## 📄 License
|
|
106
|
+
|
|
107
|
+
This project is open source and available under the [MIT License](LICENSE).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cron-build",
|
|
3
|
-
"version": "3.2.
|
|
3
|
+
"version": "3.2.1",
|
|
4
4
|
"description": "",
|
|
5
5
|
"main": "./dist/index.cjs",
|
|
6
6
|
"types": "./dist/index.d.ts",
|
|
@@ -11,9 +11,9 @@
|
|
|
11
11
|
}
|
|
12
12
|
},
|
|
13
13
|
"keywords": [],
|
|
14
|
-
"files": ["dist"],
|
|
14
|
+
"files": ["dist", "README.md"],
|
|
15
15
|
"author": "",
|
|
16
|
-
"license": "
|
|
16
|
+
"license": "MIT",
|
|
17
17
|
"type": "module",
|
|
18
18
|
"dependencies": {
|
|
19
19
|
"node-cron": "^4.2.1"
|