libphonenumber-js - npm Package Compare versions

Comparing version 1.9.26 to 1.9.27

build/helpers/getCountryByCallingCode.js

@@ -57,3 +57,6 @@ "use strict";
     var country = _ref;
-    metadata.country(country); // Leading digits check would be the simplest one
+    metadata.country(country); // Leading digits check would be the simplest and fastest one.
+    // Leading digits patterns are only defined for about 20% of all countries.
+    // https://gitlab.com/catamphetamine/libphonenumber-js/blob/master/METADATA.md#leading_digits
+    // Matching "leading digits" is a sufficient but not necessary condition.
 
@@ -60,0 +63,0 @@ if (metadata.leadingDigits()) {

build/metadata.js

@@ -312,3 +312,4 @@ "use strict";
       return this.globalMetadataObject.getNumberingPlanMetadata(this.callingCode());
-    }
+    } // Is always present.
+
   }, {
@@ -319,3 +320,4 @@ key: "IDDPrefix",
       return this.metadata[1];
-    }
+    } // Is only present when a country supports multiple IDD prefixes.
+
   }, {
@@ -332,3 +334,4 @@ key: "defaultIDDPrefix",
       return this.metadata[2];
-    }
+    } // Is always present.
+
   }, {
@@ -335,0 +338,0 @@ key: "possibleLengths",

CHANGELOG.md

 <!-- (breaking change) `parsePhoneNumberFromString()`: `extract: false` is now the default mode: non-phone-number characters aren't now trimmed on the left and on the right sides of a phone number. For example, `[phone]` is parsed as a valid phone number, but `Call: [phone]` is not, because `Call: ` doesn't automatically get trimmed now. For the old behavior, pass `extract: true` option. -->
 
-<!--
-The exported `Metadata` name is already used for exporting the "raw" JSON metadata type.
-Then, `Metadata` class has become exported, but its name is already taken, so TypeScript users seem to be unable to use the `Metadata` class.
-If someone knows a solution then they could propose it in an issue.
--->
-
 <!-- Maybe rename `metadata.full.json` -> `metadata.max.json`. -->
@@ -76,2 +70,9 @@
 
+1.9.27 / 09.09.2021
+==================
+
+* [Added](https://gitlab.com/catamphetamine/libphonenumber-js/-/issues/45) TypeScript "typings" on the exported `Metadata` class. Also rewrote `Metadata` class API [docs](https://gitlab.com/catamphetamine/libphonenumber-js#metadata) and the description of [`leading_digits`](https://gitlab.com/catamphetamine/libphonenumber-js/blob/master/METADATA.md#leading_digits) metadata property.
+
+* TypeScript `Metadata` exported type was renamed to `MetadataJson` so that the `Metadata` class type could be exported as `Metadata`.
+
 1.9.26 / 05.09.2021
@@ -78,0 +79,0 @@ ==================

core/index.d.ts

 import {
-  Metadata,
+  MetadataJson,
   PhoneNumber,
@@ -15,2 +15,3 @@ E164Number,
   NumberFormat,
+  NumberingPlan,
   ValidatePhoneNumberLengthResult
@@ -22,3 +23,3 @@ } from '../types';
 export {
-  Metadata,
+  MetadataJson,
   PhoneNumber,
@@ -36,2 +37,3 @@ E164Number,
   NumberFormat,
+  NumberingPlan,
   ValidatePhoneNumberLengthResult
@@ -41,39 +43,39 @@ };
 // `parsePhoneNumber()` named export has been renamed to `parsePhoneNumberWithError()`.
-export function parsePhoneNumber(text: string, metadata: Metadata): PhoneNumber;
-export function parsePhoneNumber(text: string, defaultCountry: CountryCode, metadata: Metadata): PhoneNumber;
+export function parsePhoneNumber(text: string, metadata: MetadataJson): PhoneNumber;
+export function parsePhoneNumber(text: string, defaultCountry: CountryCode, metadata: MetadataJson): PhoneNumber;
 
-export function parsePhoneNumberWithError(text: string, metadata: Metadata): PhoneNumber;
-export function parsePhoneNumberWithError(text: string, defaultCountry: CountryCode, metadata: Metadata): PhoneNumber;
+export function parsePhoneNumberWithError(text: string, metadata: MetadataJson): PhoneNumber;
+export function parsePhoneNumberWithError(text: string, defaultCountry: CountryCode, metadata: MetadataJson): PhoneNumber;
 
 // `parsePhoneNumberFromString()` named export is now considered legacy:
 // it has been promoted to a default export due to being too verbose.
-export function parsePhoneNumberFromString(text: string, metadata: Metadata): PhoneNumber | undefined;
-export function parsePhoneNumberFromString(text: string, defaultCountry: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string, extract?: boolean }, metadata: Metadata): PhoneNumber | undefined;
+export function parsePhoneNumberFromString(text: string, metadata: MetadataJson): PhoneNumber | undefined;
+export function parsePhoneNumberFromString(text: string, defaultCountry: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string, extract?: boolean }, metadata: MetadataJson): PhoneNumber | undefined;
 
 export default parsePhoneNumberFromString;
 
