Funx Documentation

Version: 1.3.0
Package: funx — composable async/sync function decorators for Dart.

Funx wraps ordinary functions in small, chainable, reusable building blocks. Each block adds a single concern — timing, concurrency, reliability, caching, observability, and more — without rewriting the function itself.

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

const query = 'flutter packages';

final search = Func<List<Result>>(
  () async => (await api.search(query)) as List<Result>,
).debounce(Duration(milliseconds: 300))
  .retry(maxAttempts: 3)
  .timeout(Duration(seconds: 5));

void main() async {
  final results = await search();
  print('Found ${results.length} results');
}

What is a decorator?

A decorator is an extension method on Func, Func1, or Func2 (or a standalone class) that wraps the original function and changes how it executes. Decorators are composable: you can chain them to combine behaviors.

Wrapper types

WrapperSignatureDecorators?
Func<R>Future<R> call()Full async decorator set
Func1<T, R>Future<R> call(T arg)Full async decorator set
Func2<T1, T2, R>Future<R> call(T1 arg1, T2 arg2)Full async decorator set
FuncSync<R>R call()Scheduling decorators only
FuncSync1<T, R>R call(T arg)None
FuncSync2<T1, T2, R>R call(T1 arg1, T2 arg2)None

FuncSync* wrappers exist for API symmetry; most decorators are async-only because they rely on Future, Timer, or concurrent execution.

Category map

CategoryMechanismsFile
CoreFunc, Func1, Func2, FuncSync*, AsyncFunction*, SyncFunction*core.md
Timingdebounce, throttle, delay, timeout, defer, idleCallbacktiming.md
Concurrencylock, readLock/writeLock, semaphore, bulkhead, barrier, countdownLatch, monitor, queueconcurrency.md
Schedulingschedule, scheduleRecurring, scheduleCustom, backpressurescheduling.md
Reliabilityretry, backoff, circuitBreaker, fallback, recoverreliability.md
Error HandlingcatchError, defaultValueerror_handling.md
Performancelazy, warmUp, batch, cacheAside, priorityQueue, rateLimit, memoize, deduplicate, share, compress, onceperformance.md
Observabilitytap, monitorObservability, auditobservability.md
Statesnapshotstate.md
Validationvalidate, guardvalidation.md
Control Flowwhen, repeat, switchcontrol_flow.md
Transformationtransform, merge, proxytransformation.md
Orchestrationrace, all, sagaorchestration.md

Quick start

  1. Add to pubspec.yaml:

    1
2

    dependencies:
  funx: ^1.3.0

  2. Import and wrap a function:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10

    final fetchUser = Func1<String, User>(
  (id) async => (await api.getUser(id)) as User,
).timeout(Duration(seconds: 5))
  .retry(maxAttempts: 3)
  .memoize();

void main() async {
  final user = await fetchUser('123');
  print(user);
}

  3. Call it like any async function:

    1
2
3
4
5
6
7
8

    final fetchUser = Func1<String, User>(
  (id) async => (await api.getUser(id)) as User,
);

void main() async {
  final user = await fetchUser('123');
  print(user);
}

How to read the category docs

Each mechanism is documented with the same structure:

  • What it is — short conceptual overview.
  • When to use it — typical use cases.
  • Async / sync support — which wrappers support the decorator.
  • API reference — public classes, enums, and key members with defaults.
  • Examples — minimal and real-world snippets.
  • Best practices — recommended usage.
  • Common pitfalls — exceptions, edge cases, and gotchas.

Version note

This documentation targets funx v1.3.0. v1.3.0 refactored shared logic into internal engine files (_timing_engine.dart, _reliability_engines.dart, _observability_engines.dart, _concurrency_engines.dart) without changing the public API.

Resources

Contributing

Found an inaccuracy? The source of truth is lib/funx.dart and the files under lib/src/. Open an issue or PR with a reference to the relevant source file.