# Cron

The `Cron` class provides a powerful and convenient way to schedule tasks that run automatically at specific times or intervals. It is a wrapper around the popular `node-cron` library, allowing you to define schedules using the standard **cron expression** format.

This is useful for automating recurring jobs, such as generating daily reports, performing nightly backups, or sending out scheduled notifications.

## Understanding Cron Expressions

A cron expression is a string that consists of five or six fields separated by spaces, representing a time schedule. Each field specifies a different unit of time.

```
┌─────────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌─────────── day of month (1 - 31)
│ │ │ ┌───────── month (1 - 12)
│ │ │ │ ┌─────── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
* * * * *

```

**Special Characters:**

* `*`: Asterisk. Represents "every". For example, `*` in the hour field means "every hour".
* `,`: Comma. Specifies a list of values. For example, `1,15,30` in the minute field means "at minutes 1, 15, and 30".
* `-`: Hyphen. Defines a range of values. For example, `9-17` in the hour field means "every hour from 9 AM to 5 PM".
* `/`: Slash. Specifies step values. For example, `*/15` in the minute field means "every 15 minutes".

## Static Functions

These functions are called directly on the `Cron` class and do not require you to create an instance.

### validate

Checks if a cron expression string is syntactically valid.

**Parameters**

* `expression`: The cron expression to validate.

**Example**

```
# expression
'0 9 * * 1-5'

```

Output

Returns true if the expression is valid, false otherwise.

## Instance Functions

You must create an instance of the `Cron` class to use these functions.

### create

Creates a new, empty cron scheduler instance. The task itself is defined and started using the `schedule` method.

### schedule

Defines a task and schedules it to run based on a cron expression. The scheduler starts automatically when this function is called.

**Parameters**

* `expression`: A string containing a valid cron expression.
* `listener`: The function that will be executed each time the schedule is triggered.
* `options`: An optional object for advanced control.
  * `timezone`: A string specifying the timezone for the schedule (e.g., `"America/New_York"`, `"Europe/Berlin"`). If not set, it uses the server's local timezone.
  * `noOverlap`: A boolean. If `true`, it prevents the task from starting a new execution if the previous one is still running.
  * `maxExecutions`: An integer that limits the total number of times the task will run before it is automatically destroyed.

**Example 1: Run a task every 15 minutes**

```yaml
# expression
*/15 * * * *
# listener
<callback>

```

**Example 2: Run a task at 9:00 AM and 5:00 PM every day**

```yaml
# expression
0 9,17 * * *
# listener
<callback>

```

**Example 3: Run a cleanup job at 1:30 AM every Saturday and Sunday**

```yaml
# expression
30 1 * * 6,0
# listener
<callback>

```

Output

Returns the string 'scheduled'.

### start

Starts the task scheduler. **Note**: You only need to call this if you have previously called `stop()`. The `schedule` method starts the task automatically.

### stop

Stops the task scheduler. The scheduled task will not run again until `start()` is called.

### getStatus

Provides the current lifecycle state of the task. This is useful for monitoring.

Output

A string representing the current state, such as stopped, idle (running but not executing), or running (actively executing).

### destroy

Permanently deactivates the task and cleans up all internal resources. A destroyed task cannot be restarted.

### execute

Manually executes the task's function immediately, outside of its regular schedule. This is useful for testing or for triggering on-demand runs.

### getNextRun

Returns the date and time of the next scheduled execution.

Output

A JavaScript Date object representing the next run time, or null if the task is stopped or destroyed.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.heisenware.com/app-builder/build-backend/function-explorer/utilities/cron.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.