Skip to content

Home

Jump to bottom
Eugene Lazutkin edited this page Apr 20, 2026 · 2 revisions

dynamodb-toolkit-lambda

NPM version

AWS Lambda adapter for dynamodb-toolkit v3. A single factory that turns the toolkit's standard REST route pack into a Lambda (event, context) => Promise<result> handler — same wire contract as the bundled node:http handler, translated for Lambda's event-in / plain-object-out shape.

One handler serves four event shapes — API Gateway REST (payload 1.0), API Gateway HTTP (payload 2.0), Lambda Function URLs (payload 2.0), and Application Load Balancer (single- or multi-value-headers mode). The adapter auto-detects the shape on each invocation and returns the matching result envelope.

Zero runtime dependencies. No framework peer dep — AWS Lambda's Node runtime is the target. ESM with hand-written .d.ts sidecars. Tested on Node / Bun / Deno (the last two via the local-debug bridge).

Start here

  • Getting started — install + first deploy, one example per event shape
  • Routes — the full standard route pack, one table per route
  • Options — LambdaAdapterOptions reference (policy, mountPath, keyFromPath, exampleFromContext, maxBodyBytes, sortableIndices)
  • Event shapes — how v1 / v2 / Function URL / ALB are detected, cookies, multi-value headers, reconstruction of the original URL
  • Body reading — string body, base64 handling, size cap, errors
  • Error handling — status-code mapping, custom error bodies, 405 / 413 / 400
  • Composite keys — partition + sort key tables, per-tenant keying, IAM-derived scoping
  • Local debug bridges — run the exact Lambda handler on localhost via node:http or any Fetch runtime (Bun, Deno, Workers); Koa / Express bridging recipes
  • Compatibility — Lambda runtimes, Node floor, CJS, TypeScript, cross-runtime test matrix

Why a separate package?

The parent toolkit ships a framework-agnostic REST core (dynamodb-toolkit/rest-core) and a bundled node:http adapter (dynamodb-toolkit/handler). Platform-specific adapters live in their own packages so the core stays free of platform dependencies and each adapter can evolve independently.

This adapter is thin on purpose: it's a translation layer from Lambda event / result envelopes into the toolkit's parsers + matchers + Adapter. Parsing, envelope building, policy, and route-shape recognition all live in dynamodb-toolkit itself. If you already know the REST-core contract and the HTTP handler's route pack, you already know this adapter's wire behavior — the options surface mirrors HandlerOptions almost one-for-one, with mountPath added and the exampleFromContext signature extended with the Lambda event and context arguments.

How it fits with the parent toolkit

This adapter stands on these parent pieces:

Install

npm install dynamodb-toolkit-lambda dynamodb-toolkit @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

dynamodb-toolkit is a peer dependency. No framework peer — AWS Lambda's Node 20+ runtime is the target.

30-second example

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
import {DynamoDBDocumentClient} from '@aws-sdk/lib-dynamodb';
import {Adapter} from 'dynamodb-toolkit';
import {createLambdaAdapter} from 'dynamodb-toolkit-lambda';

const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({region: process.env.AWS_REGION}));
const planets = new Adapter({client: ddb, table: 'planets', keyFields: ['name']});

export const handler = createLambdaAdapter(planets, {mountPath: '/planets'});

One Lambda, one wire contract — works behind API Gateway REST, API Gateway HTTP, a Function URL, or an ALB target. See Getting started for a guided walkthrough and Event shapes for how the auto-detection works.

Local development

import http from 'node:http';
import {createLambdaAdapter} from 'dynamodb-toolkit-lambda';
import {createNodeListener} from 'dynamodb-toolkit-lambda/local.js';

const handler = createLambdaAdapter(planets, {mountPath: '/planets'});
http.createServer(createNodeListener(handler)).listen(3000);
// curl http://localhost:3000/planets

The exact Lambda handler, driven by real HTTP, on your laptop — no deploy cycle, no sam-local, no Docker. See Local debug bridges for Bun / Deno / Cloudflare Workers variants and Koa / Express bridging.

Source

Clone this wiki locally