phone

$phone

Validates and normalizes a phone number string.

Strips common formatting (spaces, dashes, dots, parentheses, slashes) and validates the remaining digits against country-specific rules when available, or generic E.164 length rules otherwise.

Output format is controlled by the international parameter:

• When false (default): national format for the default country (e.g. (212) 555-1234 for country code 1).
• When true: international format with country code prefix (e.g. +1 212 555 1234).

Numbers without a + prefix are assumed to belong to the default country. A leading country code without + is recognized when it produces a valid subscriber length (e.g. 12125551234 is treated as +1 2125551234).

NANP validation (country code 1): area codes and exchanges must not start with 0 or 1, matching North American Numbering Plan rules.

Not supported: extensions, vanity letters (1-800-FLOWERS), international dialing prefixes (00, 011), short codes, or emergency numbers. This processor targets typical subscriber phone numbers as entered in forms or configuration files.

Parameters

• international (boolean, default false): When false, only numbers matching the default country code are accepted, and output uses the national format. When true, any valid international number is accepted, and output uses the international format with +CC prefix.
• country (string, default '1'): Default country calling code applied to numbers entered without a + prefix.
• countries (object, default null): Optional map of country calling codes to rule objects, merged over the built-in rules. Each rule object may contain:
  • lengths (number[]) — accepted subscriber digit counts
  • validate (RegExp, optional) — pattern the subscriber digits must match
  • national (string) — #-template for national formatting
  • international (string) — #-template for international formatting

Example

// Basic US number validation and national formatting
new Schema('string').validator('$phone')

// Accept international numbers
new Schema('string').validator({'$phone': {international: true}})

// Default to UK numbers
new Schema('string').validator({'$phone': {
  country: '44',
  countries: {
    '44': {lengths: [10], national: '#### ### ####', international: '#### ### ####'}
  }
}})

// Compact storage: compose with space/punctuation stripping
new Schema('string').normalizer({$pipeline: ['$trim', '$phone']})