-export function isValidPhoneNumber(text: string, metadata: Metadata): boolean;
-export function isValidPhoneNumber(text: string, defaultCountry: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string }, metadata: Metadata): boolean;
+export function isValidPhoneNumber(text: string, metadata: MetadataJson): boolean;
+export function isValidPhoneNumber(text: string, defaultCountry: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string }, metadata: MetadataJson): boolean;
 
-export function isPossiblePhoneNumber(text: string, metadata: Metadata): boolean;
-export function isPossiblePhoneNumber(text: string, defaultCountry: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string }, metadata: Metadata): boolean;
+export function isPossiblePhoneNumber(text: string, metadata: MetadataJson): boolean;
+export function isPossiblePhoneNumber(text: string, defaultCountry: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string }, metadata: MetadataJson): boolean;
 
-export function validatePhoneNumberLength(text: string, metadata: Metadata): ValidatePhoneNumberLengthResult | undefined;
-export function validatePhoneNumberLength(text: string, defaultCountry: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string }, metadata: Metadata): ValidatePhoneNumberLengthResult | undefined;
+export function validatePhoneNumberLength(text: string, metadata: MetadataJson): ValidatePhoneNumberLengthResult | undefined;
+export function validatePhoneNumberLength(text: string, defaultCountry: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string }, metadata: MetadataJson): ValidatePhoneNumberLengthResult | undefined;
 
-export function findNumbers(text: string, metadata: Metadata): NumberFoundLegacy[];
-export function findNumbers(text: string, options: CountryCode | { defaultCountry?: CountryCode, v2: true }, metadata: Metadata): NumberFound[];
+export function findNumbers(text: string, metadata: MetadataJson): NumberFoundLegacy[];
+export function findNumbers(text: string, options: CountryCode | { defaultCountry?: CountryCode, v2: true }, metadata: MetadataJson): NumberFound[];
 
-export function searchNumbers(text: string, metadata: Metadata): IterableIterator<NumberFoundLegacy>;
-export function searchNumbers(text: string, options: CountryCode | { defaultCountry?: CountryCode, v2: true }, metadata: Metadata): IterableIterator<NumberFound>;
+export function searchNumbers(text: string, metadata: MetadataJson): IterableIterator<NumberFoundLegacy>;
+export function searchNumbers(text: string, options: CountryCode | { defaultCountry?: CountryCode, v2: true }, metadata: MetadataJson): IterableIterator<NumberFound>;
 
-export function findPhoneNumbersInText(text: string, options: CountryCode | { defaultCountry?: CountryCode }, metadata: Metadata): NumberFound[];
-export function findPhoneNumbersInText(text: string, metadata: Metadata): NumberFound[];
+export function findPhoneNumbersInText(text: string, options: CountryCode | { defaultCountry?: CountryCode }, metadata: MetadataJson): NumberFound[];
+export function findPhoneNumbersInText(text: string, metadata: MetadataJson): NumberFound[];
 
-export function searchPhoneNumbersInText(text: string, options: CountryCode | { defaultCountry?: CountryCode }, metadata: Metadata): IterableIterator<NumberFound>;
-export function searchPhoneNumbersInText(text: string, metadata: Metadata): IterableIterator<NumberFound>;
+export function searchPhoneNumbersInText(text: string, options: CountryCode | { defaultCountry?: CountryCode }, metadata: MetadataJson): IterableIterator<NumberFound>;
+export function searchPhoneNumbersInText(text: string, metadata: MetadataJson): IterableIterator<NumberFound>;
 
 export class PhoneNumberMatcher {
-  constructor(text: string, metadata: Metadata);
-  constructor(text: string, options: { defaultCountry?: CountryCode, v2: true }, metadata: Metadata);
+  constructor(text: string, metadata: MetadataJson);
+  constructor(text: string, options: { defaultCountry?: CountryCode, v2: true }, metadata: MetadataJson);
   hasNext(): boolean;
@@ -83,11 +85,11 @@ next(): NumberFound | undefined;
 
-export function isSupportedCountry(countryCode: CountryCode, metadata: Metadata): boolean;
-export function getCountries(metadata: Metadata): CountryCode[];
-export function getCountryCallingCode(countryCode: CountryCode, metadata: Metadata): CountryCallingCode;
-export function getExtPrefix(countryCode: CountryCode, metadata: Metadata): string;
+export function isSupportedCountry(countryCode: CountryCode, metadata: MetadataJson): boolean;
+export function getCountries(metadata: MetadataJson): CountryCode[];
+export function getCountryCallingCode(countryCode: CountryCode, metadata: MetadataJson): CountryCallingCode;
+export function getExtPrefix(countryCode: CountryCode, metadata: MetadataJson): string;
 
-export function getExampleNumber(country: CountryCode, examples: { [country in CountryCode]: NationalNumber }, metadata: Metadata): PhoneNumber | undefined;
+export function getExampleNumber(country: CountryCode, examples: { [country in CountryCode]: NationalNumber }, metadata: MetadataJson): PhoneNumber | undefined;
 
-export function formatIncompletePhoneNumber(number: string, metadata: Metadata): string;
-export function formatIncompletePhoneNumber(number: string, countryCode: CountryCode, metadata: Metadata): string;
+export function formatIncompletePhoneNumber(number: string, metadata: MetadataJson): string;
+export function formatIncompletePhoneNumber(number: string, countryCode: CountryCode, metadata: MetadataJson): string;
 export function parseIncompletePhoneNumber(text: string): string;
@@ -98,3 +100,3 @@ export function parsePhoneNumberCharacter(character: string): string;
 export class AsYouType {
-  constructor(defaultCountryCode: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string } | undefined, metadata: Metadata);
+  constructor(defaultCountryCode: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string } | undefined, metadata: MetadataJson);
   input(text: string): string;
