GITBOOK-2: No subject

gitbook/README.md

@@ -0,0 +1,27 @@
+# What is Pulse?
+
+
+
+<figure><img src=".gitbook/assets/Pulsecron_logo.png" alt=""><figcaption></figcaption></figure>
+
+## **Definition and Context**:
+
+* Pulse is an open-source job scheduling tool in the Node.js ecosystem, serving as a fork of the discontinued Agenda project.
+* Utilizes MongoDB for managing job data, which enhances its ability to perform at scale.
+
+## **Core Features**:
+
+* **High Scalability**: Handles numerous jobs efficiently, suitable for applications that need to manage extensive workloads.
+* **Modern Architecture**: Leverages the latest Node.js features and incorporates best practices for optimal performance.
+* **Flexible Scheduling**: Supports various types of job schedules, including complex cron patterns and one-time executions.
+* **Seamless Integration**: Designed to integrate effortlessly with Node.js applications and existing MongoDB databases.
+
+## **Related Projects**:
+
+* [**pulsecron**](https://www.pulsecron.com): Provides an event-driven task scheduling management infrastructure.
+* [**nestjs-pulse**](https://github.com/pulsecron/nestjs-pulse): An official NestJS module specifically tailored for integrating Pulse into NestJS applications.
+
+## **Usage and Application**:
+
+* Ideal for developers needing a reliable, scalable, and modern job scheduling solution.
+* Applicable in scenarios ranging from simple task automation to complex job orchestration in distributed systems.

gitbook/SUMMARY.md

@@ -0,0 +1,25 @@
+# Table of contents
+
+* [What is Pulse?](README.md)
+* [Why Pulse?](why-pulse.md)
+* [Quick Start](quick-start.md)
+
+## DOCS
+
+* [Setup & Config](docs/setup-and-config/README.md)
+  * [Connection](docs/setup-and-config/connection.md)
+  * [Config](docs/setup-and-config/config/README.md)
+    * [Name](docs/setup-and-config/config/name.md)
+    * [ProcessEvery](docs/setup-and-config/config/processevery.md)
+    * [DefaultConcurrency](docs/setup-and-config/config/defaultconcurrency.md)
+    * [MaxConcurrency](docs/setup-and-config/config/maxconcurrency.md)
+    * [LockLimit](docs/setup-and-config/config/locklimit.md)
+    * [DefaultLockLimit](docs/setup-and-config/config/defaultlocklimit.md)
+    * [DefaultLockLifetime](docs/setup-and-config/config/defaultlocklifetime.md)
+    * [Sort](docs/setup-and-config/config/sort.md)
+* [Defining Job Processors](docs/defining-job-processors.md)
+* [Creating Jobs](docs/creating-jobs/README.md)
+  * [Every](docs/creating-jobs/every.md)
+  * [Schedule](docs/creating-jobs/schedule.md)
+  * [Now](docs/creating-jobs/now.md)
+  * [Create](docs/creating-jobs/create.md)

gitbook/docs/creating-jobs/README.md

@@ -0,0 +1,4 @@
+# Creating Jobs
+
+
+

gitbook/docs/creating-jobs/create.md

@@ -0,0 +1,38 @@
+# Create
+
+
+
+## `pulse.create(name, data?)`
+
+{% hint style="info" %}
+The `create` method generates a new job instance based on a specified job type and data. It is a preliminary step in the job lifecycle, allowing for the customization of job parameters before the job is scheduled and executed.\
+\
+_This does **NOT** save the job in the database._
+{% endhint %}
+
+### Example Usage
+
+```typescript
+cconst pulse = new Pulse();
+
+// Create a new job for data analysis
+const analysisJob = pulse.create('dataAnalysis', { datasetId: 101 });
+analysisJob.save()
+```
+
+
+
+#### Parameters
+
+* **`name`** (`string`): The name of the job to be created. This name should correspond to a job type previously defined with the `define` method, which dictates certain default settings such as priority and result-saving behavior.
+* **`data`** (`T`): Data to pass to the job for its execution. This data is used within the job's processing logic and can be any type of data that the job requires.
+
+#### Returns
+
+* **`Job`**: Returns a new `Job` instance configured with the provided name and data.
+
+\
+
+
+
+

gitbook/docs/creating-jobs/every.md

@@ -0,0 +1,42 @@
+# Every
+
+
+
+## `pulse.every(interval, names, data?, options?)`
+
+{% hint style="info" %}
+The `every` method schedules one or more jobs to run repeatedly at specified intervals. It allows for precise control over job execution timing and can be used to schedule routine tasks such as data synchronization, report generation, or regular maintenance tasks.
+{% endhint %}
+
+### Example Usage
+
+```typescript
+const pulse = new Pulse();
+
+// Set a custom sort order for job processing
+pulse.every('1 day', 'dailyReport', { reportId: 123 });
+
+// Schedule multiple jobs to run every 30 minutes
+pulse.every('30 minutes', ['updateCache', 'refreshData'], null, { skipImmediate: true });
+```
+
+
+
+#### Parameters
+
+* **`interval`** (`string`): The interval at which the job(s) should run. This can be a human-readable format, such as '5 minutes', '1 hour', a [cron format](https://www.npmjs.com/package/cron-parser) `String`, or a `Number`
+* **`names`** (`string | string[]`): The name or array of names of the job(s) to be scheduled. Each name corresponds to a job type previously defined with the `define` method.
+* **`data`** (`T` - optional): Data to pass to the job when it runs. This could be any type of data required by the job for its execution.
+* **`options`** (`JobOptions` - optional): Additional options for the job execution, such as starting the job at a specific time, setting a limit on the number of times the job should repeat, or other job-specific settings.
+  * **`timezone`** (`string` - optional): The timezone to use for scheduling the job, useful for jobs that depend on specific regional settings.
+  * **`startDate`** (`Date | number` - optional): The start date or timestamp from which the job should begin executing. _(_Only available  when _interval format is a cron format)_
+  * **`endDate`** (`Date | number` - optional): The end date or timestamp after which the job should no longer execute. _(_Only available  when _interval format is a cron format)_
+  * **`skipDays`** (`string` - optional): A string defining days to skip; used for creating more complex schedules.
+  * **`skipImmediate`** (`boolean` - optional): If set to true, skips the immediate first execution of the job schedule.
+
+#### Returns
+
+* **`Promise<Job | Job[] | undefined>`**: A promise that resolves with the created job or jobs. The promise will resolve after the jobs have been scheduled, or it will reject if there is an error during scheduling.
+
+
+

gitbook/docs/creating-jobs/now.md

@@ -0,0 +1,35 @@
+# Now
+
+
+
+## `pulse.now(name, data?)`
+
+{% hint style="info" %}
+The `now` method schedules a job to be executed immediately. It creates a job instance and schedules it for the current time, allowing for rapid job processing.
+{% endhint %}
+
+### Example Usage
+
+```typescript
+cconst pulse = new Pulse();
+
+// Schedule a job to run immediately to handle a high priority update
+pulse.now('urgentUpdate', { updateDetails: 'Fix critical security issue' })
+```
+
+
+
+#### Parameters
+
+* **`name`** (`string`): The name of the job to be scheduled. This name should correspond to a job type previously defined with the `define` method.
+* **`data`** (`T` - optional): Data to pass to the job for its execution. This can be any type of data that the job requires to perform its tasks.
+
+#### Returns
+
+* **`Promise<Job>`**: A promise that resolves with the created job instance. This job is scheduled to start immediately unless the job queue is currently full or other jobs are already scheduled for the same time.
+
+\
+
+
+
+

gitbook/docs/creating-jobs/schedule.md

@@ -0,0 +1,43 @@
+# Schedule
+
+
+
+## `pulse.schedule(when, names, data?)`
+
+{% hint style="info" %}
+The `schedule` method allows you to set a specific time for a job or multiple jobs to be executed. This is useful for tasks that must occur at precise times rather than at regular intervals.
+{% endhint %}
+
+### Example Usage
+
+```typescript
+cconst pulse = new Pulse();
+
+// Schedule a single job to run next Monday at 9 AM
+const nextMonday = new Date();
+nextMonday.setDate(nextMonday.getDate() + ((1 + 7 - nextMonday.getDay()) % 7 || 7));
+nextMonday.setHours(9, 0, 0, 0);
+
+pulse.schedule(nextMonday, 'weeklyMeetingReminder', { meetingId: 456 });
+
+pulse.schedule('tomorrow at noon', [
+	'printAnalyticsReport',
+	'sendNotifications',
+	'updateUserRecords'
+]);
+```
+
+
+
+#### Parameters
+
+* **`when`** (`string | Date`): The specific time when the job should be executed. This can be a string representing a date or a `Date` object.
+* **`names`** (`string | string[]`): The name or array of names of the job(s) to be scheduled. Each name corresponds to a job type previously defined with the `define` method.
+* **`data`** (`T` - optional): Data to pass to the job when it runs. This could be any type of data required by the job for its execution.
+
+#### Returns
+
+* **`Promise<Job | Job[]>`**: A promise that resolves with the created job or jobs. The promise will resolve after the job has been scheduled, or it will reject if there is an error during scheduling.
+
+
+

gitbook/docs/defining-job-processors.md

@@ -0,0 +1,58 @@
+# Defining Job Processors
+
+
+
+## `pulse.define(name, processor, options)`
+
+{% hint style="info" %}
+Before you can use a job, you must define its processing behavior.
+
+\
+The `define` method is used to configure how specific types of jobs should be handled by the `Pulse` instance. It allows you to specify a job's processing function and its operational parameters, such as concurrency limits, lock behaviors, and execution priority.
+{% endhint %}
+
+### Example Usage
+
+```typescript
+const pulse = new Pulse();
+
+// Define a job type for sending emails
+pulse.define('sendEmail', async (job, done) => {
+  try {
+    await sendEmail(job.data);
+    done(); // Mark the job as completed
+  } catch (error) {
+    console.error('Failed to send email:', error);
+  }
+}, {
+  concurrency: 5,
+  lockLimit: 2,
+  priority: 'high',
+  lockLifetime: 300000, // 5 minutes
+  shouldSaveResult: true
+});
+
+```
+
+
+
+#### Parameters
+
+* **`name`** (`string`): The unique name for the job type. This name is used to refer to and manage jobs of this type throughout their lifecycle.
+* **`processor`** (`Processor<T>`): The function that contains the logic to be executed when a job of this type is processed. The function receives a `Job` object and an optional `done` callback that should be called when the job processing completes.
+* **`options`** (`DefineOptions` - optional): Configuration options for the job, which include:
+  * **`concurrency`** (`number`): Maximum number of instances of the job that can run simultaneously. Defaults to `Pulse`'s `_defaultConcurrency`.
+  * **`lockLimit`** (`number`): Maximum number of instances of the job that can be locked at once. Defaults to `Pulse`'s `_defaultLockLimit`.
+  * **`lockLifetime`** (`number`): Duration in milliseconds that the job remains locked (i.e., unavailable for re-processing) unless explicitly unlocked sooner. Defaults to `Pulse`'s `_defaultLockLifetime`.
+  * **`priority`** (`lowest|low|normal|high|highest|number`): The priority level of the job. Jobs with higher priority are processed first. Defaults to `normal`.
+  * **`shouldSaveResult`** (`boolean`): Indicates whether the result of the job processing should be saved. Defaults to `false`.
+
+\
+
+
+#### Returns
+
+* **`void`**: This method does not return a value.
+
+
+

gitbook/docs/setup-and-config/README.md

@@ -0,0 +1,3 @@
+# Setup & Config
+
+##

gitbook/docs/setup-and-config/config/README.md

@@ -0,0 +1,3 @@
+# Config
+
+pulse.name(name)

gitbook/docs/setup-and-config/config/defaultconcurrency.md

@@ -0,0 +1,31 @@
+# DefaultConcurrency
+
+
+
+## `pulse.defaultConcurrency(concurrency)`
+
+{% hint style="info" %}
+The `defaultConcurrency` method sets the default number of jobs that can be processed concurrently by a `Pulse` instance. This setting is crucial for controlling how many jobs are run at the same time, affecting resource utilization and job throughput.
+{% endhint %}
+
+### Example Usage
+
+```typescript
+const pulse = new Pulse();
+
+// Set the default concurrency for job processing to 3
+pulse.defaultConcurrency(3);
+```
+
+
+
+#### Parameters
+
+* **`concurrency`** (`number`): The default number of concurrent jobs that the system should process. This value sets a baseline for job processing unless explicitly overridden by specific jobs.
+
+#### Returns
+
+* **`Pulse`**: Returns the `Pulse` instance, allowing for chaining of additional method calls.
+
+
+

gitbook/docs/setup-and-config/config/defaultlocklifetime.md

@@ -0,0 +1,32 @@
+# DefaultLockLifetime
+
+
+
+## `pulse.defaultLockLifetime(ms)`
+
+{% hint style="info" %}
+The `defaultLockLifetime` method sets the default duration (in milliseconds) that a job can remain locked during processing before it is automatically released. This setting helps manage job recovery and ensures that jobs do not remain locked indefinitely if an error occurs or if the job processing is not completed as expected.
+{% endhint %}
+
+### Example Usage
+
+```typescript
+const pulse = new Pulse();
+
+// Set the default lock lifetime to 5 minutes (300000 ms)
+pulse.defaultLockLifetime(300000);
+```
+
+
+
+#### Parameters
+
+* **`ms`** (`number`): The duration in milliseconds for how long jobs should be locked by default.
+  * default: 600,000ms
+
+#### Returns
+
+* **`Pulse`**: Returns the instance of the `Pulse` class, allowing for method chaining.
+
+
+

gitbook/docs/setup-and-config/config/defaultlocklimit.md

@@ -0,0 +1,31 @@
+# DefaultLockLimit
+
+
+
+## `pulse.defaultLockLimit(times)`
+
+{% hint style="info" %}
+The `defaultLockLimit` method sets the default number of times jobs of any given type can be locked concurrently. This setting helps to manage the concurrency of job processing more finely by limiting how many instances of the same job type can be prepared for execution at the same time.
+{% endhint %}
+
+### Example Usage
+
+```typescript
+const pulse = new Pulse();
+
+// Set the default concurrency for job processing to 3
+pulse.defaultLockLimit(2);
+```
+
+
+
+#### Parameters
+
+* **`times`** (`number`): The maximum number of times jobs of a specific type can be locked concurrently.
+
+#### Returns
+
+* **`Pulse`**: Returns the instance of the `Pulse` class, allowing for method chaining.
+
+
+