- DynamoDB-Toolbox v2 Patterns (TypeScript)
- Overview
- This skill provides practical TypeScript patterns for using DynamoDB-Toolbox v2 with AWS SDK v3 DocumentClient. It focuses on type-safe schema modeling,
- .build()
- command usage, and production-ready single-table design.
- When to Use
- Defining DynamoDB tables and entities with strict TypeScript inference
- Modeling schemas with
- item
- ,
- string
- ,
- number
- ,
- list
- ,
- set
- ,
- map
- , and
- record
- Implementing
- GetItem
- ,
- PutItem
- ,
- UpdateItem
- ,
- DeleteItem
- via
- .build()
- Building query and scan access paths with primary keys and GSIs
- Handling batch and transactional operations
- Designing single-table systems with computed keys and entity patterns
- Instructions
- Start from access patterns
-
- identify read/write queries first, then design keys.
- Create table + entity boundaries
-
- one table, multiple entities if using single-table design.
- Define schemas with constraints
-
- apply
- .key()
- ,
- .required()
- ,
- .default()
- ,
- .transform()
- ,
- .link()
- .
- Use
- .build()
- commands everywhere
-
- avoid ad-hoc command construction for consistency and type safety.
- Add query/index coverage
-
- validate GSI/LSI paths for each required access pattern.
- Use batch/transactions intentionally
-
- batch for throughput, transactions for atomicity.
- Keep items evolvable
- use optional fields, defaults, and derived attributes for schema evolution.
Examples
Install and Setup
npm
install
dynamodb-toolbox @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
import
{
DynamoDBClient
}
from
'@aws-sdk/client-dynamodb'
;
import
{
DynamoDBDocumentClient
}
from
'@aws-sdk/lib-dynamodb'
;
import
{
Table
}
from
'dynamodb-toolbox/table'
;
import
{
Entity
}
from
'dynamodb-toolbox/entity'
;
import
{
item
,
string
,
number
,
list
,
map
}
from
'dynamodb-toolbox/schema'
;
const
client
=
new
DynamoDBClient
(
{
region
:
process
.
env
.
AWS_REGION
??
'eu-west-1'
}
)
;
const
documentClient
=
DynamoDBDocumentClient
.
from
(
client
)
;
export
const
AppTable
=
new
Table
(
{
name
:
'app-single-table'
,
partitionKey
:
{
name
:
'PK'
,
type
:
'string'
}
,
sortKey
:
{
name
:
'SK'
,
type
:
'string'
}
,
indexes
:
{
byType
:
{
type
:
'global'
,
partitionKey
:
{
name
:
'GSI1PK'
,
type
:
'string'
}
,
sortKey
:
{
name
:
'GSI1SK'
,
type
:
'string'
}
}
}
,
documentClient
}
)
;
Entity Schema with Modifiers and Complex Attributes
const
now
=
(
)
=>
new
Date
(
)
.
toISOString
(
)
;
export
const
UserEntity
=
new
Entity
(
{
name
:
'User'
,
table
:
AppTable
,
schema
:
item
(
{
tenantId
:
string
(
)
.
required
(
'always'
)
,
userId
:
string
(
)
.
required
(
'always'
)
,
email
:
string
(
)
.
required
(
'always'
)
.
transform
(
input
=>
input
.
toLowerCase
(
)
)
,
role
:
string
(
)
.
enum
(
'admin'
,
'member'
)
.
default
(
'member'
)
,
loginCount
:
number
(
)
.
default
(
0
)
,
tags
:
list
(
string
(
)
)
.
default
(
[
]
)
,
profile
:
map
(
{
displayName
:
string
(
)
.
optional
(
)
,
timezone
:
string
(
)
.
default
(
'UTC'
)
}
)
.
default
(
{
timezone
:
'UTC'
}
)
}
)
,
computeKey
:
(
{
tenantId
,
userId
}
)
=>
(
{
PK
:
TENANT# ${ tenantId }, SK :USER# ${ userId }, GSI1PK : ` TENANT# ${ tenantId }
TYPE#USER
,
GSI1SK
:
EMAIL#
${
userId
}
}
)
}
)
;
.build()
CRUD Commands
import
{
PutItemCommand
}
from
'dynamodb-toolbox/entity/actions/put'
;
import
{
GetItemCommand
}
from
'dynamodb-toolbox/entity/actions/get'
;
import
{
UpdateItemCommand
,
$add
}
from
'dynamodb-toolbox/entity/actions/update'
;
import
{
DeleteItemCommand
}
from
'dynamodb-toolbox/entity/actions/delete'
;
await
UserEntity
.
build
(
PutItemCommand
)
.
item
(
{
tenantId
:
't1'
,
userId
:
'u1'
,
email
:
'A@Example.com'
}
)
.
send
(
)
;
const
{
Item
}
=
await
UserEntity
.
build
(
GetItemCommand
)
.
key
(
{
tenantId
:
't1'
,
userId
:
'u1'
}
)
.
send
(
)
;
await
UserEntity
.
build
(
UpdateItemCommand
)
.
item
(
{
tenantId
:
't1'
,
userId
:
'u1'
,
loginCount
:
$add
(
1
)
}
)
.
send
(
)
;
await
UserEntity
.
build
(
DeleteItemCommand
)
.
key
(
{
tenantId
:
't1'
,
userId
:
'u1'
}
)
.
send
(
)
;
Query and Scan Patterns
import
{
QueryCommand
}
from
'dynamodb-toolbox/table/actions/query'
;
import
{
ScanCommand
}
from
'dynamodb-toolbox/table/actions/scan'
;
const
byTenant
=
await
AppTable
.
build
(
QueryCommand
)
.
query
(
{
partition
:
TENANT#t1
`
,
range
:
{
beginsWith
:
'USER#'
}
}
)
.
send
(
)
;
const
byTypeIndex
=
await
AppTable
.
build
(
QueryCommand
)
.
query
(
{
index
:
'byType'
,
partition
:
'TENANT#t1#TYPE#USER'
}
)
.
options
(
{
limit
:
25
}
)
.
send
(
)
;
const
scanned
=
await
AppTable
.
build
(
ScanCommand
)
.
options
(
{
limit
:
100
}
)
.
send
(
)
;
Batch and Transaction Workflows
import
{
BatchWriteCommand
}
from
'dynamodb-toolbox/table/actions/batchWrite'
;
import
{
TransactWriteCommand
}
from
'dynamodb-toolbox/table/actions/transactWrite'
;
await
AppTable
.
build
(
BatchWriteCommand
)
.
requests
(
UserEntity
.
build
(
PutItemCommand
)
.
item
(
{
tenantId
:
't1'
,
userId
:
'u2'
,
email
:
'u2@example.com'
}
)
,
UserEntity
.
build
(
PutItemCommand
)
.
item
(
{
tenantId
:
't1'
,
userId
:
'u3'
,
email
:
'u3@example.com'
}
)
)
.
send
(
)
;
await
AppTable
.
build
(
TransactWriteCommand
)
.
requests
(
UserEntity
.
build
(
PutItemCommand
)
.
item
(
{
tenantId
:
't1'
,
userId
:
'u4'
,
email
:
'u4@example.com'
}
)
,
UserEntity
.
build
(
UpdateItemCommand
)
.
item
(
{
tenantId
:
't1'
,
userId
:
'u1'
,
loginCount
:
$add
(
1
)
}
)
)
.
send
(
)
;
Single-Table Design Guidance
Model each business concept as an entity with strict schema.
Keep PK/SK predictable and composable (
TENANT#
,
USER#
,
ORDER#
).
Encode access paths into GSI keys, not in-memory filters.
Prefer append-only timelines for audit/history data.
Keep hot partitions under control with scoped partitions and sharding where needed.
Best Practices
Design keys from access patterns first, then derive entity attributes.
Keep one source of truth for key composition (
computeKey
) to avoid drift.
Use
.options({ consistent: true })
only where strict read-after-write is required.
Prefer targeted queries over scans for runtime request paths.
Add conditional expressions for idempotency and optimistic concurrency control.
Validate batch/transaction size limits before execution to avoid partial failures.
Constraints and Warnings
DynamoDB-Toolbox v2 relies on AWS SDK v3 DocumentClient integration.
Avoid table scans in request paths unless explicitly bounded.
Use conditional writes for concurrency-sensitive updates.
Transactions are limited and slower than single-item writes; use only for true atomic requirements.
Validate key design against target throughput before implementation.
References
Primary references curated from Context7 are available in:
references/api-dynamodb-toolbox-v2.md