Cinch

https://pub.dev/documentation/cinch/latest
Admin
Cinch is a powerful Dart/Flutter HTTP client library that uses code generation for type-safe API...
Tokens:172,892
Snippets:641
Trust Score:9.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Dart Single File Upload Example

Source: https://pub.dev/documentation/cinch/latest/index

Shows how to upload a single file using the @multipart annotation and the MultipartFile class. This includes examples of uploading from a file path and from bytes.

```dart
@ApiService('https://api.example.com/')
class FileApi extends _$FileApi {
  @Post('upload')
  @multipart
  Future<Response> uploadFile(@Part('file') MultipartFile file) {
    return _$uploadFile(file);
  }
}

// Usage
void uploadExample() {
  final api = FileApi();
  
  // From file path
  api.uploadFile(MultipartFile.fromFileSync(
    '/path/to/file.txt', 
    filename: 'document.txt'
  ));
  
  // From bytes
  api.uploadFile(MultipartFile.fromBytes(
    bytes, 
    filename: 'document.txt'
  ));
}
```

--------------------------------

### Dart: Define API Service with Cinch

Source: https://pub.dev/documentation/cinch/latest/index

Example of defining an API service using Cinch annotations for GET requests. It shows how to specify the base URL, endpoint, path parameters, and query parameters.

```dart
import 'package:cinch/cinch.dart';
part 'test.cinch.dart';

@ApiService('https://api.example.com/')
class TestApi extends _$TestApi {
  TestApi() : super();

  @Get('users/{id}')
  Future<Response> getUser(@Path('id') String userId) async {
    return _$getUser(userId);
  }

  @Get('users')
  Future<Response> getUsers(@Query('page') int page) async {
    return _$getUsers(page);
  }
}
```

--------------------------------

### Dart: Make HTTP GET Request with Cinch

Source: https://pub.dev/documentation/cinch/latest/cinch/Dio/get

The 'get<T>' abstract method in the Cinch package provides a convenient way to perform HTTP GET requests. It accepts a path and optional parameters like data, query parameters, options, cancel tokens, and progress callbacks.

```dart
Future<Response<T>> get<T>(
  String path,
  {
  Object? data,
  Map<String, dynamic>? queryParameters,
  Options? options,
  CancelToken? cancelToken,
  ProgressCallback? onReceiveProgress,
}
);
```

--------------------------------

### Make HTTP GET Request with DioMixin

Source: https://pub.dev/documentation/cinch/latest/cinch/DioMixin/get

The `get<T>` method in `DioMixin` is a convenience method for performing HTTP GET requests. It takes a path, optional query parameters, data, options, cancel token, and progress callback. It utilizes the `request` method internally after checking options.

```dart
@override
Future<Response<T>> get<T>(
  String path,
  {
  Map<String, dynamic>? queryParameters,
  Object? data,
  Options? options,
  CancelToken? cancelToken,
  ProgressCallback? onReceiveProgress,
}
) {
  return request<T>(
    path,
    data: data,
    queryParameters: queryParameters,
    options: checkOptions('GET', options),
    onReceiveProgress: onReceiveProgress,
    cancelToken: cancelToken,
  );
}
```

--------------------------------

### Dart ApiUrlMixin Example

Source: https://pub.dev/documentation/cinch/latest/index

Illustrates using the ApiUrlMixin to configure the API URL. This approach allows for a more flexible way to manage API endpoints by mixing in URL configurations.

```dart
import 'package:cinch/cinch.dart';
part 'api.cinch.dart';

class ApiConfig with ApiUrlMixin {
  @override
  String get url => 'https://api.example.com/';
}

@ApiService.emptyUrl()
class UserApi extends _$UserApi with ApiConfig {
  UserApi() : super();
  
  @Get('users')
  Future<Response> getUsers() async {
    return _$getUsers();
  }
}
```

--------------------------------

### Create and Configure Dio Instance

Source: https://pub.dev/documentation/cinch/latest/cinch/Dio-class

Demonstrates how to create a Dio instance with initial configurations including base URL, connection and receive timeouts, and common headers. This setup is essential for making HTTP requests.

```dart
final dio = Dio(
  BaseOptions(
    baseUrl: "https://pub.dev",
    connectTimeout: const Duration(seconds: 5),
    receiveTimeout: const Duration(seconds: 5),
    headers: {
      HttpHeaders.userAgentHeader: 'dio',
      'common-header': 'xx',
    },
  )
);

```

--------------------------------

### Dio GET Request

Source: https://pub.dev/documentation/cinch/latest/cinch/DioMixin-class

