Idea: Strong Type Wrappers

[jpergler]

Summary

This idea proposal introduces a new strongtype keyword to C# for creating strongly-typed wrappers around primitive types with minimal boilerplate. The feature is primarily driven by two motivations:

1. Remove boilerplate code required to create type-safe wrappers around primitive types
2. Transparent integration with serialization and frameworks - maintain the underlying primitive type for serialization, storage, and framework integration while ensuring compile-time type safety

Motivation

In many C# applications, developers frequently need to create lightweight wrappers around primitive types for type safety, domain modeling, and input validation. For example:

• A string-based Email type that validates its format
• An OrderId type to prevent mixing different ID types
• A Percentage type that ensures values are between 0-100

Currently, implementing such wrappers requires repetitive boilerplate:

• Creating custom record/class types
• Implementing custom serialization
• Adding explicit/implicit conversion operators
• Implementing validation logic
• Duplicating this code for each wrapped type

Moreover, integrating these custom types with frameworks like Entity Framework, ASP.NET, and other tools that use reflection or serialization requires additional configuration:

• Custom value converters for database storage
• Custom model binders for ASP.NET Core
• Custom type handling for serialization libraries

A native language feature would enable transparent integration with these frameworks, allowing entities to use strongly-typed properties while the underlying storage and serialization would work with the primitive types seamlessly.

Syntax

Basic Definition

// Simple wrapped type - no validation
public strongtype OrderId of string;

public strongtype UserId of int;

With Validation

This validation check goes into account whenever the strongtype is instantiated or deserialized so it is ensured the instance always meets the where condition or the exception is thrown.

// With validation using 'where' clause
public strongtype Email of string 
    where Value.Contains("@") && Value.Contains(".");

// With custom error message
public strongtype ProductCode of string
    where Value.StartsWith("PRD-")
    errorMessage "Product code must start with 'PRD-'";

With Additional Members

These members are only getters. They server to extract some structured information from the default internal Value.

// With properties and methods
public strongtype ResourcePath of string {
    public string[] Segments => Value.Split('/');
    public string BasePath => Segments.FirstOrDefault() ?? "";
}

With Validation and Members

// Combined validation and members
public strongtype Percentage of decimal where Value >= 0 && Value <= 100 {
    public decimal AsRatio => Value / 100m;
    public string Display => $"{Value}%";
}

Complex Validation Block

// Complex validation logic using block syntax
public strongtype ComplexId of string {
    where {
        if (Value == null) return false;
        if (Value.Length < 10) return false;
        return Value.StartsWith("CMPLX-") && Value.EndsWith("-ID");
    }

    public string IdNumber => Value.Substring(6, Value.Length - 9);
}

Inheritance

// Base type with validation
public abstract strongtype ResourceId of string where Value.Contains("/") {
    public string[] Segments => Value.Split('/');
}

// Derived type with additional validation
public strongtype UserResourceId of string : ResourceId
    where base.IsValid && Value.StartsWith("users/") {

    public string UserId => Segments[1];
}

Secondary Constructors

public strongtype PrefixedId of string {
    // Optional secondary constructor
    public PrefixedId(string prefix, string id) : this($"{prefix.ToLowerInvariant()}/{id}");

    // Properties to access components
    public string Prefix => Value.Split('/')[0];
    public string Id => Value.Split('/')[1];
}

// Usage
var resource = new PrefixedId("User", "12345");  // Constructs with value "user/12345"

Entity Framework Use Example

// Entity with strongly-typed ID
public class User
{
    public UserId Id { get; set; }
    public Email Email { get; set; }
    public string Name { get; set; }
}

// UserId and Email are defined as:
public strongtype UserId of string where Value.StartsWith("user/");
public strongtype Email of string where Value.Contains("@");

// DbContext with no special configuration needed
public class AppDbContext : DbContext
{
    public DbSet<User> Users { get; set; }

    // No custom converters needed - framework sees the primitive type
}

// Entity Framework query with type safety
var user = await context.Users
    .Where(u => u.Id == new UserId("user/123"))
    .FirstOrDefaultAsync();

Integration with Validation Frameworks

// Essential type validation in the strong type
public strongtype Email of string where Value.Contains("@");

// Additional context-specific validation
public class UserDto {
    [Required]
    [EmailDomain("mydomain.com")]
    public Email Email { get; set; }
}

Potential Implementation Approach

This feature could be implemented as a compile-time transformation similar to how Kotlin implements inline value classes:

1. Use the wrapped type for type checking during compilation
2. Replace the wrapped type with the underlying type in the generated IL
3. Add runtime validation at boundaries where values enter the typed context
4. Insert type conversion/checking code only where needed

Benefits

