libphonenumber-metadata-generator

Generates metadata for libphonenumber-js.

Install

npm install libphonenumber-metadata-generator --save-dev

Use

Add a metadata generation script to your project's package.json. Example:

{
  "scripts": {
    "generate-libphonenumber-metadata": "libphonenumber-metadata-generator metadata.custom.json --countries RU,DE --with-phone-number-types"
  }
}

And then run it like npm run generate-libphonenumber-metadata.

The arguments are:

• The first argument is always the output metadata file path.

• --countries argument is a comma-separated list of the included countries.

  • if this argument is omitted then all countries are included.

• --with-phone-number-types argument may be passed to include the regular expressions that are required for precise phone number validation (via .isValid()) and getting phone number type (via .getType()).

  • if this argument is omitted then phone numbers will still be parseable, and they will still be recognized as "possible" (.isPossible() will return true), but they won't be recognized as "valid" (.isValid() will return false), and their "type" will be unknown (.getType() will return undefined).

• --phone-number-types argument may be passed to limit the supported phone number types to just a few ones (a comma-separated list).

  • Must be used together with --with-phone-number-types
  • Example: --with-phone-number-types --phone-number-types mobile,fixed_line
  • See the list of all possible phone number types
  • Other phone number types will still be parseable, and they will still be recognized as "possible" (.isPossible() will return true), but they won't be recognized as "valid" (.isValid() will return false), and their "type" will be unknown (.getType() will return undefined).

• --with-phone-number-type-examples argument may be passed to include example phone numbers (one for each phone number type).

  • If --non-minified argument is not passed, the examples will be removed at the minification stage.

• --non-minified argument may be passed to output non-minified metadata.

  • Example: --non-minified
  • Minification converts objects to positional arrays and removes example phone numbers.

Versioning

Metadata generated by libphonenumber-metadata-generator has a numeric version. This is for backwards compatibility, because metadata file format could change in some future. Hence, any application that uses the generated metadata should "hardcode" the version of it that it is designed to support, and when consuming generated metadata, it should compare the metadata version to the "hardcoded" one — if the two are different, it should be treated as a "breaking change".

API

async download(): { date: Date, version: string, changes: string[], xml: string }

Downloads the latest "release" of metadata. Returns the "release" version, a human-readable list of changes, and the metadata in XML format.

async generate(metadataXml: string, { countries: string[]?, withPhoneNumberTypes: boolean?, phoneNumberTypes: string[]? }): object

Converts XML metadata to (non-minified) JSON metadata.

minify(metadata: object): object

Minifies JSON metadata: converts objects to positional arrays and removes example phone numbers.

version: number

This is the version of a metadata file that would be generated when using this version of libphonenumber-metadata-generator package.