global-phone-validator 1.2.0 → 1.3.2

package/README.md

@@ -1,17 +1,17 @@
 # global-phone-validator
 
-A comprehensive Node.js + TypeScript package for validating phone numbers worldwide. Supports **all countries** with **country-specific validation rules** for 50+ major countries. Handles international formats (+CC), 0-prefixed, and plain digits. Includes mobile/landline detection for India and returns standardized E.164 format.
+A comprehensive Node.js + TypeScript package for validating **all types of phone numbers** worldwide. Supports **all countries** with **country-specific validation rules** and **phone number type detection** (mobile, landline, VoIP, toll-free, premium, special services) for 30+ major countries. Handles international formats (+CC), 0-prefixed, and plain digits. Returns standardized E.164 format.
 
 ## Features
 
-- ✅ **True Global Validation**: Validates phone numbers for **all countries** with country-specific rules for 50+ major countries
-- ✅ **Country-Specific Rules**: Accurate validation for US, UK, Germany, France, Australia, Brazil, China, Japan, India, and 40+ more countries
-- ✅ **Multiple Formats**: Handles international format (+CC), 0-prefixed, and plain digit formats
-- ✅ **India-Specific**: Mobile vs landline detection for Indian phone numbers
-- ✅ **Standardized Output**: Returns E.164 format (+CCNNNNNNNNN) with country information
-- ✅ **TypeScript**: Fully typed with TypeScript definitions
-- ✅ **Zero Dependencies**: No external dependencies required
-- ✅ **ITU-T E.164 Compliant**: Follows international telecommunication standards
+- ✅ Global validation for all countries
+- ✅ Phone type detection (mobile, landline, VoIP, toll-free, premium)
+- ✅ 50+ countries with specific validation rules
+- ✅ 70+ countries with mobile prefix detection
+- ✅ Multiple input formats (+CC, 0-prefixed, plain digits)
+- ✅ E.164 format output
+- ✅ Full TypeScript support
+- ✅ Zero dependencies
 
 ## Installation
 
@@ -38,12 +38,11 @@ const { validatePhoneNumber } = require("global-phone-validator");
 
 // Test various countries
 console.log(validatePhoneNumber("+91 98765 43210")); // India - Mobile
-console.log(validatePhoneNumber("+1 555 123 4567")); // USA
-console.log(validatePhoneNumber("+44 20 7946 0958")); // UK
+console.log(validatePhoneNumber("+1 555 123 4567")); // USA - Mobile
+console.log(validatePhoneNumber("+44 7123 456789")); // UK - Mobile
 console.log(validatePhoneNumber("+49 176 77274194")); // Germany - Mobile
-console.log(validatePhoneNumber("+49 30 12345678")); // Germany - Landline
-console.log(validatePhoneNumber("+61 2 1234 5678")); // Australia
-console.log(validatePhoneNumber("+86 138 0013 8000")); // China
+console.log(validatePhoneNumber("+61 4 1234 5678")); // Australia - Mobile
+console.log(validatePhoneNumber("+86 138 0013 8000")); // China - Mobile
 ```
 
 ### Test Locally
@@ -72,7 +71,6 @@ console.log(result1);
 //   nationalNumber: '9876543210',
 //   e164: '+919876543210',
 //   isMobile: true,
-//   isFixedLine: false,
 //   country: 'IN',
 //   countryName: 'India'
 // }
@@ -110,15 +108,20 @@ console.log(result4);
 // }
 ```
 
-### Mobile-Only Validation (India)
+### Phone Type Detection
 
 ```typescript
-// Only accept mobile numbers
-const result = validatePhoneNumber("9876543210", "IN", true);
-console.log(result.isValid); // true (mobile number)
+validatePhoneNumber("+919876543210").phoneType; // 'mobile'
+validatePhoneNumber("+442079460958").phoneType; // 'landline'
+validatePhoneNumber("+18001234567").phoneType; // 'toll-free'
+validatePhoneNumber("+19001234567").phoneType; // 'premium'
+```
+
+### Mobile-Only Validation
 
