🧠 MayrValidations #

MayrValidations is a powerful yet elegant validation library for Dart and Flutter, inspired by Laravel’s validator syntax and philosophy. It provides a fluent API to build validations that are expressive, chainable, and extensible, without compromising flexibility.

✨ Features #

• 🧩 Fluent API — Chain validation rules like Laravel.
• ⚙️ Global Configuration — Define global defaults and messages.
• 🔁 Reusable Groups — Register and reuse complex validation patterns.
• 🧱 Custom Validators — Extend the system with your own validation logic.
• ⚡ Debounce Support — Control when validations run (useful for live input validation).
• 🧍‍♂️ Standalone or Flutter-ready — Works in plain Dart and integrates perfectly with TextFormField in Flutter.

🚀 Installation #

Add to your project:

dart pub add mayr_validations

Or in pubspec.yaml:

dependencies:
  mayr_validations: ^1.0.0

🧩 Quick Start #

🧠 Basic Usage in Dart #

import 'package:mayr_validator/mayr_validator.dart';

void main() {
  // Basic validation
  final error = MayrValidator('test@example.com')
      .required()
      .email()
      .run();
  
  print(error); // null if valid, error message if invalid
}

📱 Flutter TextFormField Integration #

import 'package:flutter/material.dart';
import 'package:mayr_validator/mayr_validator.dart';

TextFormField(
  decoration: InputDecoration(labelText: 'Email'),
  validator: (value) => value.mayrValidator()
      .required()
      .email()
      .max(100)
      .run(),
)

💡 More Flutter Examples #

Registration Form

class RegistrationForm extends StatefulWidget {
  @override
  _RegistrationFormState createState() => _RegistrationFormState();
}

class _RegistrationFormState extends State<RegistrationForm> {
  final _formKey = GlobalKey<FormState>();
  final _passwordController = TextEditingController();

  @override
  void initState() {
    super.initState();
    
    // Configure global validation messages
    MayrValidationCore().setup({
      'messages': {
        'required': 'This field is required',
        'min': 'Must be at least {min} characters',
        'email': 'Please enter a valid email address',
      },
    });
  }

  @override
  Widget build(BuildContext context) {
    return Form(
      key: _formKey,
      child: Column(
        children: [
          // Email field
          TextFormField(
            decoration: InputDecoration(labelText: 'Email'),
            validator: (value) => value.mayrValidator()
                .required()
                .email()
                .run(),
          ),
          
          // Password field
          TextFormField(
            controller: _passwordController,
            decoration: InputDecoration(labelText: 'Password'),
            obscureText: true,
            validator: (value) => value.mayrValidator()
                .required()
                .min(8)
                .regex(r'(?=.*[A-Z])(?=.*[a-z])(?=.*[0-9])')
                .run(),
          ),
          
          // Confirm password field
          TextFormField(
            decoration: InputDecoration(labelText: 'Confirm Password'),
            obscureText: true,
            validator: (value) => value.mayrValidator()
                .required()
                .same(_passwordController.text, 'Passwords must match')
                .run(),
          ),
          
          // Submit button
          ElevatedButton(
            onPressed: () {
              if (_formKey.currentState!.validate()) {
                // Form is valid
                print('Form submitted!');
              }
            },
            child: Text('Register'),
          ),
        ],
      ),
    );
  }
}

⚙️ Global Configuration #

Configure MayrValidations globally to set default messages and parameters.

void main() {
  // Setup global configuration
  MayrValidationCore().setup({
    'messages': {
      'required': 'This field is required',
      'min': 'Must be at least {min} characters',
      'max': 'Must not exceed {max} characters',
      'email': 'Please enter a valid email address',
    },
    'defaults': {
      'min': 3,
      'max': 255,
    },
  });
  
  runApp(MyApp());
}

Message Placeholders #

Use placeholders in your messages that will be replaced with actual values:

⚡ Running with Debounce #

validator: (value) => MayrValidator(value)
    .required()
    .email()
    .run(debounce: Duration(milliseconds: 300));

If no debounce is passed, it defaults to Duration.zero.

🧱 Custom Validations #

Register custom validation rules to extend the validation system with your own logic.

