smart_api_executor

Lightweight • Reusable • Architecture Independent • Dart & Flutter

---

🚀 Overview

smart_api_executor is a lightweight and reusable API lifecycle execution utility for Dart and Flutter applications.

It standardizes:

• Loading state handling
• Success responses
• Failure handling
• No-internet detection

Without forcing any specific architecture or state management.

No more repeated try-catch boilerplate across projects.

---

✨ Features

• ⚡ Simplifies try/catch API calls into a clean execution flow
• 🔁 Retry support for transient network failures
• ⏱️ Timeout handling for long-running requests
• 🌐 Optional no-internet detection
• 🧠 Developer-friendly result handling with when()
• 🧱 Works with BLoC, Riverpod, Provider, GetX
• 🧪 Fully testable and framework-agnostic
• 📦 Pure Dart – no UI dependencies
• 🚀 Lightweight and production-ready

---

📱 Platform Support

Platform	Supported
Android	✅
iOS	✅
Web	✅
Windows	✅
macOS	✅
Linux	✅

---

📦 Installation

Add this to your pubspec.yaml:

dependencies:
  smart_api_executor: ^0.1.0

Then run:

dart pub get

---

❗ The Problem

Handling API calls usually looks like this:

try {
  final data = await api.getUsers();
  // handle success
} catch (e) {
  // handle error
}

This logic is repeated across many screens and projects.

---

✅ The Solution

final result = await ApiExecutor.execute(
  action: () => api.getUsers(),
);

result.when(
  success: (data) => print(data),
  failure: (e) => print(e),
  noInternet: (_) => print("No Internet"),
  loading: () {},
  initial: () {},
);

---

🌐 No-Internet Handling

final result = await ApiExecutor.execute(
  action: () async {
    throw Exception("No Internet");
  },
  isNoInternet: (error) =>
      error.toString().contains("No Internet"),
);

if (result.status == ApiStatus.noInternet) {
  print("No connection available");
}

---

🔥 Example with BLoC

emit(state.copyWith(status: DashboardStatus.loading));

final result = await ApiExecutor.execute(
  action: () => repository.getDashboard(),
);

switch (result.status) {
  case ApiStatus.success:
    emit(state.copyWith(
      status: DashboardStatus.success,
      data: result.data,
    ));
    break;

  case ApiStatus.failure:
  case ApiStatus.noInternet:
    emit(state.copyWith(
      status: DashboardStatus.failure,
      error: result.error,
    ));
    break;

  default:
    break;
}

---

💡 Why smart_api_executor?

Unlike many API helper utilities, smart_api_executor:

• Does not depend on any HTTP client
• Works with any architecture
• Adds no UI dependencies
• Encourages clean, testable code

You can use it with:

• Dio
• http
• Retrofit
• GraphQL
• Custom API clients

---

⚡ Advanced Example

final result = await ApiExecutor.execute(
  action: () => api.getUsers(),
  retry: 2,
  timeout: Duration(seconds: 10),
);

---

📊 Without smart_api_executor

try {
  final data = await api.getUsers();
} catch (e) {
  if (e is SocketException) {
    // no internet
  } else {
    // failure
  }
}

---

📊 With smart_api_executor

final result = await ApiExecutor.execute(
  action: () => api.getUsers(),
);

Cleaner. Reusable. Testable.

---

📄 License

MIT License © 2026 Yesu Balan

📚 Documentation

https://jesus-balan.github.io/smart_api_executor