Función Lambda de TypeScript

El generador de Función Lambda de TypeScript proporciona la capacidad de agregar una función lambda a un proyecto TypeScript existente.

Este generador crea un nuevo manejador lambda de TypeScript con configuración de infraestructura AWS CDK o Terraform. El manejador generado utiliza AWS Lambda Powertools for TypeScript para observabilidad, incluyendo registro, rastreo de AWS X-Ray y métricas de CloudWatch, así como seguridad de tipos opcional para el evento usando el Parser de AWS Lambda Powertools

Uso

Generar una función lambda de TypeScript

Puedes generar una función lambda de dos maneras:

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

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

Opciones

Parámetro	Tipo	Predeterminado	Descripción
project Requerido	string	-	El proyecto al que agregar la función lambda
name Requerido	string	-	El nombre de la función a agregar
functionPath	string	-	Subdirectorio opcional dentro del directorio fuente del proyecto para agregar la función
event	Any | AlbSchema | APIGatewayProxyEventSchema | APIGatewayRequestAuthorizerEventSchema | APIGatewayTokenAuthorizerEventSchema | APIGatewayProxyEventV2Schema | APIGatewayProxyWebsocketEventSchema | APIGatewayRequestAuthorizerEventV2Schema | CloudFormationCustomResourceCreateSchema | CloudFormationCustomResourceUpdateSchema | CloudFormationCustomResourceDeleteSchema | CloudWatchLogsSchema | PreSignupTriggerSchema | PostConfirmationTriggerSchema | CustomMessageTriggerSchema | MigrateUserTriggerSchema | CustomSMSSenderTriggerSchema | CustomEmailSenderTriggerSchema | DefineAuthChallengeTriggerSchema | CreateAuthChallengeTriggerSchema | VerifyAuthChallengeTriggerSchema | PreTokenGenerationTriggerSchemaV1 | PreTokenGenerationTriggerSchemaV2AndV3 | DynamoDBStreamSchema | EventBridgeSchema | KafkaMskEventSchema | KafkaSelfManagedEventSchema | KinesisDataStreamSchema | KinesisFirehoseSchema | KinesisDynamoDBStreamSchema | KinesisFirehoseSqsSchema | LambdaFunctionUrlSchema | S3EventNotificationEventBridgeSchema | S3Schema | S3ObjectLambdaEventSchema | S3SqsEventNotificationSchema | SesSchema | SnsSchema | SqsSchema | TransferFamilySchema | VpcLatticeSchema | VpcLatticeV2Schema	Any	Esquema de origen de evento opcional para usar en la función lambda
infra	lambda | none	lambda	El tipo de infraestructura con la que desplegar tu función Lambda.
iac	inherit | cdk | terraform	inherit	El proveedor de IaC preferido. Por defecto, se hereda de tu selección inicial.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establece en false para diferir la instalación cuando se ejecutan múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instala una vez al final.

Salida del Generador

El generador agregará los siguientes archivos a tu proyecto:

• Directorio<project-name>

  • Directoriosrc/

    • <lambda-function>.ts Function implementation

Si se proporciona la opción functionPath, el generador agregará el manejador a la ruta especificada dentro del directorio de origen del proyecto:

• Directorio<project-name>

  • Directoriosrc/

    • Directorio<custom-path>/

      • <function-name>.ts Function implementation

Infraestructura

Dado que este generador proporciona infraestructura como código basada en tu iac elegido, creará un proyecto en packages/common que incluye las construcciones CDK o módulos Terraform relevantes.

El proyecto común de infraestructura como código está estructurado de la siguiente manera:

CDK

• Directoriopackages/common/constructs

  • Directoriosrc

    • Directorioapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Directoriocore/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Proyecto Generado

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

Terraform

• Directoriopackages/common/terraform

  • Directoriosrc

    • Directorioapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Directoriocore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Proyecto Generado

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

El generador crea infraestructura como código para desplegar tu función basándose en tu iac seleccionado:

CDK

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

Terraform

El generador crea un módulo Terraform que puede usarse para desplegar tu función, el cual reside en el directorio packages/common/terraform/src/app/lambda-functions/<function-name>.

Arquitectura

La función desplegada tiene la siguiente arquitectura:

El generador proporciona la función en sí; usted conecta la fuente de eventos en su stack para invocarla (por ejemplo, una integración de API Gateway, una regla de EventBridge, una notificación de S3 o un mapeo de fuente de eventos de SQS).

Implementando tu Función

La implementación principal de la función está en <function-name>.ts. Aquí hay 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 varias características automáticamente:

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

Observabilidad con AWS Lambda Powertools

