Node.js Cron Scheduler

A utility for scheduling multiple cron jobs using environment variables and node-cron.

Official repo

Features

• Timezone support
• Environment variable validation
• Flexible HTTP request configuration

Configuration

Environment Variables

The following environment variables are supported:

Variable	Required	Description	Example
TIMEZONE	No	IANA timezone name (defaults to UTC)	TIMEZONE="America/New_York"
RUN_ON_START	No	Run jobs on startup (defaults to false)	RUN_ON_START="false"
JOB{n}	Yes	Cron job configuration (see below)	JOB1="* * * * *::GET::https://api.example.com"

Important notes

Environment Variable Formatting Rules. Since some environment variables have to contain spaces or special characters, it's recommended to use double quotes for all values.

Development configuration. During development or testing you can set RUN_ON_START="true" to run jobs on every file change to see result of changes faster.

Timezone

The scheduler supports all IANA timezone names. Examples:

• TIMEZONE"="UTC" (default)
• TIMEZONE"="America/New_York"
• TIMEZONE"="Europe/London"
• TIMEZONE"="Asia/Tokyo"

Note, that timezone is configured for all jobs.

See list of available timezones here.

Job Configuration

Jobs are configured using environment variables in the following format:

JOB{n}="schedule::method::url::prop1=value1::prop2=value2"

Where:

• {n}: Job number (1, 2, 3, etc.)
• schedule: Cron schedule expression
• method: HTTP method (GET, POST, PUT, DELETE, PATCH)
• url: Target URL
• prop{n}=value{n}: Optional properties for request body

Fields are separated by :: (double colon).

Examples

Basic Jobs

1. Simple GET request every minute:

JOB1="* * * * *::GET::https://api.example.com/ping"

2. POST request every day at midnight:

JOB2="0 0 * * *::POST::https://api.example.com/daily-task"

Advanced Jobs

1. POST request with properties:

JOB1="0 0 * * *::POST::https://api.example.com/task::userId=123::action=backup"

This will send a POST request with the body:

{
  "userId": "123",
  "action": "backup"
}

2. Multiple jobs with different schedules:

JOB1="*/5 * * * *::GET::https://api.example.com/health"
JOB2="0 0 * * *::POST::https://api.example.com/daily::task=backup"
JOB3="0 */2 * * *::PUT::https://api.example.com/update::status=active"

Validation

The scheduler includes comprehensive validation for all configuration:

• Cron Schedule: Validates correct cron expression format
• HTTP Method: Must be one of: GET, POST, PUT, DELETE, PATCH
• URL: Validates proper URL format
• Timezone: Validates against IANA timezone database
• Properties: Validates key-value pair format

If validation fails, the scheduler will:

1. Log detailed error messages
2. Exit with a non-zero status code

Testing

In order to test your configuration you can use these services that quickly mock API endpoints:

• Mockbin.io
• Webhook.site

Author

Aliaksandr Tsykin

License

Licensed under the MIT license.

Contribution

All PRs are welcome :)