Makes an HTTP GET request to a specified path. Supports query parameters, custom options, cancellation tokens, and progress callbacks. An overload is available for using a Uri object.

```Dart
get<T>(String path, {Map<String, dynamic>? queryParameters, Object? data, Options? options, CancelToken? cancelToken, ProgressCallback? onReceiveProgress}) → Future<Response<T>>
```

```Dart
getUri<T>(Uri uri, {Object? data, Options? options, CancelToken? cancelToken, ProgressCallback? onReceiveProgress}) → Future<Response<T>>
```

--------------------------------

### Dart Multiple File Upload with PartMap Example

Source: https://pub.dev/documentation/cinch/latest/index

Demonstrates uploading multiple files using the @partMap annotation. This allows sending a map of files along with other parameters like a description.

```dart
@ApiService('https://api.example.com/')
class FileApi extends _$FileApi {
  @Post('multi-upload')
  @multipart
  Future<Response> multiUpload(
    @Part('description') String description,
    @partMap Map<String, MultipartFile> files,
  ) {
    return _$multiUpload(description, files);
  }
}

// Usage
void multiUploadExample() {
  final api = FileApi();
  
  api.multiUpload('My files', {
    "file1": MultipartFile.fromFileSync('/path/file1.txt', filename: 'doc1.txt'),
    "file2": MultipartFile.fromFileSync('/path/file2.txt', filename: 'doc2.txt'),
  });
  
  // Dynamic file list
  api.multiUpload('Batch upload', {
    for (var i = 0; i < 5; i++)
      "file$i": MultipartFile.fromFileSync(
        '/path/file$i.txt', 
        filename: 'document$i.txt'
      ),
  });
}
```

--------------------------------

### Dio Download with Custom Save Path Function

Source: https://pub.dev/documentation/cinch/latest/cinch/Dio/download

Example of using a function to determine the save path for a downloaded file, which can access response headers.

```dart
await dio.download(
  url,
  (Headers headers) {
    // Extra info: redirect counts
    print(headers.value('redirects'));
    // Extra info: real uri
    print(headers.value('uri'));
    // ...
    return (await getTemporaryDirectory()).path + 'file_name';
  },
);
```

--------------------------------

### DioMixin download with custom save path function

Source: https://pub.dev/documentation/cinch/latest/cinch/DioMixin/download

Demonstrates how to use the `download` method with a function for `savePath`. This function receives headers and can dynamically determine the save location, for example, by accessing redirect information.

```dart
await dio.download(
  url,
  (Headers headers) {
    // Extra info: redirect counts
    print(headers.value('redirects'));
    // Extra info: real uri
    print(headers.value('uri'));
    // ...
    return (await getTemporaryDirectory()).path + 'file_name';
  },
);
```

--------------------------------

### Dio Download Methods

Source: https://pub.dev/documentation/cinch/latest/cinch/Dio-class

Facilitates downloading files to local storage. These methods allow specifying the save path, progress callbacks, and error handling options. The default HTTP method is GET, but it can be customized.

```dart
download(String urlPath, dynamic savePath, {ProgressCallback? onReceiveProgress, Map<String, dynamic>? queryParameters, CancelToken? cancelToken, bool deleteOnError = true, FileAccessMode fileAccessMode = FileAccessMode.write, String lengthHeader = Headers.contentLengthHeader, Object? data, Options? options}) → Future<Response>
     Download the file and save it in local. The default http method is "GET", you can custom it by Options.method.
```

```dart
downloadUri(Uri uri, dynamic savePath, {ProgressCallback? onReceiveProgress, CancelToken? cancelToken, bool deleteOnError = true, FileAccessMode fileAccessMode = FileAccessMode.write, String lengthHeader = Headers.contentLengthHeader, Object? data, Options? options}) → Future<Response>
     Download the file and save it in local. The default http method is "GET", you can custom it by Options.method.
```

--------------------------------

### Dart Custom ApiService Class Example

Source: https://pub.dev/documentation/cinch/latest/index

Demonstrates creating a custom ApiService class by extending the base ApiService class. This method involves defining a concrete service class and associating it with an annotation.

```dart
import 'package:cinch/cinch.dart';
part 'api.cinch.dart';

class ProductionApi extends ApiService {
  const ProductionApi() : super("https://api.production.com/");
}

@ProductionApi()
class UserApi extends _$UserApi {
  UserApi() : super();
  
  @Get('users')
  Future<Response> getUsers() async {
    return _$getUsers();
  }
}
```

