@gpkit/aws-lambda

@gpkit/aws-lambda

Construye el handler de una función Lambda según el evento que la dispara: levanta la aplicación, normaliza el evento, valida las variables de entorno y conecta el trazado, las métricas y el logging de Powertools.

Cubre siete disparadores: API Gateway, SQS, S3, EventBridge, Step Functions, DynamoDB Streams y authorizer de API Gateway.

npm i @gpkit/core @gpkit/aws @gpkit/aws-lambda

Cada paquete se importa por su nombre. Este no reexporta a los otros dos, de modo que el package.json del proyecto declara lo que realmente usa.

---

Qué exporta cada subpath

Subpath	Qué contiene
/bootstrap	Las siete factories, LambdaHandlerFactory, createNestController y las interfaces de controller
/bootstrap/api-gw … /bootstrap/authorizer	Una sola factory por archivo
/middleware	Los siete parse*EventMiddleware, requireEnvVarsMiddleware y los tipos *Extracted y *HandlerEvent
/http	ApiGwHelper
/observability	appLogger, appMetrics, appTracer y las instancias powertools*

@nestjs/*, @middy/core y Powertools son dependencias del paquete. @aws-sdk/client-dynamodb y @aws-sdk/util-dynamodb son peers opcionales, necesarios solo para deserializar eventos de DynamoDB Streams.

Los clientes de los servicios de AWS están en @gpkit/aws.

---

Construir un handler

import { ApiGwHandlerFactory } from '@gpkit/aws-lambda/bootstrap/api-gw';

export const handler = new ApiGwHandlerFactory().build(AppModule, QuoteController, [
  'QUOTES_TABLE',
]);

build() recibe el módulo raíz del que se resuelve el controller, el controller que atiende el evento y las variables de entorno obligatorias. Devuelve el handler listo para exportar.

Se importa desde /bootstrap/<trigger> para una sola factory, o desde /bootstrap cuando se necesitan varias o los tipos de controller.

La aplicación se levanta en la primera invocación y se reutiliza en las siguientes.

---

El evento normalizado

Los middlewares dejan el evento ya interpretado en event.parsed, con una forma distinta según el origen:

event.parsed.body; // api-gw: el cuerpo ya deserializado
event.parsed.pathParameters; // api-gw
event.parsed.records; // sqs, s3, dynamo-stream: la lista de registros
event.parsed.detail; // eventbridge

Los registros de SQS y de DynamoDB Streams llevan recordId, que es lo que espera executeChunkedBatch de @gpkit/core. Los de DynamoDB Streams llegan ya deserializados en newImage.

requireEnvVarsMiddleware falla al inicio de la invocación si falta alguna de las variables declaradas en build(), nombrando cuál.

---

Respuestas HTTP

import { ApiGwHelper } from '@gpkit/aws-lambda/http';

return ApiGwHelper.success(200, quote);
return ApiGwHelper.error(error);

success envuelve el dato bajo data y admite un meta opcional. error conserva el código y el estado de un CustomException; cualquier otro fallo se reporta como error interno.

---

Observabilidad

build() registra appLogger como logger de la plataforma, de modo que HandleExecution, los clientes de @gpkit/aws y el código del proyecto escriben por Powertools con el formato definido en @gpkit/core. Contra LocalStack escribe por consola.

appMetrics publica métricas en formato EMF y appTracer registra los tramos de X-Ray. Las instancias powertoolsLogger, powertoolsMetrics y powertoolsTracer quedan expuestas para lo que estas no cubran.