0
# ngx-validators
1

2
Angular form validators library providing comprehensive validation rules for Angular 13+ applications. Supports both reactive forms (model-driven) and template-driven forms through validator functions and directives, with specialized validators for passwords, emails, universal constraints, and credit cards.
3

4
## Package Information
5

6
- **Package Name**: ngx-validators
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install ngx-validators`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  PasswordValidators, 
16
  EmailValidators, 
17
  UniversalValidators, 
18
  CreditCardValidators,
19
  EqualToValidator,
20
  ValidatorsModule 
21
} from "ngx-validators";
22
```
23

24
For Angular module setup:
25

26
```typescript
27
import { ValidatorsModule } from "ngx-validators";
28

29
@NgModule({
30
  imports: [ValidatorsModule],
31
  // ...
32
})
33
export class AppModule {}
34
```
35

36
## Basic Usage
37

38
### Reactive Forms (Model-Driven)
39

40
```typescript
41
import { FormBuilder, FormGroup } from "@angular/forms";
42
import { PasswordValidators, EmailValidators } from "ngx-validators";
43

44
export class MyComponent {
45
  myForm: FormGroup;
46

47
  constructor(private fb: FormBuilder) {
48
    this.myForm = this.fb.group({
49
      email: ['', [EmailValidators.normal]],
50
      password: ['', [
51
        PasswordValidators.digitCharacterRule(1),
52
        PasswordValidators.lowercaseCharacterRule(1),
53
        PasswordValidators.uppercaseCharacterRule(1)
54
      ]],
55
      confirmPassword: [''],
56
      age: ['', [UniversalValidators.isNumber, UniversalValidators.min(18)]]
57
    }, {
58
      validators: [PasswordValidators.mismatchedPasswords('password', 'confirmPassword')]
59
    });
60
  }
61
}
62
```
63

64
### Template-Driven Forms
65

66
```html
67
<form>
68
  <input 
69
    name="email" 
70
    [(ngModel)]="user.email" 
71
    #email="ngModel"
72
    emailValidator>
73
  
74
  <input 
75
    name="password" 
76
    [(ngModel)]="user.password" 
77
    #password="ngModel"
78
    [password]="true"
79
    [digitCharacter]="1"
80
    [lowercaseCharacter]="1"
81
    [uppercaseCharacter]="1">
82
    
83
  <input 
84
    name="age" 
85
    [(ngModel)]="user.age" 
86
    #age="ngModel"
87
    isNumber
88
    [min]="18">
89
</form>
90
```
91

92
## Architecture
93

94
ngx-validators is built around several key components:
95

96
- **Validator Classes**: Static methods returning Angular ValidatorFn functions for reactive forms
97
- **Validator Directives**: Angular directives implementing the Validator interface for template-driven forms
98
- **ValidatorsModule**: Angular module that declares and exports all validator directives
99
- **Utility Classes**: Helper classes for control manipulation and email suggestions
100
- **Type Definitions**: Complete TypeScript interfaces for configuration options
101

102
## Capabilities
103

104
### Password Validation
105

106
Comprehensive password strength validation including character requirements, repetition limits, and confirmation matching.
107

108
```typescript { .api }
109
class PasswordValidators {
110
  static repeatCharacterRegexRule(repeatCount: number): ValidatorFn;
111
  static alphabeticalCharacterRule(amount: number): ValidatorFn;
112
  static digitCharacterRule(amount: number): ValidatorFn;
113
  static lowercaseCharacterRule(amount: number): ValidatorFn;
114
  static uppercaseCharacterRule(amount: number): ValidatorFn;
115
  static specialCharacterRule(amount: number): ValidatorFn;
116
  static allowedCharacterRule(allowedChars: string[]): ValidatorFn;
117
  static mismatchedPasswords(passwordControlName?: string, confirmPasswordControlName?: string): ValidatorFn;
118
}
119
```
120

121
[Password Validation](./password-validation.md)
122

123
### Email Validation
124

125
Email validation with HTML5 compliance and intelligent typo suggestion features for common email domains.
126

127
```typescript { .api }
128
class EmailValidators {
129
  static simple(control: AbstractControl): ValidationErrors | null;
130
  static normal(control: AbstractControl): ValidationErrors | null;
131
  static suggest(options?: EmailOptions): ValidatorFn;
132
}
133
```
134

135
[Email Validation](./email-validation.md)
136

137
### Universal Validation
138