--------------------------------

### Dio Download with Progress Callback and Disabled Compression

Source: https://pub.dev/documentation/cinch/latest/cinch/Dio/download

Demonstrates how to download a file, display download progress, and disable compression by setting the 'accept-encoding' header to '*'.

```dart
await dio.download(
  url,
  (await getTemporaryDirectory()).path + 'flutter.svg',
  options: Options(
    headers: {HttpHeaders.acceptEncodingHeader: '*'}, // Disable gzip
  ),
  onReceiveProgress: (received, total) {
    if (total <= 0) return;
    print('percentage: ${(received / total * 100).toStringAsFixed(0)}%');
  },
);
```

--------------------------------

### Create GET Request Annotation (Dart)

Source: https://pub.dev/documentation/cinch/latest/cinch/Get-class

Demonstrates how to create a GET request annotation using the 'Get.new' constructor. This is used to define an HTTP GET request, specifying the endpoint path and optionally a list of status codes to consider successful.

```dart
Get.new(
  "/users",
  validateStatus: [
    200,
    201,
  ],
)
```

--------------------------------

### Get Constructor - Dart

Source: https://pub.dev/documentation/cinch/latest/cinch/Get/Get

Creates a GET request annotation for a specified endpoint path. It allows for optional validation of HTTP status codes to consider the request successful. This constructor is part of the Cinch package for defining API requests.

```dart
const Get(String path, {List<int> validateStatus = const []});
```

```dart
const Get(String path, {List<int> validateStatus = const []})
    : super(path, validateStatus: validateStatus);
```

--------------------------------

### DioMixin download method implementation

Source: https://pub.dev/documentation/cinch/latest/cinch/DioMixin/download

The `download` method in `DioMixin` is used to download a file from a given URL and save it to a specified path. It supports progress callbacks, query parameters, cancellation tokens, and options for error handling and file access modes. The default HTTP method is GET, but it can be customized via `Options.method`.

```dart
@override
Future<Response> download(
  String urlPath,
  dynamic savePath, {
  ProgressCallback? onReceiveProgress,
  Map<String, dynamic>? queryParameters,
  CancelToken? cancelToken,
  bool deleteOnError = true,
  FileAccessMode fileAccessMode = FileAccessMode.write,
  String lengthHeader = Headers.contentLengthHeader,
  Object? data,
  Options? options,
}) {
  throw UnimplementedError();
}
```

--------------------------------

### Download File with DioMixin.downloadUri

Source: https://pub.dev/documentation/cinch/latest/cinch/DioMixin/downloadUri

Downloads a file from a given URI and saves it to a local path. It accepts a save path as a String or a function, allows progress tracking via onReceiveProgress, and provides options for error handling and header customization.

```dart
@override
Future<Response> downloadUri(
  Uri uri,
  dynamic savePath,
  {
  ProgressCallback? onReceiveProgress,
  CancelToken? cancelToken,
  bool deleteOnError = true,
  FileAccessMode fileAccessMode = FileAccessMode.write,
  String lengthHeader = Headers.contentLengthHeader,
  Object? data,
  Options? options,
}
) {
  return download(
    uri.toString(),
    savePath,
    onReceiveProgress: onReceiveProgress,
    lengthHeader: lengthHeader,
    deleteOnError: deleteOnError,
    cancelToken: cancelToken,
    data: data,
    fileAccessMode: fileAccessMode,
    options: options,
  );
}
```

--------------------------------

### Get length property in Dart

Source: https://pub.dev/documentation/cinch/latest/cinch/Interceptors/length

Demonstrates how to get the number of elements in a list using the `length` property. This is a common operation for collections in Dart.

```Dart
final numbers = <int>[1, 2, 3];
print(numbers.length); // 3
```

--------------------------------

### Dio Get Methods

Source: https://pub.dev/documentation/cinch/latest/cinch/Dio-class

Convenience methods for making HTTP GET requests. They support both string paths and Uri objects and allow for progress callbacks.

```dart
get<T>(String path, {Object? data, Map<String, dynamic>? queryParameters, Options? options, CancelToken? cancelToken, ProgressCallback? onReceiveProgress}) → Future<Response<T>> 
     Convenience method to make an HTTP GET request.
```

```dart
getUri<T>(Uri uri, {Object? data, Options? options, CancelToken? cancelToken, ProgressCallback? onReceiveProgress}) → Future<Response<T>> 
     Convenience method to make an HTTP GET request with Uri.
```

--------------------------------

### Create HttpClientAdapter (Dart)

