Delay

What it is

Delay inserts a fixed pause before, after, or around each function execution.

When to use it

  • Adding a small artificial delay to match user expectations (e.g., “saving…” animations).
  • Pacing outgoing requests to avoid bursts.
  • Combining with repeat() to create simple polling loops.

Async / sync support

WrapperSupport
Func<R>✅ Async
Func1<T, R>✅ Async
Func2<T1, T2, R>✅ Async
FuncSync<R>❌ No

API reference 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

// api-reference
// On Func<R>
Func<R> delay(
  Duration duration, {
  DelayMode mode = DelayMode.before,
});

// On Func1<T, R>
Func1<T, R> delay(
  Duration duration, {
  DelayMode mode = DelayMode.before,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> delay(
  Duration duration, {
  DelayMode mode = DelayMode.before,
});

enum DelayMode { before, after, both }

Parameters

ParameterTypeDefaultDescription
durationDurationrequiredDuration of the pause.
modeDelayModebeforeWhen to pause: before, after, or both.

Examples

Basic example 

1
2
3
4
5
6

final ping = Func<String>(() async => 'pong').delay(
  Duration(seconds: 1),
  mode: DelayMode.before,
);

print(await ping()); // waits 1s, then prints "pong"

Real-world example 

1
2
3
4
5
6
7
8

final poll = Func<Status>(() async => api.status() as Status).delay(
  Duration(seconds: 5),
  mode: DelayMode.before,
);

final ready = await poll
  .repeat(times: 10, until: (s) => s.ready);
print(ready);

Best practices

  • Use before for pacing and rate smoothing.
  • Use after when you want to guarantee a minimum visible duration (e.g., animations).
  • Avoid very long after delays in hot paths because they block the caller.

Common pitfalls

  • Unexpected total latency: DelayMode.both adds the delay twice plus execution time.
  • Not composable with sync code: Delay is async-only; it cannot wrap synchronous functions.