EnumCraft.Core 0.2.0-preview

EnumCraft.Core

Type-safe enumerations and flags with rich metadata for .NET

What is EnumCraft?

EnumCraft provides type-safe alternatives to standard C# enums with rich metadata, compile-time safety, and powerful features. Say goodbye to magic numbers and hello to strongly-typed enumerations!

Features

✅ TypedEnums - Smart enumerations with rich metadata
✅ TypedFlags - Type-safe bitwise flags (like [Flags] but better)
✅ Multiple ID Types - Support for int, long, short, Guid, string, and more
✅ JSON Serialization - Built-in support for clean JSON output
✅ Extensibility - Easy to extend with custom behavior
✅ Multi-Targeted - Works with .NET Framework 4.7.2+ and .NET Standard 2.0+

Quick Start

Installation

dotnet add package EnumCraft.Core

TypedEnum Example

using EnumCraft;

public class OrderStatus : TypedEnumInt<OrderStatus>
{
    public static readonly OrderStatus Pending   = new(1, "Pending", nameof(Pending));
    public static readonly OrderStatus Confirmed = new(2, "Confirmed", nameof(Confirmed));
    public static readonly OrderStatus Shipped   = new(3, "Shipped", nameof(Shipped));
    public static readonly OrderStatus Delivered = new(4, "Delivered", nameof(Delivered));
    
    private OrderStatus(int id, string description, string code)
        : base(id, description, code) { }
}

// Usage
var status = OrderStatus.Pending;
Console.WriteLine(status.ID);          // 1
Console.WriteLine(status.Description); // "Pending"
Console.WriteLine(status.Code);        // "Pending"

// Get all values
var allStatuses = OrderStatus.GetAll();

// Get by ID
var confirmed = OrderStatus.GetByID(2);

// JSON serialization
string json = status.AsJsonString();
// {"id":1,"description":"Pending","code":"Pending"}

TypedFlags Example

using EnumCraft;

public class Permissions : TypedFlagInt<Permissions>
{
    public static readonly Permissions None    = new(0, "None", nameof(None));
    public static readonly Permissions Read    = new(1, "Read", nameof(Read));
    public static readonly Permissions Write   = new(2, "Write", nameof(Write));
    public static readonly Permissions Execute = new(4, "Execute", nameof(Execute));
    public static readonly Permissions Delete  = new(8, "Delete", nameof(Delete));
    public static readonly Permissions All     = new(15, "All", nameof(All));
    
    private Permissions(int id, string description, string code)
        : base(id, description, code) { }
}

// Usage - Combine flags with bitwise operators
var userPerms = Permissions.Read | Permissions.Write;

// Check flags
if (userPerms.HasFlag(Permissions.Read))
{
    Console.WriteLine("User can read");
}

// Check multiple flags
bool canEdit = userPerms.HasAllFlags(Permissions.Read, Permissions.Write);

// Decompose combined flags
var flags = userPerms.ToFlags();
// Returns: [Permissions.Read, Permissions.Write]

// Logical NOT
var notRead = Permissions.All & ~Permissions.Read;

Available Types

TypedEnum Variants

TypedFlag Variants

Why EnumCraft?

vs. Standard Enums

Standard Enum:

public enum OrderStatus
{
    Pending = 1,
    Confirmed = 2
}

// Problems:
var status = (OrderStatus)999;  // Compiles! Runtime chaos
string desc = status.ToString(); // Just "999" - not helpful

TypedEnum:

public class OrderStatus : TypedEnumInt<OrderStatus>
{
    public static readonly OrderStatus Pending = new(1, "Order Pending", nameof(Pending));
}

// Benefits:
var status = OrderStatus.GetByID(999); // Throws ArgumentOutOfRangeException
string desc = status.Description;      // "Order Pending" - rich metadata

vs. String Constants

String Constants:

public static class Status
{
    public const string Pending = "pending";
    public const string Confirmed = "confirmed";
}

// Problems:
string status = "pendin"; // Typo - compiles, fails at runtime

TypedEnum:

OrderStatus status = OrderStatus.Pending; // Type-safe, no typos possible

Advanced Features

Custom ToString Formatting

var status = OrderStatus.Pending;

status.ToString("D");  // "Order Pending" (Description)
status.ToString("C");  // "Pending" (Code)
status.ToString("I");  // "1" (ID)
status.ToString("F");  // "ID: 1, Description: Order Pending, Code: Pending"

JSON Serialization

var status = OrderStatus.Pending;

// Simple
string json = status.AsJsonString();

// With options
var options = new JsonSerializerOptions { WriteIndented = true };
string json = status.AsJsonString(options);

TypedFlags - Advanced

// Fluent API (requires EnumCraft.Extensions)
var perms = Permissions.None
    .With(Permissions.Read)
    .With(Permissions.Write)
    .Without(Permissions.Delete);

// Decomposition
var combined = Permissions.Read | Permissions.Write | Permissions.Execute;
foreach (var flag in combined.ToFlags())
{
    Console.WriteLine(flag.Code);
}
// Output: Read, Write, Execute

Framework Support

Related Packages

• EnumCraft.FeatureFlags - Feature flag system built on TypedEnums with tenant-specific overrides

Documentation

For comprehensive documentation, examples, and best practices, visit:

• GitHub Repository
• API Documentation (coming soon)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Author

Randel Bjorkquist
GitHub | NuGet