Source: https://pub.dev/documentation/cinch/latest/cinch/HttpClientAdapter/HttpClientAdapter

This factory constructor creates an HttpClientAdapter instance based on the current platform, whether it's an IO or Web environment. It relies on an internal adapter implementation to provide the correct instance.

```dart
factory HttpClientAdapter() => adapter.createAdapter();
```

--------------------------------

### Initialize Transformer Constructor

Source: https://pub.dev/documentation/cinch/latest/cinch/Transformer/Transformer

This snippet shows the basic initialization of the Transformer constructor. It is a core part of the Cinch package for handling request and response transformations.

```dart
Transformer()
```

--------------------------------

### Download with Custom Save Path and Progress

Source: https://pub.dev/documentation/cinch/latest/cinch/Dio/downloadUri

Demonstrates downloading a file using Dio, specifying a custom save path derived from headers and providing a progress callback to display the download percentage.

```Dart
await dio.download(
  url,
  (Headers headers) {
    // Extra info: redirect counts
    print(headers.value('redirects'));
    // Extra info: real uri
    print(headers.value('uri'));
    // ...
    return (await getTemporaryDirectory()).path + 'file_name';
  },
);
```

--------------------------------

### HTTP Method Annotations (GET, POST, PUT, DELETE)

Source: https://pub.dev/documentation/cinch/latest/cinch

Annotations like Get, Post, Put, and Delete are used to define the HTTP method for a particular request. These are typically used on methods within an ApiService class.

```dart
@Get('/items/{id}')
Future<Item> getItem(@Path('id') String id);

@Post('/items')
Future<Item> createItem(@Body() Item item);
```

--------------------------------

### HttpClientAdapter Constructor

Source: https://pub.dev/documentation/cinch/latest/cinch/HttpClientAdapter-class

Creates a new HttpClientAdapter instance, automatically selecting the appropriate implementation based on the current platform (IO or Web). This factory constructor simplifies the process of obtaining a functional adapter.

```Dart
factory HttpClientAdapter.new() => /* platform-specific implementation */;
```

--------------------------------

### Dart: Initialize Cinch Options

Source: https://pub.dev/documentation/cinch/latest/cinch/Options/Options

This snippet shows the initialization of the Options constructor in Dart. It accepts numerous optional parameters to configure aspects like request method, send/receive timeouts, headers, content type, and redirection policies.

```Dart
Options({
  String? method,
  Duration? sendTimeout,
  Duration? receiveTimeout,
  Map<String, dynamic>? extra,
  Map<String, dynamic>? headers,
  bool? preserveHeaderCase,
  ResponseType? responseType,
  String? contentType,
  ValidateStatus? validateStatus,
  bool? receiveDataWhenStatusError,
  bool? followRedirects,
  int? maxRedirects,
  bool? persistentConnection,
  RequestEncoder? requestEncoder,
  ResponseDecoder? responseDecoder,
  ListFormat? listFormat,
})
  : assert(receiveTimeout == null || !receiveTimeout.isNegative),
      _receiveTimeout = receiveTimeout,
      assert(sendTimeout == null || !sendTimeout.isNegative),
      _sendTimeout = sendTimeout;
```

--------------------------------

### Interceptor: Get Range

Source: https://pub.dev/documentation/cinch/latest/cinch/Interceptors-class

Returns an iterable view of a specified range of elements within the list.

```dart
getRange(int start, int end) → Iterable<Interceptor> 
     Creates an Iterable that iterates over a range of elements.
```

--------------------------------

### Options Class Constructor

Source: https://pub.dev/documentation/cinch/latest/cinch/Options-class

The constructor for the Options class allows for the initialization of a request configuration. It accepts numerous optional parameters to define aspects like the HTTP method, send/receive timeouts, headers, content type, response type, and more. These parameters enable fine-grained control over how a request is processed.

```dart
Options.new({
  String? method,
  Duration? sendTimeout,
  Duration? receiveTimeout,
  Map<String, dynamic>? extra,
  Map<String, dynamic>? headers,
  bool? preserveHeaderCase,
  ResponseType? responseType,
  String? contentType,
  ValidateStatus? validateStatus,
  bool? receiveDataWhenStatusError,
  bool? followRedirects,
  int? maxRedirects,
  bool? persistentConnection,
  RequestEncoder? requestEncoder,
  ResponseDecoder? responseDecoder,
  ListFormat? listFormat
})
```

--------------------------------

### Interceptor: Remove Range

Source: https://pub.dev/documentation/cinch/latest/cinch/Interceptors-class

