Structura 0.9.0-beta

<img src="./logo.png" width="256" height="256">

Structura

Source Generator-Based Fluent API Type Manipulation Library

Structura is a .NET library that automatically generates new types through source generators when you define type creation and manipulation rules using a fluent API.

🚀 Key Features

• 🔄 Type Combination: Combine existing types to create new types
• 🎭 Anonymous Type Support: Complete anonymous type analysis including variable references
• 🔗 EF Core Projection Support: Convert EF Core projection results to strongly-typed types
• ⚙️ Advanced Property Manipulation: Add, exclude, and change property types
• 🏷️ Diverse Type Generation: Support for Records, Classes, and Structs
• 🎯 Smart Converter Extensions: Generate extension methods for seamless object conversion (NEW!)
• 🧪 Comprehensive Testing: 100+ comprehensive unit tests

📦 Installation

dotnet add package Structura

🏗️ Core Features

1. Type Combination

Combine existing types to create new types.

// Combine two existing types
TypeCombiner.Combine<PersonalInfo, ContactInfo>()
    .WithName("UserProfile")
    .AsRecord()
    .Generate();

// Result: Creates a UserProfile record with all properties from PersonalInfo and ContactInfo

2. Anonymous Type Support

Complete support for anonymous types and variable references.

// Direct anonymous type creation
TypeCombiner.Combine()
    .With(new { Name = "", Age = 0 })
    .With(new { Email = "", Phone = "" })
    .WithName("Contact")
    .AsRecord()
    .Generate();

// Variable reference approach (validated in actual tests)
var userInfo = new { Name = "John Doe", Age = 40, Sex = "male" };
TypeCombiner.Combine()
    .With(userInfo)
    .WithName("AnonymousUser")
    .AsClass()
    .Generate();

// Combine existing type with anonymous type
TypeCombiner.Combine<User>()
    .With(new { Department = "", Salary = 0m, Position = "" })
    .WithName("Employee")
    .AsRecord()
    .Generate();

3. EF Core Projection Support

Convert EF Core projection results to strongly-typed types.

// EF Core projection simulation
var userProjection = new List<object>
{
    new { Name = "John Doe", Email = "john@example.com" },
    new { Name = "Jane Smith", Email = "jane@example.com" }
};

TypeCombiner.Combine()
    .WithProjection(userProjection)
    .WithName("UserProjectionType")
    .AsRecord()
    .Generate();

// Dashboard data generation
var dashboardData = new List<object>
{
    new { 
        CustomerName = "John Doe", 
        TotalOrders = 12, 
        TotalSpent = 150000m,
        LastOrderDate = DateTime.Now.AddDays(-5)
    }
};

TypeCombiner.Combine()
    .WithProjection(dashboardData)
    .With(new { GeneratedAt = DateTime.Now, ReportType = "CustomerAnalysis" })
    .WithName("CustomerDashboard")
    .AsRecord()
    .Generate();

4. 🎯 Smart Converter Extensions (NEW!)

The game-changer for EF Core projections! Enable automatic conversion from anonymous objects to strongly-typed instances.

Basic Usage

// Step 1: Generate type with converter enabled
var efResult = dbContext.Users.Select(x => new { x.Name, x.Email }).ToList();

TypeCombiner.Combine()
    .WithProjection(efResult)
    .WithName("UserDto")
    .WithConverter()  // 🔥 This enables the magic!
    .AsRecord()
    .Generate();

// Step 2: Use the generated static converter methods directly on the type
List<Generated.UserDto> typedUsers = UserDto.FromCollection(efResult);
Generated.UserDto singleUser = UserDto.FromSingle(efResult.First());

// 🆕 NEW! Strongly-typed anonymous object conversion
var anonymousUsers = new[] {
    new { Name = "John", Email = "john@test.com" },
    new { Name = "Jane", Email = "jane@test.com" }
};
List<Generated.UserDto> convertedUsers = UserDto.FromTypedCollection(anonymousUsers);
Generated.UserDto convertedSingle = UserDto.FromTyped(anonymousUsers.First());

Advanced Converter Scenarios

// Complex EF Core projection with additional properties
var dashboardProjection = dbContext.Orders
    .GroupBy(o => o.CustomerId)
    .Select(g => new { 
        CustomerId = g.Key,
        CustomerName = g.First().Customer.Name,
        TotalOrders = g.Count(),
        TotalSpent = g.Sum(o => o.Amount)
    })
    .ToList();

TypeCombiner.Combine()
    .WithProjection(dashboardProjection)
    .With(new { 
        ReportDate = DateTime.Now,
        ReportType = "Customer Analytics",
        GeneratedBy = "System"
    })
    .WithName("CustomerAnalytics")
    .WithConverter()  // 🔥 Enable smart conversion
    .AsRecord()
    .Generate();

