Declarative and safe cron decorator for NestJS with UTC offset support.
npm install @usefulish/smartcron
> A lightweight, declarative cron decorator for NestJS with runtime validation, safe intervals, and built-in UTC offset support.
---
``bash`
npm install @usefulish/smartcron
or
`bash`
yarn add @usefulish/smartcron
---
`ts
import { SmartCron } from '@usefulish/smartcron';
@SmartCron({
intervalInMinutes: 13,
fromHour: 8,
toHour: 17,
fromMinute: 5,
toMinute: 50,
weekdaysOnly: true,
timezone: -3,
})
handleJob() {
// Runs every 13 minutes from 08:05 to 17:50, Monday to Friday, in UTC-3
}
`
---
| Option | Type | Required | Default | Description |
| ------------------- | ---------------- | -------- | ------- | -------------------------------------------------------------------------------------- |
| intervalInMinutes | AllowedMinutes | ✅ | — | Interval in minutes. Must be one of the allowed values. |fromHour
| | Hour | ❌ | 0 | Start hour (inclusive). |toHour
| | Hour | ❌ | 23 | End hour (inclusive). If lower than fromHour, range is treated as crossing midnight. |fromMinute
| | Minute | ❌ | 0 | Start minute (inclusive). Only applies to the first hour of the range. |toMinute
| | Minute | ❌ | 59 | End minute (inclusive). Only applies to the last hour of the range. |weekdaysOnly
| | boolean | ❌ | false | Limits execution to weekdays (Mon–Fri) if true. |timezone
| | UTCOffset | ❌ | 0 | UTC offset (e.g., -3 for UTC-3). Affects CRON scheduling context. |
---
The following minute intervals are supported:
`ts`
[7, 11, 13, 17, 19, 23, 29, 31, 37, 41];
These are intentionally non-standard (mostly primes) to minimize cron collision in shared environments.
---
You can configure the execution timezone using a UTC offset:
- Positive values (e.g., 3) represent UTC+3-5
- Negative values (e.g., ) represent UTC-50
- Default is (UTC)
Internally, the offset is converted to an IANA-compatible timezone (e.g., Etc/GMT+3 for UTC-3).
---
This package also exports the following types for use in your codebase:
`ts``
import {
SmartCronOptions,
AllowedMinutes,
Hour,
Minute,
UTCOffset,
} from '@usefulish/smartcron';
---
MIT