Add ability to change [FileMode] of the download by introducing [DioF…

…ileMode]

dio/lib/dio.dart

@@ -9,6 +9,7 @@ export 'src/adapter.dart';
 export 'src/cancel_token.dart';
 export 'src/dio.dart';
 export 'src/dio_exception.dart';
+export 'src/dio_file_mode.dart';
 export 'src/dio_mixin.dart' hide InterceptorState, InterceptorResultType;
 export 'src/form_data.dart';
 export 'src/headers.dart';
@@ -18,4 +19,4 @@ export 'src/options.dart';
 export 'src/parameter.dart';
 export 'src/redirect_record.dart';
 export 'src/response.dart';
-export 'src/transformer.dart';
+export 'src/transformer.dart';

dio/lib/src/dio.dart

@@ -5,6 +5,7 @@ import 'cancel_token.dart';
 import 'dio/dio_for_native.dart'
     if (dart.library.js_interop) 'dio/dio_for_browser.dart'
     if (dart.library.html) 'dio/dio_for_browser.dart';
+import 'dio_file_mode.dart';
 import 'dio_mixin.dart';
 import 'headers.dart';
 import 'options.dart';
@@ -209,6 +210,9 @@ abstract class Dio {
   /// [deleteOnError] whether delete the file when error occurs.
   /// The default value is [true].
   ///
+  /// [fileMode] 
+  /// {@macro dio.DioFileMode}
+  /// 
   /// [lengthHeader] : The real size of original file (not compressed).
   /// When file is compressed:
   /// 1. If this value is 'content-length', the `total` argument of
@@ -242,6 +246,7 @@ abstract class Dio {
     Map<String, dynamic>? queryParameters,
     CancelToken? cancelToken,
     bool deleteOnError = true,
+    DioFileMode fileMode = DioFileMode.write,
     String lengthHeader = Headers.contentLengthHeader,
     Object? data,
     Options? options,
@@ -254,6 +259,7 @@ abstract class Dio {
     ProgressCallback? onReceiveProgress,
     CancelToken? cancelToken,
     bool deleteOnError = true,
+    DioFileMode mode = DioFileMode.write,
     String lengthHeader = Headers.contentLengthHeader,
     Object? data,
     Options? options,
@@ -266,6 +272,7 @@ abstract class Dio {
       deleteOnError: deleteOnError,
       cancelToken: cancelToken,
       data: data,
+      fileMode: mode,
       options: options,
     );
   }

dio/lib/src/dio/dio_for_native.dart

@@ -6,6 +6,7 @@ import '../adapters/io_adapter.dart';
 import '../cancel_token.dart';
 import '../dio.dart';
 import '../dio_exception.dart';
+import '../dio_file_mode.dart';
 import '../dio_mixin.dart';
 import '../headers.dart';
 import '../options.dart';
@@ -32,6 +33,7 @@ class DioForNative with DioMixin implements Dio {
     Map<String, dynamic>? queryParameters,
     CancelToken? cancelToken,
     bool deleteOnError = true,
+    DioFileMode fileMode = DioFileMode.write,
     String lengthHeader = Headers.contentLengthHeader,
     Object? data,
     Options? options,
@@ -95,7 +97,12 @@ class DioForNative with DioMixin implements Dio {
     // Shouldn't call file.writeAsBytesSync(list, flush: flush),
     // because it can write all bytes by once. Consider that the file is
     // a very big size (up to 1 Gigabytes), it will be expensive in memory.
-    RandomAccessFile raf = file.openSync(mode: FileMode.write);
+    RandomAccessFile raf = file.openSync(
+      mode: fileMode.map(
+        write: () => FileMode.write,
+        append: () => FileMode.append,
+      ),
+    );
 
     // Create a Completer to notify the success/error state.
     final completer = Completer<Response>();

dio/lib/src/dio_file_mode.dart

@@ -0,0 +1,24 @@
+/// {@template dio.DioFileMode}
+///  The file access mode when downloading the file.
+/// - [DioFileMode.write]: Mode for opening a file for reading and writing.
+///    The file is overwritten if it already exists. The file is created if it
+///    does not already exist
+/// - [DioFileMode.append]: Mode for opening a file for reading and writing
+///    to the end of it. The file is created if it does not already exist.
+/// {@endtemplate}
+enum DioFileMode {
+  write,
+  append;
+
+  T map<T>({
+    required T Function() write,
+    required T Function() append,
+  }) {
+    switch (this) {
+      case DioFileMode.write:
+        return write();
+      case DioFileMode.append:
+        return append();
+    }
+  }
+}

dio/lib/src/dio_mixin.dart

@@ -11,6 +11,7 @@ import 'adapter.dart';
 import 'cancel_token.dart';
 import 'dio.dart';
 import 'dio_exception.dart';
+import 'dio_file_mode.dart';
 import 'form_data.dart';
 import 'headers.dart';
 import 'interceptors/imply_content_type.dart';
@@ -286,6 +287,7 @@ abstract class DioMixin implements Dio {
     ProgressCallback? onReceiveProgress,
     CancelToken? cancelToken,
     bool deleteOnError = true,
+    DioFileMode mode = DioFileMode.write,
     String lengthHeader = Headers.contentLengthHeader,
     Object? data,
     Options? options,
@@ -310,6 +312,7 @@ abstract class DioMixin implements Dio {
     Map<String, dynamic>? queryParameters,
     CancelToken? cancelToken,
     bool deleteOnError = true,
+    DioFileMode fileMode = DioFileMode.write,
     String lengthHeader = Headers.contentLengthHeader,
     Object? data,
     Options? options,

plugins/web_adapter/lib/src/dio_impl.dart

@@ -22,6 +22,7 @@ class DioForBrowser with DioMixin implements Dio {
     Map<String, dynamic>? queryParameters,
     CancelToken? cancelToken,
     bool deleteOnError = true,
+    DioFileMode fileMode = DioFileMode.write,
     String lengthHeader = Headers.contentLengthHeader,
     Object? data,
     Options? options,