Proposal: Replacing guard with when => for Fail-Fast Error Handling

[snnsnn]

Overview

Replace the current guard ... else { ... } syntax with a cleaner, more intuitive expression form:

when <condition> => <error-value>

This expression enables concise, readable, and fail-fast logic for early returns in functions—particularly useful with Result, Option, or fail!.

Motivation

The guard ... else { ... } statement in MoonBit provides a mechanism for early exit, but it often feels cryptic and awkward to use in practice. Developers are required to reason in reverse — writing what must be true to continue, rather than directly expressing what causes a failure. This inversion is unnatural and can lead to misunderstandings, especially for new users or those coming from other languages.

Furthermore, the syntax is visually noisy:

• The else {} block adds boilerplate even for simple returns
• The logic is easy to misread at a glance due to its inversion
• It breaks linear, top-down reading flow in error-heavy functions

For example, in a function checking input validity:

guard s != "" else { Err(EmptyInput) }

This reads as: “Assume this is not empty; otherwise return an error.” But in real code, the intent is usually to detect failure conditions directly: “If this is empty, return an error.”

This mismatch makes guard feel more difficult to reason about and less natural for expressing failure cases.

By replacing guard with when, we allow developers to write fail-fast logic in a way that mirrors natural reasoning: describe the failure condition directly, then exit cleanly.

Proposed Syntax

when <failure_condition> => <error_value>

Semantics

If <failure_condition> evaluates to true, immediately return <error_value> from the function.

This construct fully replaces guard ... else { ... }, offering a clearer and less verbose experience.

Examples

Example 1: Parsing

type! ParseError {
  EmptyInput
  InvalidFormat
}

fn parse_int(s: String) -> Result[Int, ParseError] {
    when s == "" => Err(EmptyInput);
    when not(s.chars().all(Char.is_digit)) => Err(InvalidFormat);
    Ok(s.to_int())
}

Example 2: Input Validation

fn compute(x: Int, y: Int) -> Result {
  when x <= 0 => Err("x must be positive");
  when y == 0 => Err("y must not be zero");
  when x >= 100 && y >= 100 => Err("values too large");

  let result = x / y;
  return Ok(result);
}

Example 3: Index Check (Option)

fn get_element(arr: Array[Int], i: Int) -> Option[Int] {
    when i >= 0 && i < arr.length() => None
    Some(arr[i])
}

Example 4: Required Field (Replicating docs)

fn read_username(input: String) -> Option[String] {
    let trimmed = input.trim()
    when trimmed == "" => None
    Some(trimmed)
}

Example 5: Fail Fast

fn get_value(x: Int) -> Int {
    when x < 0 => fail!("Negative values not allowed: {}", x)
    x
}

Example 5: Multiple when in a Pipeline

type! LoadError {
  NotFound
  PermissionDenied
}

fn read_file(path: String, user: User) -> Result[String, LoadError] {
    when not(file_exists(path)) => Err(NotFound)
    when not(user.has_permission(path)) => Err(PermissionDenied)
    Ok(read_contents(path))
}

Comparison with Existing Syntax

Intent	Current (guard)	Proposed (when =>)
Empty string check	guard s != "" else { Err(...) }	when s == "" => Err(...)
Out-of-bounds check	guard i < arr.length else { None }	when i >= arr.length => None
Fatal error	guard valid else { fail!(...) }	when !valid => fail!(...)

Reasoning Comparison: guard vs when =>

Aspect	guard	when =>
Mental model	Assert success and exit on failure	Detect failure and return explicitly
Condition logic	Positive condition (invert for failure)	Write the actual failure condition directly
Readability	Good, but takes getting used to	More intuitive and linear
Verbosity	Requires else { ... } block	Concise with no braces
Emphasis	What must be true	What causes early exit
Style	Defensive / assertive	Declarative / fail-first
Use case fit	Best for validation gates	Best for clean, readable exit handling

Why => Instead of {}

The choice to use => instead of a block-based else { ... } syntax is deliberate. The => token:

• Emphasizes the expression-based nature of the syntax
• Keeps the construct concise and single-line friendly
• Avoids the visual and structural clutter of braces for simple returns
• Aligns with other modern, lightweight match/arrow syntaxes (e.g., Rust's match, Scala's case =>, JavaScript arrow functions)