Registro

El generador configura el registro estructurado usando AWS Lambda Powertools con inyección automática de contexto a través del middleware Middy.

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

Rastreo

El rastreo de AWS X-Ray se configura automáticamente a través del middleware captureLambdaHandler. Puedes agregar subsegmentos personalizados a tus rastros:

const tracer = new Tracer();

export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  // Creates a new subsegment
  const subsegment = tracer.getSegment()?.addNewSubsegment('custom-operation');
  try {
    // Your logic here
  } 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 recopilan automáticamente para cada solicitud a través del middleware logMetrics. Puedes agregar 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

event ≠ Any

Si elegiste un event al generar tu función lambda, tu función está instrumentada con el middleware parser de AWS Lambda Powertools. Por ejemplo:

export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  event.detail // <- type-safe with IDE autocompletion
};

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

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

Manejo de Errores

Si no quieres que tu manejador lance un error cuando el evento no se ajusta al esquema, puedes usar la opción safeParse.

Datos de Evento Personalizados

Si tienes datos personalizados anidados dentro de un evento, por ejemplo un stream de DynamoDB o un evento de EventBridge, puedes beneficiarte del uso de Envelopes para proporcionar seguridad de tipos para esos datos personalizados.

event = Any

Si seleccionaste Any para tu event, el middleware parser no está conectado y el parámetro event está tipado como any. Regenera la función con un event específico si deseas seguridad de tipos en tiempo de compilación y validación en tiempo de ejecución.

Empaquetado

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

pnpm

pnpm nx bundle <project-name>

yarn

yarn nx bundle <project-name>

npm

npx nx bundle <project-name>

bun

bunx nx bundle <project-name>

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.

Configuración Personalizada

Puedes ajustar la configuración de Rolldown en rolldown.config.ts, por ejemplo, si tienes dependencias que dependen de rutas de archivos y no pueden ser empaquetadas, puedes agregarlas a la lista de módulos external.

Desplegando tu Función

Este generador crea infraestructura como código CDK o Terraform basada en tu iac seleccionado. Puedes usar esto para desplegar tu función.

CDK

Este generador crea un construct CDK para desplegar tu función en la carpeta common/constructs. Puedes usar esto en una aplicación CDK:

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Add the function to your stack
    const fn = new MyProjectMyFunction(this, 'MyFunction');
  }
}

Esto configura:

1. Función AWS Lambda
2. Grupo de logs de CloudWatch
3. Configuración de rastreo X-Ray
4. Espacio de nombres de métricas de CloudWatch

Esta función puede entonces ser usada como objetivo para cualquier fuente de eventos de lambda:

Coincidencia de Fuente de Eventos

Asegúrate de que la fuente de eventos coincida con la opción event seleccionada para garantizar que el evento se maneje correctamente dentro de tu función handler.

El ejemplo a continuación demuestra el código CDK para invocar tu función lambda en un horario 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) {
    // Add the function to your stack
    const fn = new MyProjectMyFunction(this, 'MyFunction');

    // Add the function to an EventBridge scheduled rule
    const eventRule = new Rule(this, 'MyFunctionScheduleRule', {
      schedule: Schedule.cron({ minute: '15' }),
      targets: [new LambdaFunction(fn)],
    });
  }
}

Terraform

Este generador crea un módulo Terraform para desplegar tu función en la carpeta common/terraform. Instancia el módulo compartido core/asset-bucket una vez por despliegue y pasa su bucket_name en la entrada asset_bucket_name:

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

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

  asset_bucket_name = module.asset_bucket.bucket_name

  env = {
    SOME_VARIABLE = "some value"
  }

  additional_iam_policy_statements = [
    # Add any additional permissions your function needs
  ]
}

Esto configura:

1. Función AWS Lambda
2. Grupo de logs de CloudWatch
3. Configuración de rastreo X-Ray
4. Espacio de nombres de métricas de CloudWatch

Esta función puede entonces ser usada como objetivo para cualquier fuente de eventos de lambda. El ejemplo a continuación demuestra el código Terraform para invocar tu función lambda en un horario usando EventBridge:

# EventBridge rule for scheduled execution
resource "aws_cloudwatch_event_rule" "my_function_schedule" {
  name                = "my-function-schedule"
  description         = "Trigger my function every 15 minutes"
  schedule_expression = "cron(15 * * * ? *)"
}

# EventBridge target
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
}

# Permission for EventBridge to invoke the Lambda function
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
}

Coincidencia de Fuente de Eventos

Asegúrate de que la fuente de eventos coincida con la opción event seleccionada para garantizar que el evento se maneje correctamente dentro de tu función handler.