Função Lambda em TypeScript

O gerador de Função Lambda em TypeScript permite adicionar uma função lambda a um projeto TypeScript existente.

Este gerador cria um novo handler Lambda em TypeScript com configuração de infraestrutura AWS CDK ou Terraform. O handler gerado utiliza AWS Lambda Powertools for TypeScript para observabilidade, incluindo logging, rastreamento com AWS X-Ray e métricas do CloudWatch, além de validação opcional de tipos para eventos usando o Parser do AWS Lambda Powertools

Utilização

Gerar uma função lambda TypeScript

Você pode gerar uma função lambda de duas formas:

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - ts#lambda-function
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#lambda-function

yarn

yarn nx g @aws/nx-plugin:ts#lambda-function

npm

npx nx g @aws/nx-plugin:ts#lambda-function

bun

bunx nx g @aws/nx-plugin:ts#lambda-function

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

pnpm

pnpm nx g @aws/nx-plugin:ts#lambda-function --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#lambda-function --dry-run

npm

npx nx g @aws/nx-plugin:ts#lambda-function --dry-run

bun

bunx nx g @aws/nx-plugin:ts#lambda-function --dry-run

Opções

Parâmetro	Tipo	Padrão	Descrição
project Obrigatório	string	-	The project to add the lambda function to
functionName Obrigatório	string	-	The name of the function to add
functionPath	string	-	Optional subdirectory within the project source directory to add the function to
eventSource	string	Any	Optional event source schema to use for the lambda function
iacProvider	string	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

Saída do Gerador

O gerador adicionará os seguintes arquivos ao seu projeto:

• Directory<project-name>

  • Directorysrc/

    • <lambda-function>.ts Implementação da função

Se a opção functionPath for fornecida, o gerador adicionará o handler no caminho especificado dentro do diretório source do projeto:

• Directory<project-name>

  • Directorysrc/

    • Directory<custom-path>/

      • <function-name>.ts Implementação da função

Infraestrutura

Como este gerador fornece infraestrutura como código com base no iacProvider escolhido, ele criará um projeto em packages/common que inclui os constructs CDK ou módulos Terraform relevantes.

O projeto comum de infraestrutura como código está estruturado da seguinte forma:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs para infraestrutura específica de um projeto/gerador

      • …
    • Directorycore/ Constructs genéricos reutilizados pelos constructs em app

      • …
    • index.ts Ponto de entrada exportando os constructs de app
  • project.json Metas de build e configuração do projeto

Nota

Este projeto é gerado usando o gerador ts#project e portanto configura as mesmas metas de build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Módulos Terraform para infraestrutura específica de um projeto/gerador

      • …
    • Directorycore/ Módulos genéricos reutilizados pelos módulos em app

      • …
  • project.json Metas de build e configuração do projeto

Nota

Este projeto é gerado usando o gerador terraform#project e portanto configura as mesmas metas de build.

O gerador cria infraestrutura como código para implantar sua função com base no iacProvider selecionado:

CDK

O gerador cria um construct CDK que pode ser usado para implantar sua função, localizado no diretório packages/common/constructs/src/app/lambda-functions.

Terraform

O gerador cria um módulo Terraform que pode ser usado para implantar sua função, localizado no diretório packages/common/terraform/src/app/lambda-functions/<function-name>.

Implementando sua Função

A implementação principal da função está em <function-name>.ts. Aqui está um exemplo:

import { parser } from '@aws-lambda-powertools/parser/middleware';
import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas';
import middy from '@middy/core';
import { Tracer } from '@aws-lambda-powertools/tracer';
import { captureLambdaHandler } from '@aws-lambda-powertools/tracer/middleware';
import { injectLambdaContext } from '@aws-lambda-powertools/logger/middleware';
import { Logger } from '@aws-lambda-powertools/logger';
import { Metrics } from '@aws-lambda-powertools/metrics';
import { logMetrics } from '@aws-lambda-powertools/metrics/middleware';
import { z } from 'zod';

process.env.POWERTOOLS_METRICS_NAMESPACE = 'MyFunction';
process.env.POWERTOOLS_SERVICE_NAME = 'MyFunction';

const tracer = new Tracer();
const logger = new Logger();
const metrics = new Metrics();

export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  logger.info('Received event', event);

  // TODO: implement
};

export const handler = middy()
  .use(captureLambdaHandler(tracer))
  .use(injectLambdaContext(logger))
  .use(logMetrics(metrics))
  .use(parser({ schema: EventBridgeSchema }))
  .handler(myFunction);

O gerador configura automaticamente vários recursos:

1. Pilha de middleware Middy para funcionalidades estendidas do Lambda
2. Integração com AWS Lambda Powertools para observabilidade
3. Coleta de métricas com CloudWatch
4. Validação de tipos usando middleware de parser
5. Empacotamento com Rolldown para pacotes de implantação otimizados

Observabilidade com AWS Lambda Powertools

Logging

O gerador configura logging estruturado usando AWS Lambda Powertools com injeção automática de contexto via middleware Middy.

export const handler = middy()
  .use(injectLambdaContext(logger))
  .handler(myFunction);

Tracing

O rastreamento com AWS X-Ray é configurado automaticamente via middleware captureLambdaHandler. Você pode adicionar subsegmentos personalizados aos seus traces:

const tracer = new Tracer();

export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  // Cria um novo subsegmento
  const subsegment = tracer.getSegment()?.addNewSubsegment('custom-operation');
  try {
    // Sua lógica aqui
  } catch (error) {
    subsegment?.addError(error as Error);
    throw error;
  } finally {
    subsegment?.close();
  }
};

export const handler = middy()
  .use(captureLambdaHandler(tracer))
  .handler(myFunction);

