DynamoDB-Toolbox

DynamoDB-Toolbox

DynamoDB-Toolbox is a lightweight and type-safe query builder that turns your DynamoDB journey into a ✨ bliss ✨

Example

If you've ever used the official DynamoDB Document Client, you know that it’s painful to use.

Take a look at this UpdateCommand example straight from the AWS documentation:

await documentClient.send(
  new UpdateCommand({
    TableName: 'Music',
    Key: {
      // 👇 No type-safety on the Primary Key
      artist: 'Acme Band',
      songTitle: 'Happy Day'
    },
    // 👇 Complex string expressions (+ still no type-safety)
    UpdateExpression: 'SET #Y = :y, #AT = :t',
    // 👇 Attribute names provided separately
    ExpressionAttributeNames: {
      '#AT': 'albumTitle',
      '#Y': 'year'
    },
    // 👇 Attribute values as well
    ExpressionAttributeValues: {
      // 👇 No validation or type-safety to enforce DB schema
      ':t': 'Louder Than Ever',
      ':y': '2015'
    },
    ReturnValues: 'ALL_NEW'
  })
)

It's a very simple example (updating two fields of a Music item), yet already complex 😰

Things only get messier as your data grows in complexity: What if your items have many attributes, with some of them deep or optional? What if you need to index an item based on its value or handle different types of items? What about polymorphism?

In those cases, which are fairly common, the required code to generate those requests gets very hard to maintain. That's when DynamoDB-Toolbox comes to the rescue 💪

Here's is a quick preview with the DynamoDB-Toolbox version of the UpdateCommand described above:

// Validated AND type-safe syntax 🙌
await MusicEntity.build(UpdateItemCommand)
  .item({
    artist: 'Acme Band',
    songTitle: 'Happy Day',
    albumTitle: 'Louder Than Ever',
    year: '2015'
  })
  .options({ returnValues: 'ALL_NEW' })
  .send()

And just like that, we went from an obscure 20 lines to a readable and elegant 10-liner 🤩

Features

🤗 Simpler queries: DynamoDB-Toolbox does all the heavy-lifting of crafting those complex DynamoDB requests. It makes your code clearer, more concise and easier to maintain.

📐 Data validation: Both pushed and fetched items are validated against your schemas, which guarantees the consistency of your data and the reliability of your code.

✨ A rich schema syntax that supports a broad range of edge cases like defaults, composition, transformation and polymorphism.

🌈 Type-safety pushed to the limit: Increase your development velocity with instantaneous feedbacks and slick auto-completion.

🌴 Tree-shakable: Only import what you need.

☝️ Single-table designs: DynamoDB-Toolbox makes querying multiple entities within the same table extremely simple, although it works just as well with multiple tables.

🪶 LLRT compatible: DynamoDB-Toolbox has no dependency and can be used within LLRT functions.

MCPToolkit

In addition to all those features, DynamoDB-Toolbox exposes a MCPToolkit that adds very convenient Tools to an MCP Server in just one line of code, enabling any MCP Clients (like Claude or Cursor) to interact with your DynamoDB Tables using natural language.

More details on 👉 MCP Client: Building a Smart and Robust Integration to DynamoDB with DynamoDB-Toolbox