funx

Advanced Cache

Sun, 21 Jun 2026 18:27:01 +0000

Advanced Cache

What it is

The funx performance package includes a small family of pluggable cache backends and helpers that back memoize() and cacheAside(). You can choose the eviction policy, add a weight limit, protect against cache stampedes, and keep a set of keys warm in the background.

When to use it

You need more control than the default in-memory LRU cache.
Cache entries have very different memory costs and you want a weight budget.
Hot keys are requested concurrently and you want only one loader to run.
A subset of keys should be refreshed proactively on a timer.

Components

Component	Purpose
`Cache<K, V>`	Minimal cache interface (`get`, `put`, `remove`, `clear`).
`AdvancedCache<K, V>`	Extends `Cache` with `putEntry`, `getEntry`, and `keys`.
`CacheEntry<V>`	Value plus metadata: `expiresAt`, `weight`, `accessCount`.
`LruCache<K, V>`	Evicts least-recently-used entries.
`LfuCache<K, V>`	Evicts least-frequently-used entries.
`FifoCache<K, V>`	Evicts oldest inserted entries.
`WeightedCache<K, V>`	Wraps another cache and evicts by total weight.
`StampedeProtection<K, V>`	Coalesces concurrent loads for the same key.
`CacheWarmer<K, V>`	Periodically refreshes a set of keys.

API reference

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67


// api-reference
abstract class Cache<K, V> {
 V? get(K key);
 void put(K key, V value);
 void remove(K key);
 void clear();
}

abstract class AdvancedCache<K, V> implements Cache<K, V> {
 void putEntry(K key, CacheEntry<V> entry);
 CacheEntry<V>? getEntry(K key);
 Iterable<K> get keys;
}

class CacheEntry<V> {
 CacheEntry(
 this.value, {
 this.expiresAt,
 this.weight = 1,
 this.accessCount = 1,
 });

 final V value;
 final DateTime? expiresAt;
 final int weight;
 int accessCount;
 bool get isExpired;
}

class LruCache<K, V> implements AdvancedCache<K, V> {
 LruCache({required int maxSize});
}

class LfuCache<K, V> implements AdvancedCache<K, V> {
 LfuCache({required int maxSize});
}

class FifoCache<K, V> implements AdvancedCache<K, V> {
 FifoCache({required int maxSize});
}

class WeightedCache<K, V> implements AdvancedCache<K, V> {
 WeightedCache(
 AdvancedCache<K, V> inner, {
 required int maxWeight,
 required int Function(V value) weigh,
 });

 int get totalWeight;
}

class StampedeProtection<K, V> {
 Future<V> load(K key, Future<V> Function() loader);
}

class CacheWarmer<K, V> {
 CacheWarmer({
 required AdvancedCache<K, V> cache,
 required Future<V> Function(K key) loader,
 required Duration interval,
 required Iterable<K> keys,
 });

 void start();
 void stop();
 bool get isRunning;
}

Examples

Choose an eviction policy

1
2
3


final cache = LfuCache<String, int>(maxSize: 100);
cache.put('a', 1);
print(cache.get('a'));

Weighted cache

1
2
3
4
5
6
7


final cache = WeightedCache<String, String>(
 LruCache<String, String>(maxSize: 1000),
 maxWeight: 1024 * 1024, // 1 MB
 weigh: (value) => value.length,
);
cache.put('a', 'hello');
print(cache.totalWeight);

Stampede protection

1
2
3
4
5
6


final protection = StampedeProtection<String, int>();
final value = await protection.load(
 'key',
 () async => 42,
);
print(value);

Warm a set of keys

1
2
3
4
5
6
7
8
9


final cache = LruCache<String, Product>(maxSize: 10);
final warmer = CacheWarmer<String, Product>(
 cache: cache,
 loader: (id) async => Product(),
 interval: Duration(minutes: 5),
 keys: ['featured', 'new-arrivals'],
)..start();
print(warmer.isRunning);
warmer.stop();

Best practices

Pick the eviction policy that matches your access pattern.
Always provide both maxWeight and weigh when using WeightedCache.
Keep CacheWarmer intervals reasonable to avoid hammering the data source.
Stop warmers and clear caches when disposing long-lived objects.

Common pitfalls

Weight under-counting: WeightedCache only tracks entries inserted through itself; writes made directly to the inner cache are not weighed.
Heavy entries: A single entry heavier than maxWeight is silently rejected.
Timer leaks: CacheWarmer holds a periodic timer; call stop() to avoid leaks.

All

Sun, 21 Jun 2026 18:27:01 +0000

All

What it is

all runs multiple functions concurrently and waits for all of them to complete. It returns a list of results in the same order as the input functions.

When to use it

Fan-out to multiple independent services.
Collecting results from parallel tasks.
Aggregating data from several sources.

Async / sync support

Wrapper	Support
`Func1<T, R>`	✅ Async
`Func2<T1, T2, R>`	✅ Async

API reference

1
2
3
4
5
6


// api-reference
// On Func1<T, R>
Func1<T, List<R>> all(List<Func1<T, R>> functions);

// On Func2<T1, T2, R>
Func2<T1, T2, List<R>> all(List<Func2<T1, T2, R>> functions);

Parameters

Parameter	Type	Description
`functions`	`List<Func1<T, R>>` or `List<Func2<T1, T2, R>>`	Functions to execute in parallel.

Examples

Basic example

1
2
3
4
5


final a = Func1<int, int>((n) async => n + 1);
final b = Func1<int, int>((n) async => n * 2);

final combined = a.all(functions: [b]);
print(await combined(3)); // [4, 6]

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


final getUser = Func1<String, dynamic>(
 (id) async => await api.user(id),
);
final getOrders = Func1<String, dynamic>(
 (id) async => await api.orders(id),
);
final getPreferences = Func1<String, dynamic>(
 (id) async => await api.preferences(id),
);

final dashboard = getUser.all(functions: [getOrders, getPreferences]);
final [user, orders, preferences] = await dashboard('123');
print('$user, $orders, $preferences');

Best practices

Keep functions independent; they run concurrently.
Use all when every result is required.
Combine with individual catchError wrappers if partial failure is acceptable.

Common pitfalls

One failure fails all: If any function throws, the combined future throws.
Ordering: Results are returned in the order of the input list, not completion order.

Audit

Sun, 21 Jun 2026 18:27:01 +0000

Audit

What it is

audit records every invocation, including arguments and outcome, to an optional callback and an in-memory rolling log. It is available for Func1 and Func2.

When to use it

Audit trails for security-sensitive operations.
Debugging intermittent issues by capturing full call history.
Compliance logging.

Async / sync support

Wrapper	Support
`Func<R>`	❌ No
`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
21
22


// api-reference
// On Func1<T, R>
Func1<T, R> audit({
 void Function(AuditLog<T, R> log)? onAudit,
 int maxLogs = 100,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> audit({
 void Function(AuditLog<(T1, T2), R> log)? onAudit,
 int maxLogs = 100,
});

class AuditLog<T, R> {
 final T arguments;
 final R? result;
 final Object? error;
 final DateTime timestamp;
 final Duration duration;
 bool get isSuccess;
 bool get isFailure;
}

Parameters

Parameter	Type	Description
`onAudit`	`void Function(AuditLog)`	Receives a log for every invocation.
`maxLogs`	`int`	Maximum number of logs to retain in memory.

Examples

Basic example

1
2
3
4
5
6
7
8


final logs = <AuditLog<int, int>>[];
final audited = Func1<int, int>((n) async => n * 2).audit(
 onAudit: logs.add,
);

print(await audited(5)); // 10
print(logs.first.arguments); // 5
print(logs.first.result); // 10

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


final auditedTransfer = Func2<String, double, void>(
 (account, amount) async {
 await bank.transfer(account, amount);
 },
).audit(
 onAudit: (log) => auditLog.write(
 'transfer',
 input: '${log.arguments.$1}, ${log.arguments.$2}',
 result: log.result,
 error: log.error,
 ),
);

await auditedTransfer('checking', 100.0);

Best practices

Use an append-only, tamper-evident sink for security audits.
Avoid logging sensitive data; redact PII inside the sink.
Keep the sink fast or send records asynchronously.

Common pitfalls

Sensitive data leaks: Audit records contain raw arguments; sanitize them before storage.
Sink failures: If the sink throws, the wrapper may fail; make it robust.

Backoff

Sun, 21 Jun 2026 18:27:01 +0000

Backoff

What it is

Backoff strategies determine how long to wait between retry attempts. funx provides several built-in strategies and a factory for custom ones.

When to use it

Pairing with retry() to space out repeated attempts.
Implementing polling loops that should slow down over time.
Any retry logic that should avoid fixed-interval hammering.

Async / sync support

Backoff is a pure utility; it is not tied to a wrapper type.

Backpressure

Sun, 21 Jun 2026 18:27:01 +0000

Backpressure

What it is

Backpressure controls what happens when a function receives more requests than it can process. It supports several strategies: drop, dropOldest, buffer, sample, throttle, and error.

When to use it

Real-time dashboards that should drop stale sensor readings.
Click streams where only the latest event matters.
Message queues that should buffer, drop old messages, or reject overload.

Async / sync support

Wrapper	Support
`Func<R>`	❌ No
`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
21
22
23
24
25
26
27
28
29


// api-reference
// On Func1<T, R>
BackpressureExtension<T, R> backpressure({
 required BackpressureStrategy strategy,
 int bufferSize = 100,
 double sampleRate = 0.1,
 int maxConcurrent = 10,
 BackpressureCallback? onOverflow,
 BackpressureCallback? onBufferFull,
});

// On Func2<T1, T2, R>
BackpressureExtension2<T1, T2, R> backpressure({
 required BackpressureStrategy strategy,
 int bufferSize = 100,
 double sampleRate = 0.1,
 int maxConcurrent = 10,
 BackpressureCallback? onOverflow,
 BackpressureCallback? onBufferFull,
});

enum BackpressureStrategy {
 drop,
 dropOldest,
 buffer,
 sample,
 throttle,
 error,
}

Parameters

Parameter	Type	Default	Description
`strategy`	`BackpressureStrategy`	required	Strategy used when overloaded.
`bufferSize`	`int`	`100`	Maximum number of items to buffer for `buffer` and `dropOldest`.
`sampleRate`	`double`	`0.1`	Probability of accepting an item under load for `sample`.
`maxConcurrent`	`int`	`10`	Maximum number of executions running at the same time.
`onOverflow`	`BackpressureCallback?`	`null`	Called when an item is dropped or rejected.
`onBufferFull`	`BackpressureCallback?`	`null`	Called when the buffer is full and cannot accept more items.

Strategies

Strategy	Behavior
`drop`	Drops any new request while at `maxConcurrent`. Throws `StateError` on the caller.
`dropOldest`	Keeps a queue of up to `bufferSize` pending requests; oldest are dropped when full.
`buffer`	Queues requests up to `bufferSize` while under pressure; throws `StateError` when the buffer is full.
`sample`	Emits at most one execution per window; extra calls return the latest sampled value.
`throttle`	Similar to `sample` but typically aligned to leading edge semantics.
`error`	Throws `StateError` immediately when the system is overloaded.

Examples

Drop example

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


var callCount = 0;
final worker = Func1<int, int>((_) async {
 await Future<void>.delayed(Duration(milliseconds: 100));
 return ++callCount;
}).backpressure(
 strategy: BackpressureStrategy.drop,
 maxConcurrent: 1,
);

final a = worker(1);
try {
 await worker(2);
} catch (e) {
 print('dropped: $e');
}
print(await a);
// callCount == 1

Buffer example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


var total = 0;
final worker = Func1<List<int>, int>((items) async {
 total += items.length;
 return total;
}).backpressure(
 strategy: BackpressureStrategy.buffer,
 bufferSize: 3,
 maxConcurrent: 1,
);

worker([1]);
worker([2]);
await Future<void>.delayed(Duration(milliseconds: 100));
// total == 2 (or 3 if a third call arrived in time)

Error example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


final worker = Func1<String, String>((_) async => 'done').backpressure(
 strategy: BackpressureStrategy.error,
 maxConcurrent: 1,
);

await worker('a');
try {
 await worker('b');
} on StateError catch (e) {
 print('overloaded: $e');
}

Best practices

Use drop when stale data is useless.
Use buffer when processing batches is cheaper than processing items individually.
Set bufferSize realistically to avoid unbounded memory growth.
For drop, catch StateError on concurrent calls.

Common pitfalls

Buffer overflow: buffer throws StateError when the buffer is full; set bufferSize and handle overload gracefully.
Dropped future behavior: Strategies like drop can throw StateError on the caller; handle overload gracefully.

Barrier

Sun, 21 Jun 2026 18:27:01 +0000

Barrier

What it is

A barrier blocks all callers until a predetermined number of participants have arrived. Once the expected count is reached, all waiting callers proceed at once.

When to use it

Synchronising multiple parallel workers before a shared phase.
Coordinated startup of services or isolates.
Junit-style test fixtures where all async setups must complete before assertions.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
Func<R> barrier({required int count, Barrier? barrier});

// On Func1<T, R>
Func1<T, R> barrier({required int count, Barrier? barrier});

// On Func2<T1, T2, R>
Func2<T1, T2, R> barrier({required int count, Barrier? barrier});

class Barrier {
 Barrier(int count);
 Future<void> arrive();
 Future<void> arriveAndWait();
 void reset();
}

Parameters

Parameter	Type	Default	Description
`count`	`int`	required	Number of participants required to open the barrier.
`barrier`	`Barrier?`	`Barrier(count)`	Optional shared barrier instance.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


final b = Barrier(parties: 3);
var results = <int>[];

final task = Func1<int, int>((id) async {
 results.add(id);
 return id;
}).barrier(b);

await Future.wait([task(1), task(2), task(3)]);
// results.length == 3 (all passed the barrier together)

Real-world example

1
2
3
4
5
6
7
8
9


const workerCount = 3;
final readyBarrier = Barrier(parties: workerCount);

final worker = Func1<int, void>((id) async {
 await Future<void>.delayed(Duration(milliseconds: 10));
 // All workers start processing at the same moment.
}).barrier(readyBarrier);

