# DynamoDB-Toolbox: type-safe query building over the AWS DocumentClient

> DynamoDB-Toolbox is a TypeScript library that replaces UpdateExpression strings and ExpressionAttributeNames maps with validated, type-inferred method chains over the AWS DocumentClient. It has no runtime dependencies and requires Node.js 18 or newer.

**dynamodb-toolbox/dynamodb-toolbox** — Lightweight and type-safe query builder for DynamoDB and TypeScript

- Repository: https://github.com/dynamodb-toolbox/dynamodb-toolbox
- Website: https://www.dynamodbtoolbox.com/
- Stars: 2,001 · Forks: 187
- Language: TypeScript
- License: MIT
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/dynamodb-toolbox-dynamodb-toolbox

## What the raw DocumentClient demands on every update

Using the AWS DocumentClient directly means writing UpdateExpression strings, separate ExpressionAttributeNames maps and parallel ExpressionAttributeValues objects for each write. Those three structures must stay consistent with each other across every update, and none of them is checked by TypeScript against a schema.

The README makes the cost concrete with an example from the AWS documentation: updating two fields on a Music item. The raw UpdateCommand requires the expression string 'SET #Y = :y, #AT = :t', an ExpressionAttributeNames map where '#AT' aliases 'albumTitle' and '#Y' aliases 'year', and an ExpressionAttributeValues map for the actual values. A mismatched alias between the expression string and the names map passes TypeScript compilation and fails at DynamoDB.

DynamoDB-Toolbox replaces that structure with a method chain:

```ts
await MusicEntity.build(UpdateItemCommand)
  .item({
    artist: 'Acme Band',
    songTitle: 'Happy Day',
    albumTitle: 'Louder Than Ever',
    year: '2015'
  })
  .options({ returnValues: 'ALL_NEW' })
  .send()
```

The library generates the expression string, the aliased attribute names and the values from the entity schema. The caller passes a typed object, and DynamoDB-Toolbox handles the translation to the wire format. The README puts the reduction at 20 lines down to 10, though the actual gain depends on how many attributes the entity carries.

## Schema attributes carry defaults, composition, transformation and polymorphism

Schemas define each entity stored in DynamoDB, and the README identifies four capabilities the attribute system supports: defaults, composition, transformation and polymorphism.

Defaults supply a fallback value when a caller omits an attribute on a write. Composition allows attributes to nest inside each other, which maps to DynamoDB's own map and list attribute types. Transformation covers cases where the value the application works with differs from what the database stores, such as a structured object the library serialises before writing. Polymorphism handles entity types that share a table but carry differently shaped attribute sets.

Both directions of the DynamoDB boundary are covered. Items sent to DynamoDB are validated against the schema before the write, and items retrieved from DynamoDB are validated after the read. That two-way check means type guarantees hold at both boundaries, not only during development.

The attribute definition syntax is not in the README; the official documentation at dynamodbtoolbox.com carries it. The schema syntax is a central part of the API surface, so breaking changes to it carry upgrade cost for any project that relies on it.

## The npm package, Node.js 18 floor, and an ESM-only export path the README omits

The npm package is published under the name dynamodb-toolbox. The package.json engine field sets the minimum Node.js version to 18.0.0. The README gives no install command and links to the quickstart at dynamodbtoolbox.com/docs/getting-started/overview as the setup starting point.

One structural detail the README omits: the package.json sets the type field to module, and the main, module and types fields all resolve to dist/esm/index.js and dist/esm/index.d.ts. No CommonJS path appears in those fields. The repository root includes a tsconfig.cjs.json file, which indicates a CommonJS build exists in the development toolchain, but the package.json metadata exposes only the ESM output. Projects that use CommonJS require() need to verify that their bundler or module resolution handles ESM interop before adopting the library.

The package.json lists @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb as devDependencies rather than dependencies, consistent with the README claim that the library has no runtime dependencies. Your project supplies its own AWS SDK installation, and DynamoDB-Toolbox operates on top of it. v2.11.0 was released on 2026-09-15, following v2.10.7 on 2026-09-09 and v2.10.6 on 2026-08-19.

## Multiple entity types in one table, narrowed by schema at query time

Single-table design is a DynamoDB pattern where multiple entity types share one physical table, distinguished by their key structure. The README identifies this as an explicit goal: querying multiple entities within the same table should be simple. The library supports multi-table setups as well, and the README treats neither as a special case.

The practical gain is in what happens after a query returns. A broad query over a single-table design can return records of different entity types in one response. DynamoDB-Toolbox applies schema-level type information to the result set, so the caller receives typed records rather than raw attribute maps from the DocumentClient.

What happens when a query returns items whose shapes do not match any registered entity is not covered in the README. That gap matters for tables that accumulate record shapes from older application versions, and the official documentation is where that answer lives.

