aws-lambda-typescript-integration

What this skill does

# AWS Lambda TypeScript Integration

Patterns for creating high-performance AWS Lambda functions in TypeScript with optimized cold starts.

## Overview

Two approaches for TypeScript Lambda:

1. **NestJS Framework** - Dependency injection, modular architecture, larger bundle (100KB+)
2. **Raw TypeScript** - Minimal overhead, smaller bundle (<50KB), maximum control

Both support API Gateway and ALB integration.

## When to Use

- Creating new Lambda functions in TypeScript
- Optimizing cold start performance
- Choosing between NestJS and minimal TypeScript
- Configuring API Gateway or ALB integration
- Setting up CI/CD for TypeScript Lambda

## Instructions

### 1. Choose Your Approach

| Approach | Cold Start | Bundle Size | Best For | Complexity |
|----------|------------|-------------|----------|------------|
| NestJS | < 500ms | Larger (100KB+) | Complex APIs, enterprise apps, DI needed | Medium |
| Raw TypeScript | < 100ms | Smaller (< 50KB) | Simple handlers, microservices, minimal deps | Low |

### 2. Project Structure

#### NestJS Structure
```
my-nestjs-lambda/
├── src/
│   ├── app.module.ts
│   ├── main.ts
│   ├── lambda.ts           # Lambda entry point
│   └── modules/
│       └── api/
├── package.json
├── tsconfig.json
└── serverless.yml
```

#### Raw TypeScript Structure
```
my-ts-lambda/
├── src/
│   ├── handlers/
│   │   └── api.handler.ts
│   ├── services/
│   └── utils/
├── dist/                   # Compiled output
├── package.json
├── tsconfig.json
└── template.yaml
```

### 3. Implementation Examples

See the [References](#references) section for detailed implementation guides. Quick examples:

**NestJS Handler:**
```typescript
// lambda.ts
import { NestFactory } from '@nestjs/core';
import { ExpressAdapter } from '@nestjs/platform-express';
import serverlessExpress from '@codegenie/serverless-express';
import { Context, Handler } from 'aws-lambda';
import express from 'express';
import { AppModule } from './src/app.module';

let cachedServer: Handler;

async function bootstrap(): Promise<Handler> {
  const expressApp = express();
  const adapter = new ExpressAdapter(expressApp);
  const nestApp = await NestFactory.create(AppModule, adapter);
  await nestApp.init();
  return serverlessExpress({ app: expressApp });
}

export const handler: Handler = async (event: any, context: Context) => {
  if (!cachedServer) {
    cachedServer = await bootstrap();
  }
  return cachedServer(event, context);
};
```

**Raw TypeScript Handler:**
```typescript
// src/handlers/api.handler.ts
import { APIGatewayProxyEvent, APIGatewayProxyResult, Context } from 'aws-lambda';

export const handler = async (
  event: APIGatewayProxyEvent,
  context: Context
): Promise<APIGatewayProxyResult> => {
  return {
    statusCode: 200,
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: 'Hello from TypeScript Lambda!' })
  };
};
```

## Core Concepts

### Cold Start Optimization

TypeScript cold start depends on bundle size and initialization code. Key strategies:

1. **Lazy Loading** - Defer heavy imports until needed
2. **Tree Shaking** - Remove unused code from bundle
3. **Minification** - Use esbuild or terser for smaller bundles
4. **Instance Caching** - Cache initialized services between invocations

See [Raw TypeScript Lambda](references/raw-typescript-lambda.md#cold-start-optimization) for detailed patterns.

### Connection Management

Create clients at module level and reuse:

```typescript
// GOOD: Initialize once, reuse across invocations
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

const dynamoClient = new DynamoDBClient({ region: process.env.AWS_REGION });

export const handler = async (event: APIGatewayProxyEvent) => {
  // Use dynamoClient - already initialized
};
```

### Environment Configuration

```typescript
// src/config/env.config.ts
export const env = {
  region: process.env.AWS_REGION || 'us-east-1',
  tableName: process.env.TABLE_NAME || '',
  debug: process.env.DEBUG === 'true',
};

// Validate required variables
if (!env.tableName) {
  throw new Error('TABLE_NAME environment variable is required');
}
```

## Best Practices

### Memory and Timeout Configuration

- **Memory**: Start with 512MB for NestJS, 256MB for raw TypeScript
- **Timeout**: Set based on cold start + expected processing time
  - NestJS: 10-30 seconds for cold start buffer
  - Raw TypeScript: 3-10 seconds typically sufficient

### Dependencies

Keep `package.json` minimal:

```json
{
  "dependencies": {
    "aws-lambda": "^3.1.0",
    "@aws-sdk/client-dynamodb": "^3.450.0"
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "esbuild": "^0.19.0"
  }
}
```

### Error Handling

Return proper HTTP codes with structured errors:

```typescript
export const handler = async (event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> => {
  try {
    const result = await processEvent(event);
    return {
      statusCode: 200,
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(result)
    };
  } catch (error) {
    console.error('Error processing request:', error);
    return {
      statusCode: 500,
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ error: 'Internal server error' })
    };
  }
};
```

### Logging

Use structured logging for CloudWatch Insights:

```typescript
const log = (level: string, message: string, meta?: object) => {
  console.log(JSON.stringify({
    level,
    message,
    timestamp: new Date().toISOString(),
    ...meta
  }));
};

log('info', 'Request processed', { requestId: context.awsRequestId });
```

## Deployment Options

### Quick Start

**Serverless Framework:**
```yaml
service: my-typescript-api

provider:
  name: aws
  runtime: nodejs20.x

functions:
  api:
    handler: dist/handler.handler
    events:
      - http:
          path: /{proxy+}
          method: ANY
```

**AWS SAM:**
```yaml
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Resources:
  ApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: dist/
      Handler: handler.handler
      Runtime: nodejs20.x
      Events:
        ApiEvent:
          Type: Api
          Properties:
            Path: /{proxy+}
            Method: ANY
```

### Deployment Validation

**Pre-deploy checks:**
1. Run `npm test` - verify all tests pass
2. Run `npm run build` - confirm TypeScript compiles without errors
3. Verify bundle size < 50MB (unzipped)
4. Run `serverless invoke local` or `sam local invoke` - test locally

**Post-deploy verification:**
1. Run `serverless invoke` or `aws lambda invoke` - verify handler executes
2. Test API endpoint via curl or Postman
3. Check CloudWatch logs for errors
4. Verify cold start time meets SLA

For complete deployment configurations including CI/CD, see [Serverless Deployment](references/serverless-deployment.md).

## Constraints and Warnings

### Lambda Limits

- **Deployment package**: 250MB unzipped maximum (50MB zipped)
- **Memory**: 128MB to 10GB
- **Timeout**: 15 minutes maximum
- **Concurrent executions**: 1000 default (adjustable)
- **Environment variables**: 4KB total size

### TypeScript-Specific Considerations

- **Bundle size**: TypeScript compiles to JavaScript; use bundlers to minimize size
- **Cold start**: Node.js 20.x offers best performance
- **Dependencies**: Use Lambda Layers for shared dependencies
- **Native modules**: Must be compiled for Amazon Linux 2

### Common Pitfalls

1. **Importing heavy libraries at module level** - Defer to lazy loading if not always needed
2. **Not bundling dependencies** - Include all production dependencies in the package
3. **Missing type definitions** - Install `@types/aws-lambda` for proper event typing
4. **No timeout handling** - Use `context.getRemainingTimeInMillis()` for long operations

### Security Considerations

- Never hardcode credentials; use IAM roles and environment variables
- **Input Validation for Event Data**: A