builder_plus 1.1.2

A Flutter package for simplified async operations with built-in loading, error, and empty states management.

data_builder Package

A Flutter package to simplify the management of asynchronous operations with loading, error, and empty data states.

Features

• FutureWorker: Simplified wrapper for FutureBuilder
• StreamWorker: Simplified wrapper for StreamBuilder
• State Widgets: OptionLoading, OptionEmpty, OptionError
• Error Handling: Automatic error management with retry option
• Production Mode: Hides empty states in production

Installation

dependencies:
  builder_plus: <version_code>

Usage

FutureWorker

import 'package:data_builder/data_builder.dart';

FutureWorker<User>(
  future: userService.getUser(id),
  builder: (context, user) => UserCard(user: user),
  errorBuilder: (context, error) => ErrorWidget(error.toString()),
  loadingBuilder: (context) => CircularProgressIndicator(),
)

StreamWorker

import 'package:workers/workers_helper.dart';

StreamWorker<User>(
  stream: userService.userStream,
  builder: (context, user) => UserCard(user: user),
  errorBuilder: (context, error) => ErrorWidget(error.toString()),
  loadingBuilder: (context) => CircularProgressIndicator(),
)

Custom State Widgets

// Loading with customization
const OptionLoading(
  size: 32.0,
  color: Colors.blue,
)

// Empty with icon
const OptionEmpty(
  text: 'No users found',
  icon: Icons.person_off,
  iconSize: 64.0,
)

// Error with retry
OptionError(
  error: 'Connection error',
  onRetry: () => userService.refresh(),
  retryButtonText: 'Refresh',
)

Parameters

FutureWorker / StreamWorker

Parameter	Type	Description
`future	stream`	`Future
builder	Widget Function(BuildContext, T)	Builder for the data
isProd	bool	Production mode (hides empty states)
initialData	T?	Initial data
emptyBuilder	Widget Function(BuildContext)?	Builder for empty state
errorBuilder	Widget Function(BuildContext, Object?)?	Builder for error
loadingBuilder	Widget Function(BuildContext)?	Builder for loading

OptionLoading

Parameter	Type	Default	Description
size	double	24.0	Indicator size
color	Color?	null	Color (uses theme if null)

OptionEmpty

Parameter	Type	Default	Description
text	String	-	Text to display
icon	IconData?	null	Optional icon
textStyle	TextStyle?	null	Text style
iconSize	double	48.0	Icon size
iconColor	Color?	null	Icon color
spacing	double	16.0	Spacing

OptionError

Parameter	Type	Default	Description
error	String	-	Error message
onRetry	VoidCallback?	null	Retry callback
textStyle	TextStyle?	null	Text style
iconSize	double	48.0	Icon size
iconColor	Color?	null	Icon color
spacing	double	16.0	Spacing
showRetryButton	bool	true	Show retry button
retryButtonText	String	'Retry'	Retry button text

Full Examples

Managing a User List

class UserListScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Users')),
      body: FutureWorker<List<User>>(
        future: userService.getUsers(),
        builder: (context, users) {
          if (users.isEmpty) {
            return const OptionEmpty(
              text: 'No users found',
              icon: Icons.people_outline,
            );
          }
          return ListView.builder(
            itemCount: users.length,
            itemBuilder: (context, index) => UserListItem(user: users[index]),
          );
        },
        errorBuilder: (context, error) => OptionError(
          error: 'Unable to load users',
          onRetry: () => setState(() {}),
        ),
        loadingBuilder: (context) => const OptionLoading(size: 32.0),
      ),
    );
  }
}

Real-time Stream

class ChatScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Chat')),
      body: StreamWorker<List<Message>>(
        stream: chatService.messagesStream,
        builder: (context, messages) {
          return ListView.builder(
            itemCount: messages.length,
            itemBuilder: (context, index) => MessageItem(message: messages[index]),
          );
        },
        errorBuilder: (context, error) => OptionError(
          error: 'Chat connection error',
          onRetry: () => chatService.reconnect(),
        ),
      ),
    );
  }
}

Contribution

Contributions are welcome! Feel free to open an issue or a pull request.