---

The Complete Guide to Phone Number Validation in CoffeeScript

This guide provides a comprehensive walkthrough for building a robust phone number validator in CoffeeScript. You will learn to clean, parse, and validate North American Numbering Plan (NANP) numbers using regular expressions, handling diverse user formats and edge cases to ensure data integrity for applications like SMS gateways.

You’ve just been handed a raw dataset of user-submitted contact information. It’s a mess. Some phone numbers have parentheses, others have dashes, some are prefixed with a country code, and a few are just plain gibberish. Your task is to build a system that can make sense of this chaos, filtering the valid from the invalid and standardizing the format. It feels like a daunting task, but it’s a critical one for any application that relies on clean, reliable user data.

This is a common challenge for developers. Poor data quality can lead to failed SMS notifications, frustrated users, and broken communication channels. In this deep-dive guide, we'll walk you through the entire process of building a powerful phone number cleaning and validation class in CoffeeScript. You'll move from a state of data chaos to one of structured, reliable order, mastering essential regular expression techniques along the way.

---

What is NANP Phone Number Validation?

Phone number validation is the process of verifying that a given string of characters constitutes a valid, callable phone number. This process is far more complex than simply checking if the string contains digits. It involves understanding specific formatting rules, country codes, and structural standards. For this guide, we focus on the North American Numbering Plan (NANP).

The NANP is the telephone numbering system for the United States, Canada, and many Caribbean countries. All numbers under this plan share the international country code +1. A standard NANP number is a 10-digit sequence broken into three parts:

• Numbering Plan Area (NPA) Code: The first three digits, commonly known as the "area code."
• Central Office (NXX) Code: The next three digits, also called the "exchange code."
• Line Number (XXXX): The final four digits.

The goal of our validator is to take any user input, strip away non-essential characters like (, ), -, ., and spaces, and then check if the remaining digits conform to the NANP structure. This ensures that the final, cleaned number is a 10-digit string ready for use in a database or an SMS API.

  ● User Input
  │  e.g., "(223) 456-7890"
  ▼
┌───────────────────┐
│ Sanitize & Clean  │
│ (Remove non-digits) │
└─────────┬─────────┘
          │
          ▼
    ◆  Is Length 10?
   ╱        ╲
 Yes         No ───▶ ◆ Is Length 11 and starts with '1'?
 │                   ╱        ╲
 ▼                 Yes         No
┌───────────────┐    │           │
│  Valid Number │    ▼           ▼
│ "2234567890"  │  ┌──────────────────┐  ┌───────────────┐
└───────────────┘  │ Strip '1', Valid │  │ Invalid Number│
                   └──────────────────┘  └───────────────┘
          │
          ▼
    ● System Ready

---

Why is Cleaning Phone Numbers So Challenging?

The primary challenge stems from human behavior and the lack of a universally enforced input format. Users will enter their phone numbers in whatever way seems most natural to them, leading to a huge variety of formats. A system must be robust enough to handle all of these variations gracefully.

Consider the valid ways a user might write the same number:

• 2234567890
• 223.456.7890
• 223-456-7890
• (223) 456-7890
• 1 223 456 7890
• +1 (223) 456-7890

Furthermore, a robust validator must also identify and reject clearly invalid inputs. These can include:

• Incorrect number of digits: Numbers with fewer than 10 digits or more than 11 (if including the country code).
• Invalid characters: The presence of letters or disallowed punctuation (e.g., @, !, :).
• Incorrect country code: An 11-digit number that does not start with 1.

Without a systematic cleaning process, attempting to store or use this data would result in errors, failed deliveries, and a corrupted database. The solution lies in a multi-step approach: first, check for illegal characters; second, strip all formatting; and third, validate the length and structure of the remaining digits.

---

How to Implement a Phone Number Cleaner in CoffeeScript

We will build a PhoneNumber class in CoffeeScript. This object-oriented approach encapsulates the validation logic, making it reusable and easy to manage. The class will take a raw string as input in its constructor and provide a clean() method that returns the standardized 10-digit number or throws an error if the input is invalid.