void main() {
  // Register a custom rule
  MayrValidationCore().registerRule('userId', (value, params) {
    if (value == null || value.isEmpty) {
      return 'User ID is required';
    }
    if (!value.startsWith('USR_')) {
      return 'User ID must start with USR_';
    }
    if (!RegExp(r'^USR_[A-Z0-9]+$').hasMatch(value)) {
      return 'Invalid user ID format';
    }
    return null; // null means valid
  });
}

Then use it in your validators:

// In a TextFormField
TextFormField(
  decoration: InputDecoration(labelText: 'User ID'),
  validator: (value) => value.mayrValidator()
      .required()
      .custom('userId')
      .run(),
)

Environment-Aware Behavior #

Custom rules behave differently based on the environment:

• Development Mode: Throws an exception if a custom rule is not registered
• Production Mode: Silently ignores unregistered custom rules

🧩 Validator Groups #

Validator groups allow you to register reusable validation patterns for repeated logic.

void main() {
  // Register a group for username validation
  MayrValidationCore().registerGroup('username', (validator, params) {
    return validator
        .required()
        .min(3)
        .max(20)
        .alphaDash();
  });
  
  // Register a group for strong password validation
  MayrValidationCore().registerGroup('strongPassword', (validator, params) {
    return validator
        .required()
        .min(8)
        .regex(r'(?=.*[A-Z])(?=.*[a-z])(?=.*[0-9])');
  });
}

Use the group in your validators:

// In a TextFormField
TextFormField(
  decoration: InputDecoration(labelText: 'Username'),
  validator: (value) => value.mayrValidator()
      .group('username')
      .run(),
)

TextFormField(
  decoration: InputDecoration(labelText: 'Password'),
  obscureText: true,
  validator: (value) => value.mayrValidator()
      .group('strongPassword')
      .run(),
)

Benefits of Groups #

• ✅ Reusable: Define once, use everywhere
• ✅ Maintainable: Update validation logic in one place
• ✅ Consistent: Ensure same validation rules across your app
• ✅ Clean Code: Keep your validators concise and readable

🧰 Built-in Validation Helpers #

MayrValidations ships with a comprehensive set of validation rules inspired by Laravel’s Validator, neatly grouped by type. Each rule can be chained fluently and combined with custom logic to fit your needs.

🟩 Booleans #

🧵 Strings #

🔢 Numbers #

📦 Arrays #

📅 Dates #

🖼️ Files #

🧰 Utilities #

�� Design Overview #

MayrValidations follows a clean architecture with separation of concerns:

• MayrValidationCore → Singleton core managing global setup, messages, defaults, custom rules, and validation groups
• MayrValidator → Instance-level builder handling chained validation logic for a single value
• Extension mayrValidator() → Enables the elegant value.mayrValidator() syntax

Architecture Flow #

1. Setup → Configure global messages and defaults via MayrValidationCore().setup()
2. Register → Register custom rules and groups via registerRule() and registerGroup()
3. Validate → Chain validation rules and call .run() to execute
4. Result → Returns null if valid, or an error message string if invalid

🧪 Example in Pure Dart #

void main() {
  final validator = MayrValidator('HelloWorld')
      .required()
      .min(3)
      .max(12)
      .run();

  print(validator); // null if valid, else error message
}

📢 Additional Information #

🤝 Contributing #

Contributions are highly welcome! If you have ideas for new extensions, improvements, or fixes, feel free to fork the repository and submit a pull request.

Please make sure to:

• Follow the existing coding style.
• Write tests for new features.
• Update documentation if necessary.

Let's build something amazing together!

🐛 Reporting Issues #

If you encounter a bug, unexpected behaviour, or have feature requests:

• Open an issue on the repository.
• Provide a clear description and steps to reproduce (if it's a bug).
• Suggest improvements if you have any ideas.

Your feedback helps make the package better for everyone!

🧑‍💻 Author #

MayR Labs

Crafting clean, reliable, and human-centric Flutter and Dart solutions. 🌍 mayrlabs.com

📜 Licence #

This package is licensed under the MIT License — which means you are free to use it for commercial and non-commercial projects, with proper attribution.

See the LICENSE file for more details.

MIT © 2025 MayR Labs

🌟 Support #

If you find this package helpful, please consider giving it a ⭐️ on GitHub — it motivates and helps the project grow!

You can also support by:

• Sharing the package with your friends, colleagues, and tech communities.
• Using it in your projects and giving feedback.
• Contributing new ideas, features, or improvements.

Every little bit of support counts! 🚀💙