-const result2 = validatePhoneNumber("0123456789", "IN", true);
-console.log(result2.isValid); // false (landline number)
+```typescript
+validatePhoneNumber("9876543210", "IN", true); // true (mobile)
+validatePhoneNumber("0123456789", "IN", true); // false (landline)
 ```
 
 ### Get Country Codes
@@ -158,7 +161,7 @@ Validates a phone number and returns detailed information.
     - If `defaultCountry` is provided: Validates that detected country **matches** `defaultCountry` (strict mode)
     - If `defaultCountry` is **not provided**: Validates based on the **detected country** from the dial code
   - **When number doesn't have `+` prefix**: `defaultCountry` is **REQUIRED** - no default country is assumed
-- `mobileOnly` (boolean, optional): If true, only accepts mobile numbers (currently only for India). Default: false
+- `mobileOnly` (boolean, optional): If true, only accepts mobile numbers (works for all countries with mobile prefix rules). Default: false
 
 **Returns:** `PhoneValidationResult`
 
@@ -168,8 +171,7 @@ interface PhoneValidationResult {
   countryCode?: string; // e.g., '91'
   nationalNumber?: string; // e.g., '9876543210'
   e164?: string; // e.g., '+919876543210'
-  isMobile?: boolean; // true if mobile (India only)
-  isFixedLine?: boolean; // true if landline (India only)
+  isMobile?: boolean; // true if mobile number (based on country-specific prefix rules)
   country?: string; // ISO country code, e.g., 'IN'
   countryName?: string; // Full country name, e.g., 'India'
 }
@@ -261,7 +263,7 @@ The package includes **comprehensive validation rules** for **50+ major countrie
 
 #### Asia-Pacific
 
-- **India (91)**: 10 digits (mobile: 6-9, landline: 0-5) - Mobile/landline detection
+- **India (91)**: 10 digits (mobile: 6-9) - Mobile prefix detection
 - **China (86)**: 11 digits
 - **Japan (81)**: 10-11 digits
 - **South Korea (82)**: 9-10 digits
@@ -291,6 +293,19 @@ The package includes **comprehensive validation rules** for **50+ major countrie
 - **Qatar (974)**: 8 digits
 - **And more...**
 
+### Mobile Prefix Detection
+
+The package includes **mobile prefix detection** for **70+ countries**, allowing automatic identification of mobile numbers:
+
+**Countries with Mobile Prefix Detection:**
+
+- **Europe**: Germany, UK, France, Italy, Spain, Netherlands, Sweden, Norway, Poland, Russia, Austria, Belgium, Switzerland, Portugal, Greece, Ireland, Czech Republic, Denmark, Finland, Hungary, Iceland, Romania, Slovakia, Slovenia, Ukraine, and more
+- **Asia-Pacific**: India, China, Japan, South Korea, Australia, Indonesia, Philippines, Thailand, Malaysia, Singapore, New Zealand, Vietnam, Pakistan, Bangladesh, Sri Lanka, Myanmar, Iran, Israel, Hong Kong, Taiwan, and more
+- **Americas**: Argentina, Chile, Colombia, Peru, Venezuela, Uruguay, and more
+- **Africa & Middle East**: South Africa, Nigeria, UAE, Egypt, Morocco, Qatar, Kenya, and more
+
+**Note:** Some countries (like Mexico, Brazil) have area-code-dependent mobile prefixes that require area code information for accurate detection. For these countries, format validation is performed but mobile detection may be limited.
+
 ### Other Countries
 
 - **General validation**: 4-15 digits (ITU-T E.164 standard)
