Tawfir.Toolkit 1.0.3

Tawfir.Toolkit

A comprehensive .NET utilities library containing validation attributes and helper classes for common operations including encryption, calculations, random generation, and validation (KSA ID, Email, etc.).

Installation

dotnet add package Tawfir.Toolkit

Features

• Validation Attributes: KSA ID, Saudi National ID, Non-Saudi Iqama, Email, Arabic Text, and English Text validation attributes
• Static Validators: Programmatic validation methods for all validation types
• Multilingual Text Validation: Comprehensive support for Arabic and English text validation with flexible options
• Helper Classes: Encryption, financial calculations, card expressions, and random generation
• Regex Patterns: Pre-defined regex patterns for common validations including enhanced Arabic and English patterns

Validation Attributes

KsaId

Use as a validation attribute for any KSA ID (Saudi or Non-Saudi):

using Tawfir.Toolkit.Validator;
using System.ComponentModel.DataAnnotations;

public class UserModel
{
    [KsaId(ErrorMessage = "Invalid KSA ID")]
    public string KsaIdNumber { get; set; }
    
    // Or use with Required attribute
    [Required]
    [KsaId(ErrorMessage = "KSA ID is required and must be valid")]
    public string NationalId { get; set; }
}

The attribute validates:

• 10-digit format
• Correct prefix (1 for Saudi, 2 for Non-Saudi)
• Checksum algorithm validity

SaudiNationalId

Use specifically for Saudi National Id numbers (must start with 1):

using Tawfir.Toolkit.Validator;
using System.ComponentModel.DataAnnotations;

public class SaudiUserModel
{
    [SaudiNationalId(ErrorMessage = "Invalid Saudi National Id")]
    public string SaudiNationalIdNumber { get; set; }
    
    // Or use with Required attribute
    [Required(ErrorMessage = "Saudi National Id is required")]
    [SaudiNationalId(ErrorMessage = "Must be a valid Saudi National Id starting with 1")]
    public string NationalId { get; set; }
}

The SaudiNationalId attribute validates:

• All standard Civil ID validations (format, checksum)
• Additional check: Must start with digit 1 (Saudi nationals only)

NonSaudiIqama

Use specifically for Non-Saudi Iqama numbers (must start with 2):

using Tawfir.Toolkit.Validator;
using System.ComponentModel.DataAnnotations;

public class NonSaudiUserModel
{
    [NonSaudiIqama(ErrorMessage = "Invalid Non-Saudi Iqama")]
    public string IqamaNumber { get; set; }
    
    // Or use with Required attribute
    [Required(ErrorMessage = "Non-Saudi Iqama is required")]
    [NonSaudiIqama(ErrorMessage = "Must be a valid Non-Saudi Iqama starting with 2")]
    public string IqamaId { get; set; }
}

The NonSaudiIqama attribute validates:

• All standard Civil ID validations (format, checksum)
• Additional check: Must start with digit 2 (Non-Saudi nationals only)

Email

Use for email address validation:

using Tawfir.Toolkit.Validator;
using System.ComponentModel.DataAnnotations;

public class UserModel
{
    [Email(ErrorMessage = "Invalid email address")]
    public string EmailAddress { get; set; }
    
    // Or use with Required attribute
    [Required(ErrorMessage = "Email is required")]
    [Email(ErrorMessage = "Must be a valid email address")]
    public string ContactEmail { get; set; }
}

The Email attribute validates:

• Valid email format using regex pattern
• Standard email format requirements

TextArabic

Use for Arabic text validation with comprehensive Unicode support:

using Tawfir.Toolkit.Validator;
using System.ComponentModel.DataAnnotations;

public class ContentModel
{
    // Basic Arabic text validation
    [TextArabic(ErrorMessage = "يجب أن يكون النص بالعربية فقط")]
    public string Description { get; set; }
    
    // Arabic name validation (letters only, no numbers)
    [TextArabic(NameOnly = true, ErrorMessage = "الاسم يجب أن يكون بالأحرف العربية فقط")]
    public string Name { get; set; }
    
    // Arabic text with diacritics (Tashkeel)
    [TextArabic(AllowDiacritics = true)]
    public string TextWithTashkeel { get; set; }
    
    // Arabic text with Arabic numerals
    [TextArabic(AllowArabicNumerals = true)]
    public string AddressWithNumbers { get; set; }
    
    // Combined with Required
    [Required]
    [TextArabic(NameOnly = true)]
    public string FullName { get; set; }
}

The TextArabic attribute validates:

• Full Unicode Arabic character support (U+0600-U+06FF and extended ranges)
• Arabic Supplement, Extended-A, and Presentation Forms
• Optional diacritics (Tashkeel) support
• Optional name-only validation (letters only, no numbers)
• Optional Arabic numerals support (٠-٩, ۰-۹)

Supported Unicode Ranges:

