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
• Key and field design — how to choose partition / sort keys, when to reach for LSI vs GSI, and which technical fields actually earn their bytes
• 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 — buildSearch, 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

Framework adapters

Framework-specific bindings ship as separate packages. Each one is a thin wrapper that translates its framework's request/response shape into the toolkit's REST core parsers + standard route pack. The wire contract (routes, query parameters, envelope keys, error mapping) is identical across all of them.

• dynamodb-toolkit-koa — Koa 2.x middleware. GitHub · wiki
• dynamodb-toolkit-express — Express 4.x / 5.x middleware / Router. GitHub · wiki
• dynamodb-toolkit-fetch — (Request) => Promise<Response> for Cloudflare Workers, Deno Deploy, Bun.serve, Hono, and Node's native fetch server. GitHub · wiki
• dynamodb-toolkit-lambda — AWS Lambda handler for API Gateway REST + HTTP, Function URL, and ALB; ships local-debug bridges for running the handler on real HTTP. GitHub · wiki

Recipes

Pattern-first pages for common DynamoDB problems that feel trivial in SQL but need non-obvious index shapes here. See Recipes for the full grouped index (by problem domain).

• Recipe: List records of a tier — "all states globally" via a single sparse GSI on the auto-populated typeField. Simplest cross-partition tier listing.
• Recipe: Per-tier sparse GSI markers — one GSI per tier with per-tier marker attributes. Finer control over projection + writes; sharded-marker variant for leaf-tier scale.
• Recipe: List records of a tier within a partition — sparse LSI. Cheaper than a GSI when the listing is always within a known partition.
• Recipe: Reservation with auto-release — short-lived holds (rental car, meeting room, flash-sale item) that release automatically if the caller goes silent. Composes versionField (optimistic concurrency) + createdAtField + asOf (scope-freeze) + deleteListByParams (resumable sweep).
• Recipe: Keys-only GSI with runtime projection — declare a GSI with projection: 'keys-only' + indirect: true; reads Query the GSI for keys, then BatchGetItem the base table with the caller's per-call fields. Cheap GSI storage, rich runtime projections.
• Recipe: Cascade subtree operations — deleteAllUnder / cloneAllUnder[By] / moveAllUnder[By] against composite keyFields with relationships: {structural: true}. Resumable leaf-first / root-first pagination, constructive-before-destructive moves, MassOpResult partial-failure surfacing.
• Recipe: Querying subtrees with buildKey — hierarchical subtree queries via adapter.buildKey(values, options). Three shapes: children-only (default), self + descendants ({self: true}), narrow-prefix ({partial: 'Dal'}). Plus the getListUnder sugar and composition with mass ops.

History

• Release notes — what shipped in each version