Update version to 0.1.0 and enhance functionality in CHANGELOG.md, README.md, and any_refreshable_widget.dart

- Introduced lifecycle callbacks `onBeforeRefresh` and `onAfterRefresh` for better control during refresh operations.
- Added `RefreshConcurrency` enum to manage execution of multiple futures (concurrent or sequential).
- Updated README.md with new features, usage examples, and detailed API reference.
- Enhanced CHANGELOG.md to reflect the new version and features.

Author: yamaroni

.gitignore

@@ -118,3 +118,8 @@ app.*.symbols
 !/packages/flutter_tools/test/data/dart_dependencies_test/**/.packages
 !/dev/ci/**/Gemfile.lock
 .DS_Store
+
+# Example related
+example/.vscode/launch.json
+example/.metadata
+example/analysis_options.yaml

CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.1.0
+
+* **Lifecycle callbacks** - Added `onBeforeRefresh` and `onAfterRefresh` callbacks with flexible sync/async support
+* **Concurrency control** - Added `RefreshConcurrency` enum to control future execution (sequential/concurrent)
+* **Sequential execution** - New option to execute multiple futures one after another (now default behavior)
+* **Enhanced documentation** - Comprehensive examples for lifecycle callbacks and concurrency modes
+* **Improved examples** - Updated example app with better UI and clearer demonstrations
+
 ## 0.0.2
 
 * **Improved compatibility** - Updated SDK constraint to support broader range of Dart versions (>=2.17.0 <4.0.0)

README.md

@@ -11,11 +11,13 @@ A powerful and flexible Flutter package that provides pull-to-refresh functional
 
 ## Features
 
-- 🔄 **Single & Multiple Future Support** - Handle one or multiple asynchronous operations concurrently
+- 🔄 **Single & Multiple Future Support** - Handle one or multiple asynchronous operations
 - 🎨 **Customizable Refresh Indicator** - Full control over appearance and behavior
 - 📱 **Universal Widget Support** - Works with any widget, automatically makes content scrollable
 - 🎯 **Smart Error Handling** - Comprehensive error states and callbacks
 - 🔧 **Highly Configurable** - Colors, displacement, stroke width, trigger modes, and more
+- ⚡ **Lifecycle Callbacks** - `onBeforeRefresh` and `onAfterRefresh` hooks with sync/async support
+- 🔀 **Flexible Concurrency** - Choose between concurrent (parallel) or sequential execution
 - 🚀 **Production Ready** - Thoroughly tested and optimized for real-world applications
 
 ## Installation
@@ -82,6 +84,40 @@ AnyRefreshableWidget(
 )
 ```
 
+### Concurrency Control
+
+Control how multiple futures are executed:
+
+#### Concurrent Execution (Default)
+```dart
+AnyRefreshableWidget(
+  concurrency: RefreshConcurrency.concurrent,
+  onRefresh: [
+    () => fetchUserData(),      // These run simultaneously
+    () => fetchNotifications(), // for faster completion
+    () => fetchSettings(),
+  ],
+  builder: (context, isLoading, error) {
+    return YourContentWidget();
+  },
+)
+```
+
+#### Sequential Execution
+```dart
+AnyRefreshableWidget(
+  concurrency: RefreshConcurrency.sequential, // Default
+  onRefresh: [
+    () => authenticateUser(),   // Runs first
+    () => fetchUserData(),      // Then this
+    () => fetchNotifications(), // Finally this
+  ],
+  builder: (context, isLoading, error) {
+    return YourContentWidget();
+  },
+)
+```
+
 ## Comprehensive Examples
 
 ### Custom Refresh Indicator
@@ -192,6 +228,47 @@ AnyRefreshableWidget.single(
 )
 ```
 