## LLRT compatibility and tree-shaking trace back to zero runtime dependencies

LLRT compatibility is listed in the README as a consequence of having no runtime dependencies. LLRT, the AWS Lambda runtime aimed at faster cold starts, requires packages with no native extensions and minimal overhead, and DynamoDB-Toolbox's zero-dependency design satisfies that constraint.

Tree-shaking reinforces the bundle-size story. The library is structured so that bundlers can exclude unused code paths from the output. A Lambda function that only calls PutItem does not carry the QueryCommand or UpdateItemCommand implementations in its bundle. The README names this property explicitly: 'Tree-shakable: Only import what you need.'

The package.json confirms the dependency claim at the file level. The AWS SDK packages appear only in devDependencies, not in the dependencies field. The published package carries no production runtime dependencies, which is what makes the LLRT claim credible.

## Importing from Zod and exporting to JSON Schema with type inference preserved

The portability feature lets a DynamoDB-Toolbox schema travel to and from two external formats: Zod and JSON Schema. According to the README, type inference is preserved in both directions.

Importing from Zod means an existing Zod schema can become the source for a DynamoDB-Toolbox entity definition without rewriting the type annotations. Exporting to JSON Schema produces a format that HTTP validators, API documentation generators and other tooling can consume without any knowledge of DynamoDB.

Which Zod features or JSON Schema keywords map across the boundary is not enumerated in the README. DynamoDB-Toolbox's own schema system includes transformation and polymorphism, which have no direct equivalent in standard JSON Schema. How those attribute types behave on an export round-trip is not covered; the documentation at dynamodbtoolbox.com is where that detail lives.

## Three layers DynamoDB-Toolbox does not reach

DynamoDB-Toolbox operates on top of the DocumentClient. It does not manage AWS credentials, provision DynamoDB tables, or define the global secondary indexes those tables carry. Those operations belong to infrastructure tools such as the AWS CLI, CloudFormation or CDK, and DynamoDB-Toolbox has no contact with that layer.

Schema migrations are outside the library's scope. Changing an entity schema updates the type definitions in application code but does not alter the physical table or back-fill existing records. The README references a related product, DynamoDB-Toolshack, which provides a schema-aware UI, table consistency checks and a migration system. DynamoDB-Toolshack is a paid SaaS available through the AWS Marketplace and is separate from the open-source library. The two are not bundled together.

DynamoDB Streams and cross-region replication handling are also absent. The README's feature list, the package.json keywords and the repository topics give no indication that stream consumer utilities or replication tools are part of the library.

## Conclusion

DynamoDB-Toolbox pays off when your TypeScript project already uses DynamoDB and the UpdateExpression scaffolding is the real maintenance burden. It handles the attribute aliasing and type checking at compile time while validating writes and reads against your schema. Avoid it when your project uses CommonJS require() without ESM interop support; the package.json sets the type field to module and lists only ESM paths in its main and module fields. It also provides no migration path when schemas change; that is handled by the separate DynamoDB-Toolshack product. Before adopting, verify Node.js 18.0.0 or higher and read the attribute API at dynamodbtoolbox.com, since the README does not cover it.

## FAQ

### What is DynamoDB-Toolbox?

DynamoDB-Toolbox is a TypeScript library that wraps the AWS DocumentClient to replace UpdateExpression strings and ExpressionAttributeNames maps with validated, type-safe method chains. It supports single-table designs, has no runtime dependencies and requires Node.js 18 or newer.

### How do I install DynamoDB-Toolbox?

The npm package name is dynamodb-toolbox and it requires Node.js 18.0.0 or newer. The README gives no install command and links to the official documentation at dynamodbtoolbox.com/docs/getting-started/overview for setup steps.

### Does DynamoDB-Toolbox support single-table design?

The README identifies this as an explicit goal and calls querying multiple entities within the same table extremely simple. The library also works with multi-table setups.

### Can DynamoDB-Toolbox schemas be exported to Zod or JSON Schema?

According to the README, schemas can be imported from and exported to both Zod and JSON Schema, with type inference preserved in both directions.

### What Node.js version does DynamoDB-Toolbox require?

The package.json engine field specifies Node.js 18.0.0 as the minimum version.

## Sources

- [dynamodb-toolbox/dynamodb-toolbox on GitHub](https://github.com/dynamodb-toolbox/dynamodb-toolbox)
- [License: MIT](https://github.com/dynamodb-toolbox/dynamodb-toolbox/blob/main/LICENSE)
- [Project website](https://www.dynamodbtoolbox.com/)
- [README](https://github.com/dynamodb-toolbox/dynamodb-toolbox/blob/main/README.md)
- [Releases](https://github.com/dynamodb-toolbox/dynamodb-toolbox/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dynamodb-toolbox-dynamodb-toolbox