Removes a range of elements from the list, specified by start and end indices.

```dart
removeRange(int start, int end) → void 
     Removes a range of elements from the list.
```

--------------------------------

### Implement BaseOptions Options in Dart

Source: https://pub.dev/documentation/cinch/latest/cinch/Dio/options

Demonstrates the implementation of the 'options' property using Dart's BaseOptions. This property serves as a getter/setter pair for default request configuration.

```dart
late BaseOptions options;
```

--------------------------------

### Interceptor: Get Element at Index

Source: https://pub.dev/documentation/cinch/latest/cinch/Interceptors-class

Retrieves the Interceptor element at a specified index in the list. Indices are zero-based.

```dart
elementAt(int index) → Interceptor 
     Returns the `index`th element.
```

--------------------------------

### Create Service Instance with Timeouts

Source: https://pub.dev/documentation/cinch/latest/cinch/Service/Service

This code demonstrates the creation of a new Service instance. It allows configuration of the base URL and various timeouts for network operations, including connection, receiving, and sending data. An optional function for validating HTTP status codes can also be provided.

```dart
Service(
  "https://api.example.com", // baseUrl
  connectTimeout: Duration(seconds: 5),
  receiveTimeout: Duration(seconds: 10),
  sendTimeout: Duration(seconds: 10),
  validateStatus: (status) => status >= 200 && status < 300
);
```

```dart
Service(this.baseUrl,
    {this.connectTimeout = const Duration(seconds: 5),
    this.receiveTimeout = const Duration(seconds: 10),
    this.sendTimeout = const Duration(seconds: 10),
    this.validateStatus}) {
  dio = Dio(BaseOptions(
      baseUrl: _getInitialUrl(),
      connectTimeout: connectTimeout,
      receiveTimeout: receiveTimeout,
      sendTimeout: sendTimeout,
      validateStatus: validateStatus,
      headers: <String, dynamic>{Headers.contentEncodingHeader: 'gzip'},
      responseType: ResponseType.json));
}
```

--------------------------------

### Interceptor: Set All Elements

Source: https://pub.dev/documentation/cinch/latest/cinch/Interceptors-class

Overwrites elements in the list starting from a given index with elements from another iterable.

```dart
setAll(int index, Iterable<Interceptor> iterable) → void 
     Overwrites elements with the objects of `iterable`.
```

--------------------------------

### DioMixin download with disabled compression and progress callback

Source: https://pub.dev/documentation/cinch/latest/cinch/DioMixin/download

Shows how to disable gzip compression for downloads by setting the 'accept-encoding' header to '*'. This ensures the 'total' argument in the `onReceiveProgress` callback accurately reflects the uncompressed file size. It also includes a progress callback to display the download percentage.

```dart
await dio.download(
  url,
  (await getTemporaryDirectory()).path + 'flutter.svg',
  options: Options(
    headers: {HttpHeaders.acceptEncodingHeader: '*'}, // Disable gzip
  ),
  onReceiveProgress: (received, total) {
    if (total <= 0) return;
    print('percentage: ${(received / total * 100).toStringAsFixed(0)}%');
  },
);
```

--------------------------------

### Get receiveTimeout - Dart

Source: https://pub.dev/documentation/cinch/latest/cinch/Options/receiveTimeout

Retrieves the current receive timeout duration. A null or zero duration indicates no timeout limit.

```dart
Duration? get receiveTimeout => _receiveTimeout;
```

--------------------------------

### Options Class Methods

Source: https://pub.dev/documentation/cinch/latest/cinch/Options-class

The Options class provides methods for managing request configurations. The `compose` method merges a BaseOptions object with the current Options and a path to create a complete RequestOptions. The `copyWith` method creates a new Options instance by merging attributes from the current instance, allowing for easy modification of specific settings.

```dart
compose(BaseOptions baseOpt, String path, {Object? data, Map<String, dynamic>? queryParameters, CancelToken? cancelToken, ProgressCallback? onSendProgress, ProgressCallback? onReceiveProgress, StackTrace? sourceStackTrace}) → RequestOptions
copyWith({String? method, Duration? sendTimeout, Duration? receiveTimeout, Map<String, Object?>? extra, Map<String, Object?>? headers, bool? preserveHeaderCase, ResponseType? responseType, String? contentType, ValidateStatus? validateStatus, bool? receiveDataWhenStatusError, bool? followRedirects, int? maxRedirects, bool? persistentConnection, RequestEncoder? requestEncoder, ResponseDecoder? responseDecoder, ListFormat? listFormat}) → Options
```

