diff --git a/gitbook/SUMMARY.md b/gitbook/SUMMARY.md index 4e1373a..eb97f48 100644 --- a/gitbook/SUMMARY.md +++ b/gitbook/SUMMARY.md @@ -39,9 +39,12 @@ * [Save](docs/managing-jobs/manually-working/save.md) * [Unique](docs/managing-jobs/manually-working/unique.md) * [RepeatEvery](docs/managing-jobs/manually-working/repeatevery.md) - * [Schedule](docs/managing-jobs/manually-working/repeatevery-1.md) - * [Remove](docs/managing-jobs/manually-working/repeatevery-2.md) - * [Priority](docs/managing-jobs/manually-working/repeatevery-3.md) - * [Touch](docs/managing-jobs/manually-working/repeatevery-4.md) - * [SetShouldSaveResult](docs/managing-jobs/manually-working/repeatevery-5.md) - * [Fail](docs/managing-jobs/manually-working/repeatevery-6.md) + * [RepeatAt](docs/managing-jobs/manually-working/repeatevery-1.md) + * [Schedule](docs/managing-jobs/manually-working/repeatevery-2.md) + * [Remove](docs/managing-jobs/manually-working/repeatevery-3.md) + * [Priority](docs/managing-jobs/manually-working/repeatevery-4.md) + * [Touch](docs/managing-jobs/manually-working/repeatevery-5.md) + * [SetShouldSaveResult](docs/managing-jobs/manually-working/repeatevery-6.md) + * [Run](docs/managing-jobs/manually-working/repeatevery-7.md) + * [Disable](docs/managing-jobs/manually-working/repeatevery-8.md) + * [Enable](docs/managing-jobs/manually-working/repeatevery-9.md) diff --git a/gitbook/docs/managing-jobs/manually-working/repeatevery-1.md b/gitbook/docs/managing-jobs/manually-working/repeatevery-1.md index d0c1028..6c61b16 100644 --- a/gitbook/docs/managing-jobs/manually-working/repeatevery-1.md +++ b/gitbook/docs/managing-jobs/manually-working/repeatevery-1.md @@ -1,12 +1,11 @@ -# Schedule +# RepeatAt -## `job.schedule(time)` +## `job.repeatAt(time)` {% hint style="info" %} -The `schedule` method sets a job to run at a specific time determined by the input parameter. This method accepts both `Date` objects and date strings, providing flexibility in scheduling jobs.\ -\ +The `repeatAt` method schedules a job to repeat at a specific time that is stated in a [human-readable format](https://github.com/matthewmueller/date#examples) or as a precise time value. This capability is essential for scheduling jobs that must run at regular intervals on specific schedules.\ _This does **NOT** save the job in the database. you must explicitly declare_ [_`save()`_](save.md)_if you want to save it_ @@ -16,7 +15,8 @@ _This does **NOT** save the job in the database. you must explicitly declare_ [ {% code fullWidth="false" %} ```typescript -job.schedule(new Date(2023, 11, 17, 10, 30)); +const job = pulse.create('test', {}); +job.repeatAt("17:00"); await job.save(); // If you want to save it ``` @@ -24,14 +24,16 @@ await job.save(); // If you want to save it ### Parameters -* **`time`** (`string | Date`): The time at which the job is scheduled to run. This can be a `Date` object representing the exact time for the job to run. + + +* **`time`** (`string`): The time at which the job should repeat. This can be specified in a human-readable format (e.g., "03:00 PM", "15:00").[ Format docs](https://github.com/matthewmueller/date#examples) \ ### Returns -* **`Job`**: Returns the job instance with the updated `nextRunAt` attribute, allowing for method chaining. +* **`Job`**: Returns the job instance, allowing for method chaining. This facilitates additional configurations or method calls to be chained after setting the repeat time. \ diff --git a/gitbook/docs/managing-jobs/manually-working/repeatevery-2.md b/gitbook/docs/managing-jobs/manually-working/repeatevery-2.md index a7313c7..56db166 100644 --- a/gitbook/docs/managing-jobs/manually-working/repeatevery-2.md +++ b/gitbook/docs/managing-jobs/manually-working/repeatevery-2.md @@ -1,34 +1,38 @@ -# Remove +# Schedule -## `job.remove()` +## `job.schedule(time)` {% hint style="info" %} -The `remove` method deletes a specific job from the MongoDB database, ensuring that it is no longer available for processing or querying. This method is crucial for managing job lifecycle and maintaining a clean job queue. +The `schedule` method sets a job to run at a specific time determined by the input parameter. This method accepts both `Date` objects and date strings, providing flexibility in scheduling jobs.\ +\ +_This does **NOT** save the job in the database. you must explicitly declare_ [_`save()`_](save.md)_if you want to save it_ {% endhint %} ### Example Usage {% code fullWidth="false" %} ```typescript -job.remove(); +const job = pulse.create('test', {}); +job.schedule(new Date(2023, 11, 17, 10, 30)); +await job.save(); // If you want to save it + ``` {% endcode %} ### Parameters +* **`time`** (`string | Date`): The time at which the job is scheduled to run. This can be a `Date` object representing the exact time for the job to run. + \ ### Returns -* **`Promise`**: A promise that resolves with the number of documents removed from the database. If no document is found with the specified job ID, it may resolve to `undefined`. - -\ - +* **`Job`**: Returns the job instance with the updated `nextRunAt` attribute, allowing for method chaining. \ diff --git a/gitbook/docs/managing-jobs/manually-working/repeatevery-3.md b/gitbook/docs/managing-jobs/manually-working/repeatevery-3.md index 9a4ba65..0ca3f17 100644 --- a/gitbook/docs/managing-jobs/manually-working/repeatevery-3.md +++ b/gitbook/docs/managing-jobs/manually-working/repeatevery-3.md @@ -1,35 +1,32 @@ -# Priority +# Remove -## `job.priority(priority)` +## `job.remove()` {% hint style="info" %} -The `priority` method assigns a priority level to a job, determining its processing order relative to other jobs in the queue. This method is crucial for managing execution precedence, especially in systems where certain tasks need urgent handling. +The `remove` method deletes a specific job from the MongoDB database, ensuring that it is no longer available for processing or querying. This method is crucial for managing job lifecycle and maintaining a clean job queue. + -\ -_This does **NOT** save the job in the database. you must explicitly declare_ [_`save()`_](save.md)_if you want to save it_ {% endhint %} ### Example Usage {% code fullWidth="false" %} ```typescript -job.priority('highest'); -await job.save(); // If you want to save it +const job = pulse.create('test', {}); +job.remove(); ``` {% endcode %} ### Parameters -* **`priority`** (`string` | `number`): A priority label (`'lowest'`, `'low'`, `'normal'`, `'high'`, `'highest'`) or a numeric value that corresponds to a predefined priority level. - \ ### Returns -* **`Job`**: Returns the job instance, enabling method chaining. +* **`Promise`**: A promise that resolves with the number of documents removed from the database. If no document is found with the specified job ID, it may resolve to `undefined`. \ diff --git a/gitbook/docs/managing-jobs/manually-working/repeatevery-4.md b/gitbook/docs/managing-jobs/manually-working/repeatevery-4.md index 0d691a8..b8b8f66 100644 --- a/gitbook/docs/managing-jobs/manually-working/repeatevery-4.md +++ b/gitbook/docs/managing-jobs/manually-working/repeatevery-4.md @@ -1,33 +1,36 @@ -# Touch +# Priority -## `job.touch()` +## `job.priority(priority)` {% hint style="info" %} -The `touch` method updates the `lockedAt` timestamp of a job to the current time. This is particularly useful for ensuring that a job remains locked during long-running processes, preventing it from being considered as timed out or available for reprocessing by other workers or job instances. - +The `priority` method assigns a priority level to a job, determining its processing order relative to other jobs in the queue. This method is crucial for managing execution precedence, especially in systems where certain tasks need urgent handling. +\ +_This does **NOT** save the job in the database. you must explicitly declare_ [_`save()`_](save.md)_if you want to save it_ {% endhint %} ### Example Usage {% code fullWidth="false" %} ```typescript -job.touch(); +const job = pulse.create('test', {}); +job.priority('highest'); +job.save(); // If you want to save it ``` {% endcode %} ### Parameters - +* **`priority`** (`string` | `number`): A priority label (`'lowest'`, `'low'`, `'normal'`, `'high'`, `'highest'`) or a numeric value that corresponds to a predefined priority level. \ ### Returns -* **`Promise`**: A promise that resolves with the updated job instance after the `lockedAt` time has been refreshed and the job has been saved. +* **`Job`**: Returns the job instance, enabling method chaining. \ diff --git a/gitbook/docs/managing-jobs/manually-working/repeatevery-5.md b/gitbook/docs/managing-jobs/manually-working/repeatevery-5.md index 6a084c4..0cfabfe 100644 --- a/gitbook/docs/managing-jobs/manually-working/repeatevery-5.md +++ b/gitbook/docs/managing-jobs/manually-working/repeatevery-5.md @@ -1,38 +1,34 @@ -# SetShouldSaveResult +# Touch -## `job.setShouldSaveResult(shouldSaveResult)` +## `job.touch()` {% hint style="info" %} -The `setShouldSaveResult` method sets a flag indicating whether the outcome of the job's execution should be persisted in the database. This option is useful for managing storage and performance by selectively saving results only when necessary. +The `touch` method updates the `lockedAt` timestamp of a job to the current time. This is particularly useful for ensuring that a job remains locked during long-running processes, preventing it from being considered as timed out or available for reprocessing by other workers or job instances. + -\ -_This does **NOT** save the job in the database. you must explicitly declare_ [_`save()`_](save.md)_if you want to save it_ {% endhint %} ### Example Usage {% code fullWidth="false" %} ```typescript -job.setShouldSaveResult(true); -await job.save(); +const job = pulse.create('test', {}); +job.touch(); ``` {% endcode %} ### Parameters -* **`shouldSaveResult`** (`boolean`): A boolean flag that determines if the job’s result should be saved upon completion. Setting this to `true` enables result persistence, while `false` disables it. + \ ### Returns -* **`Job`**: Returns the job instance, allowing for method chaining. - -\ - +* **`Promise`**: A promise that resolves with the updated job instance after the `lockedAt` time has been refreshed and the job has been saved. \ diff --git a/gitbook/docs/managing-jobs/manually-working/repeatevery-6.md b/gitbook/docs/managing-jobs/manually-working/repeatevery-6.md index 3a91e0d..5143200 100644 --- a/gitbook/docs/managing-jobs/manually-working/repeatevery-6.md +++ b/gitbook/docs/managing-jobs/manually-working/repeatevery-6.md @@ -1,11 +1,11 @@ -# Fail +# SetShouldSaveResult -## `job.fail(reason)` +## `job.setShouldSaveResult(shouldSaveResult)` {% hint style="info" %} -The `fail` method marks a job as failed and updates its attributes accordingly. It records the reason for failure, increments the failure count, and, if the job configuration permits, schedules the job for a retry based on the specified backoff strategy. +The `setShouldSaveResult` method sets a flag indicating whether the outcome of the job's execution should be persisted in the database. This option is useful for managing storage and performance by selectively saving results only when necessary. \ _This does **NOT** save the job in the database. you must explicitly declare_ [_`save()`_](save.md)_if you want to save it_ @@ -15,21 +15,22 @@ _This does **NOT** save the job in the database. you must explicitly declare_ [ {% code fullWidth="false" %} ```typescript -job.fail(new Error('Unable to connect to database')); -await job.save(); +const job = pulse.create('test', {}); +job.setShouldSaveResult(true); +job.save(); // If you want to save it ``` {% endcode %} ### Parameters -* **`reason`** (`string | Error`): The reason for the job's failure, which can be provided as either a string or an Error object. If an Error object is provided, its message is used as the failure reason. +* **`shouldSaveResult`** (`boolean`): A boolean flag that determines if the job’s result should be saved upon completion. Setting this to `true` enables result persistence, while `false` disables it. \ ### Returns -* **`Job`**: Returns the job instance, allowing for method chaining. This enables further actions or logging after the failure is recorded. +* **`Job`**: Returns the job instance, allowing for method chaining. \ diff --git a/gitbook/docs/managing-jobs/manually-working/repeatevery-7.md b/gitbook/docs/managing-jobs/manually-working/repeatevery-7.md new file mode 100644 index 0000000..e1ebc37 --- /dev/null +++ b/gitbook/docs/managing-jobs/manually-working/repeatevery-7.md @@ -0,0 +1,46 @@ +# Run + + + +## `job.run()` + +{% hint style="info" %} +The `run` method executes the processing logic defined for a specific job, handling lifecycle events and managing job state updates based on execution results. It's designed to be an internal method that drives the main execution flow of jobs within the system. + +\ +**Normally you never need to call this manually.** +{% endhint %} + +### Example Usage + +{% code fullWidth="false" %} +```typescript +const job = pulse.create('test', {}); +job.run() + .then(() => console.log('Job execution completed.')) + .catch(error => console.error('Job execution failed:', error)); +``` +{% endcode %} + +### Parameters + + + +\ + + +### Returns + +* **`Promise`**: A promise that resolves with the job instance after execution, whether successful or not. This method handles both successful completion and errors internally, ensuring the job's state is updated accordingly. + +\ + + +\ + + +\ + + + + diff --git a/gitbook/docs/managing-jobs/manually-working/repeatevery-8.md b/gitbook/docs/managing-jobs/manually-working/repeatevery-8.md new file mode 100644 index 0000000..a7ffdaf --- /dev/null +++ b/gitbook/docs/managing-jobs/manually-working/repeatevery-8.md @@ -0,0 +1,45 @@ +# Disable + + + +## `job.disable()` + +{% hint style="info" %} +The `disable` method sets a job's status to disabled, preventing it from being run by the job processing system. This is useful for temporarily halting a job's execution without permanently removing it from the job queue. + +\ +_This does **NOT** save the job in the database. you must explicitly declare_ [_`save()`_](save.md)_if you want to save it_ +{% endhint %} + +### Example Usage + +{% code fullWidth="false" %} +```typescript +const job = pulse.create('test', {}); +job.disable(); +job.save(); // If you want to save it +``` +{% endcode %} + +### Parameters + + + +\ + + +### Returns + +* **`Job`**: Returns the job instance, allowing for method chaining. This facilitates further modifications to the job or chaining additional method calls. + +\ + + +\ + + +\ + + + + diff --git a/gitbook/docs/managing-jobs/manually-working/repeatevery-9.md b/gitbook/docs/managing-jobs/manually-working/repeatevery-9.md new file mode 100644 index 0000000..de1b8dc --- /dev/null +++ b/gitbook/docs/managing-jobs/manually-working/repeatevery-9.md @@ -0,0 +1,45 @@ +# Enable + + + +## `job.enable()` + +{% hint style="info" %} +The `enable` method sets a job's status to active, allowing it to be run by the job processing system. This is useful for resuming the execution of a job that was previously halted without removing it from the job queue. + +\ +_This does **NOT** save the job in the database. you must explicitly declare_ [_`save()`_](save.md)_if you want to save it_ +{% endhint %} + +### Example Usage + +{% code fullWidth="false" %} +```typescript +const job = pulse.create('test', {}); +job.enable(); +job.save(); // If you want to save it +``` +{% endcode %} + +### Parameters + + + +\ + + +### Returns + +* **`Job`**: Returns the job instance, enabling method chaining. This allows for further modifications to the job or chaining additional method calls. + +\ + + +\ + + +\ + + + + diff --git a/gitbook/docs/managing-jobs/manually-working/repeatevery.md b/gitbook/docs/managing-jobs/manually-working/repeatevery.md index d2d6ca0..76fd965 100644 --- a/gitbook/docs/managing-jobs/manually-working/repeatevery.md +++ b/gitbook/docs/managing-jobs/manually-working/repeatevery.md @@ -15,6 +15,7 @@ _This does **NOT** save the job in the database. you must explicitly declare_ [ {% code fullWidth="false" %} ```typescript +const job = pulse.create('test', {}); job.unique({ 'data.type': 'email', 'data.userId': '12345' }); await job.save(); // If you want to save it diff --git a/gitbook/docs/managing-jobs/manually-working/unique.md b/gitbook/docs/managing-jobs/manually-working/unique.md index 3ddcc40..e06421c 100644 --- a/gitbook/docs/managing-jobs/manually-working/unique.md +++ b/gitbook/docs/managing-jobs/manually-working/unique.md @@ -14,6 +14,7 @@ _This does **NOT** save the job in the database. you must explicitly declare_ [ {% code fullWidth="false" %} ```typescript +const job = pulse.create('test', {}); job.unique({ 'data.type': 'email', 'data.userId': '12345' }); await job.save(); // If you want to save it ``` diff --git a/gitbook/docs/setup-and-config/config/defaultconcurrency.md b/gitbook/docs/setup-and-config/config/defaultconcurrency.md index d3b10b4..1adf635 100644 --- a/gitbook/docs/setup-and-config/config/defaultconcurrency.md +++ b/gitbook/docs/setup-and-config/config/defaultconcurrency.md @@ -15,6 +15,9 @@ const pulse = new Pulse(); // Set the default concurrency for job processing to 3 pulse.defaultConcurrency(3); + + +//or new Pulse({ defaultConcurrency: 3 }); ``` diff --git a/gitbook/docs/setup-and-config/config/defaultlocklifetime.md b/gitbook/docs/setup-and-config/config/defaultlocklifetime.md index 228efe8..e45aa95 100644 --- a/gitbook/docs/setup-and-config/config/defaultlocklifetime.md +++ b/gitbook/docs/setup-and-config/config/defaultlocklifetime.md @@ -15,6 +15,8 @@ const pulse = new Pulse(); // Set the default lock lifetime to 5 minutes (300000 ms) pulse.defaultLockLifetime(300000); + +//or new Pulse({ defaultLockLifetime: 300000 }); ``` diff --git a/gitbook/docs/setup-and-config/config/defaultlocklimit.md b/gitbook/docs/setup-and-config/config/defaultlocklimit.md index d7c3421..9cfe15c 100644 --- a/gitbook/docs/setup-and-config/config/defaultlocklimit.md +++ b/gitbook/docs/setup-and-config/config/defaultlocklimit.md @@ -15,6 +15,8 @@ const pulse = new Pulse(); // Set the default concurrency for job processing to 3 pulse.defaultLockLimit(2); + +//or new Pulse({ defaultLockLimit: 2 }); ``` diff --git a/gitbook/docs/setup-and-config/config/locklimit.md b/gitbook/docs/setup-and-config/config/locklimit.md index 2a9ef76..fb52f22 100644 --- a/gitbook/docs/setup-and-config/config/locklimit.md +++ b/gitbook/docs/setup-and-config/config/locklimit.md @@ -15,6 +15,9 @@ const pulse = new Pulse(); // Set a global lock limit to prevent too many jobs from being locked at the same time pulse.lockLimit(5); + + +//or new Pulse({ lockLimit: 5 }); ``` diff --git a/gitbook/docs/setup-and-config/config/maxconcurrency.md b/gitbook/docs/setup-and-config/config/maxconcurrency.md index 90e72f6..20ea584 100644 --- a/gitbook/docs/setup-and-config/config/maxconcurrency.md +++ b/gitbook/docs/setup-and-config/config/maxconcurrency.md @@ -15,6 +15,9 @@ const pulse = new Pulse(); // Set the default concurrency for job processing to 3 pulse.maxConcurrency(10); + + +//or new Pulse({ maxConcurrenc: 10 }); ``` diff --git a/gitbook/docs/setup-and-config/config/name.md b/gitbook/docs/setup-and-config/config/name.md index 116a7d5..b35c4a6 100644 --- a/gitbook/docs/setup-and-config/config/name.md +++ b/gitbook/docs/setup-and-config/config/name.md @@ -13,6 +13,8 @@ The `name` method of the `Pulse` class allows setting or updating the name of th ```typescript const pulse = new Pulse(); pulse.name('emailProcessingQueue'); + +//or new Pulse({ name:'emailProcessingQueue' }); ``` ### Parameters diff --git a/gitbook/docs/setup-and-config/config/processevery.md b/gitbook/docs/setup-and-config/config/processevery.md index 7bbd6eb..6dcc3cf 100644 --- a/gitbook/docs/setup-and-config/config/processevery.md +++ b/gitbook/docs/setup-and-config/config/processevery.md @@ -15,6 +15,8 @@ const pulse = new Pulse(); // Configure the job processing interval to every 10 minutes pulse.processEvery('10 minutes'); + +//or new Pulse({ processEvery:'10 minutes' }); ``` diff --git a/gitbook/docs/setup-and-config/config/sort.md b/gitbook/docs/setup-and-config/config/sort.md index 921a054..1b3a79d 100644 --- a/gitbook/docs/setup-and-config/config/sort.md +++ b/gitbook/docs/setup-and-config/config/sort.md @@ -15,6 +15,8 @@ const pulse = new Pulse(); // Set a custom sort order for job processing pulse.sort({ createdAt: -1 }); + +//or new Pulse({ sort: { createdAt: -1 } }); ``` diff --git a/gitbook/docs/setup-and-config/connection.md b/gitbook/docs/setup-and-config/connection.md index 8a4113e..a1c2b71 100644 --- a/gitbook/docs/setup-and-config/connection.md +++ b/gitbook/docs/setup-and-config/connection.md @@ -42,14 +42,15 @@ const pulse = new Pulse(pulseConfig, (error, collection) => { * **`defaultConcurrency`** (`number` - optional): The default concurrency for jobs that do not specify their own concurrency setting. Defaults to `'5'` if not specified. * **`lockLimit`** (`number` - optional): Maximum number of jobs that can be locked at the same time. This prevents a single worker from locking too many jobs. Defaults to `'0'` if not specified. * **`defaultLockLimit`** (`number` - optional): Default limit for the number of jobs each worker can lock simultaneously. Defaults to `'0'` if not specified. - * **`defaultLockLifetime`** (`number` - optional): Duration in milliseconds for how long a job can be locked before it is automatically unlocked. Useful for handling job crashes or stalls. Defaults to 600000 ms (10 minutes).Defaults to `'10 minutes'` if not specified. + * **`defaultLockLifetime`** (`number` - optional): Duration in milliseconds for how long a job can be locked before it is automatically unlocked. Useful for handling job crashes or stalls. Defaults to 600000 ms (10 minutes). Defaults to `'10 minutes'` if not specified. * **`sort`** (`any` - optional): Determines the order in which jobs are selected and locked from the database. For example, `{ nextRunAt: 1, priority: -1 }` sorts by `nextRunAt` ascending and `priority` descending. * **`mongo`** (`MongoDb` - optional): An existing MongoDB client that can be reused instead of creating a new connection. * **`db`** (`object` - optional): Configuration for the MongoDB connection if not using an existing `MongoDb` client. Includes: * **`address`** (`string`): The MongoDB connection URI. * **`collection`** (`string` - optional): Specifies the MongoDB collection to use. Defaults to `pulseJobs`. * **`options`** (`MongoClientOptions` - optional): MongoDB client options. - * **`disableAutoIndex`** (`boolean` - optional): If set to `true`, automatic indexing of job fields by the `Pulse` system is disabled. Useful for performance tuning in production environments. + * **`disableAutoIndex`** (`boolean` - optional): If set to `true`, automatic indexing of job fields by the `Pulse` system is disabled. Useful for performance tuning in production environments. Defaults to `false` if not specified. + * **`resumeOnRestart`**(`boolean` - optional) - This config is used to ensure that jobs left unfinished due to an unexpected system shutdown or restart are properly resumed once the system is back online. Defaults to `true` if not specified.