Función Lambda de TypeScript

El generador de funciones Lambda en TypeScript permite añadir una función lambda a un proyecto existente de TypeScript.

Este generador crea un nuevo manejador Lambda en TypeScript con configuración de infraestructura usando AWS CDK o Terraform. El manejador generado utiliza AWS Lambda Powertools for TypeScript para observabilidad, incluyendo registro, trazado con AWS X-Ray y métricas de CloudWatch, además de seguridad de tipos opcional para eventos usando el Parser de AWS Lambda Powertools

Uso

Generar una función Lambda en TypeScript

Puedes generar una función lambda de dos formas:

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#lambda-function
5. Complete los parámetros requeridos
6. Haga clic en 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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

Opciones

Parámetro	Tipo	Predeterminado	Descripción
project Requerido	string	-	The project to add the lambda function to
functionName Requerido	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.

Resultado del generador

El generador añadirá los siguientes archivos a tu proyecto:

• Directory<project-name>

  • Directorysrc/

    • <lambda-function>.ts Implementación de la función

Si se proporciona la opción functionPath, el generador añadirá el manejador en la ruta especificada dentro del directorio fuente del proyecto:

• Directory<project-name>

  • Directorysrc/

    • Directory<custom-path>/

      • <function-name>.ts Implementación de la función

Infraestructura

Dado que este generador proporciona infraestructura como código basada en tu proveedor de iacProvider seleccionado, creará un proyecto en packages/common que incluye los constructos CDK o módulos de Terraform correspondientes.

El proyecto común de infraestructura como código tiene la siguiente estructura:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructos para infraestructura específica de un proyecto/generador

      • …
    • Directorycore/ Constructos genéricos reutilizados por los constructos en app

      • …
    • index.ts Punto de entrada que exporta los constructos de app
  • project.json Objetivos de compilación y configuración del proyecto

Nota

Este proyecto se genera utilizando el ts#project generator y por lo tanto configura los mismos objetivos de compilación.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Módulos de Terraform para infraestructura específica de un proyecto/generador

      • …
    • Directorycore/ Módulos genéricos reutilizados por los módulos en app

      • …
  • project.json Objetivos de compilación y configuración del proyecto

Nota

Este proyecto se genera utilizando el terraform#project generator y por lo tanto configura los mismos objetivos de compilación.

El generador crea infraestructura como código para desplegar tu función según el iacProvider seleccionado:

CDK

El generador crea un constructo CDK para desplegar tu función, ubicado en el directorio packages/common/constructs/src/app/lambda-functions.

Terraform

El generador crea un módulo de Terraform para desplegar tu función, ubicado en packages/common/terraform/src/app/lambda-functions/<function-name>.

Implementando tu función

La implementación principal está en <function-name>.ts. Aquí un ejemplo:

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

El generador configura automáticamente varias características:

1. Pila de middleware Middy para funcionalidad extendida de Lambda
2. Integración con AWS Lambda Powertools para observabilidad
3. Recolección de métricas con CloudWatch
4. Seguridad de tipos usando middleware de análisis
5. Empaquetado con Rolldown para paquetes de despliegue optimizados

Observabilidad con AWS Lambda Powertools

Registro (Logging)

El generador configura registro estructurado usando AWS Lambda Powertools con inyección automática de contexto vía middleware Middy.

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

Trazado (Tracing)

El trazado con AWS X-Ray se configura automáticamente mediante el middleware captureLambdaHandler. Puedes añadir subsegmentos personalizados:

const tracer = new Tracer();

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

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

Métricas

Las métricas de CloudWatch se recolectan automáticamente por cada solicitud mediante el middleware logMetrics. Puedes añadir 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);

Seguridad de tipos

Si seleccionaste un eventSource al generar tu función Lambda, esta se instrumenta con el middleware parser de AWS Lambda Powertools. Por ejemplo:

export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  event.detail // <- tipo seguro con autocompletado en IDE
};

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

Esto provee seguridad de tipos en tiempo de compilación y validación en tiempo de ejecución para los eventos Lambda.

Precaución

Si no deseas que tu manejador lance un error cuando el evento no cumple con el esquema, puedes usar la opción safeParse.

Consejo

Si tienes datos personalizados anidados en un evento, como un stream de DynamoDB o evento de EventBridge, puedes beneficiarte usando Envelopes para proveer seguridad de tipos a esos datos.

Si no deseas tipar tu evento, puedes seleccionar Any para eventSource, lo que resultará en un tipo any para el parámetro del evento.

Empaquetado

El generador configura automáticamente un objetivo bundle que utiliza Rolldown para crear un paquete de despliegue:

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

La configuración de Rolldown se encuentra en rolldown.config.ts, con una entrada por cada bundle a generar. Rolldown gestiona la creación de múltiples bundles en paralelo si están definidos.

Consejo

Puedes ajustar la configuración de Rolldown en rolldown.config.ts, por ejemplo si tienes dependencias que requieren rutas de archivo específicas y no pueden incluirse en el bundle, puedes agregarlas a la lista de módulos external.

Desplegando tu función

Este generador crea infraestructura como código de CDK o Terraform según el iacProvider seleccionado. Puedes usarlo para implementar tu función.

CDK

Este generador crea un constructo de CDK para implementar tu función en la carpeta common/constructs. Puedes usarlo en una aplicación de CDK:

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Agrega la función a tu stack
    const fn = new MyProjectMyFunction(this, 'MyFunction');
  }
}

Esto configura:

1. Función AWS Lambda
2. Grupo de logs de CloudWatch
3. Configuración de trazado X-Ray
4. Namespace de métricas en CloudWatch

Esta función puede usarse como destino para cualquier origen de eventos de Lambda:

Nota

Asegúrate de que el origen del evento coincida con la opción eventSource seleccionada para garantizar un manejo adecuado del evento dentro de tu función handler.

El siguiente ejemplo muestra el código CDK para invocar tu función Lambda en un horario programado 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) {
    // Agrega la función a tu stack
    const fn = new MyProjectMyFunction(this, 'MyFunction');

    // Agrega la función a una regla programada de EventBridge
    const eventRule = new Rule(this, 'MyFunctionScheduleRule', {
      schedule: Schedule.cron({ minute: '15' }),
      targets: [new LambdaFunction(fn)],
    });
  }
}

Terraform

Este generador crea un módulo de Terraform para implementar tu función en la carpeta common/terraform. Puedes usarlo en una configuración de Terraform:

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

  # Variables de entorno para la función Lambda
  env = {
    SOME_VARIABLE = "some value"
  }

  # Políticas IAM adicionales si son necesarias
  additional_iam_policy_statements = [
    # Agrega los permisos adicionales que requiera tu función
  ]
}

Esto configura:

1. Función AWS Lambda
2. Grupo de logs de CloudWatch
3. Configuración de trazado X-Ray
4. Namespace de métricas en CloudWatch

Esta función puede usarse como destino para cualquier origen de eventos de Lambda. El siguiente ejemplo muestra el código Terraform para invocar tu función Lambda en un horario programado usando EventBridge:

# Regla de EventBridge para ejecución programada
resource "aws_cloudwatch_event_rule" "my_function_schedule" {
  name                = "my-function-schedule"
  description         = "Ejecuta mi función cada 15 minutos"
  schedule_expression = "cron(15 * * * ? *)"
}

# Target de 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
}

# Permiso para que EventBridge invoque la función 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

Asegúrate de que el origen del evento coincida con la opción eventSource seleccionada para garantizar un manejo adecuado del evento dentro de tu función handler.