@@ -112,7 +114,11 @@ reset(): void;
 
-// The exported `Metadata` name is already used for exporting the "raw" JSON metadata type.
-// Then, `Metadata` class has become exported, but its name is already taken, so TypeScript users seem to be unable to use the `Metadata` class.
-// If someone knows a solution then they could propose it in an issue.
-// export class Metadata {
-//   ...
-// }
+export class Metadata {
+  constructor(metadata: MetadataJson);
+  selectNumberingPlan(country: CountryCode): void;
+  // The `numberingPlan` property is declared without a `?`
+  // just so that TypeScript programmers don't have to add
+  // a needless `if (metadata.numberingPlan)` check:
+  // the `numberingPlan` property is only set after
+  // `selectNumberingPlan(country)` method has been called.
+  numberingPlan: NumberingPlan;
+}

custom.d.ts

@@ -5,3 +5,3 @@ // `/custom` export is deprecated.
 import {
-  Metadata,
+  MetadataJson,
   PhoneNumber,
@@ -28,3 +28,3 @@ E164Number,
 export {
-  Metadata,
+  MetadataJson,
   PhoneNumber,
@@ -48,64 +48,64 @@ E164Number,
 // `parsePhoneNumber()` named export has been renamed to `parsePhoneNumberWithError()`.
-export function parsePhoneNumber(text: string, metadata: Metadata): PhoneNumber;
-export function parsePhoneNumber(text: string, defaultCountry: CountryCode, metadata: Metadata): PhoneNumber;
+export function parsePhoneNumber(text: string, metadata: MetadataJson): PhoneNumber;
+export function parsePhoneNumber(text: string, defaultCountry: CountryCode, metadata: MetadataJson): PhoneNumber;
 
-export function parsePhoneNumberWithError(text: string, metadata: Metadata): PhoneNumber;
-export function parsePhoneNumberWithError(text: string, defaultCountry: CountryCode, metadata: Metadata): PhoneNumber;
+export function parsePhoneNumberWithError(text: string, metadata: MetadataJson): PhoneNumber;
+export function parsePhoneNumberWithError(text: string, defaultCountry: CountryCode, metadata: MetadataJson): PhoneNumber;
 
 // `parsePhoneNumberFromString()` named export is now considered legacy:
 // it has been promoted to a default export due to being too verbose.
-export function parsePhoneNumberFromString(text: string, metadata: Metadata): PhoneNumber;
-export function parsePhoneNumberFromString(text: string, defaultCountry: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string, extract?: boolean }, metadata: Metadata): PhoneNumber;
+export function parsePhoneNumberFromString(text: string, metadata: MetadataJson): PhoneNumber;
+export function parsePhoneNumberFromString(text: string, defaultCountry: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string, extract?: boolean }, metadata: MetadataJson): PhoneNumber;
 
 export default parsePhoneNumberFromString;
 
-export function parse(text: string, metadata: Metadata): ParsedNumber;
-export function parse(text: string, options: CountryCode | ParseNumberOptions, metadata: Metadata): ParsedNumber;
+export function parse(text: string, metadata: MetadataJson): ParsedNumber;
+export function parse(text: string, options: CountryCode | ParseNumberOptions, metadata: MetadataJson): ParsedNumber;
 
-export function parseNumber(text: string, metadata: Metadata): ParsedNumber | {};
-export function parseNumber(text: string, options: CountryCode | ParseNumberOptions, metadata: Metadata): ParsedNumber | {};
+export function parseNumber(text: string, metadata: MetadataJson): ParsedNumber | {};
+export function parseNumber(text: string, options: CountryCode | ParseNumberOptions, metadata: MetadataJson): ParsedNumber | {};
 
 // `format()` and `formatCustom` are deprecated.
 // Use `formatNumber()` and `formatNumberCustom()` instead.
-export function format(parsedNumber: ParsedNumber, format: NumberFormat, metadata: Metadata): string;
-export function format(phone: NationalNumber, format: NumberFormat, metadata: Metadata): string;
-export function format(phone: NationalNumber, country: CountryCode, format: NumberFormat, metadata: Metadata): string;
+export function format(parsedNumber: ParsedNumber, format: NumberFormat, metadata: MetadataJson): string;
+export function format(phone: NationalNumber, format: NumberFormat, metadata: MetadataJson): string;
+export function format(phone: NationalNumber, country: CountryCode, format: NumberFormat, metadata: MetadataJson): string;
 
