feat: Added findNumbers feature

BREAKING CHANGE: Added core feature

Author: grantila

README.md

@@ -9,6 +9,8 @@
 
 This library is a pre-compiled version of Google's `libphonenumber`, with a slightly simpler interface. It has a minimal footprint - is by far the smallest libphonenumber-based library available on npmjs, and has no dependencies.
 
+Unlike libphonenumber, it includes a `findNumbers( )` function to find phone numbers in text.
+
 TypeScript typings are provided within the package.
 
 Uses libphonenumber v8.13.43
@@ -32,6 +34,9 @@ Uses libphonenumber v8.13.43
    - Dropped Node 12 support
  - v6:
    - Dropped Node 16 support
+ - v7:
+   - Added `findNumbers( )` feature, to find phone numbers in text
+   - Added support for _short_ numbers
 
 
 ## Comparison with other libraries
@@ -139,6 +144,7 @@ Note that an incorrect (invalid) phone number can still be a valid _short number
 ```ts
 import {
 	parsePhoneNumber,
+	findNumbers,
 	getNumberFrom,
 	getExample,
 	getCountryCodeForRegionCode,
@@ -157,6 +163,48 @@ import {
 The first argument is the phone number to parse, on either _national_ or _international_ (e164, i.e. prefixed with a `+`) form. If _national_ form, the second argument is required to contain a `regionCode` string property, e.g. 'SE' for Sweden, 'CH' for Switzerland, etc.
 
 
+### findNumbers
+
+
+To find (extract) phone numbers in text, use `findNumbers( )`:
+
+```ts
+import { findNumbers } from 'awesome-phonenumber'
+
+const text = 'My number is +46 707 123 456, otherwise call +33777777777.';
+const numbers = findNumbers( text );
+```
+
+The returned list of numbers is of the type `PhoneNumberMatch` such as:
+
+```ts
+interface PhoneNumberMatch
+{
+	text: string; // The raw string found
+	phoneNumber: object; // Same as the result of parsePhoneNumber()
+	start: number; // Start offset in the text
+	end: number; // End offset in the text
+}
+```
+
+A second options argument to `findNumbers( text, options )` can be provided on the form:
+
+```ts
+interface FindNumbersOptions
+{
+	defaultRegionCode?: string;
+	leniency?: FindNumbersLeniency;
+	maxTries?: number;
+}
+```
+
+where `FindNumbersLeniency` is an enum of `'valid'` or `'possible'`. The default is `'valid'` meaning that only valid phone numbers are found. If this is set to `'possible'` also possible (but invalid) phone numbers are found.
+
+`defaultRegionCode` can be set (e.g. to `'SE'` for Sweden), in which case phone numbers on _national_ form (i.e. without `+` prefix) will be found, as long as they are from that region.
+
+For really large texts, `maxTries` will set the maximum number of phone numbers to _try_ to find (not necessary actually find).
+
+
 ### getNumberFrom
 
 ```ts

index-esm.mjs

@@ -107,6 +107,60 @@ export function getRegionCodeForCountryCode( countryCode: number ): string;
 export function getSupportedCallingCodes( ): string[ ];
 export function getSupportedRegionCodes( ): string[ ];
 
