Changelog
v5.0.0
Breaking Changes
- Phone-Fns is no longer transpiled down to ES5 with Babel
- The bundles in
dist/now ship modern JavaScript - Internet Explorer and other legacy browsers are no longer supported out of the box. If you still need them, transpile
phone-fnsas part of your own build
- The bundles in
- Removed the deprecated
isValidfunction- Use
validateorisValidWithFormatinstead
- Use
breakdownnow reads the original input instead of only its digits- Extensions are only picked up when they have a marker:
x,ext,ext.,extension, or#- Trailing digits with no marker (e.g.
'55544433338989') no longer become an extension
- Trailing digits with no marker (e.g.
- A country code is picked up from a leading
+(1-3 digits), or from an 11 digit number that starts with1breakdown('+1 555-444-3333')now returnscountryCode: '1', areaCode: '555', ...instead ofareaCode: '155', ...
- Always returns a
countryCodekey (an empty string when there isn't one) - 7 digit numbers now return
areaCode: ''instead ofareaCode: undefined - Throws
The phone number provided could not be broken downfor input it can't handle (empty,null, too short or too long, or containing letters) instead of crashing with aTypeError
- Extensions are only picked up when they have a marker:
isValidWithFormat(and sobreakdownWithFormat) now strictly matches the formatisValidWithFormatuses the same placeholders asformat:Nfor numbers andCfor country code. Both must be digits. Previously onlyNwas checked, and a space would pass as a digit- Every other character in the format must match the phone number exactly, so
'555.444.3333'no longer passes'NNN-NNN-NNNN', and'+2 ...'no longer passes'+1 ...' breakdownWithFormatkeeps its ownC,A,L,N, andXplaceholders, and every one of them must now be a digit
uglifynow keeps every digit- It used to drop the first digit after any letter, e.g.
uglify('5554443333x123')returned'555444333323'; it now returns'5554443333123'
- It used to drop the first digit after any letter, e.g.
validatenow checks how the number is written instead of only its digits. It stays country neutral and doesn't apply any country specific numbering rules- Groups must be split by a single space, dot, or dash, so
'555--444-3333'and'-555-444-3333'are no longer valid - Parentheses must be balanced, used at most once, and wrap 1-4 digits, so
'(555 444-3333'is no longer valid - A
+must be the first character and be followed by a country code that doesn't start with0 - Numbers can be written in at most 6 groups, so
'5 5 5 4 4 4 3 3 3 3'is no longer valid - Extensions accept the same markers as
breakdown(x,ext,ext.,extension,#), can be up to 7 digits, and no longer count towards the 10-15 digit limit _placeholders are not valid
- Groups must be split by a single space, dot, or dash, so
formatno longer runs the phone number throughisValid- Any phone whose digit count matches the number of
C/Nplaceholders in the layout is formatted; otherwise it's returned unchanged, as before - Only
CandN(any case) count as placeholders in the layout, so layouts can contain other letters, e.g.'NNN-NNN-NNNN ext NNN'
- Any phone whose digit count matches the number of
formatalways returns a string- When a number is passed in that doesn't fit the layout it's now returned as a string (e.g.
format('NNN', 12345) // => '12345') instead of the original number
- When a number is passed in that doesn't fit the layout it's now returned as a string (e.g.
- TypeScript types are now generated from the source and describe the real exports
- The types no longer use
export =, soimport phoneFns from 'phone-fns'is now a type error. There has never been a default export at runtime, useimport * as phoneFns from 'phone-fns'or named imports instead Breakdowncan be imported as a type:import type { Breakdown } from 'phone-fns'- The
phoneFnsglobal for the IIFE (script tag) build is still declared
- The types no longer use
Breakdowntype:countryCodeis no longer optional
Changed
- Simplified the build: one Rollup config now produces the ESM, CommonJS, and IIFE bundles
- Bundle sizes are now reported by a small inline Rollup plugin instead of
rollup-plugin-filesize scripts/create-export.jsnow usesnode:fsinstead ofglobby- Type definitions are generated from the JSDoc in
src/instead of being written by hand- They are built into
dist/phone-fns.d.ts(ESM) anddist/phone-fns.d.cts(CommonJS), replacing thetypes/folder - Hovering any function in your editor now shows its full documentation and examples
- Curried functions keep their real parameter names in both forms, e.g.
format(layout)returns(phone) => string
- They are built into
breakdown,format,normalize,isValidWithFormat,uglify, andvalidatetypes now accept numbers as well as strings, matching what they already accepted at runtime
Fixed
maininpackage.jsonnow points at the CommonJS build, so tools that don't readexportscanrequirethe package again- The fallback
defaultcondition inexportsnow points at the ESM build instead of the IIFE build, which has no exports - Function descriptions in the docs now render their markdown (lists and inline code) via jsdoc's
plugins/markdown - Docs build now finds
changelog.mdon case-sensitive file systems (Linux), so the changelog appears in the generated docs again formatnow treats a lowercasecas a country code placeholder, as the docs already said it wouldnormalizeno longer crashes when given a numberbreakdownWithFormatdocumentation example showed the wrong output for its curried call
Chore
- Replaced
standardwithneostandard(ESLint 10 flat config)- Linting now covers
tests/,scripts/, and config files, not justsrc/
- Linting now covers
- Removed Babel (
@babel/core,@babel/preset-env,@rollup/plugin-babel,.babelrc) - Removed
rollup-plugin-filesize,@rollup/plugin-node-resolve,npm-run-all, andglobby - Replaced
tapeandtap-onwith Node's built-in test runner (node:testandnode:assert) - Updated
rollupto v4.68.5,@rollup/plugin-terserto v1.0.2,jsdocto v4.0.5, andc8to v12 - Updated
pinetto v2.0.0 - Added npm
overridessoc8uses patched versions ofglobandminimatch - Regenerated
package-lock.json, which clears the large majority of dev dependency security advisories - Added
typescriptv7 androllup-plugin-dtsto generate and bundle type definitions, with a roottsconfig.jsonnpm run buildnow type checkssrc/(checkJs+strict) before bundling, so type errors in the JSDoc fail the build@typescript/typescript6is also installed becauserollup-plugin-dtsneeds the TypeScript compiler API, which TypeScript 7 doesn't ship yetnpm run build:typescalls TypeScript 7 by path, since that package also installs an oldertsccommand that takes overnpx tsc
- JSDoc site generation now skips
src/_internalsandsrc/index.js, which use TypeScript only type syntax eslint.config.js,tsconfig.json, and.gitattributesare no longer published to npm- CI updates:
- Node matrix is now 22.x and 24.x (Node 18 and 20 are end-of-life)
- Updated
actions/checkout,actions/setup-node, andcodecov/codecov-actionto v7 - Uses
setup-node's built-in npm cache and always runsnpm ci - Added a build step, read-only workflow permissions, and a single coverage upload per run
- Pull requests into
developmentnow run CI as well - Removed the CodeQL workflow
v4.1.2
Fixed
- Documentation examples for
breakdownWithFormatfunction
Changed
- Updated
pinetto v1.2.1
v4.1.1
New
- Deprecated
isValidfunction in favor ofisValidWithFormat
Changed
- Reset codecov coverage report using
c8package - Updated unit tests for some more coverage
- Cleaned up some round about logic in the codebase
v4.1.0
New
- Added
normalizefunction- This function strips out special characters and trims the phone number, much like uglify but skips non-digit characters
- Example:
normalize('555.444.3333 x 123') // => '5554443333x123'vsuglify('555.444.3333 x 123') // => 5554443333123
- Added
validatefunction- This is a validation function, but works better for world wide phone numbers as well. Expects the full number
- Example:
333-444-5555comes back valid but444-5555is invalid to this function
- Added
isValidWithFormatfunction- This takes a string phone number and a format string and validates the phone using the format
- It's also passed through the
validatefunction for an extra step of validation
- Added
findSeparatorsfunction- A simple function that finds the separators in a phone number and returns them as an array
- Added
breakdownWithFormatfunction- Works a lot like
breakdownbut follows a strict format provided by the user to breakdown the number into an object - This allows for a wider range of phone number support for breakdown
- Works a lot like
Changed
Phone-fnsis no longer dependant onKyaniteand is dependency free!isValiddescription to explain that it mostly focused on NANP numbersbreakdowndescription to better explain that it's main focus is NANP numbers and its gachas- We more than doubled our unit tests! Woo!
Chore
- Renamed test files to
*.spec.jsinstead of just*.js
v4.0.2
Fixed
- Typo for extension in types #14 @JonBee
Chore
- Dependency Updates
v4.0.1
New
- Added more unit tests for
isValidandbreakdown
Fixed
- Added warning into README that currently phone-fns is focused on US based phone number styles
- Updated github action to LTS of node
Chore
- Updated dependencies
v4.0.0
Breaking Changes
- Converted Phone-Fns to a standard ESM module
- This means if you are using import statements in an ESM module for phone-fns this changes:
import phoneFns from 'phone-fns'-->import * as phoneFns from 'phone-fns'- You can also just destructure from here still like so:
import { isValid } from 'phone-fns'
- Phone fns should still support common js syntax out of the box as well
- This means if you are using import statements in an ESM module for phone-fns this changes:
- Upgraded to
Kyanite v2.0.1
New
- CDN support sould be working for phone-fns again
- Updated README to reflect these changes
Improved
- Made typings less confusing
v3.2.5
:confetti_ball: Enhanced
- Added: New github flows and files
v3.2.4
Improved
- Audited packaged
- Replaced
tap-specwithtap-on - Optimized ignore files
- Removed dist from repo
v3.2.3
New
- Switched over to pinet jsdoc templating
- Changed documentation hosting
Improved
- All dependencies have been updated
- Removed docs folder
- Removed david-dm badge since it doesn't seem to be coming back
- Documentation workflow now handled by circleci
formatcan now take inNumbertype phone numbers
v3.2.2
- Dev dependency fixes
v3.2.1
Improved
- Dependency updates
- Unit tests
- Optimization of some code pieces
- Some documentation
v3.2.0
New
- Added new Placeholder support
v3.1.0
Improved
- Switched to internal currying
- Improved
formats performance and broke it down to a more intelligent function
Fixed
- Typo in
formats example - Remove unused code
v3.0.0
Breaking Changes
- Removed
findfunction since it was rather pointless - Removed
matchfunction since it was rather pointless - The main import is no longer a function but an object of functions
- Re wrote how format works so it's easier to use and more light weight
- Specify country code in the layout with C. Example:
C + (NNN) NNN-NNNN - Usage example:
format('C + (NNN) NNN-NNNN', 14445556666) // => '1 + (444) 555-6666'
- Specify country code in the layout with C. Example:
breakdownno longer handles or accepts country codes- Technically the only function that cares about Country Codes is the
formatfunction this is to make functions easier to use
- Technically the only function that cares about Country Codes is the
- Scrapped modular functions
- There is no need for this anymore, since Rollup & webpack v2+ treeshaking support curried functions, destructing works much better now
New
- Documentation was moved onto a more sustainable location for quicker and more up to date docs, should be hosted via github pages now too
Improved
- Using Kyanite to improve how format functions and better currying from the library
- Replaced
uglify-jswithterserfor performance gains isValidoptimizations using Kyanite- Overall documentation system should be built directly into its own page now
- Added Typing declarations for TS and vscode IDE support
v2.0.1
Improved
- A new script system in place for generating library documentation to make it easier for the main site to pull in the latest documentation
v2.0.0
BREAKING CHANGES
- The API usage for
formatis now different, you only need to use the letterNin your layout now in the order you want the numbers to fill in- The letter
Nis case insensitive - Example: an old layout may have looked like:
(AAA) LLL-NNNNnow it is:(NNN) NNN-NNNNor(nnn) nnn-nnNNif you wanted to get creative
- The letter
New
findhas been deprecated and may be removed in later versions, please transition tobreakdown- Added a 2nd validation level to
formatit will now validate the phone number has enough digits to fill out the layout properly - You can now pass country code as a number or string
Fixed
- JSdocs for format were backwards
- Able to properly handle numbers without an area code now
v1.0.1
New
- Rebuilt the architecture of the main source (has no effect on usage)
- Added in CDN info to documentation
- Building using Rollup now instead of webpack decreasing the overall file size of our main file to 1.86kb (vs 3.83kb with webpack) and 970B gzipped
- This also benefits each individual functions build so they're also much smaller
- Converting testing to latest babel versions
- Convert linter from
eslinttostandardjs - Created an uncompressed build along with the compressed one which you can use in dev for easier debugging
Fixed
- For some reason I didn't realize the package.json main was looking at a index.js file
- Re built automated documentation script so it performs faster
v1.0.0
v1.0.0 is almost a total re write of how the library functions from v0.3.3 it is advised you migrate with caution
BREAKING CHANGES
- Removed
findLocalfunction - Removed
getCodefunction - Removed
getCountriesfunction - Removed
getCountryCodefunction - Removed
callingCodes - Changed
identicaltomatch - Re org of entire library
- You can now create instances of the library with different country codes or none
- This applies the country code to each method that needs it meaning you don't need to send it as a param
- Changed the parameter of most of the functions
- If using the individual functions you will have to provide a country code to those that need it
findparameters have been rotated
New
- Added the ability to call
phoneFnsas a function and provide a country code to create an instance around that country code, or not for only base phone number functionality - The
formatfunction is now curried - The
findfunction is curried as well
Improved
- The
breakdownfunction to be a little more lightweight - The
formatfunction to be a bit more lightweight and functional - The
isValidfunction to do decently better phone number validation
v0.3.3
- Fix for automating docs file
- Build files should appear again
v0.3.2
- Better(working) fix for webpack builds issue
- Better Main JS generator
v0.3.1
- Fix for Webpack build issues when importing base module
- README typo fixes
v0.3.0
- Consistancy Tweaks in some files
- Changed
getCodetogetCountryCode
- Notice that this now means
getCodeis depricated- This is not yet a breaking change but may be in the future (1.0.0 release probably)
- Changed
findLocaltogetCountries
- Notice that this now means
findLocalis depricated- This is not yet a breaking change but may be in the future (1.0.0 release probably)
- Introduced webpack as the builder to help build out the public module
- This shouldn't have any large effects, if you do see an issue please let me know asap!
- Updated all dependencies
- Text Tweaks in some error messages
v0.2.0
- Tweaks to build process
- Added ability to call functional methods individually you can do so using the following:
phone-fns/formatphone-fns/findphone-fns/breakdownphone-fns/identicalphone-fns/isValidphone-fns/uglifyphone-fns/getCodephone-fns/findLocalphone-fns/callingCodes- Gives back the full list of country calling codes- You can still use just
phone-fnsto get back all of the methods in anobject- Added a minified version
phone-fns.min.jsthe module points to this version by default- Renamed the file
phone-fns.umd.jsto justphone-fns.js- Added Country Calling Codes from the Countries Repo
- Added
findLocalfunction which returns the country names associated with the passed in code- Added
getCodefunction which returns the country calling code from thejson- Removed country code dashing, since it's not really a thing
v0.1.0
- Initial Public Release