await Future.wait([for (var i = 0; i < workerCount; i++) worker(i)]);

Best practices

Reuse the same Barrier instance across all participants.
Always await arriveAndWait(); failing to do so will not block the caller.
Reset the barrier only when all participants have passed and you want to reuse it.

Common pitfalls

Wrong count: If count is larger than the number of callers, the barrier never opens.
Missing participants: If a caller throws before arriving, remaining callers hang forever unless you add a timeout or cancellation.

Batch

Sun, 21 Jun 2026 18:27:01 +0000

Batch

What it is

Batch collects multiple individual requests and invokes the inner function with a list of items. It is available for Func1 and Func2.

When to use it

Combining multiple single-row database inserts into one bulk insert.
Batching analytics events before sending.
Any workload where a single bulk operation is cheaper than many small ones.

Async / sync support

Wrapper	Support
`Func<R>`	❌ No
`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


// api-reference
// On Func1<T, R>
Func1<T, R> batch({
 required int maxSize,
 Duration? maxWait,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> batch({
 required int maxSize,
 Duration? maxWait,
});

Parameters

Parameter	Type	Default	Description
`maxSize`	`int`	required	Maximum number of items in one batch.
`maxWait`	`Duration?`	`null`	Maximum time to wait for the batch to fill.

How it changes the inner function signature

1
2
3
4
5
6


// api-reference
// Before:
Func1<T, R> inner = Func1<T, R>((T item) async => ...);

// After batch:
// inner is passed as Func1<List<T>, List<R>> to the batch executor.

Returned wrapper methods

1
2


// api-reference
void flush(); // Immediately flushes any pending batch.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


var total = 0;
final add = Func1<int, int>((n) async => n).batch(
 executor: Func1<List<int>, void>((items) async {
 total += items.length;
 }),
 maxSize: 3,
 maxWait: Duration(milliseconds: 50),
);

await add(1);
await add(2);
await Future<void>.delayed(Duration(milliseconds: 100));
// total == 2 (batch flushed by maxWait)
print(total);

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


final insertUsers = Func1<User, User>((user) async => user).batch(
 executor: Func1<List<User>, void>((users) async {
 await db.batchInsert(users);
 }),
 maxSize: 50,
 maxWait: Duration(milliseconds: 100),
);

// Each call to insertUsers(user) is automatically batched.
await insertUsers(User());

Best practices

Set maxWait low enough to keep latency acceptable.
Make sure the inner function can handle empty batches gracefully.
Call flush() during shutdown to avoid losing pending items.

Common pitfalls

Wrong inner signature: The wrapped function must accept List<T> (or List<T1>/List<T2> for Func2), not a single item.
Result ordering: The returned list of results must correspond to the input order.

Bulkhead

Sun, 21 Jun 2026 18:27:01 +0000

Bulkhead

What it is

Bulkhead isolates failures by limiting concurrent executions and optionally rejecting overload. It is similar to a semaphore but is oriented toward resilience: once full, new calls fail fast rather than queue indefinitely.

When to use it

Microservice clients where a downstream slowdown should not exhaust all local resources.
API gateways that must protect backend services.
Any resource you want to fail fast when overloaded.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
Func<R> bulkhead({
 required int maxConcurrent,
 int maxWaiting = 0,
});

// On Func1<T, R>
Func1<T, R> bulkhead({
 required int maxConcurrent,
 int maxWaiting = 0,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> bulkhead({
 required int maxConcurrent,
 int maxWaiting = 0,
});

Parameters

Parameter	Type	Default	Description
`maxConcurrent`	`int`	required	Maximum concurrent executions allowed inside the bulkhead.
`maxWaiting`	`int`	`0`	Maximum calls allowed to wait for a slot. `0` means fail immediately when full.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


var active = 0;
final work = Func<int>(() async {
 active++;
 await Future<void>.delayed(Duration(milliseconds: 50));
 active--;
 return active;
}).bulkhead(poolSize: 2, queueSize: 1);

await Future.wait([work(), work(), work()]);
// active never exceeded 2 concurrently

Real-world example

1
2
3
4
5
6
7
8


final callApi = Func1<String, Response>((endpoint) async {
 return http.get(endpoint) as Response;
}).bulkhead(poolSize: 5, queueSize: 3);

// Additional concurrent calls throw BulkheadException so the upstream
// service does not sit blocked.

await callApi('/api/data');

Best practices

Combine with retry() or fallback() if transient rejection is acceptable.
Set maxWaiting low (often zero) for fail-fast behavior.
Place bulkhead close to the resource boundary (e.g., HTTP client).

Common pitfalls

Unhandled rejection: Calls that exceed capacity throw. Wrap in catchError or fallback if needed.
Too much waiting: A large maxWaiting defeats the fail-fast purpose of a bulkhead.

Cache Aside

Sun, 21 Jun 2026 18:27:01 +0000

Cache Aside

What it is

Cache aside lets you provide your own cache implementation. The wrapper checks the cache first, calls the function on a miss, and stores the result for future calls. You can also keep a set of keys warm in the background.

When to use it

Integrating with existing cache libraries or custom caches.
Implementing TTL, LRU, LFU, FIFO, or persistence.
Sharing a cache across multiple wrapped functions.
Proactively refreshing hot keys on a timer.

Async / sync support

Wrapper	Support
`Func<R>`	❌ No
`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
21
22