-export function formatNumber(parsedNumber: ParsedNumber, format: NumberFormat, metadata: Metadata): string;
-export function formatNumber(parsedNumber: ParsedNumber, format: NumberFormat, options: FormatNumberOptions, metadata: Metadata): string;
+export function formatNumber(parsedNumber: ParsedNumber, format: NumberFormat, metadata: MetadataJson): string;
+export function formatNumber(parsedNumber: ParsedNumber, format: NumberFormat, options: FormatNumberOptions, metadata: MetadataJson): string;
 
-export function formatNumber(phone: NationalNumber, format: NumberFormat, metadata: Metadata): string;
-export function formatNumber(phone: NationalNumber, format: NumberFormat, options: FormatNumberOptions, metadata: Metadata): string;
+export function formatNumber(phone: NationalNumber, format: NumberFormat, metadata: MetadataJson): string;
+export function formatNumber(phone: NationalNumber, format: NumberFormat, options: FormatNumberOptions, metadata: MetadataJson): string;
 
-export function formatNumber(phone: NationalNumber, country: CountryCode, format: NumberFormat, metadata: Metadata): string;
-export function formatNumber(phone: NationalNumber, country: CountryCode, format: NumberFormat, options: FormatNumberOptions, metadata: Metadata): string;
+export function formatNumber(phone: NationalNumber, country: CountryCode, format: NumberFormat, metadata: MetadataJson): string;
+export function formatNumber(phone: NationalNumber, country: CountryCode, format: NumberFormat, options: FormatNumberOptions, metadata: MetadataJson): string;
 
-export function getNumberType(parsedNumber: ParsedNumber, metadata: Metadata): NumberType;
-export function getNumberType(phone: NationalNumber, metadata: Metadata): NumberType;
-export function getNumberType(phone: NationalNumber, country: CountryCode, metadata: Metadata): NumberType;
+export function getNumberType(parsedNumber: ParsedNumber, metadata: MetadataJson): NumberType;
+export function getNumberType(phone: NationalNumber, metadata: MetadataJson): NumberType;
+export function getNumberType(phone: NationalNumber, country: CountryCode, metadata: MetadataJson): NumberType;
 
-export function getExampleNumber(country: CountryCode, examples: { [country in CountryCode]: NationalNumber }, metadata: Metadata): PhoneNumber | undefined;
+export function getExampleNumber(country: CountryCode, examples: { [country in CountryCode]: NationalNumber }, metadata: MetadataJson): PhoneNumber | undefined;
 
-export function isPossibleNumber(parsedNumber: ParsedNumber, metadata: Metadata): boolean;
-export function isPossibleNumber(phone: NationalNumber, metadata: Metadata): boolean;
-export function isPossibleNumber(phone: NationalNumber, country: CountryCode, metadata: Metadata): boolean;
+export function isPossibleNumber(parsedNumber: ParsedNumber, metadata: MetadataJson): boolean;
+export function isPossibleNumber(phone: NationalNumber, metadata: MetadataJson): boolean;
+export function isPossibleNumber(phone: NationalNumber, country: CountryCode, metadata: MetadataJson): boolean;
 
-export function isValidNumber(parsedNumber: ParsedNumber, metadata: Metadata): boolean;
-export function isValidNumber(phone: NationalNumber, metadata: Metadata): boolean;
-export function isValidNumber(phone: NationalNumber, country: CountryCode, metadata: Metadata): boolean;
+export function isValidNumber(parsedNumber: ParsedNumber, metadata: MetadataJson): boolean;
+export function isValidNumber(phone: NationalNumber, metadata: MetadataJson): boolean;
+export function isValidNumber(phone: NationalNumber, country: CountryCode, metadata: MetadataJson): boolean;
 
-export function isValidNumberForRegion(phone: NationalNumber, country: CountryCode, metadata: Metadata): boolean;
+export function isValidNumberForRegion(phone: NationalNumber, country: CountryCode, metadata: MetadataJson): boolean;
 
 // Deprecated.
-export function findParsedNumbers(text: string, metadata: Metadata): NumberFoundLegacy[];
-export function findParsedNumbers(text: string, options: CountryCode | { defaultCountry?: CountryCode }, metadata: Metadata): NumberFoundLegacy[];
+export function findParsedNumbers(text: string, metadata: MetadataJson): NumberFoundLegacy[];
+export function findParsedNumbers(text: string, options: CountryCode | { defaultCountry?: CountryCode }, metadata: MetadataJson): NumberFoundLegacy[];
 
 // Deprecated.
