echoapi-cron-scheduler/readme.md

A Node.js cron scheduler for managing and executing scheduled tasks.

# CronScheduler

`CronScheduler` is a Node.js-based cron scheduler library that allows you to manage, execute, and monitor scheduled jobs. It can handle cron expressions, load jobs from a file, create new jobs, and handle job cancellation or restart.

## Features

- Supports cron expressions for flexible scheduling.
- Can schedule jobs based on preset cycles (minute, hour, day, week).
- Jobs can be loaded, created, canceled, or restarted.
- Supports graceful shutdown and reporting of job status.
- Jobs are stored in a local JSON file.

## Installation

1. Clone this repository or install it via npm:

```bash
npm install echoapi-cron-scheduler
````

2. If you're using the GitHub repository, run:

```bash
git clone https://github.com/Apipo/echoapi-cron-scheduler.git
cd echoapi-cron-scheduler
npm install
```

## Usage

### Basic Usage

First, import the `CronScheduler` class and create an instance:

```javascript
const CronScheduler = require('echoapi-cron-scheduler');
const scheduler = new CronScheduler();
```

### Creating and Running Jobs

To create a new job, use the `createJob` method. It will store the job in a JSON file and execute the job based on the schedule provided.

```javascript
const { option, test_events } = require('./tmp/request');
const { v4: uuidv4 } = require('uuid');

// Set a unique job ID
_.set(option, 'job_id', uuidv4());

// Create the job
scheduler.createJob(option, test_events);

// Load all jobs and start executing them
scheduler.loadJobs();
```

### Start Job with Cron Expression

You can start a job using a cron expression:

```javascript
scheduler.startJob('* * * * * *', 'exampleJob1', async () => {
    console.log('Executing job every minute...');
});
```

This will execute the job every minute.

### Canceling and Restarting Jobs

To cancel a running job, use `cancelJob`:

```javascript
scheduler.cancelJob('exampleJob1');
```

To restart a job, use `restartJob`:

```javascript
scheduler.restartJob('exampleJob1');
```

### Retrieving Job Information

You can retrieve a list of all scheduled jobs, including their current states (e.g., whether they are running):

```javascript
const allJobs = scheduler.getAllJobs();
console.log(allJobs);
```

### Graceful Shutdown

You can handle a graceful shutdown of all scheduled jobs by listening for `SIGINT`:

```javascript
process.on('SIGINT', () => {
    scheduler.gracefulShutdown().then(() => { process.exit(0) });
});
```

## Cron Expression Examples

Here are some cron expression examples you can use to schedule tasks:

* `* * * * * *` — Every second
* `*/5 * * * * *` — Every 5 seconds
* `0 * * * * *` — Every minute
* `0 0 * * * *` — Every hour
* `0 0 0 * * *` — Every day at midnight
* `0 0 * * 1 *` — Every Monday at midnight

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

```

### Explanation

1. **`package.json`**:
   - Defines the necessary dependencies (`node-schedule`, `axios`, `lodash`, `cron-parser`, etc.).
   - A basic `start` script that runs the main file (`index.js`).
   - Set the Node.js engine to ensure compatibility with the required Node version.

2. **`README.md`**:
   - Provides a basic overview of the CronScheduler.
   - Describes installation steps and usage examples for creating, managing, and executing cron jobs.
   - Includes explanations for cron expressions and how to handle graceful shutdowns.

### To Use This Project:

1. Clone the repository or install the package using `npm`.
2. Include your scheduler logic and job definitions in the `index.js` or another entry point.
3. Use the provided `createJob`, `startJob`, `cancelJob`, and other methods to interact with scheduled jobs.