Repository on GitHub | Report an Issue

builder_plus 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 customizable error builders and retry option
• Production Mode: Hides empty states in production

Installation #

dependencies:
  builder_plus: <latest_version>

Example #

Here is a complete example using all main features of the package:

import 'package:flutter/material.dart';
import 'package:builder_plus/builder_plus.dart';
import 'package:builder_plus/model/option_loading.dart';
import 'package:builder_plus/model/option_empty.dart';
import 'package:builder_plus/model/option_error.dart';

// A custom class to illustrate typing
typedef Id = int;

class Example {
  final Id id;
  final String name;

  Example(this.id, this.name);

  @override
  String toString() => 'Example(id: $id, name: $name)';
}

// Simulate an asynchronous operation on an Example
Future<Example?> processExample(Example example, {bool throwError = false, bool empty = false}) async {
  await Future.delayed(const Duration(seconds: 2));
  if (throwError) throw Exception('Network error');
  if (empty) return null;
  return Example(example.id, example.name.toUpperCase());
}

// Simulate a stream of operations on an Example
Stream<Example?> streamExample(Example example, {bool throwError = false, bool empty = false}) async* {
  yield null;
  await Future.delayed(const Duration(seconds: 1));
  if (throwError) throw Exception('Stream error');
  if (empty) yield null;
  else yield Example(example.id, example.name.toUpperCase());
  await Future.delayed(const Duration(seconds: 1));
  yield Example(example.id, ' [1m${example.name.toUpperCase()} (final)');
}

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'builder_plus Example',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: const ExampleScreen(),
    );
  }
}

class ExampleScreen extends StatefulWidget {
  const ExampleScreen({super.key});

  @override
  State<ExampleScreen> createState() => _ExampleScreenState();
}

class _ExampleScreenState extends State<ExampleScreen> {
  bool throwFutureError = false;
  bool throwStreamError = false;
  bool showEmpty = false;

  @override
  Widget build(BuildContext context) {
    final example = Example(1, 'demo');
    return Scaffold(
      appBar: AppBar(title: const Text('FutureWorker & StreamWorker Example')),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Row(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                Checkbox(
                  value: throwFutureError,
                  onChanged: (v) => setState(() => throwFutureError = v ?? false),
                ),
                const Text('Future Error'),
                const SizedBox(width: 16),
                Checkbox(
                  value: throwStreamError,
                  onChanged: (v) => setState(() => throwStreamError = v ?? false),
                ),
                const Text('Stream Error'),
                const SizedBox(width: 16),
                Checkbox(
                  value: showEmpty,
                  onChanged: (v) => setState(() => showEmpty = v ?? false),
                ),
                const Text('Empty State'),
              ],
            ),
            const SizedBox(height: 24),
            const Text('FutureWorker', style: TextStyle(fontWeight: FontWeight.bold)),
            FutureWorker<Example?>(
              future: processExample(example, throwError: throwFutureError, empty: showEmpty),
              builder: (context, result) => Text(
                'After processing: \n [1m [0m${result.toString()}',
                style: const TextStyle(fontSize: 18),
              ),
              loadingBuilder: (context) => const OptionLoading(size: 32),
              emptyBuilder: (context) => const OptionEmpty(
                text: 'No data received',
                icon: Icons.hourglass_empty,
              ),
              errorBuilder: (context, error) => OptionError(
                error: error,
                onRetry: () => setState(() {}),
                retryButtonText: 'Retry',
              ),
            ),
            const SizedBox(height: 32),
            const Text('StreamWorker', style: TextStyle(fontWeight: FontWeight.bold)),
            StreamWorker<Example?>(
              stream: streamExample(example, throwError: throwStreamError, empty: showEmpty),
              builder: (context, result) => Text(
                'Stream: \n${result.toString()}',
                style: const TextStyle(fontSize: 18),
              ),
              loadingBuilder: (context) => const OptionLoading(size: 32, color: Colors.orange),
              emptyBuilder: (context) => const OptionEmpty(
                text: 'Empty stream',
                icon: Icons.stream,
                iconColor: Colors.orange,
              ),
              errorBuilder: (context, error) => OptionError(
                error: error,
                onRetry: () => setState(() {}),
                retryButtonText: 'Restart stream',
              ),
            ),
          ],
        ),
      ),
    );
  }
}

Error Handling #

Both FutureWorker and StreamWorker provide flexible error handling:

• Custom Error Builder: Use errorBuilder to provide a custom widget when an error occurs. The builder receives the error object (Object?) as the second parameter.
• Default Error Widget: If no errorBuilder is provided, the widgets automatically display OptionError with the error message.
• OptionError Widget: The OptionError widget accepts any error object type and automatically converts it to a displayable string.

Example with custom error handling:

FutureWorker<User>(
  future: userService.getUser(id),
  builder: (context, user) => UserCard(user: user),
  errorBuilder: (context, error) => Column(
    children: [
      Icon(Icons.error, color: Colors.red),
      Text('Failed to load user: ${error?.toString() ?? "Unknown error"}'),
      ElevatedButton(
        onPressed: () => setState(() {}),
        child: Text('Retry'),
      ),
    ],
  ),
)

Parameters #

FutureWorker / StreamWorker #

OptionLoading #

OptionEmpty #

OptionError #

Note: The error parameter accepts any object type. If it's a String, it will be displayed directly. If it's an Exception or other object, it will be converted to a string automatically. If null, it will display "An unknown error occurred".