--------------------------------

### Interceptor: Index Of Element

Source: https://pub.dev/documentation/cinch/latest/cinch/Interceptors-class

Finds the first index of a given element in the list, optionally starting from a specified index.

```dart
indexOf(Object? element, [int start = 0]) → int 
     The first index of `element` in this list.
```

--------------------------------

### Interceptor: Index Where

Source: https://pub.dev/documentation/cinch/latest/cinch/Interceptors-class

Finds the first index of an element that satisfies a given test condition, optionally starting from a specified index.

```dart
indexWhere(bool test(Interceptor element), [int start = 0]) → int 
     The first index in the list that satisfies the provided `test`.
```

--------------------------------

### Using ResponseType.stream for ResponseBody

Source: https://pub.dev/documentation/cinch/latest/cinch/ResponseType

Demonstrates how to use the ResponseType.stream to get the response stream directly. The Response.data will be of type ResponseBody when this option is used.

```dart
Response<ResponseBody> rs = await Dio().get<ResponseBody>(
  url,
  options: Options(responseType: ResponseType.stream),
);

```

--------------------------------

### Dart: BaseOptions Constructor

Source: https://pub.dev/documentation/cinch/latest/cinch/BaseOptions-class

The BaseOptions constructor allows initialization of various request-related settings. These include method, timeouts, base URL, query parameters, headers, response type, and more. It serves as a base configuration for Dio requests.

```dart
BaseOptions({
  String? method,
  Duration? connectTimeout,
  Duration? receiveTimeout,
  Duration? sendTimeout,
  String baseUrl = '',
  Map<String, dynamic>? queryParameters,
  Map<String, dynamic>? extra,
  Map<String, dynamic>? headers,
  bool? preserveHeaderCase = false,
  ResponseType? responseType = ResponseType.json,
  String? contentType,
  ValidateStatus? validateStatus,
  bool? receiveDataWhenStatusError,
  bool? followRedirects,
  int? maxRedirects,
  bool? persistentConnection,
  RequestEncoder? requestEncoder,
  ResponseDecoder? responseDecoder,
  ListFormat? listFormat,
})
```

--------------------------------

### Dio Download Method Signature

Source: https://pub.dev/documentation/cinch/latest/cinch/Dio/download

The signature for the download method in Dio, outlining all available parameters and their types for downloading files.

```dart
Future<Response> download(
  String urlPath,
  dynamic savePath, {
  ProgressCallback? onReceiveProgress,
  Map<String, dynamic>? queryParameters,
  CancelToken? cancelToken,
  bool deleteOnError = true,
  FileAccessMode fileAccessMode = FileAccessMode.write,
  String lengthHeader = Headers.contentLengthHeader,
  Object? data,
  Options? options,
});
```

--------------------------------

### Get sendTimeout Property

Source: https://pub.dev/documentation/cinch/latest/cinch/RequestOptions/sendTimeout

This code snippet shows the getter implementation for the sendTimeout property. It returns the current Duration set for the send timeout.

```dart
Duration? get sendTimeout => _sendTimeout;
```

--------------------------------

### Get baseUrl Property

Source: https://pub.dev/documentation/cinch/latest/cinch/OptionsMixin/baseUrl

Retrieves the configured base URL for API requests. The URL can include subpaths or be a relative path for web applications.

```dart
String get baseUrl => _baseUrl;
```

--------------------------------

### Get sendTimeout Property (Dart)

Source: https://pub.dev/documentation/cinch/latest/cinch/Options/sendTimeout

Retrieves the current send timeout duration. A null or zero duration indicates no timeout limit.

```dart
Duration? get sendTimeout => _sendTimeout;
```

--------------------------------

### Post Constructor Implementation

Source: https://pub.dev/documentation/cinch/latest/cinch/Post/Post

This code snippet shows the implementation of the `Post` constructor, which creates a POST request annotation. It takes a `path` string and an optional list of `validateStatus` integers.

```dart
const Post(String path, {List<int> validateStatus = const []})
    : super(path, validateStatus: validateStatus);
```

--------------------------------

### Get Header Map

Source: https://pub.dev/documentation/cinch/latest/cinch/Headers-class

Provides access to the underlying Map representation of the headers, where keys are header names and values are lists of strings.

```dart
map → Map<String, List<String>>
```

--------------------------------

### Disable Compression for Progress Callback

Source: https://pub.dev/documentation/cinch/latest/cinch/DioMixin/downloadUri

Demonstrates how to disable gzip compression by setting the 'accept-encoding' header to '*' to ensure the 'total' argument in onReceiveProgress is not -1.