-export function searchParsedNumbers(text: string, metadata: Metadata): IterableIterator<NumberFoundLegacy>;
-export function searchParsedNumbers(text: string, options: CountryCode | { defaultCountry?: CountryCode }, metadata: Metadata): IterableIterator<NumberFoundLegacy>;
+export function searchParsedNumbers(text: string, metadata: MetadataJson): IterableIterator<NumberFoundLegacy>;
+export function searchParsedNumbers(text: string, options: CountryCode | { defaultCountry?: CountryCode }, metadata: MetadataJson): IterableIterator<NumberFoundLegacy>;
 
 // Deprecated.
 export class ParsedNumberSearch {
-  constructor(text: string, metadata: Metadata);
-  constructor(text: string, options: { defaultCountry?: CountryCode }, metadata: Metadata);
+  constructor(text: string, metadata: MetadataJson);
+  constructor(text: string, options: { defaultCountry?: CountryCode }, metadata: MetadataJson);
   hasNext(): boolean;
@@ -115,17 +115,17 @@ next(): NumberFoundLegacy | undefined;
 
-export function findNumbers(text: string, metadata: Metadata): NumberFoundLegacy[];
-export function findNumbers(text: string, options: CountryCode | { defaultCountry?: CountryCode, v2: true }, metadata: Metadata): NumberFound[];
+export function findNumbers(text: string, metadata: MetadataJson): NumberFoundLegacy[];
+export function findNumbers(text: string, options: CountryCode | { defaultCountry?: CountryCode, v2: true }, metadata: MetadataJson): NumberFound[];
 
-export function searchNumbers(text: string, metadata: Metadata): IterableIterator<NumberFoundLegacy>;
-export function searchNumbers(text: string, options: CountryCode | { defaultCountry?: CountryCode, v2: true }, metadata: Metadata): IterableIterator<NumberFound>;
+export function searchNumbers(text: string, metadata: MetadataJson): IterableIterator<NumberFoundLegacy>;
+export function searchNumbers(text: string, options: CountryCode | { defaultCountry?: CountryCode, v2: true }, metadata: MetadataJson): IterableIterator<NumberFound>;
 
-export function findPhoneNumbersInText(text: string, metadata: Metadata): NumberFound[];
-export function findPhoneNumbersInText(text: string, options: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string }, metadata: Metadata): NumberFound[];
+export function findPhoneNumbersInText(text: string, metadata: MetadataJson): NumberFound[];
+export function findPhoneNumbersInText(text: string, options: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string }, metadata: MetadataJson): NumberFound[];
 
-export function searchPhoneNumbersInText(text: string, metadata: Metadata): IterableIterator<NumberFound>;
-export function searchPhoneNumbersInText(text: string, options: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string }, metadata: Metadata): IterableIterator<NumberFound>;
+export function searchPhoneNumbersInText(text: string, metadata: MetadataJson): IterableIterator<NumberFound>;
+export function searchPhoneNumbersInText(text: string, options: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string }, metadata: MetadataJson): IterableIterator<NumberFound>;
 
 export class PhoneNumberMatcher {
-  constructor(text: string, metadata: Metadata);
-  constructor(text: string, options: { defaultCountry?: CountryCode, v2: true }, metadata: Metadata);
+  constructor(text: string, metadata: MetadataJson);
+  constructor(text: string, options: { defaultCountry?: CountryCode, v2: true }, metadata: MetadataJson);
   hasNext(): boolean;
@@ -135,11 +135,11 @@ next(): NumberFound | undefined;
 
-export function getCountries(metadata: Metadata): CountryCode[];
-export function getCountryCallingCode(countryCode: CountryCode, metadata: Metadata): CountryCallingCode;
+export function getCountries(metadata: MetadataJson): CountryCode[];
+export function getCountryCallingCode(countryCode: CountryCode, metadata: MetadataJson): CountryCallingCode;
 // Deprecated
-export function getPhoneCode(countryCode: CountryCode, metadata: Metadata): CountryCallingCode;
-export function getExtPrefix(countryCode: CountryCode, metadata: Metadata): string;
-export function isSupportedCountry(countryCode: CountryCode, metadata: Metadata): boolean;
+export function getPhoneCode(countryCode: CountryCode, metadata: MetadataJson): CountryCallingCode;
+export function getExtPrefix(countryCode: CountryCode, metadata: MetadataJson): string;
+export function isSupportedCountry(countryCode: CountryCode, metadata: MetadataJson): boolean;
 
-export function formatIncompletePhoneNumber(number: string, metadata: Metadata): string;
-export function formatIncompletePhoneNumber(number: string, countryCode: CountryCode, metadata: Metadata): string;
+export function formatIncompletePhoneNumber(number: string, metadata: MetadataJson): string;
+export function formatIncompletePhoneNumber(number: string, countryCode: CountryCode, metadata: MetadataJson): string;
 export function parseIncompletePhoneNumber(text: string): string;
@@ -150,3 +150,3 @@ export function parsePhoneNumberCharacter(character: string): string;
 export class AsYouType {
-  constructor(defaultCountryCode: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string } | undefined, metadata: Metadata);
+  constructor(defaultCountryCode: CountryCode | { defaultCountry?: CountryCode, defaultCallingCode?: string } | undefined, metadata: MetadataJson);
   input(text: string): string;
@@ -164,9 +164,2 @@ reset(): void;
   isValid(): boolean;
-}
-
-// The exported `Metadata` name is already used for exporting the "raw" JSON metadata type.
-// Then, `Metadata` class has become exported, but its name is already taken, so TypeScript users seem to be unable to use the `Metadata` class.
-// If someone knows a solution then they could propose it in an issue.
-// export class Metadata {
-//   ...
-// }
+}