+### Lifecycle Callbacks
+
+The package supports `onBeforeRefresh` and `onAfterRefresh` callbacks that can be either synchronous or asynchronous:
+
+#### Synchronous Callbacks
+```dart
+AnyRefreshableWidget.single(
+  onBeforeRefresh: () {
+    print('Starting refresh...');
+    // Synchronous setup logic
+  },
+  onRefresh: () => fetchData(),
+  onAfterRefresh: () {
+    print('Refresh completed!');
+    // Synchronous cleanup logic
+  },
+  builder: (context, isLoading, error) {
+    return YourContentWidget();
+  },
+)
+```
+
+#### Asynchronous Callbacks
+```dart
+AnyRefreshableWidget.single(
+  onBeforeRefresh: () async {
+    print('Starting refresh...');
+    await prepareForRefresh();
+    // Asynchronous setup logic
+  },
+  onRefresh: () => fetchData(),
+  onAfterRefresh: () {
+    print('Refresh completed!');
+    // Cleanup logic (always sync)
+  },
+  builder: (context, isLoading, error) {
+    return YourContentWidget();
+  },
+)
+```
+
 ## API Reference
 
 ### AnyRefreshableWidget
@@ -200,6 +277,9 @@ AnyRefreshableWidget.single(
 |-----------|------|----------|---------|-------------|
 | `onRefresh` | `List<Future<void> Function()>` | ✅ | - | List of async functions to execute on refresh |
 | `builder` | `Widget Function(BuildContext, bool, Object?)` | ✅ | - | Builder function with loading and error states |
+| `concurrency` | `RefreshConcurrency` | ❌ | `concurrent` | How futures should be executed (concurrent/sequential) |
+| `onBeforeRefresh` | `FutureOr<void> Function()?` | ❌ | `null` | Callback executed before refresh starts (sync/async) |
+| `onAfterRefresh` | `VoidCallback?` | ❌ | `null` | Callback executed after refresh completes |
 | `refreshColor` | `Color?` | ❌ | `null` | Color of the refresh indicator |
 | `backgroundColor` | `Color?` | ❌ | `null` | Background color of the refresh indicator |
 | `displacement` | `double` | ❌ | `40.0` | Distance from top to show indicator |
@@ -210,7 +290,24 @@ AnyRefreshableWidget.single(
 
 ### AnyRefreshableWidget.single
 
-Same parameters as `AnyRefreshableWidget`, but `onRefresh` takes a single `Future<void> Function()` instead of a list.
+Same parameters as `AnyRefreshableWidget`, but `onRefresh` takes a single `Future<void> Function()` instead of a list. The `concurrency` parameter is not applicable for single futures.
+
+### RefreshConcurrency Enum
+
+| Value | Description | Use Case |
+|-------|-------------|----------|
+| `RefreshConcurrency.concurrent` | Execute all futures simultaneously using `Future.wait` | fastest refresh when futures are independent |
+| `RefreshConcurrency.sequential` | Execute futures one by one in order | When futures depend on each other or to limit resource usage |
+
+## Callback Execution Order
+
+When a refresh is triggered, the callbacks execute in this order:
+
+1. **`onBeforeRefresh`** - Called first, awaited if async
+2. **Loading state** - `isLoading` becomes `true`, UI updates
+3. **`onRefresh`** - All futures execute concurrently
+4. **Loading state** - `isLoading` becomes `false`, UI updates  
+5. **`onAfterRefresh`** - Called last, always synchronous
 
 ## Advanced Configuration
 

example/lib/main.dart

@@ -1,3 +1,5 @@
+import 'dart:developer';
+
 import 'package:flutter/material.dart';
 import 'package:any_refreshable_widget/any_refreshable_widget.dart';
 
@@ -16,6 +18,7 @@ class MainApp extends StatelessWidget {
       _refreshWithCustomIndicator(),
       _refreshWithCustomWidget(),
       _refreshWithErrorCallback(),
+      _refreshWithBeforeAfterCallback(),
     ];
 
     return MaterialApp(
@@ -102,3 +105,21 @@ Widget _refreshWithErrorCallback() {
     },
   );
 }
+
+/// Refresh with Before After Callback
+Widget _refreshWithBeforeAfterCallback() {
+  return AnyRefreshableWidget.single(
+    onBeforeRefresh: () {
+      log('onBeforeRefresh');
+    },
+    onRefresh: () async {
+      await Future.delayed(const Duration(seconds: 2));
+    },
+    onAfterRefresh: () {
+      log('onAfterRefresh');
+    },
+    builder: (context, isLoading, error) {
+      return Center(child: Text('Refresh with Before After Callback'));
+    },
+  );
+}

lib/any_refreshable_widget.dart

@@ -1,5 +1,24 @@
+import 'dart:async';
 import 'package:flutter/material.dart';
 
+/// A type-safe callback that can handle both synchronous and asynchronous operations.
+///
+/// This typedef uses FutureOr<void> which is the proper way to represent a function
+/// that can return either void (synchronous) or Future<void> (asynchronous).
+/// FutureOr is part of Dart's type system and provides better type safety than dynamic.
+typedef FlexibleCallback = FutureOr<void> Function();
+
+/// Defines how multiple futures should be executed during refresh.
+enum RefreshConcurrency {
+  /// Execute all futures concurrently (in parallel).
+  /// This is the default and fastest option as all operations run simultaneously.
+  concurrent,
+
+  /// Execute futures sequentially (one after another).
+  /// This is useful when futures depend on each other or when you want to limit resource usage.
+  sequential,
+}
+
 /// A widget that provides pull-to-refresh functionality for any content.
 ///
 /// This widget can handle multiple futures, has customizable refresh indicator,
@@ -186,14 +205,24 @@ class _RefreshWidgetState extends State<_RefreshWidget>
 /// concurrently and provides unified loading and error states. It extends
 /// [ChangeNotifier] to notify listeners when the state changes.
 ///
-/// The handler automatically executes all futures using [Future.wait] to
-/// ensure they run concurrently rather than sequentially. If any future
-/// throws an error, the error is captured and made available through the
-/// [error] getter.
+/// The handler executes all futures according to the specified concurrency mode.
+/// By default, futures run sequentially, but can be configured
+/// to run concurrently. If any future throws an error, the error is captured and
+/// made available through the [error] getter.
 class _MultiFutureRefreshHandler<T> extends ChangeNotifier {
   /// List of future functions to execute when refreshing.
   final List<Future<void> Function()> _futureFunctions;
 
+  /// Callback function called before starting the refresh operation.
+  /// Can be either synchronous (void) or asynchronous (Future<void>).
+  final FlexibleCallback? _onBeforeRefresh;
+
+  /// Callback function called after completing the refresh operation.
+  final VoidCallback? _onAfterRefresh;
+
+  /// How the futures should be executed (concurrent or sequential).
+  final RefreshConcurrency _concurrency;
+
   /// Whether the futures are currently being executed.
   bool _isLoading = false;
 
@@ -206,24 +235,46 @@ class _MultiFutureRefreshHandler<T> extends ChangeNotifier {
   /// Creates a [_MultiFutureRefreshHandler] with the given future functions.
   ///
   /// [futureFunctions] is a list of functions that return futures to be
-  /// executed concurrently when [initialize] or [refresh] is called.
-  _MultiFutureRefreshHandler(List<Future<void> Function()> futureFunctions)
-      : _futureFunctions = futureFunctions;
+  /// executed when [initialize] or [refresh] is called.
+  /// [onBeforeRefresh] is called before starting the refresh operation.
+  /// Can be either synchronous or asynchronous.
+  /// [onAfterRefresh] is called after completing the refresh operation.
+  /// [concurrency] determines whether futures are executed concurrently or sequentially.
+  _MultiFutureRefreshHandler(
+    List<Future<void> Function()> futureFunctions, {
+    FlexibleCallback? onBeforeRefresh,
+    VoidCallback? onAfterRefresh,
+    RefreshConcurrency concurrency = RefreshConcurrency.concurrent,
+  })  : _futureFunctions = futureFunctions,
+        _onBeforeRefresh = onBeforeRefresh,
+        _onAfterRefresh = onAfterRefresh,
+        _concurrency = concurrency;
 
   /// Refresh all futures by re-executing them.
   ///
-  /// This is an alias for [initialize] that provides a more semantic
-  /// method name for refresh operations. It executes all futures
-  /// and updates the loading and error states.
+  /// This method executes all futures according to the specified concurrency mode.
+  /// It executes all futures and updates the loading and error states.
   Future<void> refresh() async {
+    // Call onBeforeRefresh callback before starting the refresh
+    if (_onBeforeRefresh != null) {
+      await _onBeforeRefresh!.call();
+    }
+
     _isLoading = true;
     _error = null;
     _safeNotifyListeners();
 
     try {
-      for (int i = 0; i < _futureFunctions.length; i++) {
-        if (_disposed) return;
-        await _futureFunctions[i]();
+      if (_concurrency == RefreshConcurrency.concurrent) {
+        // Execute all futures concurrently using Future.wait
+        final futures = _futureFunctions.map((fn) => fn()).toList();
+        await Future.wait(futures);
+      } else {
+        // Execute futures sequentially one by one
+        for (int i = 0; i < _futureFunctions.length; i++) {
+          if (_disposed) return;
+          await _futureFunctions[i]();
+        }
       }
     } catch (e) {
       if (!_disposed) {
@@ -233,6 +284,9 @@ class _MultiFutureRefreshHandler<T> extends ChangeNotifier {
       if (!_disposed) {
         _isLoading = false;
         _safeNotifyListeners();
+
+        // Call onAfterRefresh callback after completing the refresh
+        _onAfterRefresh?.call();
       }
     }
   }
@@ -293,6 +347,19 @@ class AnyRefreshableWidget<T> extends StatefulWidget {
   /// return a [Future<void>] that completes when its operation is done.
   final List<Future<void> Function()> onRefresh;
 
+  /// Callback function called before starting the refresh operation.
+  /// Can be either synchronous (void) or asynchronous (Future<void>).
+  final FlexibleCallback? onBeforeRefresh;
+
+  /// Callback function called after completing the refresh operation.
+  final VoidCallback? onAfterRefresh;
+
+  /// How the futures should be executed during refresh.
+  ///
+  /// - [RefreshConcurrency.concurrent]: All futures execute simultaneously
+  /// - [RefreshConcurrency.sequential] (default): Futures execute one after another
+  final RefreshConcurrency concurrency;
+
   /// Builder function that creates the widget content.
   ///
   /// Parameters:
@@ -351,7 +418,10 @@ class AnyRefreshableWidget<T> extends StatefulWidget {
   const AnyRefreshableWidget({
     super.key,
     required this.onRefresh,
+    this.onBeforeRefresh,
+    this.onAfterRefresh,
     required this.builder,
+    this.concurrency = RefreshConcurrency.sequential,
     this.notificationPredicate,
     this.refreshColor,
     this.backgroundColor,
@@ -392,6 +462,8 @@ class AnyRefreshableWidget<T> extends StatefulWidget {
   AnyRefreshableWidget.single({
     super.key,
     required Future<void> Function() onRefresh,
+    FlexibleCallback? onBeforeRefresh,
+    VoidCallback? onAfterRefresh,
     required Widget Function(BuildContext, bool, Object?) builder,
     this.notificationPredicate,
     this.refreshColor,
@@ -405,20 +477,30 @@ class AnyRefreshableWidget<T> extends StatefulWidget {
             await onRefresh();
           },
         ],
+        onBeforeRefresh = onBeforeRefresh,
+        onAfterRefresh = onAfterRefresh,
+        concurrency = RefreshConcurrency
+            .sequential, // Single future doesn't need concurrency option
         builder =
             ((context, isLoading, error) => builder(context, isLoading, error));
 
   @override
-  State<AnyRefreshableWidget<T>> createState() => _RefreshableWidgetState<T>();
+  State<AnyRefreshableWidget<T>> createState() =>
+      _AnyRefreshableWidgetState<T>();
 }
 
-class _RefreshableWidgetState<T> extends State<AnyRefreshableWidget<T>> {
+class _AnyRefreshableWidgetState<T> extends State<AnyRefreshableWidget<T>> {
   late _MultiFutureRefreshHandler<T> _handler;
 
   @override
   void initState() {
     super.initState();
-    _handler = _MultiFutureRefreshHandler<T>(widget.onRefresh);
+    _handler = _MultiFutureRefreshHandler<T>(
+      widget.onRefresh,
+      onBeforeRefresh: widget.onBeforeRefresh,
+      onAfterRefresh: widget.onAfterRefresh,
+      concurrency: widget.concurrency,
+    );
     _handler.addListener(_handleStateChange);
   }
 

pubspec.yaml

@@ -1,6 +1,6 @@
 name: any_refreshable_widget
 description: A powerful Flutter package providing pull-to-refresh functionality for any widget, with support for single/multiple futures, custom indicators, and comprehensive error handling.
-version: 0.0.2
+version: 0.1.0
 homepage: https://github.com/Yama-Roni/any_refreshable_widget
 repository: https://github.com/Yama-Roni/any_refreshable_widget
 issue_tracker: https://github.com/Yama-Roni/any_refreshable_widget/issues