```dart
await dio.download(
  url,
  (await getTemporaryDirectory()).path + 'flutter.svg',
  options: Options(
    headers: {HttpHeaders.acceptEncodingHeader: '*'}, // Disable gzip
  ),
  onReceiveProgress: (received, total) {
    if (total <= 0) return;
    print('percentage: ${(received / total * 100).toStringAsFixed(0)}%');
  },
);
```

--------------------------------

### RequestOptions and BaseOptions for Configuration

Source: https://pub.dev/documentation/cinch/latest/cinch

BaseOptions and Options are used to configure requests. They are merged into a single RequestOptions before the request is sent, allowing for centralized configuration management.

```dart
final options = BaseOptions(
  baseUrl: 'https://api.example.com',
  connectTimeout: 5000,
  receiveTimeout: 3000,
);
final dio = Dio(options);
```

--------------------------------

### Clone MultipartFile

Source: https://pub.dev/documentation/cinch/latest/cinch/MultipartFile-class

Clones a MultipartFile instance, returning a new instance with the same properties. This is useful for retrying requests, for example, after an authentication error.

```dart
clone() → MultipartFile
```

--------------------------------

### Get headers property (Dart)

Source: https://pub.dev/documentation/cinch/latest/cinch/RequestOptions/headers

Retrieves the current headers map from the RequestOptions. This getter returns a Map<String, dynamic> representing the request headers.

```dart
Map<String, dynamic> get headers => _headers;
```

--------------------------------

### Dart - Cinch DioMixin fetch Method Implementation

Source: https://pub.dev/documentation/cinch/latest/cinch/DioMixin/fetch

This Dart code snippet demonstrates the implementation of the fetch<T> method in the Cinch package's DioMixin. It outlines the logic for setting response types, wrapping interceptor callbacks, and managing the request lifecycle through a series of asynchronous operations and error handling.

```Dart
@override
Future<Response<T>> fetch<T>(RequestOptions requestOptions) async {
  if (T != dynamic &&
      !(requestOptions.responseType == ResponseType.bytes ||
          requestOptions.responseType == ResponseType.stream)) {
    if (T == String) {
      requestOptions.responseType = ResponseType.plain;
    } else {
      requestOptions.responseType = ResponseType.json;
    }
  }

  // Convert the request interceptor to a functional callback in which
  // we can handle the return value of interceptor callback.
  FutureOr Function(dynamic) requestInterceptorWrapper(
    InterceptorSendCallback cb,
  ) {
    return (dynamic incomingState) {
      final state = incomingState as InterceptorState;
      if (state.type == InterceptorResultType.next) {
        return listenCancelForAsyncTask(
          requestOptions.cancelToken,
          Future(() async {
            final handler = RequestInterceptorHandler();
            cb(state.data as RequestOptions, handler);
            return handler.future;
          }),
        );
      }
      return state;
    };
  }

  // Convert the response interceptor to a functional callback in which
  // we can handle the return value of interceptor callback.
  FutureOr<dynamic> Function(dynamic) responseInterceptorWrapper(
    InterceptorSuccessCallback cb,
  ) {
    return (dynamic incomingState) {
      final state = incomingState as InterceptorState;
      if (state.type == InterceptorResultType.next ||
          state.type == InterceptorResultType.resolveCallFollowing) {
        return listenCancelForAsyncTask(
          requestOptions.cancelToken,
          Future(() async {
            final handler = ResponseInterceptorHandler();
            cb(state.data as Response, handler);
            return handler.future;
          }),
        );
      }
      return state;
    };
  }

  // Convert the error interceptor to a functional callback in which
  // we can handle the return value of interceptor callback.
  FutureOr<dynamic> Function(Object) errorInterceptorWrapper(
    InterceptorErrorCallback cb,
  ) {
    return (dynamic error) {
      final state = error is InterceptorState
          ? error
          : InterceptorState(assureDioException(error, requestOptions));
      Future<InterceptorState> handleError() async {
        final handler = ErrorInterceptorHandler();
        cb(state.data, handler);
        return handler.future;
      }

      // The request has already been cancelled,
      // there is no need to listen for another cancellation.
      if (state.data is DioException &&
          state.data.type == DioExceptionType.cancel) {
        return handleError();
      }
      if (state.type == InterceptorResultType.next ||
          state.type == InterceptorResultType.rejectCallFollowing) {
        return listenCancelForAsyncTask(
          requestOptions.cancelToken,
          Future(handleError),
        );
      }
      throw error;
    };
  }

  // Build a request flow in which the processors(interceptors)
  // execute in FIFO order.
  Future<dynamic> future = Future<dynamic>(
    () => InterceptorState(requestOptions),
  );

  // Add request interceptors into the request flow.
  for (final interceptor in interceptors) {
    final fun = interceptor is QueuedInterceptor
        ? interceptor._handleRequest
        : interceptor.onRequest;
    future = future.then(requestInterceptorWrapper(fun));
  }

  // Add dispatching callback into the request flow.
  future = future.then(
    requestInterceptorWrapper((
      RequestOptions reqOpt,
      RequestInterceptorHandler handler,
    ) async {
      requestOptions = reqOpt;
      try {
        final value = await _dispatchRequest<T>(reqOpt);
        handler.resolve(value, true);
      } on DioException catch (e) {
        handler.reject(e, true);
      }
    }),
  );

  // Add response interceptors into the request flow
  for (final interceptor in interceptors) {
    final fun = interceptor is QueuedInterceptor
        ? interceptor._handleResponse
        : interceptor.onResponse;
    future = future.then(responseInterceptorWrapper(fun));
  }

  // Add error handlers into the request flow.
  for (final interceptor in interceptors) {
    final fun = interceptor is QueuedInterceptor
        ? interceptor._handleError
        : interceptor.onError;
    future = future.catchError(errorInterceptorWrapper(fun));
  }
  // Normalize errors, converts errors to [DioException].
  try {
    final data = await future;
    return assureResponse<T>(
      data is InterceptorState ? data.data : data,
      requestOptions,
    );
  } catch (e) {
    final isState = e is InterceptorState;
    if (isState) {
      if (e.type == InterceptorResultType.resolve) {
        return assureResponse<T>(e.data, requestOptions);
      }
    }
    throw assureDioException(isState ? e.data : e, requestOptions);
  }
}

```