+export type FindNumbersLeniency =
+	/**
+	 * Phone numbers accepted are possible, but not necessarily valid.
+	 */
+	| 'possible'
+	/**
+	 * Phone numbers accepted are possible and valid.
+	 */
+	| 'valid';
+
+export interface FindNumbersOptions
+{
+	/**
+	 * A default region code, to find local (non-e164) formatted phone numbers
+	 */
+	defaultRegionCode?: string;
+
+	/** Leniency options */
+	leniency?: FindNumbersLeniency;
+
+	/**
+	 * The maximum number of invalid numbers to try before giving up on the text
+	 */
+	maxTries?: number;
+}
+
+export interface PhoneNumberMatch
+{
+	/** The raw string found */
+	text: string;
+
+	/** The parsed phone number object */
+	phoneNumber: ParsedPhoneNumber;
+
+	/** Start offset of the found number */
+	start: number;
+
+	/** End offset of the found number */
+	end: number;
+}
+
+/**
+ * Find phone numbers in text.
+ *
+ * If the text is expected to have phone numbers for a certain region code,
+ * the option `defaultRegionCode` can be set. Phone numbers without the
+ * international prefix `+` will then be found too.
+ *
+ * Leniency can be specified using the `leniency` option, in which case
+ * `maxTries` needs to be set too.
+ */
+export function findNumbers( text: string, options?: FindNumbersOptions )
+	: PhoneNumberMatch[ ];
+
 /**
  * Get an example phone number, given a region code and a phone number
  * {@link PhoneNumberTypes type}.

index.d.ts

@@ -49,3 +49,4 @@ module.exports.getSupportedRegionCodes = module.exports.getSupportedRegionCodes;
 module.exports.getExample = module.exports.getExample;
 module.exports.getAsYouType = module.exports.getAsYouType;
 module.exports.getNumberFrom = module.exports.getNumberFrom;
+module.exports.findNumbers = module.exports.findNumbers;

index.js

@@ -6,6 +6,7 @@ const {
 	getRegionCodeForCountryCode,
 	getSupportedCallingCodes,
 	getSupportedRegionCodes,
+	findNumbers,
 	getExample,
 	getAsYouType,
 	getNumberFrom,
@@ -42,6 +43,7 @@ export {
 	getRegionCodeForCountryCode,
 	getSupportedCallingCodes,
 	getSupportedRegionCodes,
+	findNumbers,
 	getExample,
 	getAsYouType,
 	getNumberFrom,

lib/index.js

@@ -312,6 +312,43 @@ PhoneNumber.getRegionCodeForCountryCode = function( countryCode )
 	return regionCode;
 }
 
+/** @export */
+PhoneNumber.findNumbers = function( text, options )
+{
+	const defaultRegionCode = options?.[ 'defaultRegionCode' ];
+	const leniency = options?.[ 'leniency' ] ?? 'valid';
+	const maxTries = options?.[ 'maxTries' ] ?? Number.MAX_SAFE_INTEGER;
+
+	const re = /([0-9]+(?: [0-9]+)*)/g;
+	const res = [ ];
+	let m;
+	for ( let i = 0; i < maxTries; ++i )
+	{
+		m = re.exec( text );
+		if ( !m )
+			break;
+
+		let start = m.index;
+		const end = m.index + m[ 1 ].length;
+		if ( start > 0 && text.charAt( start - 1 ) === '+' )
+			--start;
+
+		const slice = text.slice( start, end );
+
+		const pn = new PhoneNumber( slice, { 'regionCode': defaultRegionCode } );
+
+		if ( pn.isValid( ) || ( leniency === 'possible' && pn.isPossible( ) ) )
+			res.push( {
+				'text': slice,
+				'phoneNumber': pn.toJSON( ),
+				'start': start,
+				'end': end,
+			} );
+	}
+
+	return res;
+}
+
 function uniq( arr )
 {
 	const lookup = { };

src/esm-outro.js

@@ -7,6 +7,7 @@ import PhoneNumberClass, {
 	getSupportedRegionCodes,
 	getSupportedCallingCodes,
 	getNumberFrom,
+	findNumbers,
 } from 'awesome-phonenumber';
 
 
@@ -379,6 +380,90 @@ describe( 'short numbers', ( ) =>
 	} );
 } );
 
