avoid_dollar_outside_do_frame

v1.0.0 Warning fpdart

This rule flags a call to a Do block’s extraction function ($) that sits inside a callback nested within the block, rather than in the block’s own frame.

Why use this rule

$ short-circuits by throwing a private marker that the Do constructor catches. That mechanism only works while control is still inside the block’s own frame.

Called from a map or flatMap callback, the marker unwinds through fpdart’s own combinator machinery, which never expects it. Instead of the Left the code appears to produce, the caller gets a raw exception — or, when an intermediate layer swallows it, a silently wrong result.

This is one of four Do pitfalls that fpdart documents in its own do_constructor_pitfalls example.

See also: fpdart: Do notation

Don’t

$ is called from inside a map callback, so its short-circuit unwinds through fpdart’s combinator machinery instead of the block:

Option<String> hostname(Option<String> rawUrl, Option<String> fallback) =>
    Option.Do(
      ($) => $(rawUrl).map(
        (url) => $(fallback), // `$` outside the Do's own frame
      ),
    );

Do

Extract in the block itself, then use the plain values in the callback:

Option<String> hostname(Option<String> rawUrl, Option<String> fallback) =>
    Option.Do(($) {
      final url = $(rawUrl);
      final host = $(fallback);
      return url.isEmpty ? host : url;
    });

Known limitations

A $ tear-off passed to another function and called from there is not reported. The rule is about lexical position, and an escaped $ is a different — and much rarer — problem.

An inner Do block’s $ belongs to that inner frame, so the outer block is not blamed for it. The nesting itself is reported by avoid_nested_do_notation.

Configuration

This rule is in the core preset, so it is on with preset: core, preset: recommended or preset: opinionated.

To turn it off:

many_lints.yaml

rules:
  avoid_dollar_outside_do_frame: false

To keep the rule on but skip certain paths, use per-rule exclude.

Related rules

• avoid_bare_await_in_do — Awaiting a raw Future inside a Do block escapes the block’s tracking.
• avoid_nested_do_notation — A nested Do block short-circuits on its own instead of failing the outer pipeline.
• prefer_do_notation — Deeply nested flatMap callbacks read flatter as a Do block.
• avoid_ad_hoc_left_type — A pipeline only composes when every step shares one error type.