es6/helpers/getCountryByCallingCode.js

@@ -45,3 +45,6 @@ import Metadata from '../metadata';
     var country = _ref;
-    metadata.country(country); // Leading digits check would be the simplest one
+    metadata.country(country); // Leading digits check would be the simplest and fastest one.
+    // Leading digits patterns are only defined for about 20% of all countries.
+    // https://gitlab.com/catamphetamine/libphonenumber-js/blob/master/METADATA.md#leading_digits
+    // Matching "leading digits" is a sufficient but not necessary condition.
 
@@ -48,0 +51,0 @@ if (metadata.leadingDigits()) {

es6/metadata.js

@@ -298,3 +298,4 @@ function _typeof(obj) { if (typeof Symbol === "function" && typeof Symbol.iterator === "symbol") { _typeof = function _typeof(obj) { return typeof obj; }; } else { _typeof = function _typeof(obj) { return obj && typeof Symbol === "function" && obj.constructor === Symbol && obj !== Symbol.prototype ? "symbol" : typeof obj; }; } return _typeof(obj); }
       return this.globalMetadataObject.getNumberingPlanMetadata(this.callingCode());
-    }
+    } // Is always present.
+
   }, {
@@ -305,3 +306,4 @@ key: "IDDPrefix",
       return this.metadata[1];
-    }
+    } // Is only present when a country supports multiple IDD prefixes.
+
   }, {
@@ -318,3 +320,4 @@ key: "defaultIDDPrefix",
       return this.metadata[2];
-    }
+    } // Is always present.
+
   }, {
@@ -321,0 +324,0 @@ key: "possibleLengths",

index.d.ts

 import {
-  Metadata,
+  MetadataJson,
   PhoneNumber,
@@ -15,2 +15,3 @@ E164Number,
   NumberFormat,
+  NumberingPlan,
   ValidatePhoneNumberLengthResult
@@ -20,3 +21,3 @@ } from './types';
 export {
-  Metadata,
+  MetadataJson,
   PhoneNumber,
@@ -34,6 +35,7 @@ E164Number,
   NumberType,
+  NumberingPlan,
   ValidatePhoneNumberLengthResult
 };
 
-type FormatExtension = (number: string, extension: string, metadata: Metadata) => string
+type FormatExtension = (number: string, extension: string, metadata: MetadataJson) => string
 
@@ -164,7 +166,11 @@ type FormatNumberOptionsWithoutIDD = {
 
-// The exported `Metadata` name is already used for exporting the "raw" JSON metadata type.
-// Then, `Metadata` class has become exported, but its name is already taken, so TypeScript users seem to be unable to use the `Metadata` class.
-// If someone knows a solution then they could propose it in an issue.
-// export class Metadata {
-//   ...
-// }
+export class Metadata {
+  constructor(metadata: MetadataJson);
+  selectNumberingPlan(country: CountryCode): void;
+  // The `numberingPlan` property is declared without a `?`
+  // just so that TypeScript programmers don't have to add
+  // a needless `if (metadata.numberingPlan)` check:
+  // the `numberingPlan` property is only set after
+  // `selectNumberingPlan(country)` method has been called.
+  numberingPlan: NumberingPlan;
+}

METADATA.md

@@ -19,3 +19,3 @@ # Metadata
 
-[International Direct Dialing prefix](https://wikitravel.org/en/International_dialling_prefix) when calling out of this country. "IDD prefixes" are used to call from one country to another. "IDD prefixes" originated when telephony was still analogue and analogue phones didn't have a `+` input. Nowadays, mobile phone users dial international numbers using a `+` rather than an "IDD prefix", but the mobile phone operating system replaces the `+` with an "IDD prefix" under the hood. For example, to call a Russian number `[phone]` from US the dialled digits would be `01178005553535` where `011` is an "IDD prefix".
+[International Direct Dialing prefix](https://wikitravel.org/en/International_dialling_prefix) when calling out of this country. "IDD prefixes" are defined for every country and are used to call from one country to another. "IDD prefixes" originated when telephony was still analogue and analogue phones didn't have a `+` input. Nowadays, mobile phone users dial international numbers using a `+` rather than an "IDD prefix", but the mobile phone operating system replaces the `+` with an "IDD prefix" under the hood. For example, to call a Russian number `[phone]` from US the dialled digits would be `01178005553535` where `011` is an "IDD prefix".
 
@@ -32,6 +32,14 @@ ### `default_idd_prefix`
 
-When several countries share the same country calling code, these "leading digits" are the means of determining which one of these countries does a phone number belong to. For example, Antigua and Barbuda have `leading_digits: "268"` and share `1` country calling code with USA, so if an international phone number starts with `+1268` then it belongs to Antigua and Barbuda.
+National (significant) number "leading digits" pattern. It's only defined for about 20% of the countries, most of which are countries sharing the same "country calling code". At the same time, two countries sharing the same "country calling code" doesn't necessarily imply that the "secondary" country has a `leading_digits` pattern defined.
 
-`leading_digits` does not contain all the prefixes valid for a country: for example, `800` numbers are valid for all [NANPA](https://en.wikipedia.org/wiki/North_American_Numbering_Plan) countries and are hence not listed here. `leading_digits` regular expression is used merely as a short-cut for working out which country a phone number comes from.
+For example, USA and Canada share the same `1` country calling code, but neither of them have a `leading_digits` pattern defined. On the other hand, Antigua and Barbuda also shares the same `1` country calling code, and its `leading_digits` pattern is `"268"`, so if an international phone number starts with `+1268` then it's certain that it belongs to Antigua and Barbuda, so "leading digits" are, in some cases, a means of determining which one of the countries sharing the same country calling code does a phone number belong to.
 
+While in most cases a `leading_digits` pattern is a sequence of digits like `"268"` for Antigua and Barbuda, in some cases it's a pattern like `"8001|8[024]9"` for Dominican Republic.
+
+Overall, `leading_digits` patterns are only used as a performance speed-up trick when determining which country a phone number belongs to, which is still simpler than looking for a match against precise phone number patterns of every country sharing a given country calling code.
+
+For that reason, matching a `leading_digits` pattern is a sufficient but not necessary condition for a phone number to belong to the country: if a `leading_digits` pattern exists and a phone number matches it that it's certain that the phone number belongs to the country, and no other country. But, if there's no `leading_digits` pattern, or if the phone number doesn't match it, then one can't say that the phone number doesn't belong to the country.
+
+For example, "toll free" numbers starting with `800` are valid for all countries having `1` country calling code, so it doesn't make sense to include `800` in their `leading_digits` patterns. But, at the same time, those "toll free" numbers could be thought of as an unrelated edge case that can be ignored if the application only deals with human phone numbers. But, at the same time, it doesn't necessarily mean that there're no other exceptions. So I'd say that `leading_digits` has a meaning of "most likely" rather than "necessarily".
+
 ### `national_number_pattern`
@@ -77,7 +85,7 @@
 
-#### `pattern`
+#### `type` `pattern`
 
 A regular expression for a national (significant) number matching the type.
 
-#### `possible_lengths`
+#### `type` `possible_lengths`
 
@@ -98,3 +106,3 @@ Possible lengths of a national (significant) number matching the type. Is always present.
 
-#### `pattern`
+#### `format` `pattern`
 
@@ -105,3 +113,3 @@ A regular expression for a phone number supported by this format.
 
-#### `format`
+#### `format` `format`
 
@@ -112,3 +120,3 @@ Defines how the aforementioned groups of digits are combined when formatting a phone number.
 
-#### `international_format`
+#### `format` `international_format`
 
@@ -119,3 +127,3 @@ Parentheses arond "area code" only make sense when formatting a national phone number, so international phone numbers don't use them, hence the explicit `international_format` in addition to the national `format`.
 
-#### `national_prefix_formatting_rule`
+#### `format` `national_prefix_formatting_rule`
 
@@ -126,7 +134,7 @@ `national_prefix_formatting_rule` is sometimes used to define how national prefix changes how a phone number should be formatted. For example, in Russia (national prefix `8`), all `format`s have `national_prefix_formatting_rule` `8 ($1)`, meaning that a `88005553535` phone number is first stripped of `8` national prefix into a `8005553535` national (significant) number, then the national (significant) number is first parsed using `format.pattern` `(\d{3})(\d{3})(\d{2})(\d{2})` and then formatted using `format.format` `$1 $2-$3-$4` while also replacing `$1` in that `format.format` with `format.national_prefix_formatting_rule` which is `8 ($1)`, so the resulting `format.format` becomes `8 ($1) $2-$3-$4`, and so the formatted number is `8 [phone]`. Have the phone number been input without the `8` national prefix, the `national_prefix_formatting_rule` wouldn't be applied, and `format.format` would stay `$1 $2-$3-$4`, and the formatted phone number would be `800 555-35-35`.
 
-#### `national_prefix_is_optional_when_formatting`
+#### `format` `national_prefix_is_optional_when_formatting`
 
 This field specifies whether the national prefix can be omitted when formatting a number in national format. For example, a UK (`GB`) number would be formatted by `libphonenumber` as `020 XXXX XXXX`. Have they seen this number commonly being written without the leading `0` (like `(20) XXXX XXXX`), they would have updated the metadata with `national_prefix_is_optional_when_formatting` being `true` for that `format`, so that such number, when formatted, wouldn't have `national_prefix_formatting_rule` applied to it. Otherwise, if `national_prefix_is_optional_when_formatting` is not set to `true`, `national_prefix_formatting_rule` is always applied (when present).
 
-#### `domestic_carrier_code_formatting_rule`
+#### `format` `domestic_carrier_code_formatting_rule`
 
@@ -137,3 +145,3 @@ Specifies how a carrier code (`$CC`) together with the first group (`$FG`) in a national significant number should be formatted, if carrier codes are used when formatting the number for dialing. For example, if a `format`'s `format` is `$1 $2-$3` and `domestic_carrier_code_formatting_rule` is `$NP $CC ($FG)`, then a national number, when having a carrier code, is formatted as `national-prefix carrier-code ($1) $2-$3`.
 
-#### `leading_digits_patterns`
+#### `format` `leading_digits_patterns`
 
@@ -140,0 +148,0 @@ "Leading digits" patterns are used in `AsYouType` formatter to choose a format suitable for the phone number being input: if a phone number's "leading digits" match those of a format, then that format is used to format the phone number being input. Each subsequent leading digits pattern in `leading_digits_patterns` array requires one more leading digit.

min/index.d.ts

 import {
-  Metadata,
+  MetadataJson,
   PhoneNumber,
@@ -15,2 +15,3 @@ E164Number,
   NumberFormat,
+  NumberingPlan,
   ValidatePhoneNumberLengthResult
@@ -22,3 +23,3 @@ } from '../types';
 export {
-  Metadata,
+  MetadataJson,
   PhoneNumber,
@@ -36,2 +37,3 @@ E164Number,
   NumberFormat,
+  NumberingPlan,
   ValidatePhoneNumberLengthResult
@@ -96,7 +98,11 @@ };
 
-// The exported `Metadata` name is already used for exporting the "raw" JSON metadata type.
-// Then, `Metadata` class has become exported, but its name is already taken, so TypeScript users seem to be unable to use the `Metadata` class.
-// If someone knows a solution then they could propose it in an issue.
-// export class Metadata {
-//   ...
-// }
+export class Metadata {
+  constructor(metadata: MetadataJson);
+  selectNumberingPlan(country: CountryCode): void;
+  // The `numberingPlan` property is declared without a `?`
+  // just so that TypeScript programmers don't have to add
+  // a needless `if (metadata.numberingPlan)` check:
+  // the `numberingPlan` property is only set after
+  // `selectNumberingPlan(country)` method has been called.
+  numberingPlan: NumberingPlan;
+}

package.json

 {
   "name": "libphonenumber-js",
-  "version": "1.9.26",
+  "version": "1.9.27",
   "description": "A simpler (and smaller) rewrite of Google Android's libphonenumber library in javascript",
@@ -5,0 +5,0 @@ "main": "index.common.js",

source/helpers/getCountryByCallingCode.js

@@ -31,3 +31,6 @@ import Metadata from '../metadata'
 		metadata.country(country)
-		// Leading digits check would be the simplest one
+		// Leading digits check would be the simplest and fastest one.
+		// Leading digits patterns are only defined for about 20% of all countries.
+		// https://gitlab.com/catamphetamine/libphonenumber-js/blob/master/METADATA.md#leading_digits
+		// Matching "leading digits" is a sufficient but not necessary condition.
 		if (metadata.leadingDigits()) {
@@ -34,0 +37,0 @@ if (nationalPhoneNumber &&

source/metadata.js

@@ -239,2 +239,3 @@ import compare from './tools/semver-compare'
 
+	// Is always present.
 	IDDPrefix() {
@@ -245,2 +246,3 @@ if (this.v1 || this.v2) return
 
+	// Is only present when a country supports multiple IDD prefixes.
 	defaultIDDPrefix() {
@@ -256,2 +258,3 @@ if (this.v1 || this.v2) return
 
+	// Is always present.
 	possibleLengths() {
@@ -258,0 +261,0 @@ if (this.v1) return

types.d.ts

@@ -26,3 +26,3 @@ // The rationale for having a separate `CountryCode` type instead of just a `string`:
 
-export type Metadata = {
+export type MetadataJson = {
   country_calling_codes: CountryCallingCodes;
@@ -44,3 +44,3 @@ countries: Countries;
 
-type FormatExtension = (formattedNumber: string, extension: Extension, metadata: Metadata) => string
+type FormatExtension = (formattedNumber: string, extension: Extension, metadata: MetadataJson) => string
 
@@ -61,3 +61,3 @@ type FormatNumberOptionsWithoutIDD = {
 export class PhoneNumber {
-  constructor(countryCallingCodeOrCountry: CountryCallingCode | CountryCode, nationalNumber: NationalNumber, metadata: Metadata);
+  constructor(countryCallingCodeOrCountry: CountryCallingCode | CountryCode, nationalNumber: NationalNumber, metadata: MetadataJson);
   countryCallingCode: CountryCallingCode;
@@ -98,4 +98,11 @@ country?: CountryCode;
 
+export interface NumberingPlan {
+  leadingDigits(): string | undefined;
+  possibleLengths(): number[];
+  IDDPrefix(): string;
+  defaultIDDPrefix(): string | undefined;
+}
+
 // The rationale for having a separate type for the result "enum" instead of just a `string`:
 // https://github.com/catamphetamine/libphonenumber-js/issues/170#issuecomment-363156068
 export type ValidatePhoneNumberLengthResult = 'INVALID_COUNTRY' | 'NOT_A_NUMBER' | 'TOO_SHORT' | 'TOO_LONG' | 'INVALID_LENGTH';

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

6367457

increased by0.12%

Lines of code

31639

increased by0.09%

Number of lines in readme file

1702

increased by2.16%

No dependency changes