@lafken/schedule

Define Amazon EventBridge scheduled rules using TypeScript decorators. @lafken/schedule lets you declare cron-based tasks directly on class methods — each one becomes a Lambda function invoked automatically by EventBridge at the specified times.

Installation

npm install @lafken/schedule

Getting Started

Define a schedule class with @Schedule, add @Cron methods, and register it through ScheduleResolver:

import { createApp, createModule } from '@lafken/main';
import { ScheduleResolver } from '@lafken/schedule/resolver';
import { Schedule, Cron } from '@lafken/schedule/main';

// 1. Define scheduled tasks
@Schedule()
export class MaintenanceJobs {
  @Cron({ schedule: 'cron(0 3 * * ? *)' })
  cleanupExpiredSessions() {
    // Runs every day at 3:00 AM UTC
  }

  @Cron({ schedule: { hour: 0, minute: 0, weekDay: 'SUN' } })
  generateWeeklyReport() {
    // Runs every Sunday at midnight UTC
  }
}

// 2. Register in a module
const maintenanceModule = createModule({
  name: 'maintenance',
  resources: [MaintenanceJobs],
});

// 3. Add the resolver to the app
createApp({
  name: 'my-app',
  resolvers: [new ScheduleResolver()],
  modules: [maintenanceModule],
});

Each @Cron method becomes an independent Lambda function with its own EventBridge rule.

Features

Schedule Class

Use the @Schedule decorator to group related cron tasks in a single class. The class itself holds no schedule logic — it acts as a container for @Cron handlers:

import { Schedule, Cron } from '@lafken/schedule/main';

@Schedule()
export class DataPipeline {
  @Cron({ schedule: 'cron(0 6 * * ? *)' })
  ingestData() { }

  @Cron({ schedule: 'cron(30 6 * * ? *)' })
  transformData() { }
}

Cron Expression (String)

Pass a standard AWS cron expression as a string. The format follows:

cron(Minutes Hours Day-of-month Month Day-of-week Year)

@Cron({ schedule: 'cron(0 12 * * ? *)' })
sendDailyDigest() {
  // Every day at 12:00 PM UTC
}

@Cron({ schedule: 'cron(0 9 1 * ? *)' })
generateMonthlyInvoice() {
  // First day of every month at 9:00 AM UTC
}

[!NOTE] AWS cron expressions require either the day-of-month or day-of-week field to be ?. You cannot specify both simultaneously. When using a cron string, include the full cron(...) wrapper.

Cron Expression (Object)

For a more readable alternative, use the ScheduleTime object format. Each field defaults to '*' when omitted:

@Cron({
  schedule: {
    minute: 0,
    hour: 8,
    weekDay: 'MON-FRI',
  },
})
startBusinessHours() {
  // Every weekday at 8:00 AM UTC
}

@Cron({
  schedule: {
    minute: 30,
    hour: 22,
    day: 15,
  },
})
midMonthAudit() {
  // 15th of every month at 10:30 PM UTC
}

ScheduleTime Fields

| Field | Type | Default | Description | | --------- | --------------------------- | ------- | -------------------- | | minute | number \| '*' \| '?' | '*' | Minute (0–59) | | hour | number \| '*' \| '?' | '*' | Hour (0–23) | | day | number \| '*' \| '?' | '*' | Day of month (1–31) | | month | number \| '*' \| '?' | '*' | Month (1–12) | | weekDay | number \| string \| '?' | '*' | Day of week (SUN–SAT or 1–7) | | year | number \| '*' \| '?' | '*' | Year |

When day is set to a specific value, weekDay is automatically set to '?' and vice versa, following the AWS cron constraint.

Retry Policy

Configure how EventBridge handles failed deliveries using retryAttempts and maxEventAge:

@Cron({
  schedule: 'cron(0 0 * * ? *)',
  retryAttempts: 3,
  maxEventAge: 3600,
})
criticalNightlyJob() {
  // Retries up to 3 times, discards events older than 1 hour
}

| Option | Type | Description | | --------------- | -------- | ---------------------------------------------------------- | | retryAttempts | number | Maximum retry attempts if the target invocation fails | | maxEventAge | number | Maximum event age in seconds before the event is discarded |