Bun AWS Lambda (Clean Architecture)

Handler Pattern - Thin Adapter

Lambda handlers are thin adapters that:

1. Initialize DI Container (cold start)
2. Parse input
3. Resolve Use Case from DI
4. Execute and return result
5. Map domain exceptions to HTTP status

// src/functions/create-category.ts
import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from 'aws-lambda'
import { DIContainer, TOKENS, initializeDI } from '@/backend/di'
import type { CreateCategoryUseCase } from '@/backend/application/category/use-cases'
import { DomainException, NotFoundException } from '@/backend/domain/shared/exceptions'

let initialized = false

export async function handler(
  event: APIGatewayProxyEventV2
): Promise<APIGatewayProxyResultV2> {
  if (!initialized) {
    await initializeDI()
    initialized = true
  }

  try {
    const input = JSON.parse(event.body ?? '{}')
    const userId = event.requestContext.authorizer?.jwt?.claims?.sub

    const useCase = DIContainer.resolve<CreateCategoryUseCase>(
      TOKENS.CreateCategoryUseCase
    )
    const result = await useCase.execute({ ...input, userId })

    return response(201, result)
  } catch (error) {
    return handleError(error)
  }
}

function response(status: number, data: unknown): APIGatewayProxyResultV2 {
  return {
    statusCode: status,
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data),
  }
}

function handleError(error: unknown): APIGatewayProxyResultV2 {
  if (error instanceof NotFoundException) {
    return response(404, { error: error.message, code: error.code })
  }
  if (error instanceof DomainException) {
    return response(400, { error: error.message, code: error.code })
  }
  console.error('Unhandled:', error)
  return response(500, { error: 'Internal server error' })
}

Event Source Types

├── HTTP API (API Gateway v2) → APIGatewayProxyEventV2
├── REST API (API Gateway v1) → APIGatewayProxyEvent
├── SQS → SQSEvent
├── SNS → SNSEvent
├── EventBridge → EventBridgeEvent<T>
├── S3 → S3Event
└── DynamoDB Streams → DynamoDBStreamEvent

Deployment: Container Image

Dockerfile

FROM oven/bun:1 AS builder
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile --production
COPY src/ ./src/
RUN bun build src/handler.ts --outdir=dist --target=bun --minify

FROM public.ecr.aws/lambda/provided:al2023
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
WORKDIR ${LAMBDA_TASK_ROOT}
COPY --from=builder /app/dist/ ./
COPY bootstrap ${LAMBDA_RUNTIME_DIR}/bootstrap
RUN chmod +x ${LAMBDA_RUNTIME_DIR}/bootstrap
CMD ["handler.handler"]

Bootstrap

// bootstrap.ts
const RUNTIME_API = `http://${Bun.env.AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime`

const [moduleName, functionName] = (Bun.env._HANDLER ?? 'handler.handler').split('.')
const handlerModule = await import(`./${moduleName}.js`)
const handler = handlerModule[functionName]

while (true) {
  const next = await fetch(`${RUNTIME_API}/invocation/next`)
  const requestId = next.headers.get('Lambda-Runtime-Aws-Request-Id')!
  const event = await next.json()

  try {
    const result = await handler(event, { awsRequestId: requestId })
    await fetch(`${RUNTIME_API}/invocation/${requestId}/response`, {
      method: 'POST',
      body: JSON.stringify(result),
    })
  } catch (error) {
    await fetch(`${RUNTIME_API}/invocation/${requestId}/error`, {
      method: 'POST',
      body: JSON.stringify({ errorMessage: String(error) }),
    })
  }
}

DI Initialization

// src/backend/di/initialize.ts
import { DIContainer, TOKENS } from './container'
import { CategoryRepositoryImpl } from '@/backend/infrastructure/category/repositories'
import { CreateCategoryUseCase, GetCategoryUseCase } from '@/backend/application/category/use-cases'

export async function initializeDI() {
  const table = await getTable() // OneTable instance

  // Register repositories
  DIContainer.register(TOKENS.CategoryRepository, {
    useFactory: () => new CategoryRepositoryImpl(table),
  })

  // Register use cases
  DIContainer.register(TOKENS.CreateCategoryUseCase, {
    useFactory: () => new CreateCategoryUseCase(
      DIContainer.resolve(TOKENS.CategoryRepository)
    ),
  })

  DIContainer.register(TOKENS.GetCategoryUseCase, {
    useFactory: () => new GetCategoryUseCase(
      DIContainer.resolve(TOKENS.CategoryRepository)
    ),
  })
}

Cold Start Optimization

1. Lazy DI init - Initialize container on first request only
2. Bundle with Bun - Single file, tree-shaken
3. AWS SDK v3 - Modular imports
4. Minimal deps - Use native fetch, Bun APIs

// Lazy repository initialization
let repository: ICategoryRepository | null = null

function getRepository(): ICategoryRepository {
  if (!repository) {
    repository = DIContainer.resolve(TOKENS.CategoryRepository)
  }
  return repository
}

SQS Handler Example

// src/functions/process-queue.ts
import type { SQSEvent, SQSBatchResponse } from 'aws-lambda'
import { DIContainer, TOKENS, initializeDI } from '@/backend/di'
import type { ProcessMessageUseCase } from '@/backend/application/messaging/use-cases'

let initialized = false

export async function handler(event: SQSEvent): Promise<SQSBatchResponse> {
  if (!initialized) {
    await initializeDI()
    initialized = true
  }

  const useCase = DIContainer.resolve<ProcessMessageUseCase>(
    TOKENS.ProcessMessageUseCase
  )

  const failures: SQSBatchResponse['batchItemFailures'] = []

  for (const record of event.Records) {
    try {
      const message = JSON.parse(record.body)
      await useCase.execute(message)
    } catch (error) {
      console.error(`Failed record ${record.messageId}:`, error)
      failures.push({ itemIdentifier: record.messageId })
    }
  }

  return { batchItemFailures: failures }
}

Anti-Patterns

References

• Feature Architecture: skills/feature-architecture/SKILL.md
• SST Infrastructure: skills/sst-infra/SKILL.md