+describe( 'find numbers', ( ) =>
+{
+	it( 'should not find in empty text', ( ) =>
+	{
+		const res = findNumbers( '' );
+		expect( res.length ).toBe( 0 );
+	} );
+
+	it( 'should not find in text without phone numbers', ( ) =>
+	{
+		const res = findNumbers( 'no numbers here 123, not even that' );
+		expect( res.length ).toBe( 0 );
+	} );
+
+	const textWithNumbers =
+		'the number is +46 707 123 456 fyi and 0707 555 555 also +11111111111.';
+
+	it( 'should find e164 numbers (default valid numbers)', ( ) =>
+	{
+		const res = findNumbers( textWithNumbers );
+		expect( res.length ).toBe( 1 );
+		expect( res[ 0 ].phoneNumber.number?.e164 ).toBe( '+46707123456' );
+		expect( res[ 0 ].start ).toBeGreaterThan( 0 );
+		expect( res[ 0 ].end ).toBeGreaterThan( res[ 0 ].start );
+	} );
+
+	it( 'should find e164 numbers (also possible numbers)', ( ) =>
+	{
+		const res = findNumbers( textWithNumbers, { leniency: 'possible' } );
+		expect( res.length ).toBe( 2 );
+		expect( res[ 0 ].phoneNumber.number?.e164 ).toBe( '+46707123456' );
+		expect( res[ 0 ].start ).toBeGreaterThan( 0 );
+		expect( res[ 0 ].end ).toBeGreaterThan( res[ 0 ].start );
+		expect( res[ 1 ].phoneNumber.number?.e164 ).toBe( '+11111111111' );
+		expect( res[ 1 ].start ).toBeGreaterThan( 0 );
+		expect( res[ 1 ].end ).toBeGreaterThan( res[ 1 ].start );
+	} );
+
+	it( 'should find e164 numbers', ( ) =>
+	{
+		const res = findNumbers( textWithNumbers, { defaultRegionCode: 'SE' } );
+		expect( res.length ).toBe( 2 );
+		expect( res[ 0 ].phoneNumber.number?.e164 ).toBe( '+46707123456' );
+		expect( res[ 0 ].start ).toBeGreaterThan( 0 );
+		expect( res[ 0 ].end ).toBeGreaterThan( res[ 0 ].start );
+		expect( res[ 1 ].phoneNumber.number?.e164 ).toBe( '+46707555555' );
+		expect( res[ 1 ].start ).toBeGreaterThan( 0 );
+		expect( res[ 1 ].end ).toBeGreaterThan( res[ 1 ].start );
+	} );
+
+	it( 'should find e164 numbers (and possible)', ( ) =>
+	{
+		const res = findNumbers(
+			textWithNumbers,
+			{ defaultRegionCode: 'SE', leniency: 'possible' },
+		);
+		expect( res.length ).toBe( 3 );
+		expect( res[ 0 ].phoneNumber.number?.e164 ).toBe( '+46707123456' );
+		expect( res[ 0 ].start ).toBeGreaterThan( 0 );
+		expect( res[ 0 ].end ).toBeGreaterThan( res[ 0 ].start );
+		expect( res[ 1 ].phoneNumber.number?.e164 ).toBe( '+46707555555' );
+		expect( res[ 1 ].start ).toBeGreaterThan( 0 );
+		expect( res[ 1 ].end ).toBeGreaterThan( res[ 1 ].start );
+		expect( res[ 2 ].phoneNumber.number?.e164 ).toBe( '+11111111111' );
+		expect( res[ 2 ].start ).toBeGreaterThan( 0 );
+		expect( res[ 2 ].end ).toBeGreaterThan( res[ 2 ].start );
+	} );
+
+	it( 'should find e164 numbers (and possible), max numbers', ( ) =>
+	{
+		const res = findNumbers(
+			textWithNumbers,
+			{ defaultRegionCode: 'SE', leniency: 'possible', maxTries: 2 },
+		);
+		expect( res.length ).toBe( 2 );
+		expect( res[ 0 ].phoneNumber.number?.e164 ).toBe( '+46707123456' );
+		expect( res[ 0 ].start ).toBeGreaterThan( 0 );
+		expect( res[ 0 ].end ).toBeGreaterThan( res[ 0 ].start );
+		expect( res[ 1 ].phoneNumber.number?.e164 ).toBe( '+46707555555' );
+		expect( res[ 1 ].start ).toBeGreaterThan( 0 );
+		expect( res[ 1 ].end ).toBeGreaterThan( res[ 1 ].start );
+	} );
+} );
+
 describe( 'getNumberFrom', ( ) =>
 {
 	it( 'Using weakmap', ( ) =>