DdbFlow
ddbflowFluent DynamoDB query params builder. Works with both AWS SDK v2 and v3. Chain conditions, projections, and filters with a clean, readable API.
Installation
npm install ddbflowyarn add ddbflowWhy it exists
Building DynamoDB queries by hand means assembling deeply nested objects for `ExpressionAttributeNames`, `ExpressionAttributeValues`, and `FilterExpression` every single time. After one too many runtime errors from mismatched `#attr` placeholders, I built DdbFlow to let you describe what you want — not how to format it. It works transparently with both AWS SDK v2 and v3 so you can adopt it without migrating your existing code.
Features
Chain filter conditions, key conditions, GSI targets, and projections in a single readable expression. No manual placeholder bookkeeping.
Outputs a plain params object that works with both `AWS.DynamoDB.DocumentClient` (v2) and `@aws-sdk/lib-dynamodb` (v3) without any adapter layer.
Generic type parameter `DdbFlow<MyItem>` types the returned Items array, giving you autocomplete and compile-time guarantees on the data you receive.
Highlights
- Fluent builder pattern — chain .where(), .project(), .limit() calls like writing SQL
- Automatic placeholder management for ExpressionAttributeNames and ExpressionAttributeValues
- SDK-agnostic output — pass the result directly to DocumentClient (v2) or DynamoDBDocumentClient (v3)
- Full TypeScript generics so returned items are typed to your table schema