bloc_superpowers library

A Dart/Flutter package that enhances Cubit state management with powerful features.

bloc_superpowers adds automatic loading/error tracking, retry logic with exponential backoff, debounce/throttle, caching, optimistic UI updates, and one-time effects to your Cubits through the mix function.

Getting Started

Wrap your app with the Superpowers widget:

Superpowers(
  child: MaterialApp(...),
)

Then use mix in your Cubits:

Future<void> loadUser() => mix(
  key: this,
  retry: retry,
  () async {
    final user = await api.getUser();
    emit(state.copyWith(user: user));
  },
);

Key Features

• Automatic loading/error tracking: Use context.isWaiting(key) and context.isFailed(key)
• Retry with backoff: retry: retry(maxRetries: 5)
• Throttle/Debounce: throttle: throttle(duration: 1.sec), debounce: debounce(duration: 300.millis)
• Freshness caching: fresh: fresh(freshFor: 5.sec)
• Sequential execution: sequential: sequential
• Internet checking: checkInternet: checkInternet
• One-time effects: Use Effect and context.effect() instead of BlocListener

For more info, see: https://blocsuperpowers.org

Classes

CheckInternetConfig

Configuration for internet connectivity checking in mix.

CheckInternetContext

Context for the checkInternet feature.

DebounceConfig

Configuration for debounce in mix.

DebounceContext

Context for the debounce feature.

Effect<T>

Effects are one-time notifications stored in your state, used to trigger side effects in widgets such as showing dialogs, clearing text fields, or navigating to new screens.

EffectQueue<E>

A queue of effects to be executed sequentially.

FreshConfig

Configuration for fresh (cache invalidation) in mix.

FreshContext

Context for the fresh feature.

MixConfig

Pre-defined configuration for mix and mix.ctx functions.

MixContext

Context object passed to mix.ctx action callback.

MixPreset

A pre-configured version of the mix function.

NonReentrantConfig

Configuration for non-reentrant protection in mix.

NonReentrantContext

Context for the nonReentrant feature.

ResolvedCheckInternetConfig

Resolved checkInternet configuration with non-nullable required fields.

ResolvedDebounceConfig

Resolved debounce configuration with non-nullable required fields.

ResolvedFreshConfig

Resolved fresh configuration with non-nullable required fields.

ResolvedNonReentrantConfig

Resolved nonReentrant configuration.

ResolvedRetryConfig

Resolved retry configuration with non-nullable required fields.

ResolvedSequentialConfig

Resolved sequential configuration with non-nullable required fields.

ResolvedThrottleConfig

Resolved throttle configuration with non-nullable required fields.

RetryConfig

Configuration for retry behavior in mix.

RetryContext

Context for the retry feature.

RunStatus

Tracks the run status of a mix call.

SequentialConfig

Configuration for sequential execution in mix.

SequentialContext

Context for the sequential feature.

Superpowers

A widget that enables context.isWaiting, context.isFailed, and context.getException to trigger widget rebuilds when method state changes.

ThrottleConfig

Configuration for throttle (rate limiting) in mix.

ThrottleContext

Context for the throttle feature.

UserExceptionDialog

A widget that listens to UserExceptions from Superpowers and displays them in a dialog.

UserExceptionToast

A widget that listens to UserExceptions from Superpowers and displays them as toast notifications (SnackBars).

Enums

SequentialDropReason

Reason why a sequential call was dropped.

Extensions

IntDurationExtension on int

Extension for creating Duration from int values.

OptimisticCommandExtension on Cubit<S>

Extension on Cubit that provides an optimistic command method.

OptimisticSyncExtension on Cubit<S>

Extension on Cubit that provides an optimistic sync method.

OptimisticSyncWithPushExtension on Cubit<S>

Extension on Cubit that provides optimistic sync with push methods.

SuperpowersContextExtension on BuildContext

BuildContext extension for checking waiting/failed state of Cubit methods.

UserExceptionAdvancedExtension on UserException

Extension on UserException for advanced features like callbacks and properties.

Constants

checkInternet → const CheckInternetConfig

Default internet check configuration preset.

debounce → const DebounceConfig

Factory for creating DebounceConfig instances.

fresh → const FreshConfig

Factory for creating FreshConfig instances.

mix → const _Mix

The global mix instance.

nonReentrant → const NonReentrantConfig

Factory for creating NonReentrantConfig instances.

retry → const RetryConfig

Default retry configuration preset.

sequential → const SequentialConfig

Factory for creating SequentialConfig instances.

throttle → const ThrottleConfig

Factory for creating ThrottleConfig instances.

Properties

optimisticSyncWithPushDeviceId ↔ int Function()

The device ID is used to differentiate revisions from different devices. The default is to use a random integer generated once per app run, but you can override this by setting optimisticSyncWithPushDeviceId.

getter/setter pair

Functions

removeAllFreshKeys() → void

Removes all fresh keys, making all actions stale immediately.

removeAllThrottleLocks() → void

Removes all throttle locks, allowing all throttled actions to run immediately.

removeFreshKey(Object key) → void

Removes a specific fresh key, making actions with that key stale immediately.

removeThrottleLock(Object key) → void

Removes a specific throttle lock, allowing the action to run immediately.

Typedefs

PushMetadata = ({int deviceId, int localRevision, int serverRevision})

Record type for push metadata containing server revision, local revision, and device ID.

ShowUserExceptionDialog = void Function(BuildContext context, UserException userException, bool useLocalContext)

Callback type for custom UserException dialog implementations.

ShowUserExceptionToast = void Function(BuildContext context, UserException userException)

Callback type for custom UserException toast implementations.

Exceptions / Errors

AbortException

An exception that can be thrown in the mix function callbacks (action, before, wrapRun, wrapError) to abort execution immediately.

AdvancedUserException

Extends the UserException to add more features.

ConnectionException

The ConnectionException is a type of UserException that warns the user when the connection is not working. Use ConnectionException.noConnectivity for a simple version that warns the users they should check the connection.

UserException

The UserException is an immutable class representing an error the user could fix, like wrong typed text, or missing internet connection.