This implementation follows a clear, logical flow: check for obvious errors first (fail-fast), then perform the cleaning, and finally, apply the structural rules.

Step 1: The Class Structure

CoffeeScript's syntax allows for a very concise class definition. We'll start by defining a PhoneNumber class that accepts a number string in its constructor.

class PhoneNumber
  constructor: (@number) ->
    # The raw input string is stored in the instance variable @number

The @number syntax is a CoffeeScript shorthand that automatically assigns the constructor argument to an instance property of the same name (this.number in JavaScript).

Step 2: Pre-validation and Sanitization

Before we start stripping characters, it's efficient to first check for inputs that are fundamentally invalid. We'll reject any string containing letters or forbidden punctuation. This is a classic "fail-fast" strategy.

We use regular expressions with the match() method for this check.

• Rejecting Letters: The regex /[a-zA-Z]/ checks for the presence of any alphabetic character. If a match is found, the number is invalid.
• Rejecting Punctuations: We can define a set of disallowed punctuation. The regex /[@:!]/g checks for characters like @, :, or !.

# Inside the clean method
clean: ->
  if @number.match /[a-zA-Z]/
    throw new Error "letters not permitted"
  else if @number.match /[@:!]/g
    throw new Error "punctuations not permitted"

  # ... more logic to come

Throwing an Error is the appropriate action here, as it signals a critical failure in validation that the calling code must handle.

Step 3: Stripping All Non-Digit Characters

Once we've confirmed the input doesn't contain illegal characters, the next step is to remove all formatting. We want to isolate the digits to analyze their structure. The replace() method with a global regular expression is perfect for this.

The regex /[^\d]/g is the key. Let's break it down:

• [ ]: A character set.
• ^: When inside a character set, this is a negation operator. It means "match anything NOT in this set."
• \d: A shorthand character class that matches any digit (0-9).
• g: The global flag, which ensures that all occurrences are replaced, not just the first one.

So, /[^\d]/g means "find every character that is not a digit." We replace these matches with an empty string ''.

# Continuing the clean method
@cleanNumber = @number.replace /[^\d]/g, ''

After this line, a string like "+1 (223) 456-7890" becomes "12234567890".

Step 4: Validating Length and Country Code

Now that we have a string of pure digits, we can apply the core NANP rules based on its length.

Condition	Rule	Action
Length is 11	Must start with the digit '1' (the country code).	If it starts with '1', strip it and keep the remaining 10 digits. Otherwise, throw an error.
Length is 10	This is a valid NANP number without a country code.	Accept as is. This is our target format.
Length > 11	Too long to be a valid NANP number.	Throw an error.
Length < 10	Too short to be a valid NANP number.	Throw an error.

This logic translates directly into a series of conditional checks in CoffeeScript:

if @cleanNumber.length == 11 and @cleanNumber[0] != '1'
  throw new Error "11 digits must start with 1"
else if @cleanNumber.length == 11
  @cleanNumber = @cleanNumber.slice 1 # Remove the leading '1'
else if @cleanNumber.length > 11
  throw new Error "more than 11 digits"
else if @cleanNumber.length < 10
  throw new Error "incorrect number of digits"

# If we pass all checks, @cleanNumber is a valid 10-digit string
return @cleanNumber

By combining these steps into a single clean method, we create a powerful and reliable validation tool.

---

Code Walkthrough: The Complete Solution Explained

Let's assemble all the pieces into the final PhoneNumber class and walk through the complete code. This implementation, part of the exclusive CoffeeScript learning path on kodikra.com, demonstrates a clean, object-oriented approach to solving the problem.

