Merge branch 'release/18.1.0'

Author: joanpablo

CHANGELOG.md

@@ -1,6 +1,13 @@
+# 18.1.0
+
+- Add `oneOf` validator to the list of validators.
+- Add `debounced` async validator that allows to specify a custom debounce time for a single validator.
+- The `Validators.delegateAsync()` function now accepts an optional `debounceTime` parameter, defaulting to 0. This allows immediate execution or custom debouncing for asynchronous validation.
+
 # 18.0.1
 
 ## Features
+- Add `allowNull` optional parameter to the `CompareValidator`.
 - The FormControl.reset() method has been updated to align with
   the common expectation that resetting a control without specifying a
   new value should revert it to its initial state.

README.md

@@ -29,6 +29,7 @@ export 'src/validators/compose_or_validator.dart';
 export 'src/validators/compose_validator.dart';
 export 'src/validators/contains_validator.dart';
 export 'src/validators/credit_card_validator.dart';
+export 'src/validators/debounced_async_validator.dart';
 export 'src/validators/delegate_async_validator.dart';
 export 'src/validators/delegate_validator.dart';
 export 'src/validators/email_validator.dart';
@@ -39,6 +40,7 @@ export 'src/validators/min_length_validator.dart';
 export 'src/validators/min_validator.dart';
 export 'src/validators/must_match_validator.dart';
 export 'src/validators/number_validator.dart';
+export 'src/validators/one_of_validator.dart';
 export 'src/validators/pattern/default_pattern_evaluator.dart';
 export 'src/validators/pattern/pattern_evaluator.dart';
 export 'src/validators/pattern/regex_pattern_evaluator.dart';

lib/reactive_forms.dart

@@ -7,6 +7,8 @@ import 'dart:async';
 import 'package:flutter/foundation.dart';
 import 'package:reactive_forms/reactive_forms.dart';
 
+// ignore_for_file: deprecated_member_use_from_same_package
+
 const _controlNameDelimiter = '.';
 
 /// This is the base class for [FormGroup], [FormArray] and [FormControl].