@@ -302,59 +317,13 @@ The package includes **comprehensive validation rules** for **50+ major countrie
 ```typescript
 import { validatePhoneNumber } from "global-phone-validator";
 
-// Valid Indian mobile number
-validatePhoneNumber("+91 98765 43210");
-// { isValid: true, isMobile: true, e164: '+919876543210', ... }
-
-// Valid Indian landline
-validatePhoneNumber("0123456789", "IN");
-// { isValid: true, isFixedLine: true, ... }
-
-// Invalid number
-validatePhoneNumber("12345");
-// { isValid: false }
-
-// US number
-validatePhoneNumber("+1 555 123 4567");
-// { isValid: true, country: 'US', e164: '+15551234567', ... }
-
-// UK number
-validatePhoneNumber("+44 20 7946 0958");
-// { isValid: true, country: 'GB', e164: '+442079460958', ... }
-
-// Germany number (mobile)
-validatePhoneNumber("+49 17677274194");
-// { isValid: true, country: 'DE', e164: '+4917677274194', ... }
-
-// Germany number (landline)
-validatePhoneNumber("+49 30 12345678");
-// { isValid: true, country: 'DE', e164: '+493012345678', ... }
-
-// France number
-validatePhoneNumber("+33 1 23 45 67 89");
-// { isValid: true, country: 'FR', e164: '+33123456789', ... }
-
-// Australia number
-validatePhoneNumber("+61 2 1234 5678");
-// { isValid: true, country: 'AU', e164: '+61212345678', ... }
-
-// Brazil number
-validatePhoneNumber("+55 11 98765 4321");
-// { isValid: true, country: 'BR', e164: '+5511987654321', ... }
-
-// China number
-validatePhoneNumber("+86 138 0013 8000");
-// { isValid: true, country: 'CN', e164: '+8613800138000', ... }
-
-// Japan number
-validatePhoneNumber("+81 3 1234 5678");
-// { isValid: true, country: 'JP', e164: '+81312345678', ... }
-
-// Germany number with different spacing (all formats work)
-validatePhoneNumber("+49 17677274194"); // With space after country code
-validatePhoneNumber("+49 176 77274194"); // With spaces in number
-validatePhoneNumber("+4917677274194"); // No spaces
-// All produce: { isValid: true, country: 'DE', nationalNumber: '17677274194', e164: '+4917677274194', ... }
+validatePhoneNumber("+91 98765 43210"); // India mobile
+validatePhoneNumber("+1 555 123 4567"); // US
+validatePhoneNumber("+44 7123 456789"); // UK mobile
+validatePhoneNumber("+49 17677274194"); // Germany mobile
+validatePhoneNumber("+18001234567"); // US toll-free
+validatePhoneNumber("+19001234567"); // US premium
+validatePhoneNumber("12345"); // Invalid
 ```
 
 ## Why Use This Package?
