You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+40-23Lines changed: 40 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,16 +5,19 @@
5
5
6
6
# JoSk
7
7
8
-
"JoSk" is a Node.js task manager for horizontally scaled apps, apps planning horizontal scaling, and apps that would need to scale horizontally in the future with ease.
8
+
"JoSk" is a Node.js task manager for horizontally scaled apps, apps planning for horizontal scaling, and apps that would need to scale horizontally in the future with ease.
9
9
10
-
"JoSk" follows `setTimeout` and `setInterval` methods native API. Optionally tasks can get scheduled using [CRON expressions](https://github.com/veliovgroup/josk?tab=readme-ov-file#cron). All queued tasks are synced between all running application instances via Redis, MongoDB, or [custom adapter](https://github.com/veliovgroup/josk/blob/master/docs/adapter-api.md).
10
+
"JoSk" mimics the native API of `setTimeout` and `setInterval`. Tasks also can get scheduled using [CRON expressions](https://github.com/veliovgroup/josk?tab=readme-ov-file#cron). All queued tasks are synced between all running application instances via Redis, MongoDB, or [custom adapter](https://github.com/veliovgroup/josk/blob/master/docs/adapter-api.md).
11
11
12
-
"JoSk" package support different horizontally scaled apps as clusters, multi-server, and multi-threaded Node.js instances. That are running either on the same or different machines or different data-centers. "JoSk" ensures that the only single execution of each *task* occurs across all running instances of the application.
12
+
"JoSk" package made for different variety of horizontally scaled apps as clusters, multi-server, and multi-threaded Node.js instances. That are running either on the same or different machines or even different data-centers. "JoSk" ensures that the only single execution of each *task* occurs across all running instances of the application.
13
+
14
+
Although "JoSk" is made with multi-instance apps in mind, — it works on a single-instance applications seamlessly.
- This package is perfect when you have multiple horizontally scaled servers for load-balancing, durability, an array of micro-services or any other solution with multiple running copies of code running repeating tasks that needs to run only once per application/cluster, not per server/instance;
75
-
- Limitation — task must be run not often than once per two seconds (from 2 to ∞ seconds). Example tasks: [Email](https://www.npmjs.com/package/mail-time), SMS queue, Long-polling requests, Periodical application logic operations or Periodical data fetch, sync, and etc;
76
-
- Accuracy — Delay of each task depends on storage and "de-synchronization delay". Trusted time-range of execution period is `task_delay ± (256 + Storage_Request_Delay)`. That means this package won't fit when you need to run a task with very certain delays. For other cases, if `±256 ms` delays are acceptable - this package is the great solution;
77
-
- Use `opts.minRevolvingDelay` and `opts.maxRevolvingDelay` to set the range for *random* delays between executions. Revolving range acts as a safety control to make sure different servers __not__ picking the same task at the same time. Default values (`128` and `768`) are the best for 3-server setup (*the most common topology*). Tune these options to match needs of your project. Higher `opts.minRevolvingDelay` will reduce storage read/writes;
78
-
- This package implements "Read Locking" via "RedLock" for Redis and dedicated `.lock` collection for MongoDB.
-`opts.prefix` {*String*} - [Optional] use to create multiple named instances
89
87
-`opts.debug` {*Boolean*} - [Optional] Enable debugging messages, useful during development
90
88
-`opts.autoClear` {*Boolean*} - [Optional] Remove (*Clear*) obsolete tasks (*any tasks which are not found in the instance memory (runtime), but exists in the database*). Obsolete tasks may appear in cases when it wasn't cleared from the database on process shutdown, and/or was removed/renamed in the app. Obsolete tasks may appear if multiple app instances running different codebase within the same database, and the task may not exist on one of the instances. Default: `false`
91
-
-`opts.resetOnInit` {*Boolean*} - [Optional] (*__use with caution__*) make sure all old tasks is completed before setting a new one. Useful when you run a singleinstance of an app, or multiple app instances on __one__ machine, in case machine was reloaded during running task and task is unfinished
92
-
-`opts.zombieTime` {*Number*} - [Optional] time in milliseconds, after this time - task will be interpreted as "*zombie*". This parameter allows to rescue task from "*zombie* mode" in case when: `ready()` wasn't called, exception during runtime was thrown, or caused by bad logic. While `resetOnInit` option helps to make sure tasks are `done` on startup, `zombieTime` option helps to solve same issue, but during runtime. Default value is `900000` (*15 minutes*). It's not recommended to set this value to less than a minute (*60000ms*)
89
+
-`opts.resetOnInit` {*Boolean*} - [Optional] (*__use with caution__*) make sure all old tasks are completed during initialization. Useful for single-instance apps to clean up unfinished that occurred due to intermediate shutdown, reboot, or exception. Default: `false`
90
+
-`opts.zombieTime` {*Number*} - [Optional] time in milliseconds, after this time - task will be interpreted as "*zombie*". This parameter allows to rescue task from "*zombie* mode" in case when: `ready()` wasn't called, exception during runtime was thrown, or caused by bad logic. While `resetOnInit` option helps to make sure tasks are `done` on startup, `zombieTime` option helps to solve same issue, but during runtime. Default value is `900000` (*15 minutes*). It's not recommended to set this value to below `60000` (*one minute*)
93
91
-`opts.minRevolvingDelay` {*Number*} - [Optional] Minimum revolving delay — the minimum delay between tasks executions in milliseconds. Default: `128`
94
92
-`opts.maxRevolvingDelay` {*Number*} - [Optional] Maximum revolving delay — the maximum delay between tasks executions in milliseconds. Default: `768`
95
93
-`opts.onError` {*Function*} - [Optional] Informational hook, called instead of throwing exceptions. Default: `false`. Called with two arguments:
JoSk is storage-agnostic (since `v4.0.0`). It's shipped with Redis and MongoDb "adapters" out of the box, with option to extend its capabilities by creating and passing a [custom adapter](https://github.com/veliovgroup/josk/blob/master/docs/adapter-api.md)
109
+
JoSk is storage-agnostic (since `v4.0.0`). It's shipped with Redis and MongoDB "adapters" out of the box, with option to extend its capabilities by creating and passing a [custom adapter](https://github.com/veliovgroup/josk/blob/master/docs/adapter-api.md)
112
110
113
111
#### Redis Adapter
114
112
115
-
JoSk has no dependencies, hence make sure `redis` NPM package is installed in order to support Redis Storage Adapter. `RedisAdapter` utilize basic set of commands `SET`, `GET`, `DEL`, `EXISTS`, `HSET`, `HGETALL`, and `SCAN`. `RedisAdapter` is compatible with all Redis-alike databases, was well-tested with [Redis](https://redis.io/) and [KeyDB](https://docs.keydb.dev/)
113
+
JoSk has no dependencies, hence make sure `redis` NPM package is installed in order to support Redis Storage Adapter. `RedisAdapter` utilize basic set of commands `SET`, `GET`, `DEL`, `EXISTS`, `HSET`, `HGETALL`, and `SCAN`. `RedisAdapter` is compatible with all Redis-alike databases, and was well-tested with [Redis](https://redis.io/) and [KeyDB](https://docs.keydb.dev/)
116
114
117
115
```js
118
116
import { JoSk, RedisAdapter } from'josk';
@@ -130,7 +128,7 @@ const jobs = new JoSk({
130
128
131
129
#### MongoDB Adapter
132
130
133
-
JoSk has no dependencies, hence make sure `mongodb` NPM package is installed in order to support MongoDB Storage Adapter. Note: this package will add two new MongoDB collections per each `new JoSk({ prefix })`. One collection for tasks and another one for "Read Locking" with `.lock` suffix
131
+
JoSk has no dependencies, hence make sure `mongodb` NPM package is installed in order to support MongoDB Storage Adapter. Note: this package will add two new MongoDB collections per each `new JoSk({ prefix })`. One collection for tasks and second for "Read Locking" with `.lock` suffix
ready(); // <-- Always run `ready()`, even if call was unsuccessful
244
+
return;
245
+
}
246
+
243
247
waitForSomethingElse(response, () => {
244
-
ready(); // <-- End of full execution
248
+
ready(); // <-- End of the full execution
245
249
});
246
250
});
247
251
}
@@ -253,11 +257,12 @@ jobs.setInterval(longRunningAsyncTask, 0, 'longRunningAsyncTask'); // run in a l
253
257
254
258
### `setTimeout(func, delay, uid)`
255
259
256
-
-`func` {*Function*} - Function to call on schedule
260
+
-`func` {*Function*} - Function to call after `delay`
257
261
-`delay` {*Number*} - Delay in milliseconds
258
262
-`uid` {*String*} - Unique app-wide task id
263
+
- Returns: {*String*}
259
264
260
-
*Set task into timeout execution.*`setTimeout`*is useful for cluster - when you need to make sure task executed only once.*`ready()`*callback is passed as the first argument into a task function.*
265
+
*Run a task after delay in ms.*`setTimeout`*is useful for cluster - when you need to make sure task executed only once.*`ready()`*callback is passed as the first argument into a task function.*
261
266
262
267
```js
263
268
constsyncTask=function (ready) {
@@ -292,6 +297,7 @@ jobs.setTimeout(asyncAwaitTask, 60 * 1000, 'asyncAwaitTaskIn1m'); // will run on
292
297
293
298
-`func` {*Function*} - Function to execute
294
299
-`uid` {*String*} - Unique app-wide task id
300
+
- Returns: {*String*}
295
301
296
302
*Immediate execute the function, and only once.*`setImmediate`*is useful for cluster - when you need to execute function immediately and only once across all servers.*`ready()`*is passed as the first argument into the task function.*
// To avoid "DB locks" — it's a good idea to use separate DB from "main" application DB
475
481
constdb=client.db('dbName');
476
-
constjobs=newJoSk({ db });
482
+
constjobs=newJoSk({
483
+
adapter: MongoAdapter,
484
+
db: db,
485
+
});
477
486
});
478
487
```
479
488
489
+
## Notes
490
+
491
+
- This package is perfect when you have multiple horizontally scaled servers for load-balancing, durability, an array of micro-services or any other solution with multiple running copies of code running repeating tasks that needs to run only once per application/cluster, not per server/instance;
492
+
- Limitation — task must be run not often than once per two seconds (from 2 to ∞ seconds). Example tasks: [Email](https://www.npmjs.com/package/mail-time), SMS queue, Long-polling requests, Periodical application logic operations or Periodical data fetch, sync, and etc;
493
+
- Accuracy — Delay of each task depends on storage and "de-synchronization delay". Trusted time-range of execution period is `task_delay ± (256 + Storage_Request_Delay)`. That means this package won't fit when you need to run a task with very precise delays. For other cases, if `±256 ms` delays are acceptable - this package is the great solution;
494
+
- Use `opts.minRevolvingDelay` and `opts.maxRevolvingDelay` to set the range for *random* delays between executions. Revolving range acts as a safety control to make sure different servers __not__ picking the same task at the same time. Default values (`128` and `768`) are the best for 3-server setup (*the most common topology*). Tune these options to match needs of your project. Higher `opts.minRevolvingDelay` will reduce storage read/writes;
495
+
- This package implements "Read Locking" via "RedLock" for Redis and dedicated `.lock` collection for MongoDB.
Copy file name to clipboardExpand all lines: docs/meteor.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
NPM `josk` package can be used in Meteor environment just perfectly fine since it's server-only Node.js package.
4
4
5
-
If Meteor.js packages are preferred in you project/environment follow this document to install JoSk as `ostrio:cron-jobs`[Atmosphere](https://atmospherejs.com/ostrio/cron-jobs) or [Packosphere](https://packosphere.com/ostrio/cron-jobs) package
5
+
If Meteor.js packages are preferred in your project/environment follow this document to install JoSk as `ostrio:cron-jobs`[Atmosphere](https://atmospherejs.com/ostrio/cron-jobs) or [Packosphere](https://packosphere.com/ostrio/cron-jobs) package
0 commit comments