• Arabic (U+0600-U+06FF)
• Arabic Supplement (U+0750-U+077F)
• Arabic Extended-A (U+08A0-U+08FF)
• Arabic Presentation Forms-A (U+FB50-U+FDFF)
• Arabic Presentation Forms-B (U+FE70-U+FEFF)
• Arabic Diacritics (U+064B-U+065F)

TextEnglish

Use for English text validation with various options:

using Tawfir.Toolkit.Validator;
using System.ComponentModel.DataAnnotations;

public class ContentModel
{
    // Basic English text validation (letters only)
    [TextEnglish(ErrorMessage = "Text must be in English only")]
    public string Description { get; set; }
    
    // English name validation (letters and hyphens)
    [TextEnglish(NameOnly = true, ErrorMessage = "Name must contain only English letters")]
    public string FullName { get; set; }
    
    // English text with punctuation
    [TextEnglish(AllowPunctuation = true)]
    public string Comment { get; set; }
    
    // English text with numbers
    [TextEnglish(AllowNumbers = true)]
    public string AddressLine { get; set; }
    
    // Combined with Required
    [Required]
    [TextEnglish(NameOnly = true)]
    public string FirstName { get; set; }
}

The TextEnglish attribute validates:

• English letters only (A-Z, a-z) by default
• Optional name validation (allows hyphens for names like "Mary-Jane")
• Optional punctuation support (.,!?;:'-)
• Optional alphanumeric support (letters + numbers)

Note: All attributes allow null/empty values by default. Use [Required] if the field is mandatory.

Static Validator Methods

You can also validate programmatically:

using Tawfir.Toolkit.Validator;

// Validate any Civil ID (Saudi or Non-Saudi)
bool isValid = KsaIdValidator.IsValid("1234567890");

// Validate specifically for Saudi National Id (must start with 1)
bool isSaudiValid = KsaSaudiNationalIdValidator.IsValid("1234567890");

// Validate specifically for Non-Saudi Iqama (must start with 2)
bool isNonSaudiValid = KsaNonSaudiIqamaValidator.IsValid("2234567890");

// Validate email address
bool isValidEmail = EmailValidator.IsValid("user@example.com");

// Validate Arabic text
bool isArabicValid = TextArabicValidator.IsValid("مرحبا بك");

// Validate Arabic text with diacritics
bool isArabicWithDiacritics = TextArabicValidator.IsValidWithDiacritics("مَرْحَباً");

// Validate Arabic name (letters only)
bool isArabicName = TextArabicValidator.IsValidName("محمد أحمد");

// Validate Arabic text with Arabic numerals
bool isArabicWithNumerals = TextArabicValidator.IsValidWithArabicNumerals("الشارع ١٢");

// Validate English text
bool isEnglishValid = TextEnglishValidator.IsValid("Hello World");

// Validate English text with punctuation
bool isEnglishWithPunctuation = TextEnglishValidator.IsValidWithPunctuation("Hello, World!");

// Validate English name (with hyphens)
bool isEnglishName = TextEnglishValidator.IsValidName("Mary-Jane Smith");

// Validate English alphanumeric text
bool isEnglishAlphanumeric = TextEnglishValidator.IsValidAlphanumeric("Street 123");

Helper Classes

EncryptionHelper

Encrypt and decrypt strings:

using Tawfir.Toolkit.Helpers;

var encrypted = EncryptionHelper.Encrypt("sensitive data");
var decrypted = EncryptionHelper.Decrypt(encrypted);

CardExpression

Card number processing:

using Tawfir.Toolkit.Helpers;

string issuerCardRefId = CardExpression.GetIssuerCardRefId(cardNo, expiryDate);
string cardNumber = CardExpression.GetCardNumber(issuerCardRefId);

APRCalculationHelper

Financial calculations for APR (Annual Percentage Rate):

using Tawfir.Toolkit.Helpers;

double apr = APRCalculationHelper.GetAPRValueBaseeta(amount, tenure, rate, date);
double pmt = APRCalculationHelper.GetPMTCompound(pv, per, r);
double pmtFlat = APRCalculationHelper.GetPMTFlat(pv, pa, per, r);

RandomGen

Generate random strings and numbers:

using Tawfir.Toolkit.Helpers;

string randomString = RandomGen.String(length: 10);
string numbersOnly = RandomGen.String(length: 6, NumbersOnly: true);
int randomInt = RandomGen.INT(from: 1, to: 100);

Regex Patterns (RegexExp)

Pre-defined regex patterns for common validations:

using Tawfir.Toolkit.Models;
using System.Text.RegularExpressions;

// Civil ID patterns
Regex.IsMatch(id, RegexExp.Saudi);        // Saudi National ID (starts with 1)
Regex.IsMatch(id, RegexExp.NonSaudi);     // Non-Saudi Iqama (starts with 2)
Regex.IsMatch(id, RegexExp.CivilId);      // Any Civil ID (starts with 1 or 2)

// Financial patterns
Regex.IsMatch(iban, RegexExp.IBAN);       // Saudi IBAN format

// Contact patterns
Regex.IsMatch(mobile, RegexExp.Mobile);   // Saudi mobile (05XXXXXXXX)
Regex.IsMatch(phone, RegexExp.Phone);     // Saudi phone (01XXXXXXXX)

// Security patterns
Regex.IsMatch(password, RegexExp.Password);  // Strong password
Regex.IsMatch(pin, RegexExp.PIN);            // 6-character PIN
Regex.IsMatch(pin, RegexExp.PINCC);          // 4-character PIN
Regex.IsMatch(otp, RegexExp.OTP);            // OTP code

// Date patterns
Regex.IsMatch(date, RegexExp.Date_G);     // Gregorian date (DD/MM/YYYY)
Regex.IsMatch(date, RegexExp.Date_H);    // Hijri date (DD/MM/YYYY)

// Text patterns
Regex.IsMatch(text, RegexExp.Alphabetical);     // Alphabetical with Arabic support
Regex.IsMatch(text, RegexExp.Alphabetical_En);   // English only
Regex.IsMatch(text, RegexExp.Alphabetical_AR);   // Arabic with numbers (basic)

// Enhanced Arabic patterns
Regex.IsMatch(text, RegexExp.Arabic_Only);              // Full Arabic Unicode support
Regex.IsMatch(text, RegexExp.Arabic_Letters_Only);      // Arabic letters + Arabic numerals
Regex.IsMatch(text, RegexExp.Arabic_With_Diacritics);   // Arabic with Tashkeel marks
Regex.IsMatch(text, RegexExp.Arabic_Name);              // Arabic names (letters only)

// Enhanced English patterns
Regex.IsMatch(text, RegexExp.English_Only);             // English letters only
Regex.IsMatch(text, RegexExp.English_Letters_Only);     // English letters + numbers
Regex.IsMatch(text, RegexExp.English_With_Punctuation); // English with punctuation
Regex.IsMatch(text, RegexExp.English_Name);             // English names (letters + hyphens)

Arabic Text Validation - Detailed Guide

The toolkit provides comprehensive Arabic text validation with multiple options:

Available Patterns

Usage Examples

using Tawfir.Toolkit.Validator;

// Validate general Arabic text
var text1 = "مرحبا بك في السعودية";
var isValid1 = TextArabicValidator.IsValid(text1); // true

// Validate Arabic name (no numbers allowed)
var name = "محمد أحمد";
var isValidName = TextArabicValidator.IsValidName(name); // true

// Validate text with Arabic numerals
var address = "الشارع ١٢ حي النخيل";
var isValidAddr = TextArabicValidator.IsValidWithArabicNumerals(address); // true

// Validate text with diacritics
var quranicText = "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ";
var isValidQuran = TextArabicValidator.IsValidWithDiacritics(quranicText); // true

Common Use Cases

1. User Names (Arabic only)

[TextArabic(NameOnly = true)]
public string FullName { get; set; }

2. Addresses (Arabic with numbers)

[TextArabic(AllowArabicNumerals = true)]
public string Address { get; set; }

3. Religious or Formal Text (with diacritics)

[TextArabic(AllowDiacritics = true)]
public string FormalText { get; set; }

4. General Arabic Content

[TextArabic]
public string Description { get; set; }

English Text Validation - Detailed Guide

The toolkit provides comprehensive English text validation with multiple options:

Available Patterns

Usage Examples

using Tawfir.Toolkit.Validator;

// Validate general English text
var text1 = "Hello World";
var isValid1 = TextEnglishValidator.IsValid(text1); // true

// Validate English name with hyphen
var name = "Mary-Jane Smith";
var isValidName = TextEnglishValidator.IsValidName(name); // true

// Validate text with alphanumeric
var address = "Street 123 Building A";
var isValidAddr = TextEnglishValidator.IsValidAlphanumeric(address); // true

// Validate text with punctuation
var sentence = "Hello, World! How are you?";
var isValidSentence = TextEnglishValidator.IsValidWithPunctuation(sentence); // true

Common Use Cases

1. User Names (English only)

[TextEnglish(NameOnly = true)]
public string FullName { get; set; }

2. Addresses (English with numbers)

[TextEnglish(AllowNumbers = true)]
public string Address { get; set; }

3. Comments and Reviews (with punctuation)

[TextEnglish(AllowPunctuation = true)]
public string Comment { get; set; }

4. General English Content

[TextEnglish]
public string Description { get; set; }

Namespaces

• Tawfir.Toolkit.Validator - Validation attributes and static validators
• Tawfir.Toolkit.Helpers - Helper classes for common operations
• Tawfir.Toolkit.Models - Models and constants (e.g., RegexExp)

Requirements

• .NET 9.0 or higher

License

MIT

Support

For support, please contact:

• Email: info@waelelazizy.com
• Phone: 00973 33030730

Author

wael EL azizy - waelelazizy.com