Home

dynamodb-toolkit (v3)

Opinionated zero-runtime-dependency micro-library for AWS DynamoDB. Built on the AWS JS SDK v3 (@aws-sdk/client-dynamodb + @aws-sdk/lib-dynamodb). ESM-only, hand-written .d.ts sidecars, no build step. Tested on Node, Deno, and Bun — usable from TypeScript and CommonJS consumers alike.

v2 documentation lives at the v2.3-docs git tag of this wiki repo. v2 source remains available on npm as dynamodb-toolkit@2.3.0.

"Toolkit", not "framework"

The pieces are independent. You don't need to adopt the Adapter to use the expression builders, and you don't need the builders to use the batch chunkers. Every layer has a public surface and is consumable on its own:

• Use buildUpdate / buildCondition to prep a params object, then send it with the raw SDK UpdateCommand — no Adapter in sight.
• Hand-build your own params and pass them to applyBatch / applyTransaction for chunking, UnprocessedItems retry, and exponential backoff.
• Use the Adapter for CRUD + hooks but swap in your own @aws-sdk/lib-dynamodb Command invocation anywhere you want raw control.
• Take the REST handler or leave it — the Adapter works standalone.

Two concrete payoffs: migration (adopt one piece at a time starting from raw-SDK code) and debugging (peel layers back one at a time when something looks off). The boundary between caller code and toolkit machinery stays explicit.

Start here

• Getting started
• Concepts — vocabulary + the additive-params-mutation model every builder uses
• Compatibility — TypeScript, CommonJS, and Node / Deno / Bun runtime support
• Migration: v2 to v3
• SDK v2 to v3 cheat sheet

Adapter

• Adapter — overview
• Adapter: Constructor options
• Adapter: CRUD methods
• Adapter: Mass methods
• Adapter: Batch builders
• Adapter: Hooks
• Adapter: Raw marker
• Adapter: Indirect indices
• Adapter: Transaction auto-upgrade

Expression builders (dynamodb-toolkit/expressions)

• Expressions: Update builder — buildUpdate, patch + array ops
• Expressions: Filter builder — buildFilter, buildFilterByExample
• Expressions: Condition builder — buildCondition
• Expressions: Projection builder — addProjection

Batch / transactions / mass / paths

• Batch and transactions — applyBatch, applyTransaction, getBatch, getTransaction
• Mass operations — paginateList, iterateList, read*, write*, delete*, copy*, move*
• Paths — getPath, setPath, applyPatch, subsetObject, normalizeFields

REST surface

• REST core — parsers, builders, policy (framework-agnostic)
• HTTP handler — node:http (req, res) handler with the standard route pack