Handler Patterns

Mantle provides factory functions for every Lambda trigger type. Each define*Handler factory wraps your handler with built-in observability (metrics, tracing, structured logging) — no decorators or base classes required.

Handler Types

Function	Package	Trigger	Guide
defineApiHandler	@mantleframework/validation	API Gateway	API Handlers
defineEventBridgeHandler	@mantleframework/core	EventBridge	Event-Driven Handlers
defineScheduledHandler	@mantleframework/core	CloudWatch Schedule	Scheduled Tasks
defineSqsHandler	@mantleframework/core	SQS Queue	SQS Queue Handlers
defineS3Handler	@mantleframework/core	S3 Event	S3 Triggers
defineWebSocketHandler	@mantleframework/core	WebSocket API	WebSocket Handlers

File-System Routing

Lambda source files are organized by trigger type under src/lambdas/:

src/lambdas/
  api/                        # API Gateway (file-system routing for paths + methods)
    sync.post.ts
    users/
      index.get.ts
      index.delete.ts
  eventbridge/                # EventBridge-triggered
    ExportHealthData/
      index.ts
  scheduled/                  # CloudWatch scheduled
    DailyCleanup/
      index.ts
  sqs/                        # SQS-triggered
    ProcessSyncQueue/
      index.ts
  s3/                         # S3-triggered
    ProcessUpload/
      index.ts
  websocket/                  # WebSocket API routes
    connect/
      index.ts
    disconnect/
      index.ts
    default/
      index.ts
  standalone/                 # Direct invocation, no triggers
    MigrateDSQL/
      index.ts

Built-in Observability

Every handler factory wraps your handler with withObservability(), which provides:

• Cold start detection — emits a ColdStart CloudWatch metric on first invocation
• Logger context — adds Lambda context, operation name, and correlation ID to the logger
• X-Ray tracing — wraps each invocation in an OpenTelemetry span
• Metrics — emits <OperationName>Attempt and <OperationName>Success metrics
• Error logging — logs errors with structured metadata on failure

defineLambda()

defineLambda() is only needed for standalone handlers that have no define*Handler call. For all other types, pass Lambda config options (timeout, memorySize, etc.) directly to the factory.

import { defineLambda } from '@mantleframework/core'

// Only for standalone handlers
defineLambda({ timeout: 60, memorySize: 256, deadLetterQueue: true })