libphonenumber-metadata-generator/README.md

Metadata generator for `libphonenumber-js`

# libphonenumber-metadata-generator

Generates metadata for [`libphonenumber-js`](https://gitlab.com/catamphetamine/libphonenumber-js).

## Install

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

## Use

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

```js
{
  "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](https://gitlab.com/catamphetamine/libphonenumber-metadata-generator/-/blob/master/source/generate.js#L6-17)
  * 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](#versioning) of a metadata file that would be generated when using this version of `libphonenumber-metadata-generator` package.