v4.1.0

changelog.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## v4.1.0
+
+### New
+
+- Added `normalize` function
+  - 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'` vs `uglify('555.444.3333 x 123') // => 5554443333123`
+- Added `validate` function
+  - This is a validation function, but works better for world wide phone numbers as well. Expects the full number
+  - Example: `333-444-5555` comes back valid but `444-5555` is invalid to this function
+- Added `isValidWithFormat` function
+  - This takes a string phone number and a format string and validates the phone using the format
+  - It's also passed through the `validate` function for an extra step of validation
+- Added `findSeparators` function
+  - A simple function that finds the separators in a phone number and returns them as an array
+- Added `breakdownWithFormat` function
+  - Works a lot like `breakdown` but 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
+
+
+### Changed
+
+- `Phone-fns` is no longer dependant on `Kyanite` and is dependency free!
+- `isValid` description to explain that it mostly focused on NANP numbers
+- `breakdown` description 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.js` instead of just `*.js`
+
 ## v4.0.2
 
 ### Fixed

package.json

@@ -1,6 +1,6 @@
 {
   "name": "phone-fns",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "description": "A small, modern, and functional phone library for javascript",
   "main": "dist/phone-fns.min.js",
   "module": "src/index.js",
@@ -11,10 +11,10 @@
   "scripts": {
     "prepack": "npm-run-all --parallel docs scripts lint test --serial build",
     "scripts": "node scripts/create-export.js",
-    "docs": "node_modules/.bin/jsdoc -c jsdoc.json",
+    "docs": "jsdoc -c jsdoc.json",
     "build": "rollup -c",
     "lint": "standard src/**/*.js",
-    "test": "tape tests/*.js | tap-on"
+    "test": "tape tests/*.spec.js | tap-on"
   },
   "exports": {
     ".": {
@@ -35,7 +35,8 @@
   "standard": {
     "ignore": [
       "docs/*",
-      "dist/*"
+      "dist/*",
+      "types/*"
     ]
   },
   "repository": {
@@ -71,14 +72,11 @@
     "globby": "13.2.2",
     "jsdoc": "4.0.3",
     "npm-run-all": "4.1.5",
-    "pinet": "1.1.5",
+    "pinet": "1.2.0",
     "rollup": "4.24.0",
     "rollup-plugin-filesize": "10.0.0",
     "standard": "17.1.2",
     "tap-on": "1.0.0",
     "tape": "5.9.0"
-  },
-  "dependencies": {
-    "kyanite": "3.1.0"
   }
 }

src/_internals/_hasPlaceholder.js

@@ -0,0 +1,9 @@
+/**
+ * @private
+ * @function
+ * @param {String} str The string to check for placeholders
+ * @returns {Boolean} Whether or not the string has a placeholder
+ */
+export default function _hasPlaceholder (str) {
+  return str.includes('_')
+}

src/_internals/_uglifyFormats.js

@@ -0,0 +1,9 @@
+/**
+ * @private
+ * @function
+ * @param {String} str The string to strip special characters
+ * @returns {String} The newly created string with special characters stripped
+ */
+export default function _uglifyFormats (str) {
+  return str.replace(/[^a-wyz]/gi, '')
+}

src/breakdown.js

@@ -6,7 +6,7 @@ import uglify from './uglify.js'
  * @function
  * @category Function
  * @sig String -> String -> Object
- * @description Takes a provided phone string and breaks it down into an object of codes
+ * @description Takes a provided phone string and breaks it down into an object of codes only works loosely for NANP numbers. The gatcha here is that NANP numbers take the form of NXX NXX XXXX where N is a digit from 2-9 and X is a digit from 0-9, but in order to support placeholders we use a [_0-9]{3} check
  * @param {String} phone The phone number to breakdown
  * @return {Object} Returns an object of the broken down phone number
  *

src/breakdownWithFormat.js

@@ -0,0 +1,67 @@
+import _curry2 from './_internals/_curry2.js'
+import isValidWithFormat from './isValidWithFormat.js'
+
+/**
+ * @name breakdownWithFormat
+ * @since v4.1.0
+ * @function
+ * @category Function
+ * @sig String -> String -> Object
+ * @description
+ * Breaks down a phone number based on a custom format provided and returns an object with the parts of the phone number
+ * C - Country Code A- Area Code L - Local Code N - Line Number X - Extension
+ * Does NOT work with placeholders
+ * @param {String} format The format to validate against
+ * @param {String} phone The phone number to breakdown
+ * @return {Object} Returns an object with the parts of the phone number
+ * @example
+ * import { breakdownWithFormat } from 'phone-fns'
+ *
+ * breakdownWithFormat('+C (AAA) LLL-NNNN xXXX', '+1-555-444-3333 x123') // => { countryCode: '1', areaCode: '555', localCode: '444', lineNumber: '3333', extension: '123' }
+ * breakdownWithFormat('AAA-LLL-NNNN', '010-XYZ-1234') // => Error: The phone number provided does not match the format provided or is an invalid phone number
+ *
+ * // it's also curried
+ * const fn = breakdownWithFormat('+C (AAA) LLL-NNNN xXXX')
+ * fn('+1-555-444-3333 x123') // => { countryCode: '', areaCode: '123', localCode: '456', lineNumber: '7890', extension: '' }
+ */
+function breakdownWithFormat (format, phone) {
+  if (!format) {
+    throw new Error('You must provide a format to breakdown')
+  }
+
+  if (!isValidWithFormat(format, phone)) {
+    throw new Error('The phone number provided does not match the format provided or is an invalid phone number')
+  }
+
+  const results = {
+    countryCode: '',
+    areaCode: '',
+    localCode: '',
+    lineNumber: '',
+    extension: ''
+  }
+
+  for (let i = 0; i < format.length; i++) {
+    switch (format[i]) {
+      case 'C':
+        results.countryCode += phone[i]
+        break
+      case 'A':
+        results.areaCode += phone[i]
+        break
+      case 'N':
+        results.lineNumber += phone[i]
+        break
+      case 'L':
+        results.localCode += phone[i]
+        break
+      case 'X':
+        results.extension += phone[i]
+        break
+    }
+  }
+
+  return results
+}
+
+export default _curry2(breakdownWithFormat)

src/findSeparators.js

@@ -0,0 +1,30 @@
+/**
+ * @name findSeparators
+ * @since v4.1.0
+ * @function
+ * @category Function
+ * @sig String -> Array
+ * @description
+ * Finds a list of separators in a phone number string
+ * @param {String} phone The phone number to breakdown
+ * @return {Array} Returns an array of separators found in the phone number
+ * @example
+ * import { findSeparators } from 'phone-fns'
+ *
+ * findSeparators('123-456-7890') // => ['-']
+ * findSeparators('123.456.7890') // => ['.']
+ * findSeparators('123 456 7890') // => [' ']
+ * findSeparators('1234567890') // => []
+ */
+function findSeparators (phone) {
+  const separators = ['-', '.', ' ']
+  const foundSeparators = []
+  for (const separator of separators) {
+    if (phone.includes(separator)) {
+      foundSeparators.push(separator)
+    }
+  }
+  return foundSeparators
+}
+
+export default findSeparators