utilities library

Re-exports runtime utilities from gmana_utils.

The two-track result type is GResult, GSuccess, and GFailure, declared in gmana_functional and re-exported by gmana_utils. GmanaStreamTimingX is hidden to prevent extension collision with StreamX from gmana_extensions.

Classes

AsyncCache<K, V>

An asynchronous key-value cache supporting TTL expiration and request deduplication.

AsyncMemoizer<T>

Caches the result of an async computation so that subsequent calls return the memoized result.

Batcher<T, R>

Batches individual calls into bulk requests based on size or time thresholds.

CircuitBreaker

Guards operations against cascading failures by tripping open when failure threshold is reached.

Debouncer

A small utility to debounce function execution.

GFailure<T, E>

A failed GResult holding an error.

GResult<T, E>

A type representing either a success value T or a failure error E.

GSuccess<T, E>

A successful GResult holding a value.

IdGenerator

Public API for generating IDs and reversible encodings.

KeyedLock<K>

Serializes asynchronous operations per key.

Lazy<T>

Utility for lazy initialization of values.

RateLimiter

A sliding-window rate limiter utility.

ResettableLazy<T>

A Lazy initialized value that can be reset/invalidated.

SecureIdGenerator

Cryptographically-secure variant of IdGenerator.

Semaphore

A counting semaphore that bounds how many operations run at once.

Throttler

A small utility to throttle function execution.

Enums

CircuitState

States of a CircuitBreaker.

Extensions

GmanaFutureResultX on Future<GResult<T, E>>

Asynchronous composition for a Future that completes with a GResult.

GmanaFutureToResultX on Future<T>

Converts a Future completion into a GResult.

GmanaIterableResultX on Iterable<GResult<T, E>>

Aggregation helpers for collections of GResult values.

GmanaResultX on GResult<T, E>

Recovery, observation, and asynchronous composition for GResult.

GmanaRetryFunctionX on FutureOr<T> Function()

Fluent retry support for synchronous or asynchronous operations.

Constants

kDefaultDebounceTime → const int

Default debounce time in milliseconds.

kDefaultThrottleDuration → const int

Default throttle time in milliseconds.

Functions

forEachConcurrent<T>(Iterable<T> items, FutureOr<void> action(T item), {int concurrency = 4}) → Future<void>

Runs action for every item in items, at most concurrency at once.

mapConcurrent<T, R>(Iterable<T> items, FutureOr<R> convert(T item), {int concurrency = 4}) → Future<List<R>>

Maps items through convert with at most concurrency running at once.

retry<T>(FutureOr<T> fn(), {int maxAttempts = 3, Duration delay = const Duration(milliseconds: 500), bool useExponentialBackoff = true, Duration? maxDelay, bool jitter = false, bool retryIf(Object error)?, RetryCallback? onRetry}) → Future<T>

Retries asynchronous operation fn up to maxAttempts times.

tryOrDefault<T>(T action(), T defaultValue) → T

Executes action and returns its result, or defaultValue if any exception occurs.

tryOrDefaultAsync<T>(Future<T> action(), T defaultValue) → Future<T>

Executes async action, or returns defaultValue if any exception occurs.

tryOrElse<T>(T action(), T onError(Object error, StackTrace stackTrace)) → T

Executes action, recovering from a thrown error with onError.

tryOrElseAsync<T>(Future<T> action(), FutureOr<T> onError(Object error, StackTrace stackTrace)) → Future<T>

Executes async action, recovering from a thrown error with onError.

tryOrNull<T>(T action()) → T?

Executes action and returns its result, or null if any exception occurs.

tryOrNullAsync<T>(Future<T> action()) → Future<T?>

Executes async action and returns its result, or null if any exception occurs.

Typedefs

RetryCallback = void Function(int attempt, Object error, Duration nextDelay)

Signature for the retry progress callback.

Exceptions / Errors

CircuitBreakerOpenException

Exception thrown when a call is executed while CircuitBreaker is open.

DebouncedException

Thrown when a debounced action never runs.