Modern Phone Validation Middleware for Express.js

First, let's set up our Node.js project.

# 1. Create a new directory and navigate into it
mkdir express-phone-validator && cd express-phone-validator

# 2. Initialize a new Node.js project
npm init -y

# 3. Add "type": "module" to your package.json to enable ES Modules
# This can be done manually or with a command like this:
node -e "const fs = require('fs'); const pkg = JSON.parse(fs.readFileSync('package.json')); pkg.type = 'module'; fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2));"

# 4. Install necessary dependencies
npm install express axios dotenv

Before we write the middleware, it's a good practice to abstract the API interaction into its own file. This makes our code cleaner, easier to test, and reusable.

import axios from 'axios';

const API_BASE_URL = 'https://phone-validator7.p.rapidapi.com/validate';

/**
 * Validates a phone number using the Payloadic Phone Validator API.
 * @param {string} phoneNumber - The phone number to validate.
 * @returns {Promise<object>} - The validation result from the API.
 * @throws {Error} - Throws an error if the API call fails or times out.
 */
export async function validatePhoneNumber(phoneNumber) {
  const options = {
    method: 'GET',
    url: API_BASE_URL,
    params: { phone: phoneNumber },
    headers: {
      'X-RapidAPI-Key': process.env.RAPIDAPI_KEY,
      'X-RapidAPI-Host': 'phone-validator7.p.rapidapi.com'
    },
    timeout: 5000 // 5-second timeout
  };

  try {
    const response = await axios.request(options);
    return response.data;
  } catch (error) {
    console.error('Phone Validator API request failed:', error.message);
    // Re-throw the error to be handled by the middleware
    throw error;
  }
}

Now, let's create the middleware. This function will intercept requests, validate the phone number using our client, and either block the request or pass it to the next handler.

import { validatePhoneNumber } from '../api/phoneValidatorClient.js';

/**
 * Express middleware to validate a phone number from the request body.
 * @param {string} [fieldName='phone'] - The name of the field in req.body containing the phone number.
 */
export const phoneValidatorMiddleware = (fieldName = 'phone') => {
  return async (req, res, next) => {
    const phoneNumber = req.body[fieldName];

    if (!phoneNumber) {
      return res.status(400).json({
        success: false,
        error: 'Phone number field ' + fieldName + ' is required.'
      });
    }

    try {
      const validationResult = await validatePhoneNumber(phoneNumber);

      if (!validationResult.valid) {
        return res.status(400).json({
          success: false,
          error: 'Invalid phone number provided.'
        });
      }

      // Attach the validated data to the request object for later use
      req.phoneValidation = validationResult;
      
      // Proceed to the next middleware or route handler
      next();
    } catch (error) {
      // This block catches errors from our API client
      if (axios.isAxiosError(error) && (error.code === 'ECONNABORTED' || error.response?.status >= 500)) {
        // Fail-open strategy: If our validation service is down, allow the request.
        // Log this event for monitoring.
        console.warn('Phone validation service is unavailable. Allowing request for ' + phoneNumber + ' to proceed.');
        next(); 
      } else {
        // For other errors (e.g., client-side issues, invalid API key), block the request.
        res.status(500).json({
          success: false,
          error: 'An internal error occurred during phone validation.'
        });
      }
    }
  };
};

Finally, let's create our main server file, import the middleware, and apply it to a route. We'll also create a mock User store to make this example fully runnable.

import express from 'express';
import 'dotenv/config'; // Loads .env file
import { phoneValidatorMiddleware } from './middleware/validatePhone.js';

const app = express();
const PORT = process.env.PORT || 3000;

// --- Mock User Store (for demonstration) ---
const users = [];
let currentId = 1;
const mockUserStore = {
  create: async (data) => {
    const newUser = { id: currentId++, ...data, createdAt: new Date() };
    users.push(newUser);
    return newUser;
  },
  findById: async (id) => users.find(u => u.id === id),
};
// -----------------------------------------

// Middleware to parse JSON bodies
app.use(express.json());

// Public route - no validation
app.get('/', (req, res) => {
  res.json({ message: 'Welcome to the API!' });
});

// Protected route with phone validation
app.post(
  '/register',
  phoneValidatorMiddleware('contactPhone'), // We'll look for the 'contactPhone' field
  async (req, res) => {
    try {
      const { email, password, contactPhone } = req.body;
      
      // The phone number has already been validated by the middleware.
      // We can now safely use the validated and formatted data.
      const validatedPhoneData = req.phoneValidation;

      console.log('Registering user with validated phone data:', validatedPhoneData);

      const user = await mockUserStore.create({
        email,
        password: 'hashed_password', // In a real app, hash this!
        phone: validatedPhoneData.number, // Use the standardized number
        phoneCountry: validatedPhoneData.country_code,
        phoneCarrier: validatedPhoneData.carrier,
      });

      res.status(201).json({
        success: true,
        message: 'User registered successfully!',
        user: { id: user.id, email: user.email, phone: user.phone },
      });
    } catch (error) {
      res.status(500).json({ success: false, error: 'User registration failed.' });
    }
  }
);

app.listen(PORT, () => {
  console.log('Server is running on http://localhost:' + PORT);
});