AWS Lambda TypeScript インテグレーション

TypeScript で高パフォーマンスな AWS Lambda 関数を作成するためのパターン（コールドスタート最適化対応）。

概要

TypeScript Lambda の 2 つのアプローチ：

1. NestJS フレームワーク - 依存性注入、モジュール型アーキテクチャ、より大きなバンドル (100KB+)
2. Raw TypeScript - 最小限のオーバーヘッド、小さいバンドル (<50KB)、最大限の制御

両方とも API Gateway と ALB インテグレーションをサポートします。

いつ使うか

• TypeScript で新しい Lambda 関数を作成する場合
• コールドスタートパフォーマンスを最適化する場合
• NestJS と最小限の TypeScript の選択を検討する場合
• API Gateway または ALB インテグレーションを設定する場合
• TypeScript Lambda の CI/CD をセットアップする場合

手順

1. アプローチの選択

アプローチ	コールドスタート	バンドルサイズ	最適な用途	複雑度
NestJS	< 500ms	より大きい (100KB+)	複雑な API、エンタープライズアプリケーション、DI が必要	中
Raw TypeScript	< 100ms	より小さい (< 50KB)	シンプルなハンドラー、マイクロサービス、最小限の依存関係	低

2. プロジェクト構造

NestJS 構造

my-nestjs-lambda/
├── src/
│   ├── app.module.ts
│   ├── main.ts
│   ├── lambda.ts           # Lambda エントリーポイント
│   └── modules/
│       └── api/
├── package.json
├── tsconfig.json
└── serverless.yml

Raw TypeScript 構造

my-ts-lambda/
├── src/
│   ├── handlers/
│   │   └── api.handler.ts
│   ├── services/
│   └── utils/
├── dist/                   # コンパイル済み出力
├── package.json
├── tsconfig.json
└── template.yaml

3. 実装例

詳細な実装ガイドは 参考資料 を参照してください。簡潔な例：

NestJS ハンドラー：

// 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 ハンドラー：

// 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!' })
  };
};

コアコンセプト

コールドスタート最適化

TypeScript のコールドスタートはバンドルサイズと初期化コードに依存します。主な戦略：

1. 遅延ローディング - 重い import が必要になるまで遅延させる
2. ツリーシェイキング - バンドルから未使用のコードを削除
3. ミニファイ - esbuild または terser でバンドルを小さくする
4. インスタンスキャッシング - 呼び出し間で初期化されたサービスをキャッシュ

詳細なパターンは Raw TypeScript Lambda を参照してください。

コネクション管理

クライアントをモジュールレベルで作成し再利用：

// 良い例: 一度初期化して複数回の呼び出しで再利用
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

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

export const handler = async (event: APIGatewayProxyEvent) => {
  // dynamoClient を使用 - 既に初期化されている
};

環境設定

// 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',
};

// 必須変数を検証
if (!env.tableName) {
  throw new Error('TABLE_NAME environment variable is required');
}

ベストプラクティス

メモリとタイムアウト設定

• メモリ: NestJS は 512MB、Raw TypeScript は 256MB から開始
• タイムアウト: コールドスタート + 予想処理時間に基づいて設定
  • NestJS: コールドスタートバッファのため 10～30 秒
  • Raw TypeScript: 通常 3～10 秒で十分

依存関係

package.json は最小限に保つ：

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

エラーハンドリング

適切な HTTP コードと構造化されたエラーを返す：

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' })
    };
  }
};

ロギング

CloudWatch Insights 用に構造化ログを使用：

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 });

デプロイメント オプション

クイックスタート

Serverless フレームワーク：

service: my-typescript-api

provider:
  name: aws
  runtime: nodejs20.x

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

AWS SAM：

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

デプロイメント検証

デプロイ前チェック：

1. npm test を実行 - すべてのテストが通過することを確認
2. npm run build を実行 - TypeScript が エラーなくコンパイルされることを確認
3. バンドルサイズが 50MB 未満 (展開済み) であることを確認
4. serverless invoke local または sam local invoke を実行 - ローカルでテスト

デプロイ後検証：

1. serverless invoke または aws lambda invoke を実行 - ハンドラーが実行されることを確認
2. curl または Postman で API エンドポイントをテスト
3. CloudWatch ログでエラーを確認
4. コールドスタート時間が SLA を満たしていることを確認

CI/CD を含むデプロイメント設定の詳細については、Serverless デプロイメント を参照してください。

制約と警告

Lambda の制限