--------------------------------

### Create MultipartFile from File Path (Async)

Source: https://pub.dev/documentation/cinch/latest/cinch/MultipartFile-class

Creates a new MultipartFile from a path to a file on disk asynchronously. This method reads the file content and prepares it for upload.

```dart
Future<MultipartFile> fromFile(String filePath, {String? filename, DioMediaType? contentType, Map<String, List<String>>? headers})
```

--------------------------------

### Get isCompleted Property - Dart

Source: https://pub.dev/documentation/cinch/latest/cinch/ResponseInterceptorHandler/isCompleted

This code snippet shows how to access the 'isCompleted' property of the ResponseInterceptorHandler class. This boolean property indicates whether the operation has been completed.

```dart
bool get isCompleted => _completer.isCompleted;
```

--------------------------------

### Clone MultipartFile Instance

Source: https://pub.dev/documentation/cinch/latest/cinch/MultipartFile/clone

The clone() method creates a new MultipartFile instance with the same properties as the original. This is beneficial for retrying requests, particularly when dealing with authentication issues that necessitate token refreshes.

```dart
MultipartFile clone() {
  return MultipartFile.fromStream(
    _dataBuilder,
    length,
    filename: filename,
    contentType: contentType,
    headers: headers,
  );
}
```

--------------------------------

### Get receiveTimeout Property (Dart)

Source: https://pub.dev/documentation/cinch/latest/cinch/RequestOptions/receiveTimeout

This code snippet shows the getter implementation for the receiveTimeout property in Dart. It returns the current value of the _receiveTimeout private variable.

```dart
Duration? get receiveTimeout => _receiveTimeout;
```

--------------------------------

### Disable Compression for Accurate Progress

Source: https://pub.dev/documentation/cinch/latest/cinch/Dio/downloadUri

Shows how to disable gzip compression by setting the 'accept-encoding' header to '*' to ensure the 'total' argument in the progress callback accurately reflects the file size.

```Dart
await dio.download(
  url,
  (await getTemporaryDirectory()).path + 'flutter.svg',
  options: Options(
    headers: {HttpHeaders.acceptEncodingHeader: '*'}, // Disable gzip
  ),
  onReceiveProgress: (received, total) {
    if (total <= 0) return;
    print('percentage: ${(received / total * 100).toStringAsFixed(0)}%');
  },
);
```

--------------------------------

### Get map property - Cinch Dart

Source: https://pub.dev/documentation/cinch/latest/cinch/Headers/map

Retrieves the map property from the Cinch package. This property is of type Map<String, List<String>> and is implemented as a getter.

```dart
Map<String, List<String>> get map => _map;
```
Tokens:
Raw