npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

node-phone-utils

v2.1.1

Published

Phone number utils library

Downloads

20

Readme

node-phone-utils

Circle CI Codacy Badge Coverage Sqale NPM

##Description

A well documented and test rich Node.js library for parsing, validating, formatting phone numbers and doing HLR lookups of phone numbers via specific or custom HLR lookup providers.

Install

npm i node-phone-utils

or from github

npm i dial.once/node-phone-utils

##Included functions

Out of the box this library offers the ability to perform action on one or more (array) phone numbers and they are:

  • isValid
  • isMobile
  • toE164
  • toNationalNumber
  • getType
  • getCountryCode
  • hlrLookup
  • asyncHlrLookup

##Examples

Validate phone number(s)

  var phoneNumberUtils = require('phone-number-utils').createInstance();
  var testPhoneNumber = '+336844321'; //e164 formatted number
  var isValid = phoneNumberUtils.isValid(testPhoneNumber);

  if (isValid) {
    console.info(phoneNumberUtils.toNationalNumber(testPhoneNumber));
  }

  // validate a bunch of phone numbers

  var results = phoneNumberUtils.isValid(['e164PhoneNum1', 'e164PhoneNum2']);
  var validPhoneNumbers = results.filter(function(result) {
    return result.isValid;
  })
  .map(function(result) {
    return result.number;
  });

  // print all valid phone numbers in national number form
  console.info(phoneNumberUtils.toNationalNumber(validPhoneNumbers));

Check if phone number(s) are mobile

  var phoneNumberUtils = require('phone-number-utils').createInstance();
  var testPhoneNumber = '+336844321'; //e164 formatted number
  var isMobile = phoneNumberUtils.isMobile(testPhoneNumber);

  if (isMobile) {
    console.info(phoneNumberUtils.toNationalNumber(testPhoneNumber));
  }

  // check a bunch of phone numbers
  var results = phoneNumberUtils.isMobile(['e164PhoneNum1', 'e164PhoneNum2']);
  var mobilePhoneNumbers = results.filter(function(result) {
    return result.isMobile;
  })
  .map(function(result) {
    return result.number;
  });;

  // print all mobile phone numbers in national number form
  console.info(phoneNumberUtils.toNationalNumber(mobilePhoneNumbers));

For more examples of other functions offered by thi library take a look at the test file here.

##Documentation

To generate fresh documentation (JSDoc) run

npm docs

and see it in the docs folder.

##Testing To start tests

npm test

##Coverage

To start istanbul coverage

npm cover

##JShint

To start jshint linting

npm jshint

##HLR Lookup Providers

Node-phone-utils uses a set of providers to do hlrLookup of phone numbers.

###Included providers

These are few included providers that come with this lib and work out of the box. They are:

  1. Hlr-lookups.com provider - a provider to get phone number data from hlr-lookups.com.
  2. Smsapi.com provider - a provider to get phone number data from smsapi.com.

Example: HlR-Lookups

  var phoneNumberUtils = require('phone-number-utils').createInstance();
  var hlrProvider = phoneNumberUtils.getProviders().hlrLookups;

  phoneNumberUtils
    .hlrLookup(<phoneNumber>, hlrProvider)
    .then(function(result){
      //handle result
    })
    .catch (function(err){
     //handle error
   });

####Example: SMSApi

  var phoneNumberUtils = require('phone-number-utils').createInstance();
  var smsApiHlrProvider = phoneNumberUtils.getProviders().smsApi;

  phoneNumberUtils
    .hlrLookup(<phoneNumber>, smsApiHlrProvider)
    .then(function(result){
      //handle result
    })`
    .catch (function(err){
     //handle error
   });

###Provider account(s)

Provider account information is required to perform HLR lookups and is set in .env file. Configuration and authentication details should be set up in your .env file. Example of an .env file with descriptions can be seen in .env.tpl file.

###Build your own provider

To plugin in your provider you only need to supply an object with a name property and hlrLookup function to node-phone-utils. You can use built in hlr-lookups-provider or sms-api--provider as references for building your own providers.

####Example:

var mySimpleProvider = {
  name: 'myProvider' ,
  hlrLookup: function (number) {
    // do your lookup stuff, feel free to return a promise
    //e.g. like this:
    return {
      number: number ,
      mcc: 12 ,
      mnc: 332
    }
  }
};

var phoneNumberUtils = require('phone-number-utils').createInstance();

phoneNumberUtils
.hlrLookup('1234567899' , mySimpleProvider)
.then(function (result) {
  //handle result
})
.catch(function (err) {
  //handle error
});

Async (bulk) HLR lookup of phone numbers

To do a lookup of a larger number of phone numbers it is recommended to use the async lookup feature of this library. Currently only hlr-lookups.com provider is supported.

To use this feature, take a look at the reference implementation example in server.js file. Since generally hlr lookups cost, this library stores any previous lookup results (per hlr lookup provider) and reuses them to minimize calls to the lookup provider. Also, phone numbers are validated prior to lookup and removed from async lookup if they are not valid E164 formatted numbers.

####Example:

// look into tests/integration/helpers/server.js for full imlpementation
var cacheManager = require('cache-manager');
var phoneUtils = require('phone-number-utils').createInstance();

var cacheStore = cacheManager.multiCaching([cacheManager.caching({
  store: 'memory',
  max: 20000,
  ttl: 5778463 //six months
})]);

var options = {
  provider: phoneUtils.getProviders().hlrLookups,
  callbackUrl: '<callbackURL>',
  callbackIdQSParam: 'id',
  cache: cacheStore,
  lookupTimeout: 180,  //seconds
  resultCallback: function (err, results) {
    //a result was processed and available
    console.info('resultCallback', err, results);
    return results;
  },
  doneCallback: function (err, results) {
    // do what you need when the entire lookup is done.
    console.info('doneCallback', err, results);
    return results;
  }
};

var utils = phoneUtils.getAsyncHlrLookup(options);
var client = utils.lookupClient; // ue client to issue async hlr lookups
var callbackMiddleware = utils.lookupMiddleware; // register this middleware to <callbackURL> on your server

// send a big array with the client
var phoneNumbers = ['+33102030', '+33102030', '...']
client
  .hlrLookup(phoneNumbers, options.callbackUrl)
  .then(function (numbers) {
    console.info('Numbers sent to hlr processing', numbers);
  })
  .catch(console.error);

##License Distributed under MIT license.

##Contribution

As always, contributions are most welcome. Fork -> work -> create PR