phone-fns

A small modern, and functional phone number library which gathers inspiration from the fun date-fns library

• Documentation

How-To

Standard module system

import phoneFns from 'phone-fns'

Common JS

const phoneFns = require('phone-fns')

Through the browser

<script src="path/to/location/dist/phone-fns.min.js"></script>

Usage

In v1.0.0 of Phone-Fns the main import is used to create separate instances in order to make usage easier as well as the library smaller.

Basic usage can be done like so, this is without setting a country code for the instance we create.

import phoneFns from 'phone-fns'

const phoneLib = phoneFns()

phoneLib.breakdown('4443332222')
// => { countryCode: '', areaCode: '444', localCode: '333', lineNumber: '2222', extension: '' }

phoneLib.format('(NNN) NNN-NNNN', '4443332222')
// => '(444) 333-2222'

If you want to set a country code you can create an instance of the library around the country code like so.

import phoneFns from 'phone-fns'

const phoneLib = phoneFns('1')

phoneLib.breakdown('4443332222')
// => { countryCode: '1', areaCode: '444', localCode: '333', lineNumber: '2222', extension: '' }

phoneLib.format('N + (NNN) NNN-NNNN', '4443332222')
// => '1 + (444) 333-2222'

Methods

You can also bring in the functions individually if you want to.

uglify(phone)

uglifies the phone number down to just the number string

Arguments

• phone - String: the desired phone number to run against

Usage

import uglify from 'phone-fns/uglify'

uglify('555-444-1111') // => '5554441111'

format(cc, layout, phone)

Customized formatting function allowing you to create your own custom formats

If you are not using an instance of the setup you will have to provide a country code to the format function if you call it by itself.

Arguments

• cc - String: The country code to use (Only required if you call format individually)
• layout - String: The desired format to transform the number to
• phone - String: The desired phone number to run against

Usage

import format from 'phone-fns/format'

// Without a country code
format('', '(NNN) NNN-NNNN', '4443332222') // => '(444) 333-2222'

// With a country code
format('112', 'NNN + (NNN)-NNN.NNNN', '4443332222') // => '112 + (444)-333.2222'

// Extensions
format('', '(NNN).NNN.NNNN x NNNN', '44433322228989') // => '(444).333.2222 x 8989'

// Case insensitive
format('', '(nnn).nnn.nnNN', '4445556666') // => (444).555.6666

If format is called from the main function like so:

import phoneFns from 'phone-fns'

const lib = phoneFns()
const withCC = phoneFns('1')

// You no longer are able to pass a country code to format
lib.format('NNN.NNN.NNNN', 4445556666) // => 444.555.6666

withCC.format('N + NNN.NNN.NNNN', 4445556666) // => 1 + 444.555.6666

find(type, phone)

Find a piece of the phone number and return it

Arguments

• phone - String: the desired phone number to run against
• type - String: the piece of the phone number to return can be areaCode, localCode, lineNumber, countryCode, or extension

Usage

import find from 'phone-fns/find'

find('areaCode', '555-444-3333') // => '555'

find is also a curried function so we could also do

import find from 'phone-fns/find'

const finder = find('areaCode')

finder('4445556666') // => '444'
finder('5554443333') // => '555'

breakdown(countryCode, phone)

Takes the provided phone string and breaks it down into an object like so:

{
  countryCode: '',
  areaCode: '',
  localCode: '',
  lineNumber: '',
  extension: ''
}

Arguments

• countryCode - String: The country code to use (Only required if you call breakdown individually)
• phone - String: the desired phone number to run against

Usage

import breakdown from 'phone-fns/breakdown'

breakdown('', '555-444-3333') // => { countryCode: '', areaCode: '555', localCode: '444', lineNumber: '3333', extension: '' }

breakdown('112', '555-444-3333') // => { countryCode: '112', areaCode: '555', localCode: '444', lineNumber: '3333', extension: '' }

breakdown('', '555-444-33338989') // => { countryCode: '', areaCode: '555', localCode: '444', lineNumber: '3333', extension: '8989' }

breakdown is also a curried function so we can use it like so

import breakdown from 'phone-fns/breakdown'

const breaker = breakdown('')

breaker('555-444-3333') // => { countryCode: '', areaCode: '555', localCode: '444', lineNumber: '3333', extension: '' }

const ccBreaker = breakdown('1')

ccBreaker('555-444-3333') // => { countryCode: '1', areaCode: '555', localCode: '444', lineNumber: '3333', extension: '' }

isValid(phone)

Validates if the provided number is valid or not.

It is important to note that this only goes off the base phone number, it does NOT take extensions or country codes into consideration

Arguments

• phone - String: the desired phone number to run against

Usage

import isValid from 'phone-fns/isValid'

isValid('555-444-3333') // => true

isValid('8896') // => false

match(phoneOne, phoneTwo)

Checks if the two provided numbers are valid numbers and matching

Arguments

• phoneOne - String: the desired phone number to run against phoneTwo
• phoneTwo - String: the desired phone number to run against phoneOne

Usage

import match from 'phone-fns/match'

match('555-444-3333', '555-444-3333') // => true

match('555-444-3333', '555-333-4444') // => false

match is also a curried function so we can do something like this

import match from 'phone-fns/match'

const matcher = match('555-444-3333')

matcher('5554443333') // => true
matcher('555-444-3333') // => true
matcher('555-333-4444') // => false
matcher('8898') // => false