nestjs-shamsi-schedule

A NestJS scheduling package with ShamsiCron support for the Jalali (Shamsi) calendar.

This project is an independent fork of nestjs/schedule and is not officially affiliated with the NestJS core team.

Features

• Supports @Cron, @Interval, and @Timeout like the NestJS schedule core
• Adds @ShamsiCron(...) for Jalali calendar scheduling
• One-time execution with Jalali date input
• Recurring execution with Jalali cron expressions (5 fields)
• Default timezone: Asia/Tehran

Installation

npm install nestjs-shamsi-schedule

Quick Start

import { Module } from '@nestjs/common';
import { ScheduleModule } from 'nestjs-shamsi-schedule';
import { TasksService } from './tasks.service';

@Module({
  imports: [ScheduleModule.forRoot()],
  providers: [TasksService],
})
export class AppModule {}

ShamsiCron Usage

1) One-time Jalali date

Supported formats:

• YYYY-MM-DD
• YYYY-MM-DD HH:mm:ss
• YYYY-MM-DD HH:mm:ss.SSS

import { Injectable } from '@nestjs/common';
import { ShamsiCron } from 'nestjs-shamsi-schedule';

@Injectable()
export class BillingService {
  @ShamsiCron('1405-01-01 08:30:00', { name: 'nowruz-billing' })
  handleNowruzBilling() {
    // runs once
  }
}

2) Recurring Jalali cron expression

Expression format:

minute hour dayOfMonth month dayOfWeek

@ShamsiCron('29 12 7 * *', { name: 'monthly-report' })
handleMonthlyReport() {
  // Runs on day 7 of every Jalali month at 12:29
}

Common examples:

// Every Jalali day at 09:00
@ShamsiCron('0 9 * * *')

// Day 1 of every Jalali month at 00:00
@ShamsiCron('0 0 1 * *')

// Every Friday at 08:15 (dayOfWeek = 5)
@ShamsiCron('15 8 * * 5')

Options

ShamsiCron accepts the same options as Cron, including:

• name
• disabled
• waitForCompletion
• timeZone
• utcOffset
• unrefTimeout

Additional option:

• useUtc?: boolean

If true, Jalali date conversion is done directly in UTC.

Note:

• If neither timeZone nor utcOffset is provided, Asia/Tehran is used by default.

Timezone Behavior

• Default timezone for ShamsiCron: Asia/Tehran
• You can override it:

@ShamsiCron('0 10 * * *', { timeZone: 'Europe/Berlin' })

Or use utcOffset:

@ShamsiCron('0 10 * * *', { utcOffset: 210 })

Common Issues

Why is my job running every minute?

If you use a Jalali expression (for example 29 12 7 * *) but the method runs every minute:

• The published package may not be in sync with source code
• An outdated dist may have been published

Fix:

1. Run npm run build in the package repo
2. Bump the package version
3. Publish again
4. Reinstall in the consumer project

Invalid shamsi date format error

If you are using recurring mode, the input must be a 5-field expression. If you are using one-time mode, the input must match supported Jalali date formats.

Scheduler Registry

You can use SchedulerRegistry exactly as in NestJS schedule:

import { SchedulerRegistry } from 'nestjs-shamsi-schedule';

constructor(private readonly schedulerRegistry: SchedulerRegistry) {}

stopJob() {
  const job = this.schedulerRegistry.getCronJob('monthly-report');
  job.stop();
}

Migration from @nestjs/schedule

1. Replace package:

npm remove @nestjs/schedule
npm install nestjs-shamsi-schedule

2. Update imports:

// before
import { ScheduleModule, Cron } from '@nestjs/schedule';

// after
import { ScheduleModule, Cron, ShamsiCron } from 'nestjs-shamsi-schedule';

3. Use ShamsiCron for Jalali-based schedules.

License

This project is licensed under MIT. Portions of this codebase are derived from nestjs/schedule.