Scheduled Tasks

defineScheduledHandler creates Lambda handlers triggered by CloudWatch scheduled events. Import from @mantleframework/core.

Pattern

import { defineScheduledHandler } from '@mantleframework/core'

const scheduled = defineScheduledHandler({
  schedule: { expression: 'rate(6 hours)' },
  timeout: 300,
  operationName: 'DailyCleanup',
})
export const handler = scheduled(async ({ event, context }) => {
  const deleted = await cleanupExpiredRecords()
  return { deleted }
})

Options

Option	Type	Default	Description
schedule	{ expression: string; enabled?: boolean }	--	Schedule expression for rule generation
operationName	string	function name	Name for metrics and tracing
timeout	number	--	Lambda timeout in seconds
memorySize	number	128	Lambda memory in MB
reservedConcurrency	number	--	Reserved concurrent executions
ephemeralStorage	number	512	Ephemeral storage in MB
deadLetterQueue	boolean | { targetArn? }	--	true = auto-generate SQS DLQ
retryAttempts	number	--	Max retry attempts (0-2)

Handler Params

interface ScheduledHandlerParams {
  event: ScheduledEvent
  context: Context
  metadata: WrapperMetadata
}

Schedule Expressions

rate() — fixed intervals

schedule: { expression: 'rate(5 minutes)' }
schedule: { expression: 'rate(1 hour)' }
schedule: { expression: 'rate(7 days)' }

Unit must be singular when the value is 1 (rate(1 hour), not rate(1 hours)).

cron() — specific times

// Every day at midnight UTC
schedule: { expression: 'cron(0 0 * * ? *)' }

// Every Monday at 9am UTC
schedule: { expression: 'cron(0 9 ? * MON *)' }

// First day of each month at 6am UTC
schedule: { expression: 'cron(0 6 1 * ? *)' }

CloudWatch cron format: cron(minutes hours day-of-month month day-of-week year). Note that day-of-month and day-of-week cannot both be specified — use ? for the one not in use.

Disabling a schedule

schedule: { expression: 'rate(1 day)', enabled: false }

enabled: false generates the CloudWatch rule in a disabled state. The Lambda is still deployed; only the trigger is inactive.

File Location

Scheduled handlers live under src/lambdas/scheduled/<HandlerName>/index.ts:

src/lambdas/scheduled/
  DailyCleanup/
    index.ts
  WeeklyReport/
    index.ts

See Also

• Handler Patterns — overview of all handler types
• Event-Driven Handlers — EventBridge triggers