// api-reference
// On Func1<T, R>
Func1<T, R> cacheAside({
 AdvancedCache<T, R>? cache,
 Duration? ttl,
 RefreshStrategy refreshStrategy = RefreshStrategy.none,
 void Function()? onCacheMiss,
 void Function()? onCacheHit,
 Iterable<T>? warmKeys,
 Duration? warmInterval,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> cacheAside({
 AdvancedCache<ArgPair<T1, T2>, R>? cache,
 Duration? ttl,
 RefreshStrategy refreshStrategy = RefreshStrategy.none,
 void Function()? onCacheMiss,
 void Function()? onCacheHit,
 Iterable<(T1, T2)>? warmKeys,
 Duration? warmInterval,
});

Parameters

Parameter	Type	Description
`cache`	`AdvancedCache?`	Custom cache backend. Defaults to an in-memory LRU cache.
`ttl`	`Duration?`	Time-to-live for cached entries.
`refreshStrategy`	`RefreshStrategy`	`none`, `backgroundRefresh`, or `refreshOnAccess`.
`onCacheMiss`	`void Function()?`	Callback invoked on a cache miss.
`onCacheHit`	`void Function()?`	Callback invoked on a cache hit.
`warmKeys`	`Iterable?`	Keys to keep warm in the background.
`warmInterval`	`Duration?`	Refresh interval for `warmKeys`.

Returned wrapper methods

1
2
3
4
5


// api-reference
void invalidate(T key);
void invalidate(T1 arg1, T2 arg2);
void clearCache();
void dispose(); // Stops the background warmer.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


var calls = 0;
final square = Func1<int, int>((n) async {
 calls++;
 return n * n;
}).cacheAside(ttl: Duration(minutes: 1));

void main() async {
 print(await square(3)); // 9
 print(await square(3)); // 9
 // calls == 1
 print(calls);
}

Custom backend and warming

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


final getProduct = Func1<String, Product>((id) async {
 return Product();
}).cacheAside(
 cache: LfuCache<String, Product>(maxSize: 200),
 ttl: Duration(minutes: 5),
 warmKeys: ['featured'],
 warmInterval: Duration(minutes: 1),
);

print(await getProduct('featured'));
getProduct.dispose();

Real-world example

1
2
3
4
5
6
7


final getProduct = Func1<String, Product>((id) async {
 return await catalogApi.get(id) as Product;
}).cacheAside(ttl: Duration(minutes: 5));

void main() async {
 await getProduct('123');
}

Best practices

Implement eviction/TTL inside your AdvancedCache class or use the built-in backends.
Use immutable keys; ArgPair is provided for Func2 keys.
Handle cache failures gracefully; the wrapper falls back to the function on a miss.
Call dispose() to stop background warmers when the wrapper is no longer needed.

Common pitfalls

Cache key collisions: Make sure the key type distinguishes all arguments you care about.
Mutable cached objects: If you mutate a cached object, you mutate the cache contents.
Timer leaks: Forgetting dispose() leaves CacheWarmer timers running.

Cancellable

Sun, 21 Jun 2026 18:27:01 +0000

Cancellable

What it is

cancellable() wraps a function so that each invocation can be cancelled before it completes. Cancellation is cooperative: the wrapped future completes with a CancelException, while any inner work that has already started continues until it finishes on its own.

When to use it

Network requests that should be dropped when a user leaves a screen.
Background computations that become obsolete after a newer request arrives.
Any async work where the caller needs the ability to say “I no longer care about the result”.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
CancellableFunc<R> cancellable({CancelToken? token});

// On Func1<T, R>
CancellableFunc1<T, R> cancellable({CancelToken? token});

// On Func2<T1, T2, R>
CancellableFunc2<T1, T2, R> cancellable({CancelToken? token});

Returned wrapper methods

1
2
3
4
5
6


// Func / Func1 / Func2 variants
Future<R> call(...); // Normal call, returns result future.
CancelableOperation<R> operation(); // Func variant.
CancelableOperation<R> operation(T arg); // Func1 variant.
CancelableOperation<R> operation(T1 a, T2 b); // Func2 variant.
void cancel(); // Cancels the most recent operation.

CancelableOperation

1
2
3
4
5


final cancellableFunc = Func<String>(() async => 'data').cancellable();
final operation = cancellableFunc.operation();
operation.cancel();

await operation.value; // throws CancelException if cancelled

CancelToken

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Future<String> workA() async => 'A';
Future<String> workB() async => 'B';

final token = CancelToken();
final a = Func(workA).cancellable(token: token);
final b = Func(workB).cancellable(token: token);

unawaited(a());
unawaited(b());

token.cancel(); // cancels both active operations

Parameters

Parameter	Type	Default	Description
`token`	`CancelToken?`	`null`	Optional shared token for cancelling multiple operations at once.

Examples

Basic example

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


var executed = false;
final slow = Func<String>(() async {
 await Future<void>.delayed(Duration(seconds: 5));
 executed = true;
 return 'done';
}).cancellable();

final operation = slow.operation();
operation.cancel();

try {
 await operation.value;
} on CancelException {
 print('cancelled');
}

print(executed); // may still become true later

Shared token example

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


final token = CancelToken();

final fetchUser = Func1<String, String>((id) async {
 await Future<void>.delayed(Duration(seconds: 2));
 return 'user:$id';
}).cancellable(token: token);

final fetchOrders = Func1<String, String>((id) async {
 await Future<void>.delayed(Duration(seconds: 2));
 return 'orders:$id';
}).cancellable(token: token);

unawaited(fetchUser('42'));
unawaited(fetchOrders('42'));

token.cancel();

Chaining example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


final fetch = Func<String>(() async {
 await Future<void>.delayed(Duration(seconds: 2));
 return 'data';
})
 .retry(maxAttempts: 3)
 .timeout(Duration(seconds: 5))
 .cancellable();

final operation = fetch.operation();
operation.cancel();

Best practices

Place cancellable() as the outermost decorator when chaining so cancellation wraps the entire pipeline.
Use CancelToken when several related operations should be cancelled together, for example on widget disposal.
Catch CancelException only when you need to react to cancellation; otherwise let it propagate to the caller.
Do not rely on cancellation to stop CPU-bound synchronous work immediately. It only prevents awaiting the result.

Common pitfalls

Forgetting that inner work continues: cancellation in Dart cannot literally abort a running Future. Timers, network requests, and other async work may keep running until they complete naturally.
Using cancellable() deep inside a chain: if placed before retry() or timeout(), the returned wrapper may not expose operation(), and cancellation may not cover the whole pipeline.
Awaiting after cancel: awaiting a cancelled operation always throws CancelException.

catchError

Sun, 21 Jun 2026 18:27:01 +0000

catchError

What it is

catchError catches specific exception types thrown by the wrapped function and routes each to a typed handler. Unmatched exceptions are either handled by catchAll or rethrown.

When to use it

Centralised error logging.
Converting low-level exceptions into domain exceptions.
Graceful suppression of non-critical failures.

Async / sync support

Wrapper	Support
`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
21


// api-reference
// On Func<R>
Func<R> catchError({
 required Map<Type, Future<R> Function(Object)> handlers,
 Future<R> Function(Object)? catchAll,
 void Function(Object error)? onCatch,
});

// On Func1<T, R>
Func1<T, R> catchError({
 required Map<Type, Future<R> Function(Object)> handlers,
 Future<R> Function(Object)? catchAll,
 void Function(Object error)? onCatch,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> catchError({
 required Map<Type, Future<R> Function(Object)> handlers,
 Future<R> Function(Object)? catchAll,
 void Function(Object error)? onCatch,
});

Parameters

Parameter	Type	Description
`handlers`	`Map<Type, Future<R> Function(Object)>`	Maps `error.runtimeType` to a recovery function.
`catchAll`	`Future<R> Function(Object)?`	Fallback handler for unmatched exceptions.
`onCatch`	`void Function(Object)?`	Called for every caught exception before its handler runs.

Examples

Basic example

1
2
3
4
5
6
7


final safe = Func<int>(() async => throw FormatException('boom')).catchError(
 handlers: {
 FormatException: (e) async => -1,
 },
);

print(await safe()); // -1

Real-world example

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


final fetchSettings = Func1<String, Settings>((userId) async {
 return (await api.settings(userId)) as Settings;
}).catchError(
 handlers: {
 NetworkException: (e) async => Settings(),
 AuthException: (e) async => Settings(),
 },
 catchAll: (e) async {
 logger.error('Settings fetch failed', e);
 return Settings();
 },
);

void main() async {
 final settings = await fetchSettings('user-123');
 print(settings);
}

Best practices

Put the most specific exception types first in the map.
Use catchAll for logging unexpected failures.
Only suppress errors you understand and can handle safely.

Common pitfalls

Matching by exact type: A SocketException handler will not catch a ClientException.
Map order matters: Handlers are checked in iteration order.
Handler exceptions: If the handler throws, the wrapper throws that new exception.

Circuit Breaker

Sun, 21 Jun 2026 18:27:01 +0000

Circuit Breaker

What it is

A circuit breaker stops calling a failing function after a threshold of failures is reached. While open, calls fail fast or return a fallback value. After a cooldown, it enters a half-open state and allows a probe to test recovery.

When to use it

External API clients that should not keep calling a down service.
Database connections under load.
Cascading failure prevention in distributed systems.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
Func<R> circuitBreaker(CircuitBreaker breaker);

// On Func1<T, R>
Func1<T, R> circuitBreaker(CircuitBreaker breaker);

// On Func2<T1, T2, R>
Func2<T1, T2, R> circuitBreaker(CircuitBreaker breaker);

enum CircuitBreakerState { closed, open, halfOpen }

Parameters

Parameter	Type	Default	Description
`failureThreshold`	`int`	`5`	Failures needed to open the circuit.
`successThreshold`	`int`	`2`	Consecutive successes in half-open needed to close.
`timeout`	`Duration`	`30s`	Time before switching from open to half-open.
`onStateChange`	`void Function(CircuitBreakerState, CircuitBreakerState)?`	`null`	Called on state transitions.

Returned wrapper properties

1
2


// api-reference
CircuitBreakerState get state;

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


var fails = 0;
final breaker = CircuitBreaker(
 failureThreshold: 2,
 timeout: Duration(milliseconds: 100),
);
final api = Func<String>(() async {
 fails++;
 throw Exception('down ($fails)');
}).circuitBreaker(breaker);

await api().catchError((_) => 'fallback');
await api().catchError((_) => 'fallback'); // circuit opens
await Future<void>.delayed(Duration(milliseconds: 150));
await api().catchError((_) => 'still fallback'); // half-open probe

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


final breaker = CircuitBreaker(
 failureThreshold: 3,
 timeout: Duration(seconds: 10),
);
final paymentGateway = Func1<Payment, Receipt>((payment) async {
 return await gateway.charge(payment) as Receipt;
}).circuitBreaker(breaker).fallback(
 fallbackFunction: Func1<Payment, Receipt>((payment) async => Receipt()),
);

// Usage
print(await paymentGateway(Payment()));

// Open circuit returns Receipt.declined() instantly.

Best practices

Combine with fallback() so callers receive a graceful degradation while the circuit is open.
Set failureThreshold based on observed normal error rates.
Keep timeout long enough for the downstream service to recover.

Common pitfalls

Threshold too low: A brief spike can open the circuit unnecessarily.
No fallback: An open circuit throws; make sure upstream code handles it.
Half-open storms: Tune successThreshold so only a few probes close the circuit.

Compress / Decompress

Sun, 21 Jun 2026 18:27:01 +0000

Compress / Decompress

What it is

compress wraps a Func1 or Func2 so that its argument is compressed before being passed in, and decompress wraps it so the argument is decompressed. They are typically used with data pipelines or transport layers.

When to use it

Sending large payloads over the network.
Persisting data where size matters.
Wrapping compression libraries transparently.

Async / sync support

Wrapper	Support
`Func<R>`	❌ No
`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 Func1<T, R>
Func1<T, R> compress<T>({
 required T Function(T data) compressor,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> compress<T>({
 required T Function(T data) compressor,
});

// On Func1<T, R>
Func1<T, R> decompress<T>({
 required T Function(T data) decompressor,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> decompress<T>({
 required T Function(T data) decompressor,
});

Parameters

Parameter	Type	Description
`compressor` / `decompressor`	`T Function(T)`	Transformation applied to the argument(s).

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


final send = Func1<String, void>((payload) async {
 await api.send(payload);
}).compress(
 algorithm: CompressionAlgorithm.gzip,
 level: CompressionLevel.balanced,
);

void main() async {
 await send('hello');
}

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


final upload = Func1<Uint8List, void>((bytes) async {
 await httpClient.post(body: bytes);
}).compressBytes(
 threshold: 1024,
 algorithm: CompressionAlgorithm.gzip,
);

void main() async {
 await upload(Uint8List(0));
}

Best practices

Use compress on the producer side and decompress on the consumer side.
Choose a compression algorithm appropriate to your data type.
For large objects, consider streaming instead of in-memory compression.

Common pitfalls

Type mismatch: compress<T> must match the argument type of the wrapped function.
Decompressor exceptions: Malformed data will throw; pair with fallback or recover if needed.

Countdown Latch

Sun, 21 Jun 2026 18:27:01 +0000

Countdown Latch

What it is

A countdown latch waits until a counter reaches zero. Unlike a barrier, the counter is decremented by calls to the latch, and waiting callers proceed once the count hits zero.

When to use it

Waiting for a set of independent initialization tasks to finish.
Boot sequences where multiple services must be ready before starting the main loop.
Triggering an action after N events have occurred.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
Func<R> countdownLatch({required int count, CountdownLatch? latch});

// On Func1<T, R>
Func1<T, R> countdownLatch({required int count, CountdownLatch? latch});

// On Func2<T1, T2, R>
Func2<T1, T2, R> countdownLatch({required int count, CountdownLatch? latch});

class CountdownLatch {
 CountdownLatch(int count);
 void countDown();
 Future<void> awaitLatch();
 int get count;
 bool get isOpen;
}

Parameters

Parameter	Type	Default	Description
`count`	`int`	required	Initial latch count.
`latch`	`CountdownLatch?`	`CountdownLatch(count)`	Optional shared latch instance.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


final latch = CountdownLatch(count: 2);
var done = false;

final init = Func<String>(() async {
 done = true;
 return 'ready';
}).countdownLatch(latch);

init();
init();

await latch.await_();
print(done); // true

Real-world example

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


final initLatch = CountdownLatch(count: 3);

final loadConfig = Func<Config>(() async => config.load() as Config)
 .countdownLatch(initLatch);
final loadCache = Func<Cache<String, String>>(() async => cache.load() as Cache<String, String>)
 .countdownLatch(initLatch);
final connectDb = Func<Db>(() async => db.connect() as Db)
 .countdownLatch(initLatch);

loadConfig();
loadCache();
connectDb();

// All three finish before the main app proceeds.
await initLatch.await_();
print('App ready');

Best practices

Call countDown() exactly once per expected event.
Use awaitLatch() for the coordinator that must wait for all tasks.
Share the same latch instance across all participants.

Common pitfalls

Counting down too many times: If countDown() is called more than count times, behavior is undefined.
Latch never opens: If a task fails before calling countDown(), the latch remains closed. Add error handling or timeouts.

Debounce

Sun, 21 Jun 2026 18:27:01 +0000

Debounce

What it is

Debounce delays execution until a specified quiet period has passed since the most recent call. If the function keeps being invoked, the timer resets and the execution is postponed again.

When to use it

Search-as-you-type input fields that should only query the server after the user stops typing.
Form validation that should run after the user pauses editing.
Resize or scroll event handlers that should fire only after the burst of events ends.

Async / sync support

Wrapper	Support
`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> debounce(
 Duration duration, {
 DebounceMode mode = DebounceMode.trailing,
});

// On Func1<T, R>
Func1<T, R> debounce(
 Duration duration, {
 DebounceMode mode = DebounceMode.trailing,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> debounce(
 Duration duration, {
 DebounceMode mode = DebounceMode.trailing,
});

enum DebounceMode { trailing, leading, both }

Parameters

Parameter	Type	Default	Description
`duration`	`Duration`	required	Quiet period required before execution.
`mode`	`DebounceMode`	`trailing`	When to execute: `trailing`, `leading`, or `both`.

Returned wrapper methods

1
2


// api-reference
void cancel(); // Cancels the pending timer.

Modes

trailing (default): executes once after the quiet period, using the last arguments.
leading: executes immediately on the first call and ignores subsequent calls until the window expires.
both: executes immediately on the first call and again after the quiet period.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


var callCount = 0;
final search = Func1<String, String>((query) async {
 callCount++;
 return 'Results for: $query';
}).debounce(Duration(milliseconds: 50));

search('a');
search('ab');
search('abc');

await Future<void>.delayed(Duration(milliseconds: 100));
print('calls: $callCount'); // 1

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


final searchApi = Func1<String, List<SearchResult>>(
 (query) async => api.search(query) as List<SearchResult>,
).debounce(
 Duration(milliseconds: 300),
 mode: DebounceMode.trailing,
);

await searchApi('query');

// In a text-field onChanged listener:
// searchApi(query);

Best practices

Use trailing for server requests so you only send the final value.
Use leading for actions that should respond immediately to the first user gesture.
Keep duration short enough to feel responsive but long enough to avoid excessive calls.
Call cancel() when the widget is disposed to prevent stale executions.

Common pitfalls

Assuming every call returns a value: In trailing mode only the last call’s future resolves with the result; earlier futures may resolve to the same last result depending on implementation. Prefer treating debounced calls as fire-and-forget or awaiting the final one.
Forgetting to dispose: A pending debounce timer can call your function after the screen is gone.
Using leading for network calls: This can cause a request on every first keystroke, which is usually not desired.

Deduplicate

Sun, 21 Jun 2026 18:27:01 +0000

Deduplicate

What it is

Deduplicate ensures that only one execution is in flight for a given key at a time. If the same key is requested while a previous call is still pending, the new caller receives the same future.

When to use it

Preventing thundering herd on cache misses.
Coalescing identical network requests.
Avoiding duplicate expensive computations started in parallel.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
Func<R> deduplicate();

// On Func1<T, R>
Func1<T, R> deduplicate();

// On Func2<T1, T2, R>
Func2<T1, T2, R> deduplicate();

No parameters.

Default Value

Sun, 21 Jun 2026 18:27:01 +0000

Default Value

What it is

defaultValue provides a static fallback returned whenever the wrapped function throws. An optional predicate controls which errors trigger the default.

When to use it

Providing a safe default for optional data.
Ensuring non-critical operations never crash.
Simple defensive wrapping.

Async / sync support

Wrapper	Support
`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
21


// api-reference
// On Func<R>
Func<R> defaultValue({
 required R defaultValue,
 bool Function(Object error)? defaultIf,
 void Function()? onDefault,
});

// On Func1<T, R>
Func1<T, R> defaultValue({
 required R defaultValue,
 bool Function(Object error)? defaultIf,
 void Function()? onDefault,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> defaultValue({
 required R defaultValue,
 bool Function(Object error)? defaultIf,
 void Function()? onDefault,
});

Parameters

Parameter	Type	Description
`defaultValue`	`R`	Value to return on failure.
`defaultIf`	`bool Function(Object)?`	If provided and returns `false`, the error is rethrown.
`onDefault`	`void Function()?`	Called when the default value is used.

Examples

Basic example

1
2
3


final safe = Func<int>(() async => throw Exception('boom'))
 .defaultValue(defaultValue: 0);
print(await safe()); // 0

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


final getTimeout = Func<Duration>(() async {
 return Duration(seconds: config['timeout'] as int);
}).defaultValue(
 defaultValue: Duration(seconds: 30),
 defaultIf: (e) => e is FormatException,
 onDefault: () => logger.warn('Using default timeout'),
);

void main() async {
 final timeout = await getTimeout();
 print(timeout);
}

Best practices

Use defaultValue only when any failure is equivalent and safe to ignore.
Prefer catchError or fallback when you need logging or conditional handling.

Common pitfalls

Masking bugs: A broad default value can hide configuration or parsing errors.
Non-nullable defaults: Make sure the default value is a valid instance of R.

Defer

Sun, 21 Jun 2026 18:27:01 +0000

Defer

What it is

Defer schedules the wrapped function to run in the next microtask. The returned future begins execution as soon as possible without blocking the current synchronous block.

When to use it

Moving work out of a build or layout phase in Flutter.
Batching multiple synchronous operations so they all run after the current event loop iteration.
Creating a “lazy promise” that starts work immediately but allows awaiting later.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
Func<R> asDeferred();

// On Func1<T, R>
Func1<T, R> asDeferred();

// On Func2<T1, T2, R>
Func2<T1, T2, R> asDeferred();

No parameters.

Delay

Sun, 21 Jun 2026 18:27:01 +0000

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

Wrapper	Support
`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

Parameter	Type	Default	Description
`duration`	`Duration`	required	Duration of the pause.
`mode`	`DelayMode`	`before`	When 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.

Fallback

Sun, 21 Jun 2026 18:27:01 +0000

Fallback

What it is

Fallback provides a value or action to use when the wrapped function throws. It is a simpler alternative to full retry logic when a degraded result is acceptable.

When to use it

Returning cached data when a network call fails.
Returning a default UI state when analytics tracking fails.
Converting hard failures into soft failures.

Async / sync support

Wrapper	Support
`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
21
22
23
24


// api-reference
// On Func<R>
Func<R> fallback({
 R? fallbackValue,
 Func<R>? fallbackFunction,
 bool Function(Object error)? fallbackIf,
 void Function(Object error)? onFallback,
});

// On Func1<T, R>
Func1<T, R> fallback({
 R? fallbackValue,
 Func1<T, R>? fallbackFunction,
 bool Function(Object error)? fallbackIf,
 void Function(Object error)? onFallback,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> fallback({
 R? fallbackValue,
 Func2<T1, T2, R>? fallbackFunction,
 bool Function(Object error)? fallbackIf,
 void Function(Object error)? onFallback,
});

Parameters

Parameter	Type	Description
`fallbackValue`	`R?`	Constant value returned on failure.
`fallbackFunction`	`Func<R>?` / `Func1<T, R>?` / `Func2<T1, T2, R>?`	Computed fallback receiving the original arguments.
`fallbackIf`	`bool Function(Object error)?`	Predicate deciding whether to use the fallback.
`onFallback`	`void Function(Object error)?`	Called when fallback is used.

Examples

Basic example

1
2
3
4
5


final flaky = Func<int>(() async => throw Exception('fail')).fallback(
 fallbackValue: 42,
);

print(await flaky()); // 42

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


final fetchProfile = Func1<String, Profile>((id) async {
 return await api.profile(id) as Profile;
}).fallback(
 fallbackFunction: Func1<String, Profile>((id) async {
 final cached = cache.getProfile(id) as Profile?;
 return cached ?? Profile();
 }),
);

print(await fetchProfile('123'));

Best practices

Log the original error inside the fallback handler for observability.
Return a value of the same type R as the wrapped function.
Use fallback for failures where degraded behavior is better than crashing.

Common pitfalls

Throwing inside fallback: If the handler throws, the wrapper itself throws; keep handlers simple.
Type mismatch: The fallback must return the same R type as the original function.

Function Queue

Sun, 21 Jun 2026 18:27:01 +0000

Function Queue

What it is

Function queue serializes calls through a FIFO queue. Unlike a lock, which simply waits for the resource, a queued function gives explicit queue semantics and is available only for unary (Func1) and binary (Func2) wrappers.

When to use it

Sequencing user actions (e.g., undo/redo, command queue).
Ordered processing of messages or jobs.
Any workload where order of arrival must be preserved.

Async / sync support

Wrapper	Support
`Func<R>`	❌ No
`Func1<T, R>`	✅ Async
`Func2<T1, T2, R>`	✅ Async
`FuncSync<R>`	❌ No

API reference

1
2
3
4
5
6


// api-reference
// On Func1<T, R>
Func1<T, R> functionQueue({int? capacity});

// On Func2<T1, T2, R>
Func2<T1, T2, R> functionQueue({int? capacity});

Parameters

Parameter	Type	Default	Description
`capacity`	`int?`	`null`	Maximum number of queued calls. `null` means unbounded.

Returned wrapper methods

1
2


// api-reference
int get queueLength; // Current number of pending items in the queue.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


var log = <int>[];
final process = Func1<int, void>((value) async {
 await Future<void>.delayed(Duration(milliseconds: 10));
 log.add(value);
}).queue(concurrency: 1);

process(1);
process(2);
process(3);

await Future<void>.delayed(Duration(milliseconds: 100));
// log == [1, 2, 3]

Real-world example

1
2
3
4
5
6
7


final submitCommand = Func1<Command, void>((command) async {
 await Future<void>.delayed(Duration(milliseconds: 10));
}).queue(concurrency: 1, maxQueueSize: 100);

// UI calls submitCommand(...) in order; commands run one at a time.

await submitCommand(Command());

Best practices

Set a capacity if callers can enqueue faster than the function can process to avoid unbounded memory growth.
Monitor queueLength in UI code to show a loading indicator.
Keep queue items small; avoid queuing large objects.

Common pitfalls

Capacity overflow: If capacity is set and the queue is full, additional calls throw StateError.
Assuming lock semantics: A queue preserves order but still runs one at a time; use lock() if order is irrelevant.

Guard

Sun, 21 Jun 2026 18:27:01 +0000

Guard

What it is

guard checks pre-conditions before and/or post-conditions after executing the wrapped function. If a condition returns false, the wrapper throws a GuardException.

When to use it

Enforcing invariants at the function boundary.
Failing fast when arguments are invalid.
Authorization checks before running a command.

Async / sync support

Wrapper	Support
`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
21
22
23
24


// api-reference
// On Func<R>
Func<R> guard({
 bool Function()? preCondition,
 bool Function(R result)? postCondition,
 String preConditionMessage = 'Pre-condition failed',
 String postConditionMessage = 'Post-condition failed',
});

// On Func1<T, R>
Func1<T, R> guard({
 bool Function(T arg)? preCondition,
 bool Function(R result)? postCondition,
 String preConditionMessage = 'Pre-condition failed',
 String postConditionMessage = 'Post-condition failed',
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> guard({
 bool Function(T1 arg1, T2 arg2)? preCondition,
 bool Function(R result)? postCondition,
 String preConditionMessage = 'Pre-condition failed',
 String postConditionMessage = 'Post-condition failed',
});

Parameters

Parameter	Type	Description
`preCondition`	`bool Function(...)?`	Checked before execution; must return `true` to proceed.
`postCondition`	`bool Function(R)?`	Checked after execution with the result.
`preConditionMessage`	`String`	Message used when the pre-condition fails.
`postConditionMessage`	`String`	Message used when the post-condition fails.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


final onlyPositive = Func1<int, int>((n) async => n * 2).guard(
 preCondition: (n) => n > 0,
);

print(await onlyPositive(5)); // 10
try {
 await onlyPositive(-1);
} on GuardException {
 print('guarded');
}

Real-world example

1
2
3
4
5


final deleteAccount = Func1<String, void>((userId) async {
 await accounts.delete(userId);
}).guard(preCondition: (_) => currentUser.isAdmin as bool);

await deleteAccount('user-123');

Best practices

Keep predicates pure and side-effect free.
Use specific predicates rather than broad checks.
Combine with catchError or fallback if guard failures should be handled gracefully.

Common pitfalls

Predicate side effects: Mutating state inside a guard predicate makes behavior unpredictable.
Expensive predicates: Guards run synchronously before every execution; keep them cheap.

Idle Callback

Sun, 21 Jun 2026 18:27:01 +0000

Idle Callback

What it is

Idle callback executes the wrapped function only when a custom detector reports that the system is idle. It polls the detector at a configurable interval until the detector returns true.

When to use it

Running heavy maintenance tasks when the app is not busy.
Compressing logs or flushing analytics when CPU usage is low.
Deferred image decoding or cache cleanup.

Async / sync support

Wrapper	Support
`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
21


// api-reference
// On Func<R>
Func<R> idleCallback({
 Duration? checkInterval,
 IdleDetector? idleDetector,
});

// On Func1<T, R>
Func1<T, R> idleCallback({
 Duration? checkInterval,
 IdleDetector? idleDetector,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> idleCallback({
 Duration? checkInterval,
 IdleDetector? idleDetector,
});

typedef IdleDetector = bool Function();
bool defaultIdleDetector() => true;

Parameters

Parameter	Type	Default	Description
`checkInterval`	`Duration`	`100ms`	How often to poll the detector.
`idleDetector`	`IdleDetector`	`defaultIdleDetector`	Function that returns `true` when the system is idle.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


var isIdle = false;

final cleanup = Func<String>(() async => 'cleaned').idleCallback(
 checkInterval: Duration(milliseconds: 50),
 idleDetector: () => isIdle,
);

// Later:
isIdle = true;
print(await cleanup()); // cleaned

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


var cpuLoad = 0.1;
var pendingFrames = 0;

bool isSystemIdle() => cpuLoad < 0.3 && pendingFrames == 0;

final compressLogs = Func<String>(() async => 'logs compressed')
 .idleCallback(
 checkInterval: Duration(seconds: 1),
 idleDetector: isSystemIdle,
 );

await compressLogs(); // runs only when the app is idle

Best practices

Keep the detector cheap because it runs on every polling tick.
Use a longer checkInterval for heavy background work to reduce overhead.
Always provide a timeout or cancellation mechanism in production so the call does not hang forever if the system never becomes idle.

Common pitfalls

Hanging forever: With the default detector, the function runs at the next tick, but a custom detector that never returns true leaves the future pending indefinitely.
Expensive detector: Running heavy logic inside idleDetector defeats the purpose of deferring work.

Lazy Loading

Sun, 21 Jun 2026 18:27:01 +0000

Lazy Loading

What it is

Lazy loading defers execution until the result is first requested. This is the default behavior for most wrapped functions, but the explicit decorator can be combined with others for clarity.

When to use it

Expensive resources that may never be needed.
Avoiding startup cost for optional features.
Composing with warm up or memoize to control when work happens.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
Func<R> lazy();

// On Func1<T, R>
Func1<T, R> lazy();

// On Func2<T1, T2, R>
Func2<T1, T2, R> lazy();

No parameters.

Lock

Sun, 21 Jun 2026 18:27:01 +0000

Lock

What it is

A Lock guarantees that only one execution of the wrapped function happens at a time. Concurrent calls queue and run sequentially.

When to use it

Protecting a critical section around shared mutable state.
Preventing duplicate writes to a database or file.
Serializing access to a non-thread-safe resource.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
Func<R> lock([Lock? lock]);

// On Func1<T, R>
Func1<T, R> lock([Lock? lock]);

// On Func2<T1, T2, R>
Func2<T1, T2, R> lock([Lock? lock]);

class Lock {
 Future<T> synchronized<T>(FutureOr<T> Function() computation);
}

Parameters

Parameter	Type	Default	Description
`lock`	`Lock?`	`Lock()`	Optional shared lock instance. If omitted, a new lock is created.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


var balance = 0;
final deposit = Func1<int, int>((amount) async {
 final current = balance;
 await Future<void>.delayed(Duration(milliseconds: 10));
 balance = current + amount;
 return balance;
}).lock();

await Future.wait([deposit(10), deposit(20)]);
// balance == 30 (serialised, no lost updates)

Real-world example

1
2
3
4
5
6
7


final writeToLog = Func1<String, void>((entry) async {
 await storage.write('$entry\n');
}).lock();

// Many callers can invoke writeToLog safely; writes are serialised.

await writeToLog('entry');

Best practices

Keep critical sections as short as possible to reduce queuing.
Reuse the same Lock instance across multiple wrapped functions if they access the same resource.
Avoid calling the wrapped function recursively from within the same lock to prevent self-deadlock.

Common pitfalls

Forgetting the lock parameter: Without a shared lock, each wrapper has its own lock and they no longer coordinate.
Deadlock: Holding a lock while awaiting another operation that also needs the same lock causes deadlock.

Memoize

Sun, 21 Jun 2026 18:27:01 +0000

Memoize

What it is

Memoize caches the result of a function call and returns the cached value on subsequent calls.

When to use it

Expensive computations with deterministic inputs.
Repeated service lookups that rarely change.
Avoiding redundant network or database requests within a session.

Async / sync support

Wrapper	Support
`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
21
22
23
24
25
26
27
28
29


// api-reference
// On Func<R>
Func<R> memoize({
 Duration? ttl,
 int maxSize = 100,
 EvictionPolicy evictionPolicy = EvictionPolicy.lru,
});

// On Func1<T, R>
Func1<T, R> memoize({
 Duration? ttl,
 int maxSize = 100,
 EvictionPolicy evictionPolicy = EvictionPolicy.lru,
 AdvancedCache<T, R>? cache,
 int? maxWeight,
 int Function(R result)? weigh,
 bool stampedeProtection = false,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> memoize({
 Duration? ttl,
 int maxSize = 100,
 EvictionPolicy evictionPolicy = EvictionPolicy.lru,
 AdvancedCache<ArgPair<T1, T2>, R>? cache,
 int? maxWeight,
 int Function(R result)? weigh,
 bool stampedeProtection = false,
});

Parameters

Parameter	Type	Description
`ttl`	`Duration?`	Time-to-live for cached results. `null` means no expiration.
`maxSize`	`int`	Maximum entries when using the default cache backend.
`evictionPolicy`	`EvictionPolicy`	`lru`, `lfu`, or `fifo`.
`cache`	`AdvancedCache?`	Optional custom cache backend.
`maxWeight`	`int?`	Total weight budget when using weighted eviction.
`weigh`	`int Function(R)?`	Returns the weight of a result.
`stampedeProtection`	`bool`	Coalesce concurrent loads for the same key.

Returned wrapper methods

1
2
3
4
5


// api-reference
void clear(); // Clears all cached values.
// On Func1 / Func2 only:
void clearArg(T arg);
void clearArgs(T1 arg1, T2 arg2);

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


var calls = 0;
final compute = Func<int>(() async {
 calls++;
 return 42;
}).memoize();

print(await compute()); // 42
print(await compute()); // 42
// calls == 1
print(calls);

Custom backend and stampede protection

1
2
3
4
5
6
7
8
9


final fetchUser = Func1<String, User>((id) async {
 return User();
}).memoize(
 cache: LruCache<String, User>(maxSize: 100),
 ttl: Duration(minutes: 5),
 stampedeProtection: true,
);

print(await fetchUser('123'));

Weighted eviction

1
2
3
4
5
6
7
8
9


final fetchPage = Func1<String, String>((url) async {
 return '<html>Hello</html>';
}).memoize(
 cache: LruCache<String, String>(maxSize: 1000),
 maxWeight: 1024 * 1024,
 weigh: (html) => html.length,
);

print((await fetchPage('/')).length);

Real-world example

1
2
3
4
5
6
7


final fetchConfig = Func<Config>(() async {
 return await remoteConfig.fetch() as Config;
}).memoize();

void main() async {
 await fetchConfig();
}

Best practices

Use memoize for functions whose result does not change during the cache lifetime.
Call clear() when you know the cached value is stale.
Combine with timeout() if the first call should not hang forever.
Enable stampedeProtection for hot keys that are expensive to load.

Common pitfalls

Stale data: Without a ttl, cached values persist for the lifetime of the wrapper.
Memory leaks: Long-lived wrappers cache results indefinitely; clear them when no longer needed.
Weight budget: maxWeight without weigh (or vice versa) triggers an assertion.

Merge

Sun, 21 Jun 2026 18:27:01 +0000

Merge

What it is

MergeExtension combines multiple functions into a single function whose result aggregates the results of all sources.

When to use it

Running several independent queries and combining their results.
Parallel fan-out where you need all outputs.
Composing multiple validators or enrichers.

API reference

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


// api-reference
class MergeExtension1<T, R> {
 MergeExtension1(
 List<Func1<T, dynamic>> sources, {
 required R Function(List<dynamic> results) combiner,
 });

 Future<R> call(T arg);
}

class MergeExtension2<T1, T2, R> {
 MergeExtension2(
 List<Func2<T1, T2, dynamic>> sources, {
 required R Function(List<dynamic> results) combiner,
 });

 Future<R> call(T1 arg1, T2 arg2);
}

Parameters

Parameter	Type	Description
`sources`	`List<Func1<T, dynamic>>`	Functions to execute in parallel.
`combiner`	`R Function(List<dynamic>)`	Combines all source results into a single result.

Examples

Basic example

1
2
3
4
5
6
7
8
9


final merge = MergeExtension1<int, int>(
 [
 Func1<int, int>((n) async => n + 1),
 Func1<int, int>((n) async => n * 2),
 ],
 combiner: (results) => results.cast<int>().reduce((a, b) => a + b),
);

print(await merge(3)); // (3 + 1) + (3 * 2) == 10

Real-world example

1
2
3
4
5
6
7
8
9


final enrichUser = MergeExtension1<String, UserProfile>(
 [
 Func1<String, UserProfile>((id) async => await profileApi.get(id) as UserProfile),
 Func1<String, UserProfile>((id) async => await preferencesApi.get(id) as UserProfile),
 ],
 combiner: (profiles) => UserProfile(),
);

await enrichUser('123');

Best practices

Keep targets independent; Merge runs them concurrently.
Make the merger handle result ordering deterministically.
Combine with catchError on individual targets if partial failure is acceptable.

Common pitfalls

One failure fails all: If any target throws, the merge throws. Wrap targets individually if you need resilience.
Merger assumptions: The merger receives results in the same order as targets.

Monitor

Sun, 21 Jun 2026 18:27:01 +0000

Monitor

What it is

A monitor is a concurrency primitive that combines mutual exclusion with a condition-wait mechanism. A wrapped function can wait until a predicate becomes true while holding the monitor.

When to use it

Producer-consumer patterns where consumers must wait for data.
Scenarios requiring both locking and signaling between tasks.
Complex critical-section coordination.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
Func<R> monitor([Monitor? monitor]);

// On Func1<T, R>
Func1<T, R> monitor([Monitor? monitor]);

// On Func2<T1, T2, R>
Func2<T1, T2, R> monitor([Monitor? monitor]);

class Monitor {
 Future<T> synchronized<T>(FutureOr<T> Function() computation);
 Future<void> waitUntil(bool Function() predicate);
}

Parameters

Parameter	Type	Default	Description
`monitor`	`Monitor?`	`Monitor()`	Optional shared monitor instance.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


final monitor = Monitor();
var ready = false;

final waitForReady = Func<String>(() async {
 await monitor.synchronized(() async {
 await monitor.waitUntil(() => ready);
 });
 return 'go';
}).monitor(monitor);

waitForReady();
await Future<void>.delayed(Duration(milliseconds: 50));
ready = true;
await Future<void>.delayed(Duration(milliseconds: 50));
// Future resolves with 'go'

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


final queueMonitor = Monitor();
final queue = <Task>[];

final consumer = Func<Task?>(() async {
 return await queueMonitor.synchronized<Task?>(() async {
 await queueMonitor.waitUntil(() => queue.isNotEmpty);
 return queue.removeAt(0);
 });
}).monitor(queueMonitor);

// Producer adds tasks and the consumer wakes up automatically.

await consumer();

Best practices

Always acquire the monitor with synchronized() before calling waitUntil().
Keep predicate checks fast because they are polled internally.
Signal state changes by mutating shared state while holding the monitor.

Common pitfalls

Calling waitUntil outside synchronized: This leads to races; always enter the monitor first.
Spurious wakeups: The predicate is re-checked on each wake, so write predicates that are correct even if they fire multiple times.

Monitor Observability

Sun, 21 Jun 2026 18:27:01 +0000

Monitor Observability

What it is

monitorObservability is a richer observability decorator that tracks execution metrics such as duration, success, and failure counts.

When to use it

Collecting latency histograms.
Health checks that count failures.
Triggering alerts when error rates exceed thresholds.

Async / sync support

Wrapper	Support
`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
21
22
23
24
25
26


// api-reference
// On Func<R>
Func<R> monitorObservability({
 void Function(Metrics metrics)? onMetricsUpdate,
});

// On Func1<T, R>
Func1<T, R> monitorObservability({
 void Function(Metrics metrics)? onMetricsUpdate,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> monitorObservability({
 void Function(Metrics metrics)? onMetricsUpdate,
});

class Metrics {
 int executionCount;
 int errorCount;
 Duration totalDuration;
 Duration? lastDuration;
 Object? lastError;
 DateTime? lastExecutionTime;
 Duration get averageDuration;
 double get successRate;
}

Parameters

Parameter	Type	Description
`onMetricsUpdate`	`void Function(Metrics)?`	Callback invoked after each execution.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


final measured = Func<int>(() async {
 await Future<void>.delayed(Duration(milliseconds: 50));
 return 42;
}).monitorObservability(
 onMetricsUpdate: (m) {
 print('compute: ${m.lastDuration?.inMilliseconds}ms, success=${m.successRate == 1.0}');
 },
);

await measured();

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


final measuredApi = Func1<String, User>((id) async {
 return await api.getUser(id) as User;
}).monitorObservability(
 onMetricsUpdate: (m) {
 if (m.lastDuration != null) {
 metrics.histogram('api_latency_ms', m.lastDuration!.inMilliseconds);
 }
 if (m.successRate < 1.0) {
 metrics.increment('api_errors', tags: {'op': 'getUser'});
 }
 },
);

await measuredApi('user-123');

Best practices

Keep onMetricsUpdate synchronous and non-blocking.
Do not mutate the function’s behavior inside the metrics callback.

Common pitfalls

Slow metrics callback: Blocks the result from being returned; use a fire-and-forget metrics sink if needed.
Callback exceptions: Exceptions in onMetricsUpdate can alter the wrapper’s result.

Once

Sun, 21 Jun 2026 18:27:01 +0000

Once

What it is

Once guarantees that the wrapped function executes at most one time. All subsequent calls return the cached result.

When to use it

Singleton initialization.
Feature flags or configuration loaded once per app lifetime.
One-time analytics setup.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
Func<R> once();

// On Func1<T, R>
Func1<T, R> once();

// On Func2<T1, T2, R>
Func2<T1, T2, R> once();

No parameters.

Priority Queue

Sun, 21 Jun 2026 18:27:01 +0000

Priority Queue

What it is

Priority queue orders pending executions by a priority function. Higher-priority calls run before lower-priority ones.

When to use it

Task schedulers where user-facing work should preempt background work.
Message processing where some messages are urgent.
Work queues with SLAs.

Async / sync support

Wrapper	Support
`Func<R>`	❌ No
`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


// api-reference
// On Func1<T, R>
Func1<T, R> priorityQueue({
 required int Function(T arg) priority,
 int? capacity,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> priorityQueue({
 required int Function(T1 arg1, T2 arg2) priority,
 int? capacity,
});

Parameters

Parameter	Type	Default	Description
`priority`	`int Function(...)`	required	Returns priority; higher values run first.
`capacity`	`int?`	`null`	Maximum queue size. `null` means unbounded.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


var order = <int>[];
final process = Func1<int, void>((value) async {
 order.add(value);
}).priorityQueue(priorityFn: (int value) => value);

process(1);
process(10);
process(5);

await Future<void>.delayed(Duration(milliseconds: 100));
// order == [10, 5, 1]
print(order);

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


final handleTask = Func1<int, void>((priority) async {
 print('handling $priority');
}).priorityQueue(
 priorityFn: (int priority) => priority,
 maxQueueSize: 100,
);

void main() async {
 handleTask(10);
 handleTask(1);
}

Best practices

Keep the priority function fast and deterministic.
Set a capacity to prevent memory exhaustion under overload.
Consider using stable sorting so equal-priority tasks preserve FIFO order.

Common pitfalls

Priority inversion: If a high-priority task is slow, lower-priority tasks can starve.
Full queue: When capacity is set and the queue is full, new calls throw StateError.

Proxy

Sun, 21 Jun 2026 18:27:01 +0000

Proxy

What it is

proxy is a decorator that intercepts function calls with before/after hooks and argument transformation.

When to use it

Dependency injection and testing.
A/B testing where you switch between implementations.
Feature flags that change behavior dynamically.

API reference

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


// api-reference
// On Func<R>
Func<R> proxy({
 void Function()? beforeCall,
 R Function(R result)? afterCall,
 void Function(Object error, StackTrace stackTrace)? onError,
});

// On Func1<T, R>
Func1<T, R> proxy({
 void Function(T arg)? beforeCall,
 T Function(T arg)? transformArg,
 R Function(R result)? afterCall,
 void Function(Object error, StackTrace stackTrace)? onError,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> proxy({
 void Function(T1 arg1, T2 arg2)? beforeCall,
 (T1, T2) Function(T1 arg1, T2 arg2)? transformArgs,
 R Function(R result)? afterCall,
 void Function(Object error, StackTrace stackTrace)? onError,
});

Parameters

Parameter	Type	Description
`beforeCall`	`void Function(...)?`	Invoked before the wrapped function.
`transformArg` / `transformArgs`	`T Function(T)?` / `(T1, T2) Function(T1, T2)?`	Transforms arguments before passing them to the wrapped function.
`afterCall`	`R Function(R)?`	Transforms the result after successful execution.
`onError`	`void Function(Object, StackTrace)?`	Called when the wrapped function throws; the error is still rethrown.

Examples

Basic example

1
2
3
4
5
6
7


final proxy = Func1<int, int>((n) async => n * 2).proxy(
 beforeCall: (n) => print('input: $n'),
 transformArg: (n) => n.abs(),
 afterCall: (r) => r * 10,
);

print(await proxy(-5)); // 100

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


final apiProxy = Func1<String, User>((id) async {
 return await api.getUser(id) as User;
}).proxy(
 beforeCall: (id) => logger.info('Fetching user $id'),
 afterCall: (user) {
 logger.info('Got user: $user');
 return user;
 },
);

print(await apiProxy('123'));

Best practices

Use proxy for cross-cutting concerns like logging, normalization, or enrichment.
Prefer tap when you only need to observe results without transforming them.

Common pitfalls

onError is called but the original exception is still rethrown.
afterCall is not called when the function fails.

Race

Sun, 21 Jun 2026 18:27:01 +0000

Race

What it is

race runs multiple functions concurrently and returns the result of the first one to complete. The remaining futures are ignored.

When to use it

Trying several equivalent data sources and using the fastest response.
Timeout patterns when combined with a timed fallback.
Competitive probes.

Async / sync support

Wrapper	Support
`Func1<T, R>`	✅ Async
`Func2<T1, T2, R>`	✅ Async

API reference

1
2
3
4
5
6


// api-reference
// On Func1<T, R>
Func1<T, R> race(List<Func1<T, R>> competitors);

// On Func2<T1, T2, R>
Func2<T1, T2, R> race(List<Func2<T1, T2, R>> competitors);

Parameters

Parameter	Type	Description
`competitors`	`List<Func1<T, R>>` or `List<Func2<T1, T2, R>>`	Functions to race against each other.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


final fast = Func1<int, String>((n) async {
 await Future<void>.delayed(Duration(milliseconds: 10));
 return 'fast';
});
final slow = Func1<int, String>((n) async {
 await Future<void>.delayed(Duration(milliseconds: 100));
 return 'slow';
});

final racer = fast.race(competitors: [slow]);
print(await racer(0)); // fast

Real-world example

1
2
3
4
5
6
7
8
9


final fetchQuote = Func1<String, Quote>(
 (symbol) async => await primaryApi.quote(symbol) as Quote,
).race(competitors: [
 Func1<String, Quote>((symbol) async => await secondaryApi.quote(symbol) as Quote),
 Func1<String, Quote>((symbol) async => await backupExchange.quote(symbol) as Quote),
]);

final quote = await fetchQuote('AAPL');
print(quote);

Best practices

Ensure all competitors return the same type.
Be aware that losers continue running in the background; cancel them if they hold resources.
Combine with fallback if all competitors might fail.

Common pitfalls

Resource leaks: Losing competitors are not automatically cancelled.
First error wins: If the first future to complete is an error, race returns that error even if others would succeed.

Rate Limit

Sun, 21 Jun 2026 18:27:01 +0000

Rate Limit

What it is

Rate limit restricts how many executions can occur within a time window. Excess calls either wait or fail, depending on the strategy.

When to use it

API clients that must respect a server’s rate limit.
Sending notifications or emails without overwhelming the provider.
Throttling high-frequency user actions.

Async / sync support

Wrapper	Support
`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
21
22
23


// api-reference
// On Func<R>
Func<R> rateLimit({
 required int maxCalls,
 required Duration window,
 RateLimitStrategy strategy = RateLimitStrategy.queue,
});

// On Func1<T, R>
Func1<T, R> rateLimit({
 required int maxCalls,
 required Duration window,
 RateLimitStrategy strategy = RateLimitStrategy.queue,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> rateLimit({
 required int maxCalls,
 required Duration window,
 RateLimitStrategy strategy = RateLimitStrategy.queue,
});

enum RateLimitStrategy { queue, reject }

Parameters

Parameter	Type	Default	Description
`maxCalls`	`int`	required	Maximum allowed executions per window.
`window`	`Duration`	required	Sliding time window.
`strategy`	`RateLimitStrategy`	`queue`	`queue` waits for the next slot; `reject` throws `RateLimitException`.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


var calls = 0;
final limitedApi = Func<int>(() async => ++calls).rateLimit(
 maxCalls: 2,
 window: Duration(seconds: 1),
 strategy: RateLimitStrategy.tokenBucket,
);

await limitedApi();
await limitedApi();
final third = limitedApi(); // queued until the window refreshes
await third;
// calls == 3
print(calls);

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


final sendEmail = Func1<Email, void>((email) async {
 await mailer.send(email);
}).rateLimit(
 maxCalls: 10,
 window: Duration(minutes: 1),
 strategy: RateLimitStrategy.slidingWindow,
);

void main() async {
 await sendEmail(Email());
}

Best practices

Choose reject for user-facing operations that should fail fast.
Choose queue for background tasks where latency is acceptable.
Set maxCalls slightly below the actual provider limit to leave headroom.

Common pitfalls

Bursts at window boundaries: Sliding windows smooth bursts better than fixed windows; funx uses a sliding window.
Queue growth: With queue, a sustained overload can create a long backlog.

Recovery

Sun, 21 Jun 2026 18:27:01 +0000

Recovery

What it is

Recovery intercepts failures and runs a recovery action. It is intended for side effects such as logging, cleanup, or compensating work; by default the original error is rethrown.

When to use it

Cleaning up resources after a partial failure.
Running an alternative workflow when the primary one fails.
Transforming an error into a meaningful result with side effects.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
Func<R> recover(RecoveryStrategy strategy);

// On Func1<T, R>
Func1<T, R> recover(RecoveryStrategy strategy);

// On Func2<T1, T2, R>
Func2<T1, T2, R> recover(RecoveryStrategy strategy);

class RecoveryStrategy {
 const RecoveryStrategy({
 required Future<void> Function(Object error) onError,
 bool Function(Object error)? shouldRecover,
 bool rethrowAfterRecovery = true,
 });
}

Parameters

Parameter	Type	Description
`onError`	`Future<void> Function(Object error)`	Side effect to run when an error occurs.
`shouldRecover`	`bool Function(Object error)?`	Predicate deciding whether to run the recovery action.
`rethrowAfterRecovery`	`bool`	Whether to rethrow the original error after the action (default `true`).

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


final risky = Func<int>(() async => throw Exception('boom')).recover(
 RecoveryStrategy(
 onError: (error) async => print('recovered from $error'),
 ),
);

try {
 await risky();
} catch (_) {
 print('-1'); // recovery action ran before the original error was rethrown
}

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


final processPayment = Func1<Payment, Receipt>((payment) async {
 return await primaryGateway.charge(payment) as Receipt;
}).recover(
 RecoveryStrategy(
 onError: (error) async => logger.warning(
 'Primary gateway failed',
 error,
 ),
 shouldRecover: (error) => error is NetworkException,
 ),
);

// Usage
await processPayment(Payment()).catchError((_) => Receipt());

Best practices

Log the failure before recovering.
Keep recovery paths simpler than the main path.
Use fallback when you only need a default value; use recover when you need logic.

Common pitfalls

Recovery masking errors: Make sure recovery failures are also handled or logged.
Type mismatch: The recovery handler must return the same result type R.

Repeat

Sun, 21 Jun 2026 18:27:01 +0000

Repeat

What it is

repeat executes the wrapped function multiple times, optionally until a condition is met. It can be used as a decorator or as a standalone helper.

When to use it

Polling loops.
Retrying with a custom condition.
Executing a side effect a fixed number of times.

Async / sync support

Wrapper	Support
`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
21
22
23
24


// api-reference
// As a decorator on Func<R>
Func<R> repeat({
 int? times,
 Duration? interval,
 bool Function(R result)? until,
 void Function(int iteration, R result)? onIteration,
});

// As a decorator on Func1<T, R>
Func1<T, R> repeat({
 int? times,
 Duration? interval,
 bool Function(R result)? until,
 void Function(int iteration, R result)? onIteration,
});

// As a decorator on Func2<T1, T2, R>
Func2<T1, T2, R> repeat({
 int? times,
 Duration? interval,
 bool Function(R result)? until,
 void Function(int iteration, R result)? onIteration,
});

Parameters

Parameter	Type	Default	Description
`times`	`int?`	`null`	Maximum number of repetitions. `null` means infinite, so always provide `times` or `until`.
`interval`	`Duration?`	`null`	Optional delay between repetitions.
`until`	`bool Function(R)?`	`null`	If provided, stops early when the predicate returns `true`.
`onIteration`	`void Function(int, R)?`	`null`	Callback invoked after each iteration.

Examples

Basic example

1
2
3
4


var calls = 0;
final counter = Func<int>(() async => ++calls).repeat(times: 3);

print(await counter()); // 3

Real-world example

1
2
3
4
5
6
7


final waitForReady = Func<Status>(() async => await api.status() as Status).repeat(
 times: 20,
 until: (status) => status.ready,
 interval: Duration(seconds: 1),
);

print(await waitForReady());

Best practices

Always set a finite times to avoid infinite loops.
Use delay to avoid tight polling loops.
Combine with timeout() to add a hard deadline.

Common pitfalls

No delay polling: Without a delay, the loop can consume excessive CPU.
Until predicate never true: If until never matches, repeat returns the last result after times attempts.

Resilience Policy

Sun, 21 Jun 2026 18:27:01 +0000

Resilience Policy

What it is

ResiliencePolicy composes the most common reliability decorators — timeout, retry, circuitBreaker, and fallback — into a single, reusable policy. It applies them in the order recommended for resilient remote calls, so you do not have to remember the correct chaining order.

When to use it

HTTP or RPC calls that need timeout, retry, circuit breaker, and fallback together.
Any function where you want a pre-packaged resilience stack.
When the same resilience settings are reused across multiple functions.

Async / sync support

Wrapper	Support
`Func<R>`	✅ Async
`Func1<T, R>`	✅ Async
`Func2<T1, T2, R>`	✅ Async
`FuncSync<R>`	❌ No

How it works

The policy applies decorators from the inside out in this order:

Retry

Sun, 21 Jun 2026 18:27:01 +0000

Retry

What it is

Retry re-executes a function when it throws, up to a maximum number of attempts. It supports configurable delay/backoff, jitter, and filtering of retryable exceptions.

When to use it

Network requests that fail transiently.
Flaky external APIs.
Operations that may briefly contend for locks or resources.

Async / sync support

Wrapper	Support
`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
21
22
23
24


// api-reference
// On Func<R>
Func<R> retry({
 int maxAttempts = 3,
 BackoffStrategy? backoff,
 bool Function(Object error)? retryIf,
 void Function(int attempt, Object error)? onRetry,
});

// On Func1<T, R>
Func1<T, R> retry({
 int maxAttempts = 3,
 BackoffStrategy? backoff,
 bool Function(Object error)? retryIf,
 void Function(int attempt, Object error)? onRetry,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> retry({
 int maxAttempts = 3,
 BackoffStrategy? backoff,
 bool Function(Object error)? retryIf,
 void Function(int attempt, Object error)? onRetry,
});

Parameters

Parameter	Type	Default	Description
`maxAttempts`	`int`	`3`	Maximum total attempts (including the first).
`backoff`	`BackoffStrategy?`	`null`	Backoff strategy between attempts. See Backoff.
`retryIf`	`bool Function(Object error)?`	`null`	Predicate deciding whether an error is retryable.
`onRetry`	`void Function(int attempt, Object error)?`	`null`	Called before each retry.

Examples

Basic example

1
2
3
4
5
6
7
8
9


var attempt = 0;
final flaky = Func<String>(() async {
 attempt++;
 if (attempt < 3) throw Exception('fail');
 return 'success';
}).retry(maxAttempts: 5);

print(await flaky()); // success
// attempt == 3

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


final fetchUser = Func1<String, User>((id) async {
 return api.user(id) as User;
}).retry(
 maxAttempts: 4,
 backoff: ExponentialBackoff(
 initialDelay: Duration(milliseconds: 200),
 maxDelay: Duration(seconds: 5),
 ),
 retryIf: (error) => error is NetworkException,
);

// Usage
print(await fetchUser('user-123'));

Best practices

Always set maxAttempts to a finite value.
Use retryIf to avoid retrying programming errors or auth failures.
Combine with backoff to avoid hammering a failing service.
Place retry outside timeouts if you want each attempt to have its own deadline, or inside if the deadline covers all attempts.

Common pitfalls

Retrying too much: Without a backoff, retries can overload a recovering service.
Retrying everything: A retryIf that returns true for every error can mask logic bugs and waste time.
Uncaught final failure: After exhausting attempts, the last exception is rethrown; handle it at the call site.

RWLock

Sun, 21 Jun 2026 18:27:01 +0000

RWLock

What it is

RWLock allows multiple concurrent readers or a single writer. Read operations do not block each other, but a writer blocks all readers and other writers.

When to use it

Caches or lookup tables that are read often and written rarely.
Shared configuration that multiple isolates or async tasks read.
Any read-heavy workload where reader concurrency matters.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
Func<R> readLock([RWLock? lock]);
Func<R> writeLock([RWLock? lock]);

// On Func1<T, R>
Func1<T, R> readLock([RWLock? lock]);
Func1<T, R> writeLock([RWLock? lock]);

// On Func2<T1, T2, R>
Func2<T1, T2, R> readLock([RWLock? lock]);
Func2<T1, T2, R> writeLock([RWLock? lock]);

class RWLock {
 void acquireRead();
 void releaseRead();
 Future<void> acquireWrite();
 void releaseWrite();
}

Parameters

Parameter	Type	Default	Description
`lock`	`RWLock?`	`RWLock()`	Optional shared `RWLock` instance.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


var value = 0;
final rwLock = RWLock();

final read = Func<int>(() async => value).readLock(rwLock);
final write = Func1<int, void>((v) async {
 value = v;
}).writeLock(rwLock);

await write(42);
print(await read()); // 42

Real-world example

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


final config = <String, String>{};
final rwLock = RWLock();

final getConfig = Func1<String, String?>(
 (key) async => config[key],
).readLock(rwLock);

final setConfig = Func2<String, String, void>(
 (key, value) async {
 config[key] = value;
 },
).writeLock(rwLock);

await setConfig('theme', 'dark');
print(await getConfig('theme'));

// Multiple readers can run concurrently; writes are exclusive.

Best practices

Use readLock for pure read operations.
Use writeLock for any operation that mutates shared state.
Share the same RWLock instance between readers and writers.

Common pitfalls

Writer starvation: If readers keep arriving continuously, a writer may wait indefinitely.
Mixing lock types: Using a plain lock() on writers while readers use readLock() will not coordinate; use the same RWLock.

Saga

Sun, 21 Jun 2026 18:27:01 +0000

Saga

What it is

Saga models a long-running business transaction as a sequence of steps, each with a compensation action. If a step fails, previously completed steps are rolled back in reverse order.

When to use it

Distributed transactions across multiple services.
Booking workflows (reserve, charge, confirm) that must undo earlier steps on failure.
Any multi-step process that requires compensating actions.

Async / sync support

Wrapper	Support
`Func1<T, R>`	✅ Async
`Func2<T1, T2, R>`	✅ Async

API reference

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// api-reference
class Saga<T, R> {
 Saga();

 Saga<T, R> step(
 Func1<T, R> action, {
 required Func2<R, T, void> compensate,
 });

 Future<R> execute(T input);
}

Methods

Method	Description
`step(action, {required compensate})`	Adds a step with its compensation action.
`execute(T input)`	Runs all steps sequentially. On failure, compensations run in reverse order.

Parameters

Parameter	Type	Description
`action`	`Func1<T, R>`	Step to execute.
`compensate`	`Func2<R, T, void>`	Undo action receiving the step result and original input.

Examples

Basic example

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


final saga = Func1<int, int>((n) async => n).saga(
 steps: [
 SagaStep<int, int>(
 action: Func1<int, int>((n) async => n + 10),
 compensation: Func1<int, void>((result) async {
 print('compensate +10');
 }),
 ),
 SagaStep<int, int>(
 action: Func1<int, int>((n) async => throw Exception('fail')),
 compensation: Func1<int, void>((result) async {
 print('compensate fail');
 }),
 ),
 ],
);

try {
 await saga(0);
} catch (e) {
 print('rolled back');
}

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


final bookingSaga = Func1<BookingRequest, Reservation>(
 (req) async => await bookingApi.reserve(req) as Reservation,
).saga(
 steps: [
 SagaStep<Reservation, Payment>(
 action: Func1<Reservation, Payment>(
 (reservation) async =>
 await paymentService.charge(reservation) as Payment,
 ),
 compensation: Func1<Payment, void>(
 (payment) async => await paymentService.refund(payment),
 ),
 ),
 SagaStep<Payment, Booking>(
 action: Func1<Payment, Booking>(
 (payment) async => await bookingApi.confirm(payment) as Booking,
 ),
 compensation: Func1<Booking, void>(
 (booking) async => await bookingApi.cancel(booking),
 ),
 ),
 ],
);

final booking = await bookingSaga(BookingRequest());
print(booking);

Best practices

Make compensation actions idempotent.
Keep compensation logic simple and reliable; it must not fail often.
Log every compensation for auditability.
Test both the happy path and each failure point.

Common pitfalls

Compensation failures: If a compensation throws, the saga is left in a partially compensated state. Add monitoring and manual intervention procedures.
Non-idempotent compensations: Running the same compensation twice should be safe.
Shared mutable state: Steps should communicate through their inputs/outputs, not shared mutable state.

schedule

Sun, 21 Jun 2026 18:27:01 +0000

schedule

What it is

schedule executes a function once after a specified delay. It is the simplest one-shot timer decorator.

When to use it

Showing a tooltip after the user hovers for a short time.
Firing a one-time analytics beacon.
Kicking off async work later in the event loop or after a delay.

Async / sync support

Wrapper	Support
`Func<R>`	✅ Async
`Func1<T, R>`	✅ Async
`Func2<T1, T2, R>`	✅ Async
`FuncSync<R>`	✅ Sync

API reference

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


// api-reference
// On Func<R>
ScheduleExtension<R> schedule({
 required DateTime at,
 MissedExecutionPolicy onMissed = MissedExecutionPolicy.skip,
 MissedExecutionCallback? onMissedExecution,
 ScheduleErrorCallback? onScheduleError,
});

// On Func1<T, R>
ScheduleExtension1<T, R> schedule({
 required DateTime at,
 MissedExecutionPolicy onMissed = MissedExecutionPolicy.skip,
 MissedExecutionCallback? onMissedExecution,
 ScheduleErrorCallback? onScheduleError,
});

// On Func2<T1, T2, R>
ScheduleExtension2<T1, T2, R> schedule({
 required DateTime at,
 MissedExecutionPolicy onMissed = MissedExecutionPolicy.skip,
 MissedExecutionCallback? onMissedExecution,
 ScheduleErrorCallback? onScheduleError,
});

// On FuncSync<R>
ScheduleExtensionSync<R> schedule({
 required DateTime at,
 MissedExecutionPolicy onMissed = MissedExecutionPolicy.skip,
 MissedExecutionCallback? onMissedExecution,
 ScheduleErrorCallback? onScheduleError,
});

Parameters

Parameter	Type	Default	Description
`at`	`DateTime`	required	Time at which to execute the function.

Returned wrapper methods

1
2
3


// api-reference
ScheduleSubscription<R> start(); // Starts the schedule and returns a subscription.
// ScheduleSubscription exposes pause(), resume(), and cancel().

Examples

Basic example

1
2
3
4
5
6
7


final greet = Func<String>(() async => 'hello').schedule(
 at: DateTime.now().add(Duration(milliseconds: 50)),
);

final subscription = greet.start();
await Future<void>.delayed(Duration(milliseconds: 100));
subscription.cancel();

Real-world example

1
2
3
4
5
6
7
8
9


final showHint = Func<void>(() async => logger.info('tooltip')).schedule(
 at: DateTime.now().add(Duration(milliseconds: 400)),
);

// On hover:
final subscription = showHint.start();

// On unhover:
subscription.cancel();

Best practices

Always keep the subscription returned by start() so you can call cancel().
Use schedule for one-shot delays; use scheduleRecurring for repeated execution.
For Flutter widgets, cancel in dispose().

Common pitfalls

Lost timers: Calling start() begins the timer; keep the subscription so you can cancel it later.
Forgetting to await: If you do not await the returned future and the widget is disposed, the function may still run.

scheduleCustom

Sun, 21 Jun 2026 18:27:01 +0000

scheduleCustom

What it is

scheduleCustom lets you define your own scheduling policy through a scheduler function. The scheduler receives the last execution time and returns the next execution time, allowing irregular or adaptive schedules.

When to use it

Exponential backoff polling.
Adaptive schedules that respond to load or result values.
Any schedule that cannot be expressed by schedule or scheduleRecurring.

Async / sync support

Wrapper	Support
`Func<R>`	✅ Async
`FuncSync<R>`	✅ Sync

API reference

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


// api-reference
// On Func<R>
ScheduleExtension<R> scheduleCustom({
 required DateTime Function(DateTime? lastExecution) scheduler,
 int? maxIterations,
 bool Function(R result)? stopCondition,
 ScheduleTickCallback? onTick,
 ScheduleErrorCallback? onScheduleError,
});

// On FuncSync<R>
ScheduleExtensionSync<R> scheduleCustom({
 required DateTime Function(DateTime? lastExecution) scheduler,
 int? maxIterations,
 bool Function(R result)? stopCondition,
 ScheduleTickCallback? onTick,
 ScheduleErrorCallback? onScheduleError,
});

Parameters

Parameter	Type	Default	Description
`scheduler`	`DateTime Function(DateTime? lastExecution)`	required	Returns the next execution time.
`maxIterations`	`int?`	`null`	Stops after this many executions.
`stopCondition`	`bool Function(R result)?`	`null`	Optional early-stop predicate.

`scheduler` contract

lastExecution is the time of the previous execution; null on the first call.
Return a DateTime in the future to schedule the next execution.
Use maxIterations or stopCondition to stop the scheduler.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


var callCount = 0;
final task = Func<int>(() async => ++callCount).scheduleCustom(
 scheduler: (_) => DateTime.now().add(Duration(milliseconds: 50)),
 maxIterations: 3,
);

final subscription = task.start();
await Future<void>.delayed(Duration(milliseconds: 300));
subscription.cancel();
// callCount == 3

Real-world example

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


var iteration = 0;
final pollWithBackoff = Func<Status>(() async => api.status() as Status)
 .scheduleCustom(
 scheduler: (_) {
 final base = Duration(seconds: 1);
 if (iteration > 5) iteration = 5;
 final delay = base * (1 << iteration);
 iteration++;
 return DateTime.now().add(delay);
 },
 stopCondition: (status) => status.ready,
 );

final subscription = pollWithBackoff.start();
await Future<void>.delayed(Duration(seconds: 5));
subscription.cancel();

Best practices

Cap exponential growth so delays do not become unreasonably long.
Use maxIterations or stopCondition to stop the scheduler cleanly.
Keep the policy pure when possible; side effects make schedules hard to reason about.

Common pitfalls

First-execution timing: The scheduler is called before the first execution, so lastExecution is null. Returning the current time starts immediately; returning a future DateTime defers the first run.
Infinite loops: If the scheduler never reaches maxIterations and stopCondition is absent, the scheduler runs forever.

scheduleRecurring

Sun, 21 Jun 2026 18:27:01 +0000

scheduleRecurring

What it is

scheduleRecurring runs a function repeatedly at a fixed interval until cancelled or until a predicate tells it to stop.

When to use it

Background polling of an API.
Heartbeat or keep-alive pings.
Periodic cleanup or cache refresh.

Async / sync support

Wrapper	Support
`Func<R>`	✅ Async
`FuncSync<R>`	✅ Sync

API reference

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


// api-reference
// On Func<R>
ScheduleExtension<R> scheduleRecurring({
 required Duration interval,
 int? maxIterations,
 bool Function(R result)? stopCondition,
 MissedExecutionPolicy onMissed = MissedExecutionPolicy.skip,
 MissedExecutionCallback? onMissedExecution,
 ScheduleTickCallback? onTick,
 ScheduleErrorCallback? onScheduleError,
 bool executeImmediately = false,
});

// On FuncSync<R>
ScheduleExtensionSync<R> scheduleRecurring({
 required Duration interval,
 int? maxIterations,
 bool Function(R result)? stopCondition,
 MissedExecutionPolicy onMissed = MissedExecutionPolicy.skip,
 MissedExecutionCallback? onMissedExecution,
 ScheduleTickCallback? onTick,
 ScheduleErrorCallback? onScheduleError,
 bool executeImmediately = false,
});

Parameters

Parameter	Type	Default	Description
`interval`	`Duration`	required	Delay between executions.
`stopCondition`	`bool Function(R result)?`	`null`	If provided, the scheduler stops when this predicate returns `true`.

Returned `ScheduleExtension` methods

1
2
3


// api-reference
ScheduleSubscription<R> start(); // Begins recurring execution.
// ScheduleSubscription exposes pause(), resume(), and cancel().

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


var counter = 0;
final ticker = Func<int>(() async => ++counter).scheduleRecurring(
 interval: Duration(milliseconds: 50),
 stopCondition: (value) => value >= 3,
);

final subscription = ticker.start();
await Future<void>.delayed(Duration(milliseconds: 300));
subscription.cancel();
// counter == 3

Real-world example

1
2
3
4
5
6
7
8
9


final pollStatus = Func<Status>(() async => api.status() as Status)
 .scheduleRecurring(
 interval: Duration(seconds: 10),
 stopCondition: (status) => status.ready,
 );

final subscription = pollStatus.start();
await Future<void>.delayed(Duration(seconds: 5));
subscription.cancel();

Best practices

Always call cancel() on the subscription when the component is disposed to avoid memory leaks.
Keep the interval longer than the expected execution time; otherwise executions will queue up or overlap.
Use stopCondition for finite tasks to avoid manual cleanup.

Common pitfalls

No automatic start: Calling scheduleRecurring returns a controller; you must call start() to begin execution.
Overlapping executions: If the function is slower than the interval, executions may overlap; add a lock or use throttle if this is a problem.

Semaphore

Sun, 21 Jun 2026 18:27:01 +0000

Semaphore

What it is

A semaphore limits the number of concurrent executions. Once the limit is reached, additional calls wait until a slot becomes free.

When to use it

Limiting concurrent network requests to the same host.
Controlling CPU or memory usage by bounding parallel work.
Pool-style resource access.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
Func<R> semaphore(int maxConcurrent, {Semaphore? semaphore});

// On Func1<T, R>
Func1<T, R> semaphore(int maxConcurrent, {Semaphore? semaphore});

// On Func2<T1, T2, R>
Func2<T1, T2, R> semaphore(int maxConcurrent, {Semaphore? semaphore});

class Semaphore {
 Semaphore(int maxConcurrency);
 Future<void> acquire();
 void release();
}

Parameters

Parameter	Type	Default	Description
`maxConcurrent`	`int`	required	Maximum number of concurrent executions.
`semaphore`	`Semaphore?`	`Semaphore(maxConcurrent)`	Optional shared semaphore instance.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


var running = 0;
var maxRunning = 0;

final worker = Func<int>(() async {
 running++;
 if (running > maxRunning) maxRunning = running;
 await Future<void>.delayed(Duration(milliseconds: 50));
 running--;
 return running;
}).semaphore(maxConcurrent: 2);

await Future.wait([for (var i = 0; i < 5; i++) worker()]);
// maxRunning == 2

Real-world example

1
2
3
4
5
6


final urls = <String>['a.txt', 'b.txt'];
final download = Func1<String, File>((url) async {
 return http.download(url) as File;
}).semaphore(maxConcurrent: 4); // at most 4 downloads at once

await Future.wait<File>(urls.map(download));

Best practices

Choose maxConcurrent based on the bottleneck resource (network, CPU, file handles).
Use a shared semaphore across multiple functions if they share the same resource pool.
Do not acquire the same semaphore twice in the same call stack.

Common pitfalls

Semaphore leaks: If the inner function throws, the semaphore must release. The wrapper handles this internally; do not wrap acquire()/release() manually.
Too small limit: A limit of 1 is equivalent to a lock; make sure you need concurrency before choosing a higher value.

Sun, 21 Jun 2026 18:27:01 +0000

What it is

Share ensures that a single underlying execution is shared among all concurrent callers, even with different arguments. It is similar to deduplicate but typically shares the result of a no-argument or global operation.

When to use it

One-time initialization that multiple callers await.
Singleton setup that must not run twice.
Shared resource warm-up.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
Func<R> share();

// On Func1<T, R>
Func1<T, R> share();

// On Func2<T1, T2, R>
Func2<T1, T2, R> share();

No parameters.

Snapshot

Sun, 21 Jun 2026 18:27:01 +0000

Snapshot

What it is

snapshot captures and restores external state before and after function calls. It can create snapshots manually on demand or automatically before each execution, making it useful for undo/redo, rollback, and checkpointing workflows.

When to use it

Building undo/redo functionality.
Checkpointing long-running workflows.
Rolling back state when an operation fails or needs retrying.

Async / sync support

Wrapper	Support
`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
21
22
23
24
25
26
27


// api-reference
// On Func<R>
SnapshotExtension<R, S> snapshot<S>({
 required S Function() getState,
 required void Function(S state) setState,
 bool autoSnapshot = false,
 void Function(Snapshot<S> snapshot)? onSnapshot,
 void Function(Snapshot<S> snapshot)? onRestore,
});

// On Func1<T, R>
SnapshotExtension1<T, R, S> snapshot<S>({
 required S Function() getState,
 required void Function(S state) setState,
 bool autoSnapshot = false,
 void Function(Snapshot<S> snapshot)? onSnapshot,
 void Function(Snapshot<S> snapshot)? onRestore,
});

// On Func2<T1, T2, R>
SnapshotExtension2<T1, T2, R, S> snapshot<S>({
 required S Function() getState,
 required void Function(S state) setState,
 bool autoSnapshot = false,
 void Function(Snapshot<S> snapshot)? onSnapshot,
 void Function(Snapshot<S> snapshot)? onRestore,
});

No parameters on the call itself.

Switch

Sun, 21 Jun 2026 18:27:01 +0000

Switch

What it is

SwitchExtension is a standalone multi-branch control-flow wrapper. It evaluates the selector and executes the matching branch, or a default branch if none match.

When to use it

Replacing long if/else if chains.
Routing events to handlers based on type or value.
Configurable strategy selection.

API reference

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


// api-reference
class SwitchExtension1<T, R> {
 SwitchExtension1({
 required Object? Function(T arg) selector,
 required Map<Object?, Func1<T, R>> cases,
 Func1<T, R>? defaultCase,
 });

 Future<R> call(T arg);
}

class SwitchExtension2<T1, T2, R> {
 SwitchExtension2({
 required Object? Function(T1 arg1, T2 arg2) selector,
 required Map<Object?, Func2<T1, T2, R>> cases,
 Func2<T1, T2, R>? defaultCase,
 });

 Future<R> call(T1 arg1, T2 arg2);
}

Parameters

Parameter	Type	Description
`selector`	`Object? Function(T)`	Returns a value matched against `cases` keys.
`cases`	`Map<Object?, Func1<T, R>>`	Map of selector values to function branches.
`defaultCase`	`Func1<T, R>?`	Optional branch used when no case matches.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


final classify = SwitchExtension1<int, String>(
 selector: (n) => n < 0 ? 'negative' : n == 0 ? 'zero' : 'other',
 cases: {
 'negative': Func1<int, String>((n) async => 'negative'),
 'zero': Func1<int, String>((n) async => 'zero'),
 },
 defaultCase: Func1<int, String>((n) async => 'positive'),
);

print(await classify(-3)); // negative
print(await classify(0)); // zero
print(await classify(7)); // positive

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


final handleEvent = SwitchExtension1<String, void>(
 selector: (event) => event,
 cases: {
 'login': Func1<String, void>((e) async => auth.login(e)),
 'logout': Func1<String, void>((e) async => auth.logout()),
 },
 defaultCase: Func1<String, void>((e) async => analytics.track(e)),
);

await handleEvent('login');

Best practices

Order cases from most specific to least specific.
Provide a defaultCase unless you want unmatched inputs to throw.
Keep predicates side-effect free.

Common pitfalls

Case order matters: The first matching case wins; overlapping predicates can hide later branches.
No default case: If no predicate matches and there is no default, the switch throws.

Tap

Sun, 21 Jun 2026 18:27:01 +0000

Tap

What it is

tap runs a side-effect callback on the result or error of the wrapped function without changing the returned value.

When to use it

Logging results for debugging.
Emitting metrics after a function completes.
Triggering notifications on success or failure.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
Func<R> tap({
 FutureOr<void> Function(R result)? onValue,
 FutureOr<void> Function(Object error, StackTrace stackTrace)? onError,
});

// On Func1<T, R>
Func1<T, R> tap({
 FutureOr<void> Function(R result)? onValue,
 FutureOr<void> Function(Object error, StackTrace stackTrace)? onError,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> tap({
 FutureOr<void> Function(R result)? onValue,
 FutureOr<void> Function(Object error, StackTrace stackTrace)? onError,
});

Parameters

Parameter	Type	Description
`onValue`	`FutureOr<void> Function(R result)`	Called with the result on success.
`onError`	`FutureOr<void> Function(Object error, StackTrace stackTrace)`	Called with the error and stack trace on failure.

Examples

Basic example

1
2
3
4
5
6


final logResult = Func1<int, int>((n) async => n * 2).tap(
 onValue: (result) => print('doubled -> $result'),
);

print(await logResult(5)); // 10
// logs: doubled -> 10

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


final trackPayment = Func1<Payment, Receipt>((payment) async {
 return await gateway.charge(payment) as Receipt;
}).tap(
 onValue: (receipt) {
 analytics.track('payment_success', {'id': receipt.hashCode});
 },
 onError: (error, stack) {
 analytics.track('payment_failed', {'error': error.toString()});
 },
);

await trackPayment(Payment());

Best practices

Keep tap callbacks fast; slow callbacks delay the result.
Do not throw inside onValue or onError unless you want to change the wrapper’s outcome.
Use tap for observation only, not for business logic.

Common pitfalls

Callback exceptions: If a tap callback throws, the wrapper may fail even though the original function succeeded.
Mutating results: Modifying the result object inside onValue affects downstream callers.

Throttle

Sun, 21 Jun 2026 18:27:01 +0000

Throttle

What it is

Throttle limits a function to at most one execution per time window. Unlike debounce, which waits for activity to stop, throttle enforces a strict minimum interval between executions.

When to use it

Button click handlers that should not fire more than once per second.
Scroll or drag event handlers that need periodic updates without overwhelming the UI.
Metrics/reporting calls that should sample at a fixed rate.

Async / sync support

Wrapper	Support
`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> throttle(
 Duration duration, {
 ThrottleMode mode = ThrottleMode.leading,
});

// On Func1<T, R>
Func1<T, R> throttle(
 Duration duration, {
 ThrottleMode mode = ThrottleMode.leading,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> throttle(
 Duration duration, {
 ThrottleMode mode = ThrottleMode.leading,
});

enum ThrottleMode { leading, trailing, both }

Parameters

Parameter	Type	Default	Description
`duration`	`Duration`	required	Minimum interval between executions.
`mode`	`ThrottleMode`	`leading`	When to execute: `leading`, `trailing`, or `both`.

Returned wrapper methods

1
2


// api-reference
void reset(); // Clears the throttle window so the next call executes immediately.

Modes

leading (default): first call executes immediately; calls inside the window throw StateError.
trailing: first call schedules execution at the end of the window; subsequent calls inside the window return the same pending future.
both: executes immediately and schedules a trailing execution.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


var callCount = 0;
final track = Func1<double, void>((position) async {
 callCount++;
}).throttle(Duration(milliseconds: 50));

await track(100);
try {
 await track(200);
} catch (e) {
 print('throttled: $e');
}

print('calls: $callCount'); // 1

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


final saveProgress = Func1<Progress, void>(
 (progress) async {
 await cloud.save(progress);
 },
).throttle(
 Duration(seconds: 2),
 mode: ThrottleMode.trailing,
);

await saveProgress(Progress());

// Game loop calls saveProgress(progress) frequently;
// only the latest progress is saved every 2 seconds.

Best practices

Use leading for actions where the first user interaction must be immediate (e.g., a save button).
Use trailing when you care about the final state (e.g., tracking the last scroll position).
Call reset() after a major state change when you want to allow an immediate re-execution.

Common pitfalls

Unhandled StateError in leading mode: Calls inside the window throw. Wrap them in try/catch or switch to trailing mode.
Losing results in trailing mode: Multiple calls inside the window share the same pending future, which is usually what you want, but be aware that arguments from intermediate calls are ignored.

Timeout

Sun, 21 Jun 2026 18:27:01 +0000

Timeout

What it is

Timeout caps how long a single function invocation may run. If the inner function does not complete in time, the wrapper either throws a TimeoutException or returns a fallback value provided by onTimeout.

When to use it

Wrapping network calls that might hang.
Adding a deadline to long-running computations.
Preventing resource leaks from runaway async operations.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
Func<R> timeout(
 Duration duration, {
 FutureOr<R> Function()? onTimeout,
});

// On Func1<T, R>
Func1<T, R> timeout(
 Duration duration, {
 FutureOr<R> Function()? onTimeout,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> timeout(
 Duration duration, {
 FutureOr<R> Function()? onTimeout,
});

Parameters

Parameter	Type	Default	Description
`duration`	`Duration`	required	Maximum time allowed for one execution.
`onTimeout`	`FutureOr<R> Function()?`	`null`	Optional fallback factory invoked on timeout. If omitted, a `TimeoutException` is thrown.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


final slow = Func<String>(() async {
 await Future<void>.delayed(Duration(seconds: 5));
 return 'done';
}).timeout(Duration(seconds: 2));

try {
 await slow();
} on TimeoutException {
 print('timed out');
}

Real-world example

1
2
3
4
5
6
7
8
9


final fetchUser = Func1<String, User>(
 (id) async => api.getUser(id) as User,
).timeout(
 Duration(seconds: 5),
 onTimeout: () => User(),
);

final user = await fetchUser('123'); // fallback if API hangs
print(user);

Best practices

Place timeout() as the outer layer when you want the deadline to cover retries, or inner when the deadline should apply to a single attempt.
Provide onTimeout when a degraded result is acceptable; omit it when the caller must handle the failure explicitly.
Choose deadlines based on the 99th percentile latency of the operation, not the average.

Common pitfalls

Resource leak: Timing out a future cancels the returned future but does not necessarily cancel the underlying work. The inner operation may continue running in the background.
Fallback mismatches: onTimeout must return the same type R as the wrapped function, otherwise the code will not compile.

Transform

Sun, 21 Jun 2026 18:27:01 +0000

Transform

What it is

transform maps the result of a wrapped function from one type to another.

When to use it

Adapting between different data representations.
Normalising input before processing.
Converting internal models to DTOs and back.

API reference

1
2
3
4
5
6
7
8
9


// api-reference
// On Func<R1>
Func<R2> transform<R2>(R2 Function(R1 result) mapper);

// On Func1<T, R1>
Func1<T, R2> transform<R2>(R2 Function(R1 result) mapper);

// On Func2<T1, T2, R1>
Func2<T1, T2, R2> transform<R2>(R2 Function(R1 result) mapper);

Parameters

Parameter	Type	Description
`mapper`	`R2 Function(R1)`	Maps the wrapped function’s result to a new type.

Examples

Basic example

1
2
3
4
5


final toUpper = Func1<String, String>((s) async => s.toUpperCase());

final transform = toUpper.transform<String>((s) => s.trim());

print(await transform(' hello ')); // HELLO

Real-world example

1
2
3
4
5


final transform = Func1<ApiRequest, String>((req) async {
 return await api.post(req.toString()) as String;
}).transform<DomainModel>((response) => DomainModel());

await transform(ApiRequest());

Best practices

Keep mappers pure and synchronous.
Handle nulls and edge cases inside mappers to avoid surprising the target.

Common pitfalls

Type mismatch: Mappers must match the generic types exactly; otherwise the code will not compile.
Mapper exceptions: Exceptions thrown in mappers propagate to the caller.

Validate

Sun, 21 Jun 2026 18:27:01 +0000

Validate

What it is

validate applies a validator to the arguments before execution. If validation fails, the wrapper throws a ValidationException.

When to use it

Input sanitization and validation at function entry.
Enforcing domain constraints (e.g., email format, positive amounts).
Converting validation logic into reusable decorators.

Async / sync support

Wrapper	Support
`Func<R>`	❌ No
`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


// api-reference
// On Func1<T, R>
Func1<T, R> validate({
 required List<String? Function(T arg)> validators,
 ValidationMode mode = ValidationMode.failFast,
 void Function(List<String> errors)? onValidationError,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> validate({
 required List<String? Function(T1 arg1, T2 arg2)> validators,
 ValidationMode mode = ValidationMode.failFast,
 void Function(List<String> errors)? onValidationError,
});

Parameters

Parameter	Type	Description
`validators`	`List<String? Function(...)>`	Returns `null` if valid, or an error message string if invalid.
`mode`	`ValidationMode`	`failFast` or `aggregate`.
`onValidationError`	`void Function(List<String>)?`	Called with the errors before throwing.

Examples

Basic example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


final doublePositive = Func1<int, int>((n) async => n * 2).validate(
 validators: [
 (n) => n > 0 ? null : 'must be positive',
 ],
);

print(await doublePositive(5)); // 10
try {
 await doublePositive(-1);
} on ValidationException catch (e) {
 print(e.message); // must be positive
}

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


final createUser = Func2<String, String, User>((email, name) async {
 return await userRepo.create(email: email, name: name) as User;
}).validate(
 validators: [
 (email, name) => email.contains('@') ? null : 'invalid email',
 (email, name) => name.isNotEmpty ? null : 'name required',
 ],
);

await createUser('user@example.com', 'Name');

Best practices

Return clear, actionable error messages.
Keep validators synchronous and free of side effects.
Layer multiple validators when order matters.

Common pitfalls

Null return semantics: Returning null means valid; any non-null string is treated as an error.
Validators throwing: If the validator throws, the wrapper propagates that exception, not a ValidationException.

Warm Up

Sun, 21 Jun 2026 18:27:01 +0000

Warm Up

What it is

Warm up eagerly executes the wrapped function once, so that subsequent callers receive a pre-computed result.

When to use it

Preloading configuration at app startup.
Warming caches before traffic arrives.
Preparing heavy objects during idle time.

Async / sync support

Wrapper	Support
`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


// api-reference
// On Func<R>
Func<R> warmUp();

// On Func1<T, R>
Func1<T, R> warmUp();

// On Func2<T1, T2, R>
Func2<T1, T2, R> warmUp();

No parameters.

When

Sun, 21 Jun 2026 18:27:01 +0000

When

What it is

when is a decorator that conditionally executes the wrapped function or an alternative branch depending on a predicate.

When to use it

Feature flags that choose between implementations.
Conditional execution without if/else at every call site.
Branching logic that you want to compose and reuse.

API reference

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


// api-reference
// On Func<R>
Func<R> when({
 required bool Function() condition,
 Future<R> Function()? otherwise,
});

// On Func1<T, R>
Func1<T, R> when({
 required bool Function(T arg) condition,
 Future<R> Function(T arg)? otherwise,
});

// On Func2<T1, T2, R>
Func2<T1, T2, R> when({
 required bool Function(T1 arg1, T2 arg2) condition,
 Future<R> Function(T1 arg1, T2 arg2)? otherwise,
});

Parameters

Parameter	Type	Description
`condition`	`bool Function(...)`	Decides whether to execute the wrapped function.
`otherwise`	`Future<R> Function(...)?`	Optional branch executed when the condition is `false`.

Examples

Basic example

1
2
3
4
5
6
7


final route = Func1<int, String>((n) async => 'positive').when(
 condition: (n) => n > 0,
 otherwise: (n) async => 'non-positive',
);

print(await route(5)); // positive
print(await route(-1)); // non-positive

Real-world example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


final useCache = false;

final fetchUser = Func1<String, User>((id) async {
 return await cache.get(id) as User;
}).when(
 condition: (_) => useCache,
 otherwise: (id) async {
 return await api.getUser(id) as User;
 },
);

await fetchUser('123');

Best practices

Keep predicates fast and free of side effects.
Ensure both branches return the same type R.

Common pitfalls

Async predicate timing: If the predicate depends on mutable state, branches may flip between calls.
Branch exceptions: Exceptions in either branch propagate to the caller.

funx

Advanced Cache

Advanced Cache link

What it is link

When to use it link

Components link

API reference link

Examples link

Choose an eviction policy link

Weighted cache link

Stampede protection link

Warm a set of keys link

Best practices link

Common pitfalls link

All

All link

What it is link

When to use it link

Async / sync support link

API reference link

Parameters link

Examples link

Basic example link

Real-world example link

Best practices link

Common pitfalls link

Audit

Audit link

What it is link

When to use it link

Async / sync support link

API reference link

Parameters link

Examples link

Basic example link

Real-world example link

Best practices link

Common pitfalls link

Backoff

Backoff link

What it is link

When to use it link

Async / sync support link

Backpressure

Backpressure link

What it is link

When to use it link

Async / sync support link

API reference link

Parameters link

Strategies link

Examples link

Drop example link

Buffer example link

Error example link

Best practices link

Common pitfalls link

Barrier

Barrier link

What it is link

When to use it link

Async / sync support link

API reference link

Parameters link

Examples link

Basic example link

Real-world example link

Best practices link

Common pitfalls link

Batch

Batch link

What it is link

When to use it link

Async / sync support link

API reference link

Parameters link

How it changes the inner function signature link

Returned wrapper methods link

Examples link

Basic example link

Advanced Cache

What it is

When to use it

Components

API reference

Examples

Choose an eviction policy

Weighted cache

Stampede protection

Warm a set of keys

Best practices

Common pitfalls

All

What it is

When to use it

Async / sync support

API reference

Parameters

Examples

Basic example

Real-world example

Best practices

Common pitfalls

Audit

What it is

When to use it

Async / sync support

API reference

Parameters

Examples

Basic example

Real-world example

Best practices

Common pitfalls

Backoff

What it is

When to use it

Async / sync support

Backpressure

What it is

When to use it

Async / sync support

API reference

Parameters

Strategies

Examples

Drop example

Buffer example

Error example

Best practices

Common pitfalls

Barrier

What it is

When to use it

Async / sync support

API reference

Parameters

Examples

Basic example

Real-world example

Best practices

Common pitfalls

Batch

What it is

When to use it

Async / sync support

API reference

Parameters

How it changes the inner function signature

Returned wrapper methods

Examples

Basic example

Real-world example

Best practices

Common pitfalls

Bulkhead

What it is

When to use it

Async / sync support

API reference