# The PhoneNumber class is designed to parse and validate NANP numbers.
class PhoneNumber
  # The constructor takes a raw string input and stores it.
  # The '@' symbol is CoffeeScript shorthand for creating an instance property.
  # So, `new PhoneNumber("123")` creates an object with `this.number = "123"`.
  constructor: (@number) ->

  # The clean method performs the core validation and formatting logic.
  # It returns a 10-digit string if valid, or throws an Error if not.
  clean: ->
    # Step 1: Reject inputs with any alphabetic characters.
    # The regex /[a-zA-Z]/ matches any character from a-z, case-insensitive.
    # If a match is found, the input is invalid.
    if @number.match /[a-zA-Z]/
      throw new Error "letters not permitted"

    # Step 2: Reject inputs with specific, disallowed punctuation.
    # The regex /[@:!]/g finds any occurrence of '@', ':', or '!'.
    # The 'g' flag ensures it checks the whole string.
    else if @number.match /[@:!]/g
      throw new Error "punctuations not permitted"

    # Step 3: Strip all non-digit characters to isolate the numbers.
    # The regex /[^\d]/g matches any character that is NOT a digit (\d).
    # The replace() function removes them by replacing them with an empty string.
    # Example: "(123) 456-7890" becomes "1234567890".
    @cleanNumber = @number.replace /[^\d]/g, ''

    # Step 4: Validate the length and structure of the cleaned number.

    # Case A: 11 digits. This is only valid if it's a US number with a country code.
    if @cleanNumber.length == 11 and @cleanNumber[0] != '1'
      # An 11-digit number that doesn't start with '1' is invalid.
      throw new Error "11 digits must start with 1"
    else if @cleanNumber.length == 11
      # If it's 11 digits and starts with '1', strip the country code.
      # .slice(1) returns a new string from the second character to the end.
      @cleanNumber = @cleanNumber.slice 1
    
    # Case B: More than 11 digits. This is always invalid for NANP.
    else if @cleanNumber.length > 11
      throw new Error "more than 11 digits"

    # Case C: Less than 10 digits. This is always invalid.
    else if @cleanNumber.length < 10
      throw new Error "incorrect number of digits"

    # If none of the error conditions were met, the number is a valid 10-digit string.
    # It has either been validated as 10 digits or stripped from a valid 11-digit string.
    return @cleanNumber

Optimizations and Modern JavaScript (ES6+) Perspective

The provided CoffeeScript solution is clean and effective. When transpiled to JavaScript, it works perfectly. However, if we were writing this from scratch today using modern ES6+ JavaScript, we might structure it slightly differently for enhanced readability and robustness. We could use a chain of .replace() calls or a more comprehensive single regex.

Here's how a modern ES6+ JavaScript version might look:

class PhoneNumber {
    constructor(inputString) {
        this.rawInput = inputString;
    }

    clean() {
        if (/[a-zA-Z]/.test(this.rawInput)) {
            throw new Error('letters not permitted');
        }
        if (/[@:!]/.test(this.rawInput)) {
            throw new Error('punctuations not permitted');
        }

        const cleaned = this.rawInput.replace(/\D/g, ''); // \D is a shorthand for [^\d]

        if (cleaned.length === 11) {
            if (cleaned.startsWith('1')) {
                return cleaned.substring(1); // Return the last 10 digits
            } else {
                throw new Error('11 digits must start with 1');
            }
        }

        if (cleaned.length === 10) {
            return cleaned;
        }

        if (cleaned.length < 10) {
            throw new Error('incorrect number of digits');
        }
        
        if (cleaned.length > 11) {
            throw new Error('more than 11 digits');
        }
    }
}

This ES6 version is functionally identical but uses more explicit modern syntax like class, const, startsWith(), and substring(), which can be clearer to developers unfamiliar with CoffeeScript's shorthand. Understanding both helps bridge the gap between legacy and modern codebases. For more foundational knowledge, you can dive deeper into CoffeeScript fundamentals on our platform.

---

Where is this Pattern Used in Real-World Applications?

The logic we've built is not just a theoretical exercise; it's a fundamental pattern used in countless production systems. Data sanitization and validation are cornerstones of robust software engineering.

Here are some common applications:

• User Registration Forms: Ensuring a user provides a valid phone number during signup to be used for two-factor authentication (2FA) or account recovery.
• E-commerce Checkouts: Validating a shipping or billing phone number to ensure courier services can contact the customer.
• CRM and Data Import Tools: Cleaning up large datasets imported from spreadsheets or other systems to standardize contact information.
• SMS and Communication Platforms: Before attempting to send a message, an API gateway must validate that the destination number is correctly formatted to avoid failed sends and unnecessary costs.
• Contact Management Apps: Automatically formatting phone numbers as a user types them in, providing a clean and consistent user experience.