// Now seamlessly convert your projection results
List<Generated.CustomerAnalytics> analytics = CustomerAnalytics.FromCollection(dashboardProjection);

// Or convert individual items
Generated.CustomerAnalytics single = CustomerAnalytics.FromSingle(dashboardProjection.First());

// Convert from named types (if combining PersonalInfo + ContactInfo)
Generated.UserProfile profile1 = UserProfile.FromPersonalInfo(personalInfo);
Generated.UserProfile profile2 = UserProfile.FromContactInfo(contactInfo);
Generated.UserProfile profile3 = UserProfile.FromBoth(personalInfo, contactInfo);
```### 5. Advanced Property Manipulation

#### Property Exclusion

```csharp
TypeCombiner.From<PersonalInfo>()
    .Exclude(p => p.Password)
    .Exclude(p => p.BirthDate)
    .WithName("PublicPersonalInfo")
    .Generate();

Property Addition

TypeCombiner.From<User>()
    .Add("CreatedAt", typeof(DateTime))
    .Add("LastLoginAt", typeof(DateTime?))
    .Add("Metadata", typeof(Dictionary<string, object>))
    .WithName("ExtendedUser")
    .AsClass()
    .Generate();

Type Changes

TypeCombiner.From<Product>()
    .ChangeType(p => p.Price, typeof(string))      // decimal → string
    .ChangeType(p => p.StockQuantity, typeof(string)) // int → string
    .WithName("ProductDto")
    .Generate();

Conditional Exclusion

bool isAdmin = false;
TypeCombiner.From<PersonalInfo>()
    .ExcludeIf(p => p.Password, condition: !isAdmin)
    .WithName("ContextualUser")
    .Generate();

6. Complex Operations

All features can be used together, including the new converter functionality.

TypeCombiner.Combine<PersonalInfo, ContactInfo>()
    .Exclude<PersonalInfo>(p => p.Password)           // Exclude sensitive information
    .Add("LastLoginAt", typeof(DateTime?))            // Add new property
    .ChangeType<ContactInfo>(c => c.PhoneNumber, typeof(string)) // Change type
    .WithConverter()                                  // Enable smart conversion
    .WithName("SecureUserProfile")
    .AsRecord()
    .Generate();

// Now you can convert anonymous objects to SecureUserProfile
var anonymousData = new { FirstName = "John", Email = "john@example.com", LastLoginAt = DateTime.Now };
Generated.SecureUserProfile profile = SecureUserProfile.FromTyped(anonymousData);

🏷️ Supported Type Generation

🎯 Target Frameworks

• .NET Standard 2.0 and above
• .NET 9 recommended
• C# 12.0 syntax support

🚀 Advanced Usage

Real-World EF Core Integration

// 1. EF Core projection query
var customerAnalytics = await dbContext.Orders
    .Include(o => o.Customer)
    .GroupBy(o => new { o.CustomerId, o.Customer.Name })
    .Select(g => new {
        CustomerId = g.Key.CustomerId,
        CustomerName = g.Key.Name,
        TotalOrders = g.Count(),
        TotalRevenue = g.Sum(o => o.Amount),
        AverageOrderValue = g.Average(o => o.Amount),
        FirstOrderDate = g.Min(o => o.OrderDate),
        LastOrderDate = g.Max(o => o.OrderDate)
    })
    .ToListAsync();

// 2. Generate strongly-typed DTO with converter
TypeCombiner.Combine()
    .WithProjection(customerAnalytics)
    .With(new { 
        AnalysisDate = DateTime.UtcNow,
        AnalysisType = "Customer Revenue Analysis",
        Currency = "USD"
    })
    .WithName("CustomerRevenueDto")
    .WithConverter()  // 🔥 Enable seamless conversion
    .AsRecord()
    .Generate();

// 3. Convert to strongly-typed collection
List<Generated.CustomerRevenueDto> typedAnalytics = CustomerRevenueDto.FromCollection(customerAnalytics);

// 4. Use with full IntelliSense and type safety
var topCustomers = typedAnalytics
    .Where(c => c.TotalRevenue > 10000)
    .OrderByDescending(c => c.TotalRevenue)
    .Take(10)
    .ToList();

Collection Type Support

TypeCombiner.From<User>()
    .Add("Tags", typeof(List<string>))
    .Add("Permissions", typeof(string[]))
    .Add("Properties", typeof(Dictionary<string, object>))
    .WithName("TaggedUser")
    .WithConverter()
    .Generate();

Various Data Types

var complexData = new { 
    StringValue = "test string",
    IntValue = 42,
    LongValue = 123L,
    FloatValue = 3.14f,
    DoubleValue = 2.718,
    DecimalValue = 99.99m,
    BoolValue = true,
    DateValue = DateTime.Now,
    GuidValue = Guid.NewGuid()
};