Encourages Thinking in Terms of Failures

Another subtle but powerful benefit of using => is that it naturally nudges developers to think in terms of failure cases. Rather than expressing what must be true (as in guard) and then writing an inverted fallback, developers instead express:

“When this specific thing goes wrong, exit immediately with this value.”

This maps closely to how humans reason about validation, checks, and failures in real-world logic. The => token visually and semantically reflects a directional control flow: from a known error condition toward an early return.

Using => also allows:

• A consistent look in pipelines of when expressions
• Easier parsing and less indentation overhead
• A clear visual distinction between when and traditional control blocks

The simplicity and readability of when <cond> => <value> mirrors the mental model of: “If this condition is true, immediately yield this result.”

Why when?

The keyword when was chosen because it reads naturally in the context of early-exit logic:

when condition => fallback

• Reads like: “When this is true, exit with that”
• Aligns closely with natural language and decision-making
• Fits functional and imperative styles
• One word, minimal punctuation

Alternatives Considered

We explored a number of one-word and minimal alternatives to replace guard. Our goals were:

• Natural language flow
• Clarity in expressing failure
• Minimal syntax and noise

Keyword	Pros	Cons
fail	Clear error signal	Too strong for soft exits like Option
exit	Control-flow friendly	Feels imperative
check	Simple and neutral	Lacks return/exit semantics
if	Familiar	Too generic; syntax conflict
do	Ultra-short	Ambiguous and overloaded

Grammar Considerations

• when is a keyword expression that evaluates the condition.
• => separates the fallback/early-return value.
• Only usable inside function bodies.
• Type of <fallback_value> must match function return type.
• <condition> must evaluate to Boolean.

Conclusion

Replacing guard ... else { ... } with when => results in clearer, more expressive fail-fast logic that better aligns with human reasoning. The when => syntax makes error conditions visually and semantically clear, improves ergonomics, and reduces boilerplate—all while keeping the language syntax minimal and familiar.

This proposal aims to simplify error-handling syntax in MoonBit by providing a more direct alternative to guard. I believe when => improves clarity in everyday code, reduces boilerplate, and fits naturally with pattern-matching-based control flow. It aligns well with the language’s existing principles and helps reduce the chance of errors in early-exit scenarios.

I'd appreciate feedback, ideas, or counterpoints from others who have worked with guard in real code. It’s intended as a practical refinement to patterns already common in real-world MoonBit code and worth considering on those merits.

[gmlewis]

My first reaction is that guard is much more flexible and powerful than I think is given credit above.
Not only can it do early returns, raise errors, or allow side effects (due to the mandatory block... such as logging, etc.), but it also handles pattern matching that can be further used in the following statements and final expression.

Just today I found its pattern matching super helpful:
https://github.com/gmlewis/moonbit-jsonrpc2/blob/master/message.mbt#L84-L85

pub fn as_call(self : Message) -> Request? {
  guard self is Request(req) else { return None }
  guard req.id is Some(_) else { return None }
  Some(req)
}

This would have been much more verbose with multi-line "match" statements (which honestly I really prefer to avoid whenever possible).

Additionally, I'm having troubles understanding "Example 2" above:

  when x > 0  => Err("x must be positive");
  when y != 0 => Err("y must not be zero");
  when x < 100 && y < 100 => Err("values too large");

So when "x > 0", return an error that "x must be positive"... is this a typo?
Same with "y != 0"... and in fact same with the last one. Those don't make sense to me.

If those are simply typos, then I can see the value of a quick and easy return... however, I really like the pattern-matching capabilities of the guard statement and would sorely miss it if it were removed.

Maybe there is room for both guard and when ?

[snnsnn]

My first reaction is that guard is more flexible and powerful than it's been given credit for above.

The original intent of the guard statement is to reduce deeply nested if let constructs by offering a cleaner, flatter alternative—specifically guard let. In that context, side effects aren’t really the main concern. In fact, it’s generally not recommended to rely on side effects inside guard ... else blocks, since they’re designed as conditional early-exit constructs, not for arbitrary control flow.

From what I’ve seen in other languages, guard statements are meant to conditionally allow execution to continue based on a boolean expression. They’re commonly used as a clear and concise way to exit early when a condition isn't met—similar in spirit to early return or error propagation patterns in other languages.

