feat(mappers): add nested object mapping support with reusable helper methods

[j-d-ha]

🚀 Pull Request

📋 Summary

This PR introduces comprehensive support for mapping nested objects in DynamoMapper, enabling efficient serialization and deserialization of complex object graphs. The implementation uses reusable helper methods to handle nested type mappings, reducing code duplication and improving maintainability.

Key Features

• Helper Method Infrastructure: New HelperMethodRegistry and HelperMethodInfo types manage reusable helper methods for nested object mappings
• Multi-Level Nesting: Full support for deeply nested object hierarchies (Level1 → Level2 → Level3 → Level4, etc.)
• Enhanced Property Analysis: Integrated PropertyAnalyzer to track nullability, requiredness, getters, setters, and default values for nested properties
• Optimized Dictionary Initialization: Dictionary capacity is pre-calculated based on the number of properties to reduce allocations
• Expression-Bodied Members: Cleaner code generation using arrow syntax for helper methods
• Accurate Requiredness Handling: Nested properties correctly handle required vs optional semantics with proper fallback management

Technical Implementation

1. HelperMethodEmitter: Generates ToItem_* and FromItem_* helper methods for nested types
2. HelperMethodRegistry: Ensures the same nested type reuses the same helper method (no duplication)
3. NestedObjectTypeAnalyzer: Enhanced to perform deep property analysis with nullability and requiredness tracking
4. PropertyMappingCodeRenderer: Refactored to leverage helper methods and enhanced property analysis

Example Generated Code

For a mapper with nested Address objects, the generator now creates:

// Helper method for Address type
private static global::System.Collections.Generic.Dictionary<string, global::Amazon.DynamoDBv2.Model.AttributeValue> ToItem_Address(global::MyNamespace.Address address) =>
    new global::System.Collections.Generic.Dictionary<string, global::Amazon.DynamoDBv2.Model.AttributeValue>(3)
        .SetString("Street", address.Street)
        .SetString("City", address.City)
        .SetString("ZipCode", address.ZipCode);

// Reused in parent mapper
.SetMap("BillingAddress", customer.BillingAddress != null ? ToItem_Address(customer.BillingAddress) : null)

---

✅ Checklist

• My changes build cleanly
• I've added/updated relevant tests (multi-level nesting, requiredness handling)
• I've updated documentation (inline code comments and XML docs)
• I've followed the coding style for this project
• I've tested the changes locally with snapshot tests

---

🧪 Related Issues or PRs

This PR builds foundational support for nested object mapping, which will be essential for Phase 2 of the DynamoMapper roadmap (collections and complex types).

---

💬 Notes for Reviewers

Files to Review

• Core Infrastructure: HelperMethodRegistry.cs, HelperMethodInfo.cs, HelperMethodEmitter.cs
• Property Analysis: NestedObjectTypeAnalyzer.cs (enhanced with PropertyAnalyzer integration)
• Code Rendering: PropertyMappingCodeRenderer.cs (refactored for helper method support)
• Test Coverage: NestedObjectVerifyTests.cs (multi-level nesting, requiredness tests)

Design Decisions

1. Helper methods over inline expansion: Reduces code size and improves readability when the same nested type is used multiple times
2. Expression-bodied members: Aligns with modern C# style guidelines and reduces visual noise
3. Pre-calculated dictionary capacity: Measurable performance improvement by avoiding dictionary resizes
4. Requiredness tracking: Ensures generated code handles required vs optional properties correctly, preventing null reference exceptions

Known Limitations

• This PR focuses on nested objects with scalar properties only (consistent with Phase 1 scope)
• Collections of nested objects and recursive types are planned for Phase 2

[ncipollina]

Feedback from Claude:

---

High Priority

1. Incremental pipeline equality broken — MapperInfo stores mutable GeneratorContext and HelperMethodRegistry in a record used by the incremental pipeline. Since these are reference types without value equality, the generator will re-execute on every keystroke, defeating caching. This is the most architecturally significant concern.
2. Unbounded while(true) loop in MapperEmitter.Generate (line 55-81) — If a bug causes helper methods to register under different names, this becomes an infinite loop inside the compiler/IDE. Add a maxIterations safety bound.

Medium Priority

3. Missing brace depth tracking — HelperMethodEmitter.SplitPropertiesRespectingNesting tracks () and <> depth but ignores {}. Any future code producing commas inside braces will silently corrupt output.
4. .Set over-counting — CountSetMethodCalls counts every .Set substring including those inside arguments (e.g., source.Settings), inflating dictionary capacity in generated code.
5. Unconditional null-checks for non-nullable types — RenderInlineNestedToItem always emits is null ? checks even for struct/required properties, generating dead code and potential compiler warnings.
6. Duplicated type-name sanitization — Three near-identical implementations of type-name extraction across HelperMethodEmitter, HelperMethodRegistry, and PropertyMappingCodeRenderer.

Low Priority

7. Re-parsing own output — Rendering a single-line string then re-parsing it character by character to format it. Follow-up refactor candidate.
8. Minor style inconsistencies — Mix of string.Empty vs "" patterns.

Recommended Follow-ups (quick wins)

• Add {/} to SplitPropertiesRespectingNesting depth tracking
• Add maxIterations guard to the helper rendering loop
• Consolidate type-name extraction into a shared utility
• Conditionally emit null-checks based on Nullability.IsNullableType

Refactor RFC: Extract transient state from MapperInfo

The GeneratorContext and HelperMethodRegistry should be passed separately to MapperEmitter.Generate() rather than stored in the pipeline record, to restore proper incremental caching behavior. Estimated ~2-3 hours, low risk, internal-only change.

[j-d-ha]

1. Incremental pipeline equality broken — MapperInfo stores mutable GeneratorContext and HelperMethodRegistry in a record used by the incremental pipeline. Since these are reference types without value equality, the generator will re-execute on every keystroke, defeating caching. This is the most architecturally significant concern.

Resolved 1, 2, 3, 4, 6, and 7. I did not like the others (at least for now).

[ncipollina]

✅ LGTM