TypeCombiner.Combine()
    .With(complexData)
    .WithName("TypedData")
    .WithConverter()
    .AsStruct()
    .Generate();

// Convert with intelligent type handling
Generated.TypedData converted = TypedData.FromTyped(complexData);

💼 Real-World Scenarios

API DTO Generation

// Generate public API DTO from internal entity
TypeCombiner.From<PersonalInfo>()
    .Exclude(u => u.Password)
    .Add("PublicId", typeof(Guid))
    .WithConverter()
    .WithName("UserApiDto")
    .AsRecord()
    .Generate();

Database Migration

// Add new columns to existing table schema
TypeCombiner.From<User>()
    .Add("CreatedAt", typeof(DateTime))
    .Add("UpdatedAt", typeof(DateTime?))
    .ChangeType(u => u.IsActive, typeof(int)) // bool → int conversion
    .WithName("ModernUserTable")
    .Generate();

Complex Business Logic

// Combine multiple data sources into view model
var personalData = new { FirstName = "John", LastName = "Developer", Age = 28 };
var workData = new { Company = "TechCompany", Position = "Backend Developer", Salary = 60000m };

TypeCombiner.Combine()
    .With(personalData)
    .With(workData)
    .WithConverter()  // Enable conversion from anonymous objects
    .WithName("EmployeeProfile")
    .AsClass()
    .Generate();

// Convert combined data to strongly-typed object
var combinedAnonymous = new { 
    FirstName = "John", 
    LastName = "Developer", 
    Age = 28,
    Company = "TechCompany", 
    Position = "Backend Developer", 
    Salary = 60000m 
};
Generated.EmployeeProfile employee = EmployeeProfile.FromTyped(combinedAnonymous);

🧪 Testing

Running Tests

dotnet test

Comprehensive Test Coverage

Structura is validated with 100+ comprehensive unit tests:

🎯 Test Results

• Total Tests: 100+
• Passed: 100+ ✅
• Failed: 0
• Skipped: 0
• Execution Time: < 2 seconds

📁 Project Structure

Structura/
├── 📂 Structura/                     # Main library
│   ├── TypeCombiner.cs               # Fluent API entry point
│   ├── TypeCombinerBuilder.cs        # Multi-type combination builder
│   ├── AnonymousTypeCombinerBuilder.cs # Anonymous type builder
│   ├── TypeDefinitions.cs            # Core type definitions
│   └── StructuraSourceGenerator.cs   # Source generator engine
├── 📂 Structura.Test.Console/        # Integration test console
│   └── Program.cs                    # Real usage examples and demos
├── 📂 Structura.Tests/              # Unit test project
│   ├── UnitTest.cs                  # Basic functionality unit tests
│   ├── VariableReferenceTests.cs    # Variable reference feature tests
│   ├── EFCoreProjectionTests.cs     # EF Core projection tests
│   ├── ConverterExtensionTests.cs   # 🆕 Smart converter tests
│   ├── IntegrationTests.cs          # Integration and scenario tests
│   └── TestModels.cs                # Test model classes
└── 📄 README.md                     # Documentation

📈 Development Status

✅ Completed Features

🔧 Partially Completed Features

🚀 Getting Started

1. Installation

dotnet add package Structura

2. Basic Usage

using Structura;

// Create new type from anonymous types
TypeCombiner.Combine()
    .With(new { Name = "", Age = 0 })
    .With(new { Email = "", Phone = "" })
    .WithName("Contact")
    .AsRecord()
    .Generate();

// Use the generated type
var contact = new Generated.Contact("John Doe", 30, "john@example.com", "555-1234");

3. Advanced Usage with Converter

// Add properties to existing type with converter support
TypeCombiner.From<User>()
    .Add("CreatedAt", typeof(DateTime))
    .Add("Metadata", typeof(Dictionary<string, object>))
    .WithConverter()  // 🔥 Enable smart conversion
    .WithName("ExtendedUser")
    .AsClass()
    .Generate();

// Convert anonymous object to strongly-typed instance
var anonymousUser = new {
    Name = "Developer",
    Age = 25,
    Email = "dev@example.com",
    CreatedAt = DateTime.Now,
    Metadata = new Dictionary<string, object>()
};

Generated.ExtendedUser typedUser = ExtendedUser.FromTyped(anonymousUser);

🎨 API Reference

TypeCombiner Static Methods

Fluent Methods

🆕 Generated Static Converter Methods

When .WithConverter() is used, the following static methods are automatically generated on the generated type itself:

🤝 Contributing

Issues and pull requests are welcome!

📄 License

MIT License

Structura - Simplify type manipulation with smart conversion! 🚀