Rustly 10.2.1

Rustly (v10.2.1)

Rust-inspired Result<T, E>, Option<T>, Unit, and EnumValue types for C#. Replace exceptions with explicit, composable error handling. Zero-allocation value types.

All types and helpers are auto-imported when you add the package -- no using statements needed.

Installation

dotnet add package Rustly --version 10.2.1

Types

Usage

Option<T>

// Implicit conversion: T -> Some(T)
Option<int> age = 25;                        // Some(25)
Option<string> name = "Alice";               // Some("Alice")

// None via default
Option<int> empty = default;                 // None
Option<string> noName = default;             // None

// Note: Option<object> cannot be assigned null directly -- use default
Option<object> obj = default;                // None (correct)
// Option<object> obj = null;                // compile error

// Explicit cast: Option<T> -> T (equivalent to Unwrap)
int value = (int)age;                        // 25

// Safe access
Option<string> FindUser(int id) =>
    id == 1 ? Some("Admin") : None<string>();

string name = FindUser(1).UnwrapOr("Unknown");

// Chaining
var greeting = FindUser(1)
    .Map(n => $"Hello, {n}!")
    .UnwrapOr("Hello, stranger!");

// Filtering
var admin = FindUser(1).Filter(n => n == "Admin");

// Convert to Result
Result<string, string> r = FindUser(42).OkOr("User not found");

// Pattern matching (U is inferred from lambdas)
var message = FindUser(42).Match(
    n => $"Found: {n}",
    () => "Not found"
);

Result<T, E>

// Implicit conversion: T -> Ok(T)
Result<int, string> Divide(int a, int b) =>
    b == 0 ? Err<int, string>("Division by zero") : a / b;

// Explicit cast: E -> Err(E)
Result<int, string> err = (Result<int, string>)"something went wrong";

// Explicit cast: Result<T, E> -> T (equivalent to Unwrap)
int value = (int)Divide(10, 2);              // 5

// Pattern matching (U is inferred from lambdas)
string message = Divide(10, 0).Match(
    value => $"Result: {value}",
    error => $"Error: {error}"
);

// Chaining
var doubled = Divide(10, 2)
    .Map(x => x * 2)
    .UnwrapOr(0);

// Composition
var final = Divide(10, 2)
    .AndThen(x => Divide(x, 3))
    .MapErr(e => $"Pipeline failed: {e}");

// Querying
bool isPositive = Divide(10, 2).IsOkAnd(x => x > 0);
bool isBadInput = Divide(10, 0).ContainsErr("Division by zero");

Result<Unit, E> (void operations)

Result<Unit, string> SaveFile(string path)
{
    // ... operation ...
    return Unit.Value;  // implicit Unit -> Ok
}

SaveFile("/tmp/data.txt")
    .InspectErr(e => Console.WriteLine($"Save failed: {e}"));

Combining

// Zip two options
var pair = Some(1).Zip(Some("hello"));  // Some((1, "hello"))

// Flatten nested types
Option<Option<int>> nested = Some(Some(42));
Option<int> flat = nested.Flatten();  // Some(42)

// Transpose
Option<Result<int, string>> optRes = Some(Ok<int, string>(42));
Result<Option<int>, string> resOpt = optRes.Transpose();  // Ok(Some(42))

// Xor
var a = Some(1);
var b = None<int>();
var x = a.Xor(b);  // Some(1) -- exactly one is Some

EnumValue -- Rust-style Enum Variants

public enum LogLevel
{
    [EnumValue("TRC")] Trace,
    [EnumValue("DBG")] Debug,
    [EnumValue("INF")] Info,
}

// Value<T>() returns Option<T> -- no nullable
Option<string> label = LogLevel.Trace.Value<string>();   // Some("TRC")
Option<string> none  = LogLevel.Trace.Value<int>();      // None (wrong type)

// RawValue() returns Option<object>
Option<object> raw = LogLevel.Info.RawValue();           // Some("INF")

EnumValue JSON Serialization

// System.Text.Json -- apply per-enum or globally via factory
using System.Text.Json;
using Rustly.Serialization;

[JsonConverter(typeof(EnumValueJsonConverter<LogLevel>))]
public enum LogLevel { [EnumValue("TRC")] Trace, [EnumValue("DBG")] Debug }

JsonSerializer.Serialize(LogLevel.Trace);                // "TRC"
JsonSerializer.Deserialize<LogLevel>("\"TRC\"");         // LogLevel.Trace

// Global factory -- auto-detects all enums with [EnumValue]
var options = new JsonSerializerOptions();
options.Converters.Add(new EnumValueJsonConverterFactory());

// Newtonsoft.Json -- works on all platforms including netstandard2.1
using Newtonsoft.Json;
using Rustly.Serialization.Newtonsoft;

var settings = new JsonSerializerSettings();
settings.Converters.Add(new EnumValueNewtonsoftJsonConverter());
JsonConvert.SerializeObject(LogLevel.Trace, settings);   // "TRC"

JSON Serialization (Option & Result)

Option<T> and Result<T, E> work with System.Text.Json automatically (.NET 5+). No registration needed:

// System.Text.Json (auto, .NET 5+)
JsonSerializer.Serialize(Some("hello"));                 // "hello"
JsonSerializer.Serialize(None<string>());                // null
JsonSerializer.Serialize(Ok<int, string>(42));           // {"ok":42}
JsonSerializer.Serialize(Err<int, string>("fail"));      // {"err":"fail"}

// Newtonsoft.Json (register converters)
using Rustly.Serialization.Newtonsoft;

var settings = new JsonSerializerSettings();
settings.Converters.Add(new OptionNewtonsoftJsonConverter());
settings.Converters.Add(new ResultNewtonsoftJsonConverter());

JsonConvert.SerializeObject(Some(42), settings);                     // 42
JsonConvert.SerializeObject(Option<string>.None, settings);          // null
JsonConvert.SerializeObject(Result<int, string>.Ok(42), settings);   // {"ok":42}

EnumValue TypeConverter (Configuration.Binder)

using System.ComponentModel;
using Rustly.Converters;

[TypeConverter(typeof(EnumValueTypeConverter))]
public enum LogLevel
{
    [EnumValue("TRC")] Trace,
    [EnumValue("DBG")] Debug,
}

// appsettings.json: { "MinimumLevel": "TRC" }
// Binds to LogLevel.Trace via EnumValueTypeConverter

Configuration Binding (Option<T>)

public class AppSettings
{
    public Option<string> ConnectionString { get; set; }
    public Option<int> MaxRetries { get; set; }
}

// appsettings.json:  { "MaxRetries": 5 }
var settings = new AppSettings();
configuration.GetSection("App").Bind(settings);

var retries = settings.MaxRetries.UnwrapOr(3);   // 5 (from config)
var connStr = settings.ConnectionString;          // None (not in config)

API Reference

Result<T, E>

Option<T>

Prelude (auto-imported)

License

MIT