quantique-field-validator 2.0.0 → 2.0.1

package/README.md

@@ -0,0 +1,258 @@
+# quantique-field-validator
+
+Enterprise-grade dynamic field validator for Indian and international form fields. Written in TypeScript with full type safety, ReDoS-safe regex handling, and tree-shakeable named exports.
+
+[![npm version](https://img.shields.io/npm/v/quantique-field-validator)](https://www.npmjs.com/package/quantique-field-validator)
+[![license](https://img.shields.io/npm/l/quantique-field-validator)](LICENSE)
+
+---
+
+## Installation
+
+```bash
+npm install quantique-field-validator
+# or
+yarn add quantique-field-validator
+# or
+pnpm add quantique-field-validator
+```
+
+---
+
+## Quick Start
+
+```ts
+import dynamicValidator from 'quantique-field-validator';
+
+dynamicValidator('test@example.com', 'email');
+// { isValid: true, error: '' }
+
+dynamicValidator('', 'email', { required: true });
+// { isValid: false, error: 'This field is required' }
+```
+
+---
+
+## Usage
+
+### `dynamicValidator(value, type, rules?, customValidator?)`
+
+The single entry point that dispatches to the correct validator based on `type`.
+
+| Parameter         | Type                    | Description                                                  |
+|-------------------|-------------------------|--------------------------------------------------------------|
+| `value`           | `unknown`               | The raw input value                                          |
+| `type`            | `ValidatorType`         | Validator type key (see table below)                         |
+| `rules`           | `ValidationRules`       | Optional rules (required, minLength, regex, etc.)            |
+| `customValidator` | `CustomValidatorFn`     | Optional external validator — runs before type dispatch      |
+
+**Returns** `ValidationResult`:
+
+```ts
+{ isValid: boolean; error: string }
+```
+
+---
+
+## Supported Types
+
+| Type            | Description                                           |
+|-----------------|-------------------------------------------------------|
+| `string`        | Generic string with optional length and regex rules   |
+| `alphanumeric`  | Letters and digits (lowercase by default)             |
+| `number`        | Integer strings                                       |
+| `float`         | Decimal number strings                                |
+| `date`          | Date strings (DD/MM/YYYY by default)                  |
+| `name`          | Personal or corporate name                            |
+| `firstName`     | First name (no spaces, no digits)                     |
+| `middleName`    | Middle name (no spaces, no digits)                    |
+| `lastName`      | Last name (no spaces, no digits)                      |
+| `email`         | Standard email address                                |
+| `mobile`        | Indian mobile number (10 digits, starts with 6–9)     |
+| `address`       | Postal/street address                                 |
+| `password`      | Password with configurable strength                   |
+| `url`           | HTTP/HTTPS URL                                        |
+| `pincode`       | Indian 6-digit PIN code                               |
+| `aadhaar`       | 12-digit Aadhaar number                               |
+| `pan`           | PAN card (e.g. ABCDE1234F)                            |
+| `gst`           | GSTIN (15-character)                                  |
+| `ifsc`          | Bank IFSC code                                        |
+| `chassis`       | Vehicle chassis number (17-char VIN)                  |
+| `engine`        | Vehicle engine number                                 |
+| `rto`           | RTO vehicle registration code                         |
+| `ip`            | IPv4 or IPv6 address                                  |
+| `custom`        | Custom regex-based validator                          |
+
+---
+
+## Validation Rules
+
+All rules are optional. Pass only what you need.
+
+```ts
+interface ValidationRules {
+  required?: boolean;
+  minLength?: number;
+  maxLength?: number;
+  minValue?: number;           // number / float validators
+  maxValue?: number;           // number / float validators
+  regex?: string;              // custom regex string (compiled safely at runtime)
+  format?: string;             // date format, e.g. "DD/MM/YYYY"
+  minAge?: number;             // date: minimum age in years
+  maxAge?: number;             // date: maximum age in years
+  minPlus?: number;            // date: minimum days/months/years in the future
+  maxPlus?: number;            // date: maximum days/months/years in the future
+  minMinus?: number;           // date: minimum days/months/years in the past
+  maxMinus?: number;           // date: maximum days/months/years in the past
+  unit?: 'day'|'days'|'month'|'months'|'year'|'years';
+  decimalPrecision?: number;   // float: max decimal places
+  maxWholeDigits?: number;     // float: max digits before decimal point
+  version?: 'v4' | 'v6';      // ip: restrict to IPv4 or IPv6
+  type?: 'user' | 'corporate'; // name: sub-type
+  strength?: 'basic' | 'medium' | 'strong'; // password strength
+  errorMessages?: ErrorMessages;
+  customValidator?: (value: string) => ValidationResult | boolean;
+}
+```
+
+---
+
+## Examples
+
+### Required field
+
+```ts
+dynamicValidator('', 'email', { required: true });
+// { isValid: false, error: 'This field is required' }
+```
+
+### Length constraints
+
+```ts
+dynamicValidator('Hi', 'string', { minLength: 5 });
+// { isValid: false, error: 'Minimum 5 characters required' }
+```
+
+### Password strength
+
+```ts
+// basic — at least one letter and one digit
+dynamicValidator('hello1', 'password', { strength: 'basic' });
+// { isValid: true, error: '' }
+
+// medium — uppercase + lowercase + digit
+dynamicValidator('Hello1', 'password', { strength: 'medium' });
+// { isValid: true, error: '' }
+
+// strong — uppercase + lowercase + digit + special character
+dynamicValidator('Hello1!', 'password', { strength: 'strong' });
+// { isValid: true, error: '' }
+```
+
+### Date with age restriction
+
+```ts
+dynamicValidator('01/01/2010', 'date', { minAge: 18 });
+// { isValid: false, error: 'Must be at least 18 years old' }
+```
+
+### IP address version filter
+
+```ts
+dynamicValidator('192.168.1.1', 'ip', { version: 'v4' });
+// { isValid: true, error: '' }
+
+dynamicValidator('192.168.1.1', 'ip', { version: 'v6' });
+// { isValid: false, error: 'Invalid IP address' }
+```
+
+### Custom error messages
+
+```ts
+dynamicValidator('', 'mobile', {
+  required: true,
+  errorMessages: { required: 'Phone number is required' },
+});
+// { isValid: false, error: 'Phone number is required' }
+```
+
+### Custom regex
+
+```ts
+dynamicValidator('ABC123', 'custom', {
+  regex: '^[A-Z]{3}[0-9]{3}$',
+});
+// { isValid: true, error: '' }
+```
+
+### External custom validator
+
+```ts
+dynamicValidator('taken@example.com', 'email', {}, (value) => {
+  const takenEmails = ['taken@example.com'];
+  if (takenEmails.includes(value)) {
+    return { isValid: false, error: 'Email is already in use' };
+  }
+  return true;
+});
+// { isValid: false, error: 'Email is already in use' }
+```
+
+### Inline custom validator (via rules)
+
+```ts
+dynamicValidator('hello', 'string', {
+  customValidator: (value) => value.startsWith('hello'),
+});
+// { isValid: true, error: '' }
+```
+
+---
+
+## Tree-Shakeable Named Exports
+
+Import individual validators directly to keep your bundle lean:
+
+```ts
+import { validateEmail, validateMobile, validateAadhaar } from 'quantique-field-validator';
+
+validateEmail('user@example.com', {}, defaultErrorMessages, 'email');
+```
+
+All named validator exports follow the same signature:
+
+```ts
+(value: string, rules: ValidationRules, defaultErrorMessages: DefaultErrorMessagesFn, type: string) => ValidationResult
+```
+
+---
+
+## TypeScript Types
+
+All types are exported:
+
+```ts
+import type {
+  ValidationResult,
+  ValidationRules,
+  ErrorMessages,
+  ValidatorType,
+  ValidatorFn,
+  CustomValidatorFn,
+  DefaultErrorMessagesFn,
+} from 'quantique-field-validator';
+```
+
+---
+
+## Notes
+
+- **Emoji rejection** — all validators block emoji characters by default.
+- **ReDoS safety** — user-supplied `regex` strings are compiled with a length cap and timeout guard to prevent catastrophic backtracking.
+- **Empty + not required** — passing an empty value with `required: false` (or omitted) always returns `{ isValid: true }` without running further checks.
+
+---
+
+## License
+
+MIT © [Saket Brij Sinha](https://github.com/saketsinhaquantique)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quantique-field-validator",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Enterprise-grade dynamic field validator for Indian and international form fields.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",