While our custom validator is excellent for the specific NANP rules, real-world global applications often turn to comprehensive libraries like Google's libphonenumber (and its JavaScript port, libphonenumber-js). These libraries contain extensive metadata about numbering plans for almost every country in the world, handling complex rules far beyond the scope of NANP. However, the core principle remains the same: sanitize, strip, and validate.

  ● NANP Number Structure
  │
  ├─▶ Country Code (Optional for domestic)
  │   └── "1"
  │
  ├─▶ Area Code (NPA)
  │   ├── First 3 digits
  │   └── e.g., "223"
  │
  ├─▶ Exchange Code (NXX)
  │   ├── Next 3 digits
  │   └── e.g., "456"
  │
  └─▶ Line Number
      ├── Last 4 digits
      └── e.g., "7890"

---

Frequently Asked Questions (FAQ)

What exactly is the North American Numbering Plan (NANP)?

The NANP is a telephone numbering system for the United States, its territories, Canada, and several Caribbean nations. It's characterized by a 10-digit number format (3-digit area code + 7-digit local number) and the shared international country code +1.

Why can't I just use one complex regular expression for everything?

While it's technically possible to write a single, complex regex to validate a phone number, it's often considered bad practice. A monolithic regex is difficult to read, debug, and maintain. A step-by-step approach, as shown in our class, is far more explicit, readable, and easier to modify if requirements change.

How does the CoffeeScript code handle parentheses and dashes?

It handles them during the stripping phase. The line @cleanNumber = @number.replace /[^\d]/g, '' uses a regular expression that finds any character that is not a digit (including parentheses, dashes, spaces, dots, etc.) and removes it by replacing it with an empty string.

What is the difference between match() and replace() in this context?

We use match() for validation checks. It returns an array of matches or null if no match is found. This is perfect for an if condition to see if an illegal character exists. We use replace() for transformation. It finds matching characters and returns a new string with the replacements made, which is ideal for cleaning the input.

Is CoffeeScript still relevant for new projects?

While CoffeeScript's popularity has declined in favor of modern JavaScript (ES6+) and TypeScript, it was highly influential. Many of its features (like arrow functions and class syntax) inspired their native JavaScript counterparts. Understanding CoffeeScript is valuable for maintaining legacy projects and for appreciating the evolution of JavaScript. For new projects, TypeScript or vanilla ES6+ is generally recommended.

What are the business risks of poor phone number validation?

The risks are significant: failed SMS/call notifications leading to poor customer experience, increased operational costs from attempting to contact invalid numbers, data corruption in your CRM or database, and potential security vulnerabilities if phone numbers are used for authentication without proper validation.

How would I extend this class to handle international numbers?

Handling all international numbers is extremely complex due to varying lengths, country codes, and internal formatting rules. A custom solution would require a massive database of rules for each country. For this reason, it is strongly recommended to use a dedicated, well-maintained library like libphonenumber-js for any application that needs to support global phone numbers.

---

Conclusion: From Chaos to Order

We have successfully navigated the complexities of user-submitted phone numbers, transforming a chaotic stream of data into a clean, validated, and reliable format. By building the PhoneNumber class, we've implemented a robust, step-by-step validation process: first rejecting invalid characters, then stripping all formatting, and finally applying the specific length and structural rules of the North American Numbering Plan.

This module from the kodikra.com curriculum not only teaches the specifics of phone number validation in CoffeeScript but also reinforces fundamental software engineering principles: data sanitization, the "fail-fast" approach, and the power of regular expressions. The skills you've honed here are directly applicable to countless other data processing challenges you will face in your development career.

Ready to tackle the next challenge? Explore our complete CoffeeScript learning path to continue building practical, real-world projects.

Disclaimer: The code and explanations in this article are based on CoffeeScript and modern JavaScript (ES6+) standards. Always ensure your development environment is configured to handle the appropriate language versions.

---

Published by Kodikra — Your trusted Coffeescript learning resource.