Supabase Result Handler

A robust Flutter package to simplify error handling and result wrapping for Supabase applications. It leverages freezed to provide a type-safe Result pattern, automatically catching Supabase-specific exceptions (Auth, Postgrest, Functions) and converting them into user-friendly messages with multi-language support (English & Arabic).

Features 🚀

Result Pattern: Wraps responses in Success or Failure types.
Auto Error Handling: Automatically catches and categorizes Supabase errors (Auth, Database, Edge Functions).
Localization Support: Built-in support for English and Arabic error messages.
Type Safety: Built using freezed to ensure compile-time safety.
Clean Syntax: Reduces boilerplate code with helper methods.

Installation 📦

Add this to your package's pubspec.yaml file:

dependencies:
  supabase_result_handler: ^1.0.0

Usage

Basic Usage

Use SupaResult.catchError to automatically handle try-catch blocks and convert exceptions.

import 'package:supabase_flutter/supabase_flutter.dart';
import 'package:supabase_result_handler/supabase_result_handler.dart';

class AuthRepository {
  final SupabaseClient _supabase = Supabase.instance.client;

  // Return Future<SupaResult<T>>
  Future<SupaResult<User>> login(String email, String password) async {
    // Fast use with easy way to catch error
    return SupaResult.catchError(() async {
      final response = await _supabase.auth.signInWithPassword(
        email: email,
        password: password,
      );
      // Return the data you want on success
      return response.user!;
    });
  }
}

Handling the Result in UI (Smart Localization)

The .toErrorMessage() method is now smarter! You don't need to pass the language manually if you have the context.

  result.when(
    success: (user) => print("Done!"),
    failure: (exception) {
      // 1. Automatic: Get language from MaterialApp's Locale
      final msg = exception.toErrorMessage(context: context);
    
      // 2. Manual: Force a specific language
      final msgEn = exception.toErrorMessage(lang: AppLanguage.en);
    
      // 3. System: If no params, it follows the device OS language
      final msgSystem = exception.toErrorMessage();
    
      ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(msg)));
    },
  );

Manual Usage (more customization)

If you prefer to handle try-catch blocks manually, or need to do some complex logic in Catch:

try {
  final data = await supabase.from('table').select();
  return SupaResult.success(data: data);
} catch (e) {
  // Convert generic error to NetworkExceptions
  return SupaResult.failure(error: NetworkExceptions.getException(e));
}

Localization 🌍

The package supports English and Arabic out of the box. It looks for the language in the following order:

Manual: If lang parameter is provided.
Context: If context is provided, it uses Localizations.localeOf(context).
System: Fallback to PlatformDispatcher.instance.locale (Device Language).

Supported Exceptions 🛡️

The package handles a wide range of status codes and exceptions:

Auth Errors: 400, 401, 403, 422 (User already exists / Same password), etc.
Postgrest Errors: Database-related errors.
Edge Functions: Function execution errors.
Network: No Internet, Timeout, Socket Exceptions.
General: Format Exceptions, Unknown Errors.