Event-Driven Handlers

defineEventBridgeHandler creates Lambda handlers triggered by EventBridge events. Import from @mantleframework/core.

Pattern

import { defineEventBridgeHandler } from '@mantleframework/core'
import { exportToS3 } from '@mantleframework/aws'
import { emitEvent } from '@mantleframework/core'
import { getRequiredEnv } from '@mantleframework/env'

const eb = defineEventBridgeHandler({
  detailTypes: ['ExportHealthData'],
  timeout: 60,
  operationName: 'ExportHealthData',
})
export const handler = eb(async ({ detail, detailType }) => {
  const bucket = getRequiredEnv('DATA_BUCKET')
  const generatedAt = new Date().toISOString()
  await exportToS3({ bucket, key: `health/${generatedAt}.json`, data: detail })
  await emitEvent({ detailType: 'ExportHealthDataCompleted', detail: { generatedAt } })
  return { generatedAt, detailType }
})

Options

Option	Type	Default	Description
detailTypes	string[]	(required)	Detail types this handler responds to
source	string	--	Event source for filtering
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 EventBridgeHandlerParams<TDetailType, TDetail> {
  event: EventBridgeEvent<TDetailType, TDetail>
  context: Context
  metadata: WrapperMetadata
  detailType: TDetailType        // The detail-type from the event
  detail: TDetail                // The event detail payload
  source: string                 // The event source
}

Event Routing

The detailTypes array tells the CLI which EventBridge rules to generate. Each handler responds only to the listed detail types. Multiple handlers can share the same event bus but respond to different detail types.

// Responds to order events
const eb = defineEventBridgeHandler({ detailTypes: ['OrderPlaced', 'OrderUpdated'] })

// Responds to export completion events
const eb2 = defineEventBridgeHandler({ detailTypes: ['ExportCompleted'] })

Publishing Follow-up Events

Use emitEvent from @mantleframework/core to publish events back to the bus:

import { emitEvent } from '@mantleframework/core'

await emitEvent({
  detailType: 'ProcessingCompleted',
  detail: { recordsProcessed: 42, completedAt: new Date().toISOString() },
})

emitEvent uses the EVENT_BUS_NAME environment variable injected by the CLI. The bus name is configured in mantle.config.ts:

export default defineConfig({
  eventbridge: { bus: 'my-app-events' },
})

Exporting to S3

Use exportToS3 from @mantleframework/aws to write JSON exports:

import { exportToS3 } from '@mantleframework/aws'

await exportToS3({
  bucket: getRequiredEnv('DATA_BUCKET'),
  key: `exports/${new Date().toISOString()}.json`,
  data: { generatedAt, records },
})

Built-in Observability

The handler automatically:

• Adds X-Ray annotations for detailType and eventSource
• Logs a structured entry with the detail type and source
• Extracts correlation IDs from the event detail

File Location

EventBridge handlers live under src/lambdas/eventbridge/<DetailType>/index.ts:

src/lambdas/eventbridge/
  ExportHealthData/
    index.ts
  ProcessOrder/
    index.ts

See Also

• Handler Patterns — overview of all handler types
• Scheduled Tasks — time-based triggers