atomic_flutter library

AtomicFlutter is a lightweight, reactive state management solution for Flutter applications with async state support.

It provides a simple way to create, manage, and react to state changes with minimal boilerplate and maximum type safety.

Classes

AsyncAtom<T>

An atom that manages async operations and their states

AsyncAtomBuilder<T>

Builds UI from an AsyncAtom's state.

AsyncAtomEvent

A recorded state transition event for an AsyncAtom. Only recorded when debug mode is enabled.

AsyncEventLog

Global ring buffer for async events. Debug mode only.

AsyncValue<T>

Container for async data with loading and error states

Atom<T>

A single atomic unit of state

AtomBuilder<T>

Flutter widget that efficiently subscribes to atoms

AtomDebugger

Debugging utilities for AtomicFlutter

AtomFamily<T, K>

Atom family for creating related atoms with different keys

AtomHistory<T>

Wraps an Atom with bounded undo/redo history.

AtomicFlutterDevToolsService

Service layer for AtomicFlutter DevTools extension.

AtomMemoryTracker

Memory usage tracking

AtomMetrics

Metrics for a single atom

AtomMiddleware

Base class for atom middleware.

AtomPerformanceMonitor

Performance monitoring for atoms

AtomSelector<T, S>

Widget that only rebuilds when selected part of atom changes

AtomStorage

Storage backend for persistAtom.

InMemoryAtomStorage

In-memory AtomStorage — useful for tests and ephemeral state.

LoggingMiddleware

Built-in middleware that prints every atom state change to the console.

MultiAtomBuilder

Widget that subscribes to multiple atoms

StreamAtom<T>

An atom that bridges an external Stream into the atom world.

WidgetRebuildTracker

Tracks widget rebuild counts per atom for performance monitoring. Only active in debug mode.

Enums

AsyncState

Represents the state of an async operation

Mixins

WatchAtom<T extends StatefulWidget>

Mixin that allows a State to reactively watch atoms inside build.

Extensions

AsyncAtomExtensions on AsyncAtom<T>

Extensions for AsyncAtom

AtomAsyncExtensions on Atom<T>

Extensions for regular Atom to create AsyncAtom

AtomExtensions on Atom<T>

Extension methods for Atom class

Functions

atomicUpdate(void updates()) → void

Update multiple atoms in a single batch — listeners are notified only after all updates in updates have completed.

combineAsync<T>(List<AsyncAtom<T>> atoms) → AsyncAtom<List<T>>

Create an async atom that combines multiple async atoms

computed<R>(R compute(), {List<Atom> tracked = const [], String? id, bool autoDispose = true, Duration? disposeTimeout, bool equals(R, R)?}) → Atom<R>

Create a derived atom that depends on others

computedAsync<R>(Future<R> compute(), {List<Atom> tracked = const [], String? id, bool autoDispose = true, Duration? disposeTimeout, Duration debounce = const Duration(milliseconds: 500)}) → AsyncAtom<R>

Create async computed atoms

disableDebugMode() → void

Disable debug mode

enableDebugMode() → void

Enable debug mode to see atom operations in console

persistAtom<T>(T defaultValue, {required String key, required AtomStorage storage, required T fromJson(Object? json), required Object? toJson(T value), bool autoDispose = false, bool equals(T, T)?, String? id}) → Atom<T>

Creates an Atom whose value is persisted in storage.

setDefaultDisposeTimeout(Duration timeout) → void

Set the default auto-dispose timeout for atoms

Typedefs

AtomTransformer<T> = T Function(T oldValue, T newValue)

Per-atom value transformer. Receives the old and proposed new value, returns the value to actually store. Return oldValue to block the update.