At their core, guard statements are designed to simplify early-exit logic and improve code clarity in a few key ways:

Early Exit / Fail Fast

If the condition evaluates to false, the else block runs and the function typically returns early—often with an error or default value.

Reduced Cognitive Load

Instead of deeply nested if statements, guard clauses let you define preconditions up front, keeping the remaining logic linear and easy to follow.

Error Handling

They're widely used for validating input, checking invariants, and enforcing preconditions—core tasks in writing robust code.

Because guard expresses a common early-exit pattern in a standardized form, it gives the compiler more room to analyze control flow and apply optimizations—such as better jump prediction, streamlined branching, or lower-level code generation.

• Better control-flow analysis
• Improved branch prediction
• Lower-level code generation with fewer jumps

These kinds of optimizations are harder to apply when equivalent logic is expressed using scattered if/return constructs.

On the pattern matching side—yes, you’re right to bring up the as_call function example. I didn’t include similar examples earlier, but I agree that when should support destructuring and variable bindings just like guard.

That said, we shouldn't conflate flexibility with good design. If we want to generate better optimized code and reduce complexity, we should lean toward constructs that limit flexibility in favor of clarity and structure. For everything else, we still have if.

I was trying to come up with a syntax that complements pattern matching both syntactically and logically, but focuses specifically on filtering out error cases to clear the way for the happy path. The goal is to encourage a flat, linear style—avoiding nesting and improving readability, especially when there are multiple early-exit conditions. Pattern matching is ideal for structural validation—checking if a value has the right shape—but it becomes verbose or awkward when additional logical constraints are layered on. The when construct fills that gap by allowing invalid conditions to be filtered out in a concise, expression-friendly way that aligns naturally with early exits and implicit error propagation in expression-based code.

If those are simply typos

Yes — after several iterations, some mistakes slipped in. I was using AI to help come up with real-world use cases, but it kept falling back to outdated syntax or invalid logic instead of producing realistic examples.

Thanks for taking the time to read and share your thoughts—it's helpful to get other perspectives.

[peter-jerry-ye]

If I understand correctly, I think what you proposed is just:

if something is failure {
  let result = f(failure)
  return result
}
return success

While guard is the exact opposite:

guard something is success else {
  return failure
}
let result = f(success)
return result

[snnsnn]

Yes, but with a syntax that mirrors pattern matching, meaning => should be followed by error types only.

type! Error

if something is failure => Error;

return success

For side effects, a block that evaluates to an error may follow:

type! Error

if something is failure => {
  // Run side effects here.
  Error
};

return success

This new syntax creates a clear control flow for errors that runs alongside the happy path. We now have two parallel but clearly separated paths—one handling errors, the other handling success.

Since MoonBit has a distinct syntax for errors—namely, type! Err—it also enforces a uniform error model across the language.

Since conditions read positively, and the syntax is very clear and easy to read, it will provide mental clarity. Because => consistently yields an error, it provides a predictable pattern that should be easier to optimize at the compiler level.

Edit: I should have used <error-value> when describing the return value in the proposed syntax:

when <condition> => <error-value>

Fixed it.

[Metalymph]

Hi all! My two cents on this:
When is not necessary due to multiple reasons:

1. If you want to match over an error variant given a function call, you already have try catch and try catch!
2. As a shortcut you've call?() to receive a Result to match over for a careful data handling, and call!() to rethrow the error.
3. Guard statement is meant to split the logic of the main codepath from the error one, simplifying the following idea: "Ok I want this data to be of this type, or this condition to stay there, else...let's manage the error". guard is not only a gate, but a clear way to instantiate a logical requirement (e.g: a resource like a connection, socket, file descriptor, etc...).

Using when would require an other pattern matching later on the main codepath, to be consistent with the right data flow. It's only a way to express this:

if result is Err(error) {
  match err { ... } // or even `return err`
}

Which is already addressed by result.unwrap_or_error!() in the case of return err.

Small Counter-Proposal

That said, what I was thinking is that guard could be more powerful compared to other programming languages.
What I mean is empowering guard statement else branch with an implicit matched declaration, exactly what already happens with try catch.
Let's give an example:

fn ok(toggle: Bool) -> String {
  guard toggle else {
    // The implicit value is useless so is discarded by compiler
    return "a"
  }
  return "ok"
}

