Fonction Lambda TypeScript

Le générateur de fonction Lambda TypeScript permet d’ajouter une fonction lambda à un projet TypeScript existant.

Ce générateur crée un nouveau gestionnaire lambda TypeScript avec une configuration d’infrastructure AWS CDK. Le gestionnaire généré utilise AWS Lambda Powertools for TypeScript pour l’observabilité, incluant le logging, le tracing AWS X-Ray et les métriques CloudWatch, ainsi qu’une validation optionnelle des événements via le Parser d’AWS Lambda Powertools.

Utilisation

Générer une fonction lambda TypeScript

Vous pouvez générer une fonction lambda de deux manières :

VSCode

1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - ts#lambda-function
5. Remplissez les paramètres requis
6. Cliquez sur 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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

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

Options

Paramètre	Type	Par défaut	Description
project Requis	string	-	The project to add the lambda function to
functionName Requis	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

Sortie du générateur

Le générateur ajoutera les fichiers suivants à votre projet :

• Répertoire<project-name>

  • Répertoiresrc/

    • <lambda-function>.ts Implémentation de la fonction

Le générateur créera également un construct CDK utilisable pour déployer votre fonction, situé dans le répertoire packages/common/constructs/src/app/lambda-functions.

Si l’option functionPath est spécifiée, le générateur ajoutera le gestionnaire au chemin indiqué dans le répertoire source du projet :

• Répertoire<project-name>

  • Répertoiresrc/

    • Répertoire<custom-path>/

      • <function-name>.ts Implémentation de la fonction

Implémentation de votre fonction

L’implémentation principale de la fonction se trouve dans <function-name>.ts. Voici un exemple :

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

Le générateur configure automatiquement plusieurs fonctionnalités :

1. Stack middleware Middy pour des fonctionnalités Lambda étendues
2. Intégration AWS Lambda Powertools pour l’observabilité
3. Collecte de métriques avec CloudWatch
4. Validation de type via le middleware parser
5. Bundling avec esbuild pour des packages de déploiement optimisés

Observabilité avec AWS Lambda Powertools

Journalisation

Le générateur configure le logging structuré avec AWS Lambda Powertools et l’injection automatique de contexte via le middleware Middy.

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

Traçage

Le tracing AWS X-Ray est configuré automatiquement via le middleware captureLambdaHandler. Vous pouvez ajouter des sous-segments personnalisés :

const tracer = new Tracer();

export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  // Crée un nouveau sous-segment
  const subsegment = tracer.getSegment()?.addNewSubsegment('custom-operation');
  try {
    // Votre logique ici
  } catch (error) {
    subsegment?.addError(error as Error);
    throw error;
  } finally {
    subsegment?.close();
  }
};

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

Métriques

Les métriques CloudWatch sont collectées automatiquement via le middleware logMetrics. Vous pouvez ajouter des métriques personnalisées :

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

Validation de type

Si vous avez choisi un eventSource lors de la génération, votre fonction est instrumentée avec le middleware parser d’AWS Lambda Powertools. Exemple :

export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  event.detail // <- typage fort avec autocomplétion IDE
};

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

Cela fournit un typage à la compilation et une validation à l’exécution pour les événements Lambda.

Attention

Si vous ne souhaitez pas que votre handler lance une erreur lorsque l’événement ne correspond pas au schéma, utilisez l’option safeParse.

Astuce

Pour des données personnalisées imbriquées (ex: flux DynamoDB ou événement EventBridge), utilisez les Envelopes pour un typage fort.

Si vous ne souhaitez pas typer votre événement, sélectionnez Any pour eventSource, ce qui donnera un type any au paramètre event.

Bundling

Le générateur configure automatiquement esbuild pour des packages de déploiement optimisés :

Bundlez une fonction spécifique avec :

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>

Bundlez toutes les fonctions du projet avec :

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

Déploiement de votre fonction

Le générateur crée un construct CDK pour le déploiement dans le dossier common/constructs. Utilisez-le dans une application CDK :

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Ajoute la fonction à votre stack
    const fn = new MyProjectMyFunction(this, 'MyFunction');
  }
}

Ceci configure :

1. Une fonction AWS Lambda
2. Un groupe de logs CloudWatch
3. La configuration du tracing X-Ray
4. Un namespace de métriques CloudWatch

Cette fonction peut ensuite être utilisée comme cible pour toute source d’événement Lambda :

Note

Assurez-vous que la source d’événement correspond à l’option eventSource choisie pour garantir un traitement correct dans votre handler.

L’exemple suivant montre comment invoquer votre fonction selon un planning via 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) {
    // Ajoute la fonction à votre stack
    const fn = new MyProjectMyFunction(this, 'MyFunction');

    // Ajoute la fonction à une règle planifiée EventBridge
    const eventRule = new Rule(this, 'MyFunctionScheduleRule', {
      schedule: Schedule.cron({ minute: '15' }),
      targets: [new LambdaFunction(fn)],
    });
  }
}