safe_result 2.0.1

A Dart package providing a Result type for handling success and error cases in a type-safe way, with support for custom error types.

example/safe_result_example.dart

import 'package:safe_result/safe_result.dart';

// Custom error types
sealed class AppError {
  final String message;
  const AppError(this.message);

  @override
  String toString() => message;
}

class ValidationError extends AppError {
  const ValidationError(super.message);
}

class NetworkError extends AppError {
  final int statusCode;
  const NetworkError(super.message, this.statusCode);

  @override
  String toString() => '$message (Status: $statusCode)';
}

class DatabaseError extends AppError {
  const DatabaseError(super.message);
}

void main() {
  // Basic usage examples
  basicExample();

  // Pattern matching examples
  patternMatchingExample();

  // Transformation examples
  transformationExample();

  // Validation example
  validationExample();

  // Async example
  asyncExample();
}

void basicExample() {
  // Creating Results with specific error types
  final success = Result<int, ValidationError>.ok(42);
  final failure = Result<int, ValidationError>.error(
      ValidationError('Value must be positive'));

  // Checking result type
  print('Is success? ${success.isOk}'); // true
  print('Is failure? ${failure.isError}'); // true

  // Getting values
  final value = success.getOrElse(0);
  print('Value or default: $value'); // 42

  final fallback = failure.getOrElse(0);
  print('Fallback value: $fallback'); // 0
}

void patternMatchingExample() {
  // Pattern matching with switch expressions
  Result<String, ValidationError> processInput(String input) => switch (input) {
        '' => Result.error(ValidationError('Input cannot be empty')),
        var str when str.length < 3 =>
          Result.error(ValidationError('Input too short')),
        var str => Result.ok(str.toUpperCase())
      };

  // Using pattern matching in switch statements
  void handleResult(Result<String, ValidationError> result) {
    switch (result) {
      case Ok(value: final v):
        print('Success: $v');
      case Error(error: final e):
        print('Error: $e');
    }
  }

  handleResult(processInput('')); // Error: Input cannot be empty
  handleResult(processInput('hi')); // Error: Input too short
  handleResult(processInput('hello')); // Success: HELLO
}

void transformationExample() {
  final result = Result<int, ValidationError>.ok(42);

  // Using map to transform success values
  final doubled = result.map((value) => value * 2);
  print(doubled); // Ok(84)

  // Using fold to transform both value and error types
  final networkResult = result.fold<String, NetworkError>(
    onOk: (value) => Result.ok('Success: $value'),
    onError: (error) => Result.error(NetworkError(error.toString(), 400)),
  );
  print(networkResult); // Ok(Success: 42)

  // Example with error case
  final failedResult = Result<int, ValidationError>.error(
    ValidationError('Invalid input'),
  );

  final transformedError = failedResult.fold<String, NetworkError>(
    onOk: (value) => Result.ok('Success: $value'),
    onError: (error) => Result.error(NetworkError(error.toString(), 400)),
  );
  print(transformedError); // Error: Invalid input (Status: 400)

  // Chaining transformations with different error types
  final dbResult = result.map((value) => value * 2).fold<String, DatabaseError>(
        onOk: (value) => value > 50
            ? Result.ok('Large number: $value')
            : Result.error(DatabaseError('Number too small')),
        onError: (error) => Result.error(DatabaseError(error.toString())),
      );
  print(dbResult); // Ok(Large number: 84)
}

// Data class for validation
class User {
  final String name;
  final int age;
  final String email;

  User(this.name, this.age, this.email);

  @override
  String toString() => 'User(name: $name, age: $age, email: $email)';
}

void validationExample() {
  // Validation functions returning Result with ValidationError
  Result<String, ValidationError> validateName(String name) {
    if (name.isEmpty) {
      return Result.error(ValidationError('Name cannot be empty'));
    }
    if (name.length < 2) {
      return Result.error(ValidationError('Name too short'));
    }
    return Result.ok(name);
  }

  Result<int, ValidationError> validateAge(int age) {
    if (age < 0 || age > 120) {
      return Result.error(ValidationError('Invalid age'));
    }
    return Result.ok(age);
  }

  Result<String, ValidationError> validateEmail(String email) {
    final emailRegex = RegExp(r'^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$');
    if (!emailRegex.hasMatch(email)) {
      return Result.error(ValidationError('Invalid email format'));
    }
    return Result.ok(email);
  }

  // Combining multiple validations
  Result<User, ValidationError> createUser(String name, int age, String email) {
    final nameResult = validateName(name);
    final ageResult = validateAge(age);
    final emailResult = validateEmail(email);

    return switch ((nameResult, ageResult, emailResult)) {
      (Ok(value: final n), Ok(value: final a), Ok(value: final e)) =>
        Result.ok(User(n, a, e)),
      (Error(error: final e), _, _) => Result.error(e),
      (_, Error(error: final e), _) => Result.error(e),
      (_, _, Error(error: final e)) => Result.error(e),
    };
  }

  // Example usage
  final validUser = createUser('John', 30, '[e-mail]');
  final invalidUser = createUser('', -5, 'invalid-email');

  print(validUser); // Ok(User(name: John, age: 30, email: [e-mail]))
  print(invalidUser); // Error: Name cannot be empty
}

Future<void> asyncExample() async {
  // Simulated async operations returning Result with NetworkError
  Future<Result<String, NetworkError>> fetchUserName() async {
    try {
      // Simulate API call
      await Future.delayed(Duration(seconds: 1));
      return Result.ok('John Doe');
    } catch (e) {
      return Result.error(NetworkError('Failed to fetch user', 500));
    }
  }

  Future<Result<int, NetworkError>> fetchUserAge(String userName) async {
    try {
      // Simulate API call
      await Future.delayed(Duration(seconds: 1));
      return Result.ok(30);
    } catch (e) {
      return Result.error(NetworkError('Failed to fetch age', 404));
    }
  }

  // Using andThen for chaining async operations
  final result = await fetchUserName().andThen((name) => fetchUserAge(name));

  // Handle the final result
  switch (result) {
    case Ok(value: final age):
      print('User age: $age');
    case Error(error: final e):
      print('Error: $e');
  }
}