@@ -40,7 +42,14 @@ abstract class AbstractControl<T> {
   /// Async validators debounce timer.
   Timer? _debounceTimer;
 
+  /// **DEPRECATED**: Use [Validators.debounced] to specify a debounce time for
+  /// individual asynchronous validators. This property will be removed in a
+  /// future major version.
+  ///
   /// Async validators debounce time in milliseconds.
+  @Deprecated(
+    "Use [Validators.debounced] to specify a debounce time for individual asynchronous validators.",
+  )
   final int _asyncValidatorsDebounceTime;
 
   bool _touched;
@@ -50,6 +59,12 @@ abstract class AbstractControl<T> {
   AbstractControl({
     List<Validator<dynamic>> validators = const [],
     List<AsyncValidator<dynamic>> asyncValidators = const [],
+    @Deprecated(
+      "Use [Validators.debounced] to specify a debounce time for individual asynchronous validators.",
+    )
+    /// **DEPRECATED**: Use [Validators.debounced] to specify a debounce time for
+    /// individual asynchronous validators. This property will be removed in a
+    /// future major version.
     int asyncValidatorsDebounceTime = 250,
     bool disabled = false,
     bool touched = false,
@@ -699,32 +714,54 @@ abstract class AbstractControl<T> {
       return;
     }
 
-    _status = ControlStatus.pending;
+    markAsPending(emitEvent: true);
+
+    final debouncedValidators = _asyncValidators
+        .whereType<DebouncedAsyncValidator>()
+        .map((v) => v.validate(this));
+
+    final regularValidators = _asyncValidators.where(
+      (v) => v is! DebouncedAsyncValidator,
+    );
+
+    final allValidators = <Future<Map<String, dynamic>?>>[];
+    allValidators.addAll(debouncedValidators);
 
     _debounceTimer?.cancel();
 
-    _debounceTimer = Timer(
-      Duration(milliseconds: _asyncValidatorsDebounceTime),
-      () {
-        final validatorsStream = Stream.fromFutures(
-          asyncValidators.map((validator) => validator.validate(this)).toList(),
-        );
+    if (regularValidators.isNotEmpty) {
+      final completer = Completer<List<Map<String, dynamic>?>>();
+      _debounceTimer = Timer(
+        Duration(milliseconds: _asyncValidatorsDebounceTime),
+        () => completer.complete(
+          Future.wait(regularValidators.map((v) => v.validate(this))),
+        ),
+      );
+      allValidators.add(
+        completer.future.then(
+          (errors) => errors.fold<Map<String, dynamic>>(
+            {},
+            (previousValue, element) => previousValue..addAll(element ?? {}),
+          ),
+        ),
+      );
+    }
 
-        final asyncValidationErrors = <String, dynamic>{};
-        _asyncValidationSubscription = validatorsStream.listen(
-          (Map<String, dynamic>? error) {
-            if (error != null) {
-              asyncValidationErrors.addAll(error);
-            }
-          },
-          onDone: () {
-            final allErrors = <String, dynamic>{};
-            allErrors.addAll(errors);
-            allErrors.addAll(asyncValidationErrors);
-
-            setErrors(allErrors, markAsDirty: false);
-          },
-        );
+    final validatorsStream = Stream.fromFutures(allValidators);
+
+    final asyncValidationErrors = <String, dynamic>{};
+    _asyncValidationSubscription = validatorsStream.listen(
+      (Map<String, dynamic>? error) {
+        if (error != null) {
+          asyncValidationErrors.addAll(error);
+        }
+      },
+      onDone: () {
+        final allErrors = <String, dynamic>{};
+        allErrors.addAll(errors);
+        allErrors.addAll(asyncValidationErrors);
+
+        setErrors(allErrors, markAsDirty: false);
       },
     );
   }
@@ -842,6 +879,12 @@ class FormControl<T> extends AbstractControl<T> {
     T? value,
     super.validators,
     super.asyncValidators,
+    @Deprecated(
+      "Use [Validators.debounced] to specify a debounce time for individual asynchronous validators.",
+    )
+    /// **DEPRECATED**: Use [Validators.debounced] to specify a debounce time for
+    /// individual asynchronous validators. This property will be removed in a
+    /// future major version.
     super.asyncValidatorsDebounceTime,
     super.touched,
     super.disabled,

lib/src/models/models.dart

@@ -0,0 +1,62 @@
+// Copyright 2020 Joan Pablo Jimenez Milian. All rights reserved.
+// Use of this source code is governed by the MIT license that can be
+// found in the LICENSE file.
+
+import 'dart:async';
+
+import 'package:reactive_forms/reactive_forms.dart';
+
+/// Delays the execution of an [AsyncValidator] by a specified duration.
+///
+/// This validator is useful for scenarios where you want to delay validation
+/// until the user has stopped typing for a certain period. It helps to
+/// avoid excessive validation requests, for example, when validating a
+/// username for availability against a remote server.
+///
+/// The [DebouncedAsyncValidator] should be used when you need to specify a
+/// custom debounce time for a single validator. If you want to apply the same
+/// debounce time to all asynchronous validators of a form control, it is
+/// more convenient to use the [FormControl.asyncValidatorsDebounceTime]
+/// property.
+///
+/// ## Example:
+///
+/// ```dart
+/// final control = FormControl<String>(
+///   asyncValidators: [
+///     DebouncedAsyncValidator(
+///       Validators.delegateAsync((control) async {
+///         // Your validation logic here
+///         return null;
+///       }),
+///       500, // Debounce time in milliseconds
+///     ),
+///   ],
+/// );
+/// ```
+///
+/// In this example, the validation will only be triggered after the user has
+/// stopped typing for 500 milliseconds.
+class DebouncedAsyncValidator extends AsyncValidator<dynamic> {
+  final AsyncValidator<dynamic> _validator;
+  final int _debounceTime;
+  Timer? _debounceTimer;
+
+  /// Creates a new instance of the [DebouncedAsyncValidator] class.
+  ///
+  /// The [validator] is the async validator to be debounced.
+  /// The [debounceTime] is the duration in milliseconds to wait before
+  /// validating the control.
+  DebouncedAsyncValidator(this._validator, this._debounceTime)
+    : assert(_debounceTime >= 0);
+
+  @override
+  Future<Map<String, dynamic>?> validate(AbstractControl<dynamic> control) {
+    final completer = Completer<Map<String, dynamic>?>();
+    _debounceTimer?.cancel();
+    _debounceTimer = Timer(Duration(milliseconds: _debounceTime), () {
+      completer.complete(_validator.validate(control));
+    });
+    return completer.future;
+  }
+}

lib/src/validators/debounced_async_validator.dart

@@ -0,0 +1,54 @@
+// Copyright 2020 Joan Pablo Jimenez Milian. All rights reserved.
+// Use of this source code is governed by the MIT license that can be
+// found in the LICENSE file.
+
+import 'package:reactive_forms/reactive_forms.dart';
+
+/// Represents a validator that requires the control's value to be one of
+/// the values in the provided [collection].
+///
+/// For [String] values, the comparison can be made case-sensitive or insensitive
+/// using the [caseSensitive] parameter. For other types, this parameter is ignored.
+class OneOfValidator extends Validator<dynamic> {
+  final List<dynamic> collection;
+  final bool caseSensitive;
+
+  /// Constructs an instance of [OneOfValidator].
+  ///
+  /// The [collection] parameter is the list of allowed values.
+  /// The [caseSensitive] parameter determines if string comparison
+  /// should be case-sensitive. Defaults to true.
+  OneOfValidator(this.collection, {this.caseSensitive = true});
+
+  @override
+  Map<String, dynamic>? validate(AbstractControl<dynamic> control) {
+    final value = control.value;
+    var found = false;
+
+    for (final item in collection) {
+      if (value is String && item is String && !caseSensitive) {
+        if (item.toLowerCase() == value.toLowerCase()) {
+          found = true;
+          break;
+        }
+      } else {
+        if (item == value) {
+          found = true;
+          break;
+        }
+      }
+    }
+
+    if (found) {
+      return null; // Valid
+    } else {
+      return {
+        ValidationMessage.oneOf: {
+          'requiredOneOf': collection,
+          'actual': value,
+          if (value is String) 'caseSensitive': caseSensitive,
+        },
+      };
+    }
+  }
+}

lib/src/validators/one_of_validator.dart

@@ -59,6 +59,9 @@ class ValidationMessage {
   /// Key text for `contains` validation message.
   static const String contains = 'contains';
 
+  /// Key text for `oneOf` validation message.
+  static const String oneOf = 'oneOf';
+
   /// Key text for `any` validation message.
   static const String any = 'any';
 }