139
Common data validation rules for whitespace, numeric ranges, string lengths, dates, and data types.
140

141
```typescript { .api }
142
class UniversalValidators {
143
  static noWhitespace(control: AbstractControl): ValidationErrors | null;
144
  static noEmptyString(control: AbstractControl): ValidationErrors | null;
145
  static isNumber(control: AbstractControl): ValidationErrors | null;
146
  static isInRange(minValue: number, maxValue: number): ValidatorFn;
147
  static minLength(minLength: number): ValidatorFn;
148
  static maxLength(maxLength: number): ValidatorFn;
149
  static min(min: number): ValidatorFn;
150
  static max(max: number): ValidatorFn;
151
  static minDate(minDate: Date): ValidatorFn;
152
  static maxDate(minDate: Date): ValidatorFn;
153
  static type(type: "number" | "string" | "object" | "boolean"): ValidatorFn;
154
}
155
```
156

157
[Universal Validation](./universal-validation.md)
158

159
### Credit Card Validation
160

161
Credit card format validation for major card types including Visa, MasterCard, American Express, and more.
162

163
```typescript { .api }
164
class CreditCardValidators {
165
  static isCreditCard(control: AbstractControl): ValidationErrors | null;
166
  static americanExpress(control: AbstractControl): ValidationErrors | null;
167
  static dinersclub(control: AbstractControl): ValidationErrors | null;
168
  static discover(control: AbstractControl): ValidationErrors | null;
169
  static jcb(control: AbstractControl): ValidationErrors | null;
170
  static maestro(control: AbstractControl): ValidationErrors | null;
171
  static mastercard(control: AbstractControl): ValidationErrors | null;
172
  static visa(control: AbstractControl): ValidationErrors | null;
173
}
174
```
175

176
[Credit Card Validation](./credit-card-validation.md)
177

178
### Template-Driven Forms Support
179

180
Angular directives for using validators in template-driven forms with two-way data binding support.
181

182
```typescript { .api }
183
@NgModule({
184
  declarations: [/* all validator directives */],
185
  exports: [/* all validator directives */]
186
})
187
export class ValidatorsModule {}
188
```
189

190
[Template-Driven Forms](./template-driven-forms.md)
191

192
### Form Control Utilities
193

194
Utility functions for form control manipulation and validation state management.
195

196
```typescript { .api }
197
class AbstractControlUtil {
198
  static isNotPresent(control: AbstractControl): boolean;
199
  static addError(control: AbstractControl | null, errorId: string, value: any): void;
200
  static removeError(control: AbstractControl | null, errorId: string): void;
201
}
202

203
class EqualToValidator {
204
  static equalTo(c1Name: string, c2Name: string): ValidatorFn;
205
}
206
```
207

208
[Form Control Utilities](./form-control-utilities.md)
209

210
## Email Utility Classes
211

212
Complete email processing utilities including suggestion algorithms and email parsing.
213

214
```typescript { .api }
215
interface EmailOptions {
216
  domains: string[];
217
  secondLevelDomains: string[];
218
  topLevelDomains: string[];
219
}
220

221
interface SplittedEmail {
222
  topLevelDomain: string;
223
  secondLevelDomain: string;
224
  domain: string;
225
  address: string;
226
}
227

228
interface Suggestion {
229
  address: string;
230
  domain: string;
231
  full: string;
232
}
233

234
class EmailSuggestion {
235
  suggest(email: string, options?: EmailOptions): { [key: string]: Suggestion } | null;
236
  splitEmail(email: string): SplittedEmail | null;
237
}
238
```
239

240
## Types
241

242
```typescript { .api }
243
// Angular Forms types (external dependency)
244
interface AbstractControl {
245
  value: any;
246
  errors: ValidationErrors | null;
247
  // ... other Angular AbstractControl properties
248
}
249

250
interface ValidationErrors {
251
  [key: string]: any;
252
}
253

254
interface ValidatorFn {
255
  (control: AbstractControl): ValidationErrors | null;
256
}
257

258
// Email validation types
259
interface EmailOptions {
260
  domains: string[];
261
  secondLevelDomains: string[];
262
  topLevelDomains: string[];
263
}
264

265
interface Suggestion {
266
  address: string;
267
  domain: string;
268
  full: string;
269
}
270

271
interface SplittedEmail {
272
  topLevelDomain: string;
273
  secondLevelDomain: string;
274
  domain: string;
275
  address: string;
276
}
277
```