Métricas

Métricas do CloudWatch são coletadas automaticamente para cada requisição via middleware logMetrics. Você pode adicionar métricas personalizadas:

const metrics = new Metrics();

export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  metrics.addMetric("CustomMetric", MetricUnit.Count, 1);
  metrics.addMetric("ProcessingTime", MetricUnit.Milliseconds, processingTime);
};

export const handler = middy()
  .use(logMetrics(metrics))
  .handler(myFunction);

Validação de Tipos

Se você escolheu um eventSource ao gerar sua função Lambda, seu handler será instrumentado com o middleware parser do AWS Lambda Powertools. Por exemplo:

export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  event.detail // <- tipagem segura com autocompletar do IDE
};

export const handler = middy()
  .use(parser({ schema: EventBridgeSchema }))
  .handler(myFunction);

Isso fornece segurança de tipos em tempo de compilação e validação em runtime para eventos Lambda.

Cuidado

Se você não quer que seu handler lance um erro quando o evento não conformar com o schema, você pode usar a opção safeParse.

Dica

Se você tem dados personalizados aninhados em um evento, por exemplo em um stream do DynamoDB ou evento do EventBridge, pode se beneficiar usando Envelopes para fornecer validação de tipos para esses dados.

Se você não deseja tipar seu evento, pode selecionar Any para o eventSource, resultando em um tipo any para o parâmetro event.

Empacotamento

O gerador configura automaticamente um destino bundle que utiliza o Rolldown para criar um pacote de implantação:

pnpm

pnpm nx run <project-name>:bundle

yarn

yarn nx run <project-name>:bundle

npm

npx nx run <project-name>:bundle

bun

bunx nx run <project-name>:bundle

A configuração do Rolldown pode ser encontrada em rolldown.config.ts, com uma entrada para cada pacote a ser gerado. O Rolldown gerencia a criação de múltiplos pacotes em paralelo, se definidos.

Dica

Você pode ajustar a configuração do Rolldown em rolldown.config.ts. Por exemplo, se tiver dependências que dependem de caminhos de arquivo e não podem ser empacotadas, você pode adicioná-las à lista de módulos external.

Implantando sua Função

Este gerador cria infraestrutura como código CDK ou Terraform com base no iacProvider selecionado. Você pode usar isso para implantar sua função.

CDK

Este gerador cria um construct CDK para implantar sua função na pasta common/constructs. Você pode usar isso em uma aplicação CDK:

import { MyProjectMyFunction } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Adiciona a função à sua stack
    const fn = new MyProjectMyFunction(this, 'MyFunction');
  }
}

Isso configura:

1. Função AWS Lambda
2. Grupo de logs do CloudWatch
3. Configuração de rastreamento do X-Ray
4. Namespace de métricas do CloudWatch

Esta função pode ser usada como destino para qualquer fonte de evento lambda:

Nota

Certifique-se de que a fonte de evento corresponda à opção eventSource selecionada para garantir que o evento seja processado corretamente dentro de sua função handler.

O exemplo abaixo demonstra o código CDK para invocar sua função lambda em um agendamento usando o EventBridge:

import { Rule, Schedule } from 'aws-cdk-lib/aws-events';
import { LambdaFunction } from 'aws-cdk-lib/aws-events-targets';
import { MyProjectMyFunction } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Adiciona a função à sua stack
    const fn = new MyProjectMyFunction(this, 'MyFunction');

    // Adiciona a função a uma regra agendada do EventBridge
    const eventRule = new Rule(this, 'MyFunctionScheduleRule', {
      schedule: Schedule.cron({ minute: '15' }),
      targets: [new LambdaFunction(fn)],
    });
  }
}

Terraform

Este gerador cria um módulo Terraform para implantar sua função na pasta common/terraform. Você pode usar isso em uma configuração Terraform:

module "my_project_my_function" {
  source = "../../common/terraform/src/app/lambda-functions/my-project-my-function"

  # Variáveis de ambiente para a função Lambda
  env = {
    SOME_VARIABLE = "some value"
  }

  # Políticas IAM adicionais se necessário
  additional_iam_policy_statements = [
    # Adicione quaisquer permissões adicionais necessárias
  ]
}

Isso configura:

1. Função AWS Lambda
2. Grupo de logs do CloudWatch
3. Configuração de rastreamento do X-Ray
4. Namespace de métricas do CloudWatch

Esta função pode ser usada como destino para qualquer fonte de evento lambda. O exemplo abaixo demonstra o código Terraform para invocar sua função lambda em um agendamento usando o EventBridge:

# Regra do EventBridge para execução agendada
resource "aws_cloudwatch_event_rule" "my_function_schedule" {
  name                = "my-function-schedule"
  description         = "Aciona minha função a cada 15 minutos"
  schedule_expression = "cron(15 * * * ? *)"
}

# Target do EventBridge
resource "aws_cloudwatch_event_target" "lambda_target" {
  rule      = aws_cloudwatch_event_rule.my_function_schedule.name
  target_id = "MyFunctionTarget"
  arn       = module.my_project_my_function.function_arn
}

# Permissão para o EventBridge invocar a função Lambda
resource "aws_lambda_permission" "allow_eventbridge" {
  statement_id  = "AllowExecutionFromEventBridge"
  action        = "lambda:InvokeFunction"
  function_name = module.my_project_my_function.function_name
  principal     = "events.amazonaws.com"
  source_arn    = aws_cloudwatch_event_rule.my_function_schedule.arn
}

Nota

Certifique-se de que a fonte de evento corresponda à opção eventSource selecionada para garantir que o evento seja processado corretamente dentro de sua função handler.