ktsu.StrongStrings 1.4.3-pre.17

ktsu.StrongStrings

A transparent wrapper around strings that provides strong typing, compile-time feedback, and runtime validation.

Introduction

ktsu.StrongStrings is a .NET library that provides a way to create strongly-typed wrappers around standard strings. It gives you the benefits of strong typing, compile-time feedback, and runtime validation while maintaining full compatibility with string operations. The intention is to provide usage context and validation to naked strings in a similar way that Enums do for integers.

Features

• Strong Typing: Create distinct types for different string usages (e.g., EmailAddress, UserId, Url)
• Compile-Time Safety: Prevent mixing of semantically different strings
• Runtime Validation: Apply custom validation rules that throw exceptions for invalid data
• Transparent Usage: Works with existing string APIs through implicit conversion
• String Operation Support: Full access to standard string methods and properties
• Immutability: Implemented as records for value semantics and immutability

Installation

Package Manager Console

Install-Package ktsu.StrongStrings

.NET CLI

dotnet add package ktsu.StrongStrings

Package Reference

<PackageReference Include="ktsu.StrongStrings" Version="x.y.z" />

Usage Examples

Basic Example

using ktsu.StrongStrings;

// Create a strong type by deriving a record class from StrongStringAbstract<TDerived>:
public record class MyStrongString : StrongStringAbstract<MyStrongString> { }

public class MyDemoClass
{
    public MyStrongString Stronk { get; set; } = new();

    public static void Demo(MyStrongString inStrongString, string inSystemString, out MyStrongString outStrongString, out string outSystemString)
    {
        // You can implicitly cast down to a System.String
        outSystemString = inStrongString;

        // You must explicitly cast up to a StrongString
        outStrongString = (MyStrongString)inSystemString;

        //You can provide a StrongString to a method that expects a System.String
        Path.Combine(inStrongString, inSystemString);

        // You can use the .WeakString property or the .ToString() method to get the value of the underlying System.String
        outSystemString = inStrongString.WeakString;
        outSystemString = inStrongString.ToString();

        // You can not implicitly cast up to a StrongString
        // outStrongString = inSystemString; // This will not compile

        // You can not cast from one StrongString to another
        // OtherStrongString other = inStrongString; // This will not compile
        // OtherStrongString other = (OtherStrongString)inStrongString; // This will not compile either
    }
}

Validation Example

public abstract class StartsWithHttp : IValidator
{
    public static bool IsValid(AnyStrongString? strongString)
    {
        ArgumentNullException.ThrowIfNull(strongString);

        return strongString.StartsWith("http", StringComparison.InvariantCultureIgnoreCase);
    }
}

public abstract class EndsWithDotCom : IValidator
{
    public static bool IsValid(AnyStrongString? strongString)
    {
        ArgumentNullException.ThrowIfNull(strongString);

        return strongString.EndsWith(".com", StringComparison.InvariantCultureIgnoreCase);
    }
}

public record class MyValidatedString : StrongStringAbstract<MyValidatedString, StartsWithHttp, EndsWithDotCom> { }

// This will work:
MyValidatedString valid = (MyValidatedString)"http://example.com";

// This will throw a FormatException:
MyValidatedString invalid = (MyValidatedString)"ftp://example.net";

Advanced Usage

Creating Domain-Specific String Types

using ktsu.StrongStrings;

// Define validators
public abstract class ValidEmail : IValidator
{
    private static readonly Regex EmailRegex = new Regex(@"^[^@\s]+@[^@\s]+\.[^@\s]+$");
    
    public static bool IsValid(AnyStrongString? strongString)
    {
        ArgumentNullException.ThrowIfNull(strongString);
        return EmailRegex.IsMatch(strongString.ToString());
    }
}

// Create domain-specific types
public record class EmailAddress : StrongStringAbstract<EmailAddress, ValidEmail> { }
public record class Username : StrongStringAbstract<Username> { }
public record class UserId : StrongStringAbstract<UserId> { }

// Use in a service
public class UserService
{
    public User GetUser(UserId id) { /* ... */ }
    
    public void SendEmail(EmailAddress to, string subject) { /* ... */ }
    
    // Type safety ensures you can't pass a Username where UserId is expected
}

Modifying Strong Strings

// Strong strings are immutable, but you can create new ones with modifications
public record class Path : StrongStringAbstract<Path> { }

Path basePath = (Path)"/home/user";

// Add prefixes or suffixes
Path documentsPath = basePath.WithSuffix("/documents");  // "/home/user/documents"
Path etcPath = (Path)"/etc".WithSuffix("/config");       // "/etc/config"

// Combine with standard string methods
Path combined = (Path)(basePath + "/downloads");         // "/home/user/downloads"

API Reference

StrongStringAbstract<TDerived>

The base class for creating strongly-typed strings.

Properties

Methods

IValidator Interface

Interface for implementing custom validation rules.

Methods

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure to update tests as appropriate.

License

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