@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.

Additional Options

@Cron also accepts these options, none of which affect the cron/schedule expression itself:

@Cron({
  schedule: 'cron(0 3 * * ? *)',
  timezone: 'America/Santiago',
  description: 'Nightly cleanup job',
  state: 'disabled',        // paused without deleting the schedule
  startDate: '2026-07-01T00:00:00Z',
  endDate: '2026-12-31T23:59:59Z',
  flexibleWindowMinutes: 15, // EventBridge may run anywhere within this window
  outputs: [{ type: 'output', name: 'cleanup_schedule_arn', value: 'arn' }],
  ref: 'nightly-cleanup',
})
cleanupExpiredSessions() { }

| Option | Type | Description | | ------------------------ | ----------------------------------------- | ------------------------------------------------------------------------- | | timezone | string | IANA timezone the schedule is evaluated in (e.g. 'America/Santiago'). Defaults to UTC. | | description | string | Human-readable description shown in the AWS console. See note below. | | state | 'enabled' \| 'disabled' | Pauses the schedule without deleting it. Defaults to 'enabled'. | | startDate / endDate | string (ISO 8601) | Window during which the schedule is allowed to trigger its target. | | flexibleWindowMinutes | number | Runs in FLEXIBLE mode within this window (minutes) instead of firing at the exact time — useful to avoid thundering-herd invocations. Omit to run in OFF mode (exact time). | | outputs | ResourceOutputType<'arn' \| 'id'> | Exports the schedule's arn/id to SSM Parameter Store or a Terraform output. | | ref | string | Registers the schedule as a named global reference, retrievable via Refs.resourceValue('schedule::<ref>', attr). |

[!NOTE] description is shared with the underlying Lambda: @Cron's props are merged into the same handler metadata used to build the LambdaHandler, so the string you pass to description is applied to both the EventBridge Schedule's description and the Lambda function's description. There is currently no way to set a different description for each.

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 |