rop-patterns

Railway-Oriented Programming (ROP) Patterns

This skill guides correct use of the GA.Core.Functional monadic types in Guitar Alchemist. Consult it whenever writing or reviewing service-layer C# code.

The Four Types — When to Use Each

Type	Use when	Success side	Failure side
Try<T>	Wrapping an operation that might throw (infrastructure calls, parsing)	T value	Exception
Result<T, TError>	Business logic with explicit typed errors	T value	TError (e.g. ChordError)
Validation<T>	Input validation that should accumulate multiple errors	T value	IReadOnlyList<string>
Option<T>	A value that may legitimately be absent (lookup by id)	Some(T)	None

The Core Rule

Service methods must never throw. Return a monadic type instead.

// ❌ WRONG — naked throw leaks past the service boundary
public async Task<List<Chord>> GetByQualityAsync(string quality)
{
    if (string.IsNullOrWhiteSpace(quality))
        throw new ArgumentException("Quality required");  // ← forces caller to catch
    return await _db.GetChordsByQualityAsync(quality);
}

// ✅ CORRECT — caller gets typed information, no try/catch needed
public async Task<Result<List<Chord>, ChordError>> GetByQualityAsync(string quality)
{
    var validation = ValidateQuality(quality);
    if (validation.IsInvalid)
        return Result<List<Chord>, ChordError>.Failure(
            new ChordError(ChordErrorType.ValidationError, validation.Errors.First()));

    var tryResult = await Try.OfAsync(() => _db.GetChordsByQualityAsync(quality));
    return tryResult.Match<Result<List<Chord>, ChordError>>(
        onSuccess: chords => Result<List<Chord>, ChordError>.Success(chords),
        onFailure: ex  => Result<List<Chord>, ChordError>.Failure(
            new ChordError(ChordErrorType.DatabaseError, ex.Message)));
}

Boundary Rule — Controllers and CLI Entry Points May Throw

Exceptions from external inputs (invalid HTTP payloads, bad CLI args) are fine to catch at the boundary and convert to HTTP status codes or exit codes. Internal service layers must not throw.