Let's evolute it a bit:

fn message_from_future(year: Uint16) -> String {
  guard num < 2026 else {
   // Here the implicit value is involved and compiler already knows what to match over
    2026..<3026 => "You're in the next millennium!"
    _ => "A future too far away, dude!"
  }
  year
}

An other more interesting one:

fn check(year~: Result[UInt64, @strconv.StrConvError] = @strconv.parse_uint64?("2025")) -> UInt64! {
  guard year is Ok(num) else {
    @strconv.StrConvError(message) => fail!(message)
  }
  num
}

Instead of adding more syntax and keyword, or even break the guard backward compatibility, why not simply enhance it to be able to manage each possible case?
Thanks a lot for reading and your time!

[snnsnn]

@Metalymph I believe there are a few misunderstandings. We are trying to come up with a convenience; otherwise, guard is also unnecessary since we can achieve the same outcome using if/else blocks.

A guard let statement is a control flow construct you find in some languages that lets you early-exit if a condition isn’t met, while safely unwrapping or binding a value. It is not about handling errors but about providing a linear code flow while unwrapping and binding a value. Instead of deeply nesting our code inside multiple if blocks, we "guard" our assumptions up-front. If the condition fails, we exit immediately.

The guard let statement complements the if let statement. guard let name = person["name"] tries to extract the "name" key from the dictionary. If name is nil, it immediately executes the else block (which must exit the current scope). Otherwise, after the guard, you are guaranteed that name is a valid, non-optional value.

if let introduces a new local scope (inside the if block); guard let forces success to continue — failure leads to immediate exit.

Let's have a simple example:

fn greet(person: [String: String]) {
    guard let name = person["name"] else {
        print("No name provided.")
        return
    }

    print("Hello, \(name)!")
}

While the 'guard' terminology can make sense metaphorically by conveying the idea of guarding assumptions, there are a few downsides associated with the word guard and how it executes. More specifically, its try logic reads inverted, and the following else blocks make it even harder to reason about.

From your third argument, I believe we completely agree on the use of the guard statement. The main issue with the guard statement is that the try conditional reads inverted, and the else branch creates convoluted control flow. While many developers find early exits beneficial to prevent nesting, the inverted reading and the resulting structure can still make the flow harder to reason about compared to a more straightforward binding-first approach. Also, the word guard itself does not convey our intent.

Regarding your suggestion to enhance guard: while it is an interesting idea, the core inverted flow of guard remains, which is what when aims to avoid.

The same logic with a when statement:

fn greet(person: [String: String]) {
    when let name = person["name"] => Err("Missing name");
    // Use name here
}

The code reads: when the condition is satisfied, do the binding; else, exit immediately. The arrow syntax provides clarity and forces us to return a single value by collapsing multiple failing conditions into a single value, maintaining a flat, linear code structure.

While pattern matching branches into multiple distinct execution paths based on data structure or condition, when does the opposite: it collapses multiple failing conditions into a single, unified exit. This maintains a flat, linear code flow, where failures are handled early and uniformly without creating multiple branches.

The word when may not be the best, but it is the clearest option I could come up with to convey our intent. I am open to suggestions, and in my original proposal, I also suggested alternative keywords to better match the intended meaning.

If there are multiple points of failure that would otherwise require separate guard clauses, we can stack them up, as I showed in earlier examples.

when x > 0  => Err("x must be positive");
when y != 0 => Err("y must not be zero");
when x < 100 && y < 100 => Err("values too large");

// use x and y here

Now, the code reads naturally, with absolute clarity.

The try/catch blocks do not provide the same level of flexibility or flattened flow. Catching an error and pattern-matching on its value is not the same as using a guard/when statement. With when, we return a value, but with try/catch, we handle an error. With try/catch plus pattern matching, we introduce an indirection.

The when construct complements pattern matching at the language level: while pattern matching branches execution based on value shape, when enforces preconditions in a flat, linear way. Together, they enable a clean separation between validating assumptions and handling diverse cases, allowing both safer and clearer code structures.

While backward compatibility is important, I believe it should not constrain us at this point. Our focus should be on designing the best possible syntax, learning from the experiences of other programming languages, even if it requires careful adjustments later. I am not saying we should break the existing syntax for trivial reasons, but the way I see it, we are trying to create the best possible syntax.