@@ -379,17 +348,113 @@ npm run build
 npm test
 ```
 
+## Data Structure
+
+The package uses a **generalized, unified data structure** that makes it easy to extend and maintain:
+
+### Country Data Structure
+
+All country information is consolidated into a single `CountryData` interface:
+
+```typescript
+interface CountryData {
+  name: string; // Country name
+  dial_code: string; // Dial code with + (e.g., "+91")
+  code: string; // ISO country code (e.g., "IN")
+
+  validation?: {
+    // Optional validation rules
+    pattern?: RegExp | string;
+    minLength?: number;
+    maxLength?: number;
+  };
+
+  phoneTypes?: {
+    // Phone type detection rules
+    mobilePrefixes?: string[];
+    landlinePrefixes?: string[];
+    voipPrefixes?: string[];
+    tollFreePrefixes?: string[];
+    premiumPrefixes?: string[];
+    specialPrefixes?: string[];
+  };
+
+  metadata?: {
+    // Optional metadata
+    notes?: string;
+    areaCodeDependent?: boolean;
+    lastUpdated?: string;
+  };
+}
+```
+
+### Data Sources
+
+1. **CountryCodes.json**: Basic country information (name, dial_code, code)
+2. **phoneTypes.ts**: Phone type detection rules (mobile, landline, VoIP, etc.)
+3. **countryData.ts**: Unified structure that merges both sources
+
+### Extending the Data
+
+You can easily add or update country data:
+
+```typescript
+import { addCountryData } from "global-phone-validator/dataAccess";
+
+// Add new country with phone type rules
+addCountryData("123", {
+  name: "New Country",
+  dial_code: "+123",
+  code: "NC",
+  validation: {
+    pattern: "^\\d{10}$",
+    minLength: 10,
+    maxLength: 10,
+  },
+  phoneTypes: {
+    mobilePrefixes: ["9"],
+    landlinePrefixes: ["1", "2", "3"],
+    tollFreePrefixes: ["800"],
+  },
+});
+```
+
+### Data Access API
+
+```typescript
+import {
+  getCountryData,
+  getPhoneTypeRules,
+  getValidationRules,
+  getCountriesWithPhoneTypeSupport,
+  hasPhoneTypeSupport,
+} from "global-phone-validator/dataAccess";
+
+// Get complete country data
+const india = getCountryData("91");
+
+// Get phone type rules only
+const rules = getPhoneTypeRules("91");
+
+// Get validation rules only
+const validation = getValidationRules("91");
+
+// Get all countries with phone type support
+const countries = getCountriesWithPhoneTypeSupport();
+
+// Check if country supports specific phone type
+const hasMobile = hasPhoneTypeSupport("91", "mobile");
+```
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
-### Adding Country Validation Rules
-
-If you'd like to add or improve validation rules for specific countries, please:
+### Contributing
 
 1. Fork the repository
-2. Add the validation rule to the `validationRules` object in `src/index.ts`
-3. Update the README with the country information
+2. Add validation rules to `src/index.ts`
+3. Add phone type rules to `src/phoneTypes.ts`
 4. Submit a Pull Request
 
 ## License
@@ -398,10 +463,6 @@ MIT
 
 ## Links
 
-- **NPM Package**: [global-phone-validator](https://www.npmjs.com/package/global-phone-validator)
-- **GitHub Repository**: [AVantala/global-phone-validator](https://github.com/AVantala/global-phone-validator)
-- **Issues**: [Report a bug or request a feature](https://github.com/AVantala/global-phone-validator/issues)
-
-## License
-
-MIT
+- [NPM Package](https://www.npmjs.com/package/global-phone-validator)
+- [GitHub Repository](https://github.com/AVantala/global-phone-validator)
+- [Report Issues](https://github.com/AVantala/global-phone-validator/issues)

package/dist/countryData.d.ts

@@ -0,0 +1,24 @@
+import { PhoneTypeRules } from "./phoneTypes";
+export interface CountryData {
+    name: string;
+    dial_code: string;
+    code: string;
+    validation?: {
+        pattern?: RegExp | string;
+        minLength?: number;
+        maxLength?: number;
+    };
+    phoneTypes?: PhoneTypeRules;
+    metadata?: {
+        notes?: string;
+        areaCodeDependent?: boolean;
+        lastUpdated?: string;
+    };
+}
+export declare const COUNTRY_DATA: Record<string, Partial<CountryData>>;
+export declare function initializeCountryData(): Record<string, CountryData>;
+export declare function clearCountryDataCache(): void;
+export declare function getCountryData(countryCode: string): CountryData | undefined;
+export declare function getCountryDataByIsoCode(isoCode: string): CountryData | undefined;
+export declare function getAllCountryData(): Record<string, CountryData>;
+export declare function setCountryData(countryCode: string, data: Partial<CountryData>): void;

package/dist/countryData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"countryData.d.ts","sourceRoot":"","sources":["../src/countryData.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,WAAW,WAAW;IAE1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IAGb,UAAU,CAAC,EAAE;QACX,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IAGF,UAAU,CAAC,EAAE,cAAc,CAAC;IAG5B,QAAQ,CAAC,EAAE;QACT,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAOD;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAgGpD,CAAC;AAKF;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CA8CnE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAG3E;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAGhF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAE/D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI,CAkBpF"}