1. Type Safety: Prevents mixing different semantic types (e.g., UserId vs GroupId)
2. Validation: Centralized, enforced validation at creation points
3. Reduced Boilerplate: Eliminates repetitive code for operators and serialization
4. Framework Integration: Seamless integration with ORMs, serializers, etc.
5. Performance: Minimal runtime overhead compared to manual implementations
6. Consistency: Standardized approach for all wrapped types in a codebase
7. Self-Documenting Code: Types clearly communicate their semantic meaning

Key Design Considerations

Validation Behavior

The strong type's validation occurs at instantiation time, ensuring that no invalid instances can exist:

public strongtype Email of string where Value.Contains("@");

// Instantiation validation
Email valid = new Email("user@example.com");  // Works
Email invalid = new Email("invalid-email");   // Throws exception

// Explicit conversion validation
Email converted = (Email)"user@example.com";  // Works
Email alsoInvalid = (Email)"invalid-email";   // Throws exception

Validation of the strongtype object is not meant to replace general data validation especially for user inputs. When user input needs to be validated usually a string value is needed and some validation mechanism such as attribute annotation validation takes place.

The validated string values then can be put into strongtype object which ensures that a static format is met for example on API calls when the value is deserialized or when it comes from database.

Type Erasure

At runtime, strong types would be replaced with their underlying primitive type:

// What you write
public strongtype OrderId of string where Value.StartsWith("ORD-");
public class Order { public OrderId Id { get; set; } }

// What happens during deserialization (conceptually)
string json = @"{""id"":""ORD-12345""}";

// During JSON deserialization
Order order = JsonSerializer.Deserialize<Order>(json);
// The compiler generates code similar to:
// 1. Deserialize "id" as string
// 2. Validate the string (if !value.StartsWith("ORD-"), throw exception)
// 3. Create OrderId instance with the validated value
// 4. At runtime, the OrderId is stored as a string

// When the property is accessed, no boxing/unboxing overhead
string rawId = order.Id; // Implicit conversion, no runtime cost

Type Safety and Equality

Different strong types are not equal, even with the same underlying value:

public strongtype CustomerId of string;
public strongtype OrderId of string;

// Creating instances
CustomerId custId = new CustomerId("ABC123");
OrderId orderId = new OrderId("ABC123");

// Type safety in action
bool areEqual = custId.Equals(orderId);  // False - different types
bool stringsEqual = (string)custId == (string)orderId; // True - same string value

Comparison with Other Languages

This proposal is similar to Kotlin's inline value classes, which solve a similar problem:

// Kotlin inline value class
@JvmInline
value class Email(val value: String) {
    init {
        require(value.contains("@")) { "Invalid email format" }
    }
}

However, this proposal extends the concept with:

• Dedicated validation syntax
• Framework integration
• Inheritance support
• More concise syntax for common cases

The strongtype X of Y syntax is more explicit about the wrapping relationship than Kotlin's approach, making the code more self-documenting.

Open Questions

1. Checks on Boundaries: How exactly the check would be enforced on all places?
2. Impact on Frameworks: How far would it work transparently with various frameworks?
3. Complex Validation: Should more complex validation patterns be supported directly?
4. Serialization Details: How would custom serialization scenarios be supported?
5. Syntax: While this proposal uses strongtype, alternative keywords like wraptype or wrapper could also be considered. And there are more syntax challenges as well.

Conclusion

I see some patterns which repeat again and again when implementing strongly typed wrappers above primitive types. This is an attempt to bring an idea of syntax which can be self-explanatory and aims for specific problems in code which many developers solve on a daily basis.

The strongtype feature would provide a powerful tool for domain modeling and type safety in C# applications. By eliminating boilerplate while maintaining transparent framework integration, it would significantly improve code quality and developer productivity.

I understand that there are many unanswered questions. I will be happy for any feedback or just to bring a little light on this topic or different thoughts.

[timcassell]

Roles? #8431

[jpergler]

I know about Roles and it is not really solving the problem I am trying to discuss. It seems similar to the part where the members are in the proposal but that is actually not the main part of the problem.

The main goal is to have strongly typed objects in syntax while primitive type in place when compiled. The secondary part to it is the "Roles" addition but in the way that the getters are in the same block of code so the information about the strongly typed object and it's members is close to each other.

[CyrusNajmabadi]

while primitive type in place when compiled.

That's what a role would do. It's effectively a transparent wrapper so there is no overhead whatsoever.

[jpergler]

Okey now I understand the role more, thanks. It would not solve the validation part of the problem but most of common primitive type obsession it would solve. Even more when it would be transparent for libraries like EntityFramework or other database libraries.

[RikkiGibson]

I would be interested to see someone attempt to address this problem with a source generator and see how far they get. Basically, I would be reluctant to invest here on the language side, except if there is some deeply compelling scenario here which can't be addressed by a source generator.

[StrongTypeWrapper(typeof(string))]
public partial struct Email;

[333fred]

That would be: https://github.com/SteveDunn/Vogen

[jpergler]

@333fred I didn't encounter this, thanks for sharing. It seems to be promising. It also supports validation of the primitive value. It would be nice to have built-in feature anyway.