• デプロイメントパッケージ: 最大 250MB 展開済み (50MB 圧縮)
• メモリ: 128MB～10GB
• タイムアウト: 最大 15 分
• 同時実行: デフォルト 1000 (調整可能)
• 環境変数: 合計 4KB

TypeScript 固有の考慮事項

• バンドルサイズ: TypeScript は JavaScript にコンパイルされます。バンドラーを使用してサイズを最小化します
• コールドスタート: Node.js 20.x が最高のパフォーマンスを提供します
• 依存関係: 共有依存関係には Lambda Layers を使用します
• ネイティブモジュール: Amazon Linux 2 用にコンパイルが必要です

よくある落とし穴

1. モジュールレベルで重いライブラリをインポート - 常に必要でない場合は遅延ロードを検討
2. 依存関係をバンドルしない - すべての本番環境の依存関係をパッケージに含める
3. 型定義がない - イベント型の適切な定義のため @types/aws-lambda をインストール
4. タイムアウト処理がない - 長い操作の場合は context.getRemainingTimeInMillis() を使用

セキュリティ考慮事項

• 認証情報をハードコーディングしない。IAM ロールと環境変数を使用
• イベントデータの入力検証: API Gateway リクエストボディ、S3 イベントオブジェクト、SQS メッセージボディなどの受信イベントデータはすべて信頼できない外部コンテンツです。インジェクション攻撃を防ぐため、処理する前に必ず検証とサニタイズを行ってください
• コンテンツサニタイズ: S3 オブジェクトまたは SQS メッセージペイロードを処理する場合、コンテンツを信頼できないサードパーティのデータとして扱う。処理前に適切な検証、スキーマチェック、サニタイズを適用してください
• すべての入力データを検証
• 最小権限の IAM ポリシーを使用
• CloudTrail での監査ログを有効化
• 機密データ漏洩を避けるため、ログをサニタイズ

参考資料

特定のトピックの詳細なガイダンス：

• NestJS Lambda - NestJS の完全なセットアップ、依存性注入、Express/Fastify アダプター
• Raw TypeScript Lambda - 最小限のハンドラーパターン、バンドリング、ツリーシェイキング
• Serverless 設定 - Serverless フレームワーク と SAM 設定
• Serverless デプロイメント - CI/CD パイプライン、環境管理
• テスト - Jest、インテグレーションテスト、SAM Local

例

例 1: NestJS REST API を作成

入力: Create a TypeScript Lambda REST API using NestJS for a todo application

プロセス:

1. nest new で NestJS プロジェクトを初期化
2. Lambda 依存関係をインストール: @codegenie/serverless-express, aws-lambda
3. Express アダプター付き lambda.ts エントリーポイントを作成
4. API Gateway イベントで serverless.yml を設定
5. Serverless フレームワークでデプロイ

検証:

• serverless invoke local -f api を実行 - ハンドラーが機能することを確認
• バンドルサイズが 250MB 未満であることを確認
• デプロイされたエンドポイントが 200 OK を返すことをテスト

出力: REST API、DynamoDB インテグレーション、デプロイメント設定を備えた NestJS プロジェクト

例 2: Raw TypeScript Lambda を作成

入力: Create a minimal TypeScript Lambda function with optimal cold start

プロセス:

1. esbuild で TypeScript プロジェクトをセットアップ
2. 適切な AWS 型でハンドラーを作成
3. 最小限の依存関係を設定
4. SAM または Serverless デプロイメントをセットアップ
5. ツリーシェイキングでバンドルサイズを最適化

検証:

• sam local invoke を実行 - デプロイ前にローカルでテスト
• du -sh dist/ でバンドルが 50KB 未満であることを確認
• CloudWatch でコールドスタートが 100ms 未満であることを確認

出力: 最小限の TypeScript Lambda、バンドル < 50KB、コールドスタート < 100ms

例 3: GitHub Actions でデプロイ

入力: Configure CI/CD for TypeScript Lambda with SAM

プロセス:

1. GitHub Actions ワークフローを作成
2. Node.js 環境をセットアップ
3. Jest でテストを実行
4. esbuild でバンドル
5. SAM でデプロイ

検証:

• CI パイプラインが npm test を正常に実行することを確認
• パイプラインで sam validate が通ることを確認
• CloudFormation スタックが正常に作成されたことを確認

出力: GitHub Actions ワークフロー、マルチステージパイプライン、テスト自動化

バージョン

Version: 1.0.0