# @gpkit/aws-lambda

> Factories de handler por trigger, middleware middy, helpers HTTP y observabilidad Powertools para Lambda + NestJS. Los clientes de AWS viven en @gpkit/aws.

Latest version **1.0.1** (published 2026-09-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install @gpkit/aws-lambda
pnpm add @gpkit/aws-lambda
yarn add @gpkit/aws-lambda
bun add @gpkit/aws-lambda
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2026-09-23 |
| First published | 2026-09-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 10 |
| Unpacked size | 84.9 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Maintainers | gpalacios |

## Links

- npm: https://www.npmjs.com/package/@gpkit/aws-lambda
- npm.io page: https://npm.io/package/@gpkit/aws-lambda

## Dependencies (10)

- [rxjs](https://npm.io/package/rxjs.md) ^7.8.0
- [@gpkit/aws](https://npm.io/package/@gpkit/aws.md) 1.1.0
- [@gpkit/core](https://npm.io/package/@gpkit/core.md) 1.0.0
- [@middy/core](https://npm.io/package/@middy/core.md) ^3.6.2
- [@nestjs/core](https://npm.io/package/@nestjs/core.md) ^10.4.0
- [@nestjs/common](https://npm.io/package/@nestjs/common.md) ^10.4.0
- [reflect-metadata](https://npm.io/package/reflect-metadata.md) ^0.2.2
- [@aws-lambda-powertools/logger](https://npm.io/package/@aws-lambda-powertools/logger.md) ^2.33.1
- [@aws-lambda-powertools/tracer](https://npm.io/package/@aws-lambda-powertools/tracer.md) ^2.33.1
- [@aws-lambda-powertools/metrics](https://npm.io/package/@aws-lambda-powertools/metrics.md) ^2.33.1

## Recent versions

- 1.0.1 (latest) — 2026-09-23
- 1.0.0 — 2026-09-17

## README

<p align="center">
  <a href="https://gustavopalacios.dev">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/gpalaciosvx3/gpalaciosvx3/master/assets/brand/logo-dark.svg">
      <img src="https://raw.githubusercontent.com/gpalaciosvx3/gpalaciosvx3/master/assets/brand/logo-light.svg" alt="Gustavo Palacios" height="64">
    </picture>
  </a>
</p>

<p align="center">
  <a href="https://gustavopalacios.dev"><img src="https://img.shields.io/badge/web-gustavopalacios.dev-17a267?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA2NCA2NCI%2BPGRlZnM%2BPG1hc2sgaWQ9Im0iPjxwYXRoIGQ9Ik0zMiAyIEw1OCAxNyBMNTggNDcgTDMyIDYyIEw2IDQ3IEw2IDE3IFoiIGZpbGw9IiNmZmYiLz48cGF0aCBkPSJNMjggMTQgTDE3LjUgNTAgTTI4IDE0IEw0Ni41IDUwIiBzdHJva2U9IiMwMDAiIHN0cm9rZS13aWR0aD0iNC44IiBzdHJva2UtbGluZWNhcD0icm91bmQiLz48Y2lyY2xlIGN4PSIyOCIgY3k9IjE0IiByPSI0LjYiIGZpbGw9IiMwMDAiLz48L21hc2s%2BPC9kZWZzPjxyZWN0IHdpZHRoPSI2NCIgaGVpZ2h0PSI2NCIgZmlsbD0id2hpdGUiIG1hc2s9InVybCgjbSkiLz48L3N2Zz4%3D" alt="Web"></a>
  <a href="https://www.npmjs.com/org/gpkit"><img src="https://img.shields.io/badge/npm-%40gpkit-CB3837?logo=npm&logoColor=white" alt="npm @gpkit"></a>
  <a href="https://www.linkedin.com/in/gustavopalaciosv"><img src="https://img.shields.io/badge/LinkedIn-gustavopalaciosv-0A66C2?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0yMC40NSAyMC40NWgtMy41NnYtNS41N2MwLTEuMzMtLjAzLTMuMDQtMS44NS0zLjA0LTEuODYgMC0yLjE0IDEuNDUtMi4xNCAyLjk0djUuNjdIOS4zNVY5aDMuNDF2MS41NmguMDVjLjQ4LS45IDEuNjQtMS44NSAzLjM3LTEuODUgMy42IDAgNC4yNyAyLjM3IDQuMjcgNS40NnY2LjI4ek01LjM0IDcuNDNhMi4wNiAyLjA2IDAgMSAxIDAtNC4xMyAyLjA2IDIuMDYgMCAwIDEgMCA0LjEzek03LjEyIDIwLjQ1SDMuNTZWOWgzLjU2djExLjQ1eiIvPjwvc3ZnPg%3D%3D" alt="LinkedIn"></a>
  <a href="https://github.com/gpalaciosvx3"><img src="https://img.shields.io/badge/GitHub-gpalaciosvx3-181717?logo=github&logoColor=white" alt="GitHub"></a>
</p>

# `@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.

```bash
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

```ts
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:

```ts
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

```ts
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.

---
_Source: https://npm.io/package/@gpkit/aws-lambda · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._