Função Lambda em TypeScript

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

Este gerador cria um novo handler Lambda TypeScript com configuração de infraestrutura AWS CDK. O handler gerado utiliza AWS Lambda Powertools for TypeScript para observabilidade, incluindo logging, rastreamento AWS X-Ray e métricas 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

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

O gerador também criará um construct CDK para implantação da função, localizado no diretório packages/common/constructs/src/app/lambda-functions.

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

• Directory<project-name>

  • Directorysrc/

    • Directory<custom-path>/

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

Implementando sua Função

A implementação principal da função está em <function-name>.ts. Veja 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. Stack 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. Bundling com esbuild 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 AWS X-Ray é configurado automaticamente através do middleware captureLambdaHandler. Você pode adicionar subsegmentos personalizados:

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 CloudWatch são coletadas automaticamente a 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, o handler será instrumentado com o middleware parser do AWS Lambda Powertools. Exemplo:

export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  event.detail // <- tipo seguro com autocompletar da 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 não quiser que seu handler lance erro quando o evento não conformar com o schema, use a opção safeParse.

Dica

Para dados personalizados aninhados em eventos (ex: streams DynamoDB ou eventos EventBridge), você pode usar Envelopes para garantir segurança de tipos.

Se não desejar tipar seu evento, selecione Any como eventSource, resultando no tipo any para o parâmetro do evento.

Bundling

O gerador configura automaticamente esbuild para pacotes de implantação otimizados:

Faça bundling de uma função específica com:

pnpm

pnpm nx run <project-name>:bundle-<function-name>

yarn

yarn nx run <project-name>:bundle-<function-name>

npm

npx nx run <project-name>:bundle-<function-name>

bun

bunx nx run <project-name>:bundle-<function-name>

Faça bundling de todas as funções do projeto com:

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

Implantando sua Função

O gerador cria um construct CDK para implantação no diretório common/constructs. Use em uma aplicação CDK:

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

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

Isso configura:

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

Esta função pode ser usada como alvo para qualquer event source Lambda:

Nota

Garanta que o event source corresponda à opção eventSource selecionada para tratamento adequado do evento.

O exemplo abaixo demonstra código CDK para invocar sua função em um agendamento usando 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) {
    // Adicione a função à stack
    const fn = new MyProjectMyFunction(this, 'MyFunction');

    // Configure uma regra de agendamento
    const eventRule = new Rule(this, 'MyFunctionScheduleRule', {
      schedule: Schedule.cron({ minute: '15' }),
      targets: [new LambdaFunction(fn)],
    });
  }
}