LayeredCraft.DynamoMapper

High-performance source generator for DynamoDB attribute mapping

Migrating from DynamoMapper? This package (LayeredCraft.DynamoMapper) is the successor to the original DynamoMapper NuGet package. Update your using DynamoMapper.Runtime; statements to using LayeredCraft.DynamoMapper.Runtime;.

---

DynamoMapper is a .NET incremental source generator that generates high-performance mapping code between domain models and Amazon DynamoDB AttributeValue dictionaries. Using compile-time code generation, it eliminates runtime reflection, reduces allocations, and provides type-safe mapping for single-table DynamoDB patterns.

Why DynamoMapper?

• ⚡ Zero reflection overhead - All mapping code generated at compile time
• 🎯 Type-safe - Catches configuration errors at compile time with diagnostics
• 🚀 Allocation-free - Uses efficient dictionary operations, no LINQ or unnecessary allocations
• 🔧 Simple - Convention-first with minimal attribute configuration
• 🌐 Single-table friendly - Designed for single-table DynamoDB patterns with customization hooks
• 📦 Clean domain models - No attributes on your domain classes required

📚 View Full Documentation

Installation

Install the NuGet package:

dotnet add package LayeredCraft.DynamoMapper --prerelease

Install the DynamoMapper agent skill:

npx skills add https://github.com/LayeredCraft/dynamo-mapper --skill dynamo-mapper

Ensure your project uses C# 11 or later:

<PropertyGroup>
<LangVersion>11</LangVersion>
<!-- or <LangVersion>latest</LangVersion> -->
</PropertyGroup>

Quick Start

1. Define your domain model

publicclassProduct{publicstringUserId{get;set;}publicGuidProductId{get;set;}publicstringName{get;set;}publicdecimalPrice{get;set;}publicstring?Description{get;set;}publicProductStatusStatus{get;set;}}

2. Create a mapper class

usingLayeredCraft.DynamoMapper.Runtime;usingAmazon.DynamoDBv2.Model;namespaceMyApp.Data;[DynamoMapper(Convention=DynamoNamingConvention.CamelCase)][DynamoField(nameof(Product.Description),OmitIfNull=true,OmitIfEmptyString=true)]publicstaticpartialclassProductMapper{publicstaticpartialDictionary<string,AttributeValue>ToItem(Productsource);publicstaticpartialProductFromItem(Dictionary<string,AttributeValue>item);}

3. That's it!

At compile time, DynamoMapper generates the mapping code. Use it like this:

varproduct=newProduct{UserId="user-123",ProductId=Guid.NewGuid(),Name="Laptop",Price=999.99m,Status=ProductStatus.Available};// Convert to DynamoDB itemvaritem=ProductMapper.ToItem(product);awaitdynamoDbClient.PutItemAsync(newPutItemRequest{TableName="MyTable",Item=item});// Convert from DynamoDB itemvargetResponse=awaitdynamoDbClient.GetItemAsync(newGetItemRequest{TableName="MyTable",Key=newDictionary<string,AttributeValue>{["pk"]=newAttributeValue{S=$"USER#{product.UserId}"},["sk"]=newAttributeValue{S=$"PRODUCT#{product.ProductId}"}}});varretrievedProduct=ProductMapper.FromItem(getResponse.Item);

For more examples including single-table patterns and custom converters, see the Quick Start Guide.

Key Features

• Attribute-Based Configuration (Phase 1): Configure mapping via [DynamoField] and [DynamoIgnore] on mapper classes
• Fluent DSL Configuration (Phase 2): Optional strongly-typed DSL for configuration
• Naming Conventions: CamelCase, SnakeCase, or Exact field naming
• Required Field Validation: Compile-time and runtime validation of required fields
• Omission Policies: Flexible null/empty value omission strategies
• Custom Converters: Type-safe converter pattern for custom serialization
• Customization Hooks: Before/After hooks for injecting pk/sk and custom logic
• Single-Table Support: Built for single-table DynamoDB design patterns
• Supported Types: strings, numerics, bool, Guid, DateTime, DateTimeOffset, TimeSpan, enums, plus lists/maps/sets of supported element types
• Comprehensive Diagnostics: Clear compile-time errors with actionable messages
• Zero Configuration: Sensible defaults for most use cases

Learn more in the Core Concepts documentation.

Requirements

• C# 11+ (for partial method generation)
• .NET Standard 2.0+ (package targets)
• AWSSDK.DynamoDBv2 (for AttributeValue types)

See the Requirements page for full details.

Documentation

📖 Full Documentation - Comprehensive guides and API reference

Key sections:

• Installation - Get started with DynamoMapper
• Quick Start - Your first mapper in 5 minutes
• Core Concepts - Understand how it works
• Usage Guide - Detailed usage patterns
• Examples - Real-world DynamoDB scenarios
• Roadmap - Phase 1 and Phase 2 plans

For AI tooling, install the repo skill with:

npx skills add https://github.com/LayeredCraft/dynamo-mapper --skill dynamo-mapper

Contributing

Contributions are welcome! See our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with ⚡ by the LayeredCraft team

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Jonas Ha 💻

Nick Cipollina 💻

